]>
Commit | Line | Data |
---|---|---|
9fa01778 | 1 | //! Compiler intrinsics. |
1a4d82fc | 2 | //! |
1b1a35ee XL |
3 | //! The corresponding definitions are in `compiler/rustc_codegen_llvm/src/intrinsic.rs`. |
4 | //! The corresponding const implementations are in `compiler/rustc_mir/src/interpret/intrinsics.rs` | |
dfeec247 XL |
5 | //! |
6 | //! # Const intrinsics | |
7 | //! | |
8 | //! Note: any changes to the constness of intrinsics should be discussed with the language team. | |
9 | //! This includes changes in the stability of the constness. | |
10 | //! | |
11 | //! In order to make an intrinsic usable at compile-time, one needs to copy the implementation | |
29967ef6 | 12 | //! from <https://github.com/rust-lang/miri/blob/master/src/shims/intrinsics.rs> to |
1b1a35ee | 13 | //! `compiler/rustc_mir/src/interpret/intrinsics.rs` and add a |
dfeec247 XL |
14 | //! `#[rustc_const_unstable(feature = "foo", issue = "01234")]` to the intrinsic. |
15 | //! | |
16 | //! If an intrinsic is supposed to be used from a `const fn` with a `rustc_const_stable` attribute, | |
17 | //! the intrinsic's attribute must be `rustc_const_stable`, too. Such a change should not be done | |
3dfed10e | 18 | //! without T-lang consultation, because it bakes a feature into the language that cannot be |
dfeec247 | 19 | //! replicated in user code without compiler support. |
1a4d82fc JJ |
20 | //! |
21 | //! # Volatiles | |
22 | //! | |
23 | //! The volatile intrinsics provide operations intended to act on I/O | |
24 | //! memory, which are guaranteed to not be reordered by the compiler | |
25 | //! across other volatile intrinsics. See the LLVM documentation on | |
26 | //! [[volatile]]. | |
27 | //! | |
28 | //! [volatile]: http://llvm.org/docs/LangRef.html#volatile-memory-accesses | |
29 | //! | |
30 | //! # Atomics | |
31 | //! | |
32 | //! The atomic intrinsics provide common atomic operations on machine | |
33 | //! words, with multiple possible memory orderings. They obey the same | |
34 | //! semantics as C++11. See the LLVM documentation on [[atomics]]. | |
35 | //! | |
36 | //! [atomics]: http://llvm.org/docs/Atomics.html | |
37 | //! | |
38 | //! A quick refresher on memory ordering: | |
39 | //! | |
40 | //! * Acquire - a barrier for acquiring a lock. Subsequent reads and writes | |
41 | //! take place after the barrier. | |
42 | //! * Release - a barrier for releasing a lock. Preceding reads and writes | |
43 | //! take place before the barrier. | |
44 | //! * Sequentially consistent - sequentially consistent operations are | |
45 | //! guaranteed to happen in order. This is the standard mode for working | |
46 | //! with atomic types and is equivalent to Java's `volatile`. | |
47 | ||
dfeec247 XL |
48 | #![unstable( |
49 | feature = "core_intrinsics", | |
50 | reason = "intrinsics are unlikely to ever be stabilized, instead \ | |
62682a34 | 51 | they should be used through stabilized interfaces \ |
e9174d1e | 52 | in the rest of the standard library", |
dfeec247 XL |
53 | issue = "none" |
54 | )] | |
1a4d82fc JJ |
55 | #![allow(missing_docs)] |
56 | ||
f9f354fc | 57 | use crate::marker::DiscriminantKind; |
416331ca XL |
58 | use crate::mem; |
59 | ||
3dfed10e XL |
60 | // These imports are used for simplifying intra-doc links |
61 | #[allow(unused_imports)] | |
62 | #[cfg(all(target_has_atomic = "8", target_has_atomic = "32", target_has_atomic = "ptr"))] | |
63 | use crate::sync::atomic::{self, AtomicBool, AtomicI32, AtomicIsize, AtomicU32, Ordering}; | |
64 | ||
cc61c64b | 65 | #[stable(feature = "drop_in_place", since = "1.8.0")] |
dfeec247 XL |
66 | #[rustc_deprecated( |
67 | reason = "no longer an intrinsic - use `ptr::drop_in_place` directly", | |
68 | since = "1.18.0" | |
69 | )] | |
48663c56 | 70 | pub use crate::ptr::drop_in_place; |
1a4d82fc | 71 | |
cc61c64b | 72 | extern "rust-intrinsic" { |
0731742a | 73 | // N.B., these intrinsics take raw pointers because they mutate aliased |
1a4d82fc JJ |
74 | // memory, which is not valid for either `&` or `&mut`. |
75 | ||
476ff2be | 76 | /// Stores a value if the current value is the same as the `old` value. |
74b04a01 | 77 | /// |
476ff2be | 78 | /// The stabilized version of this intrinsic is available on the |
3dfed10e XL |
79 | /// [`atomic`] types via the `compare_exchange` method by passing |
80 | /// [`Ordering::SeqCst`] as both the `success` and `failure` parameters. | |
81 | /// For example, [`AtomicBool::compare_exchange`]. | |
ba9703b0 | 82 | pub fn atomic_cxchg<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool); |
476ff2be | 83 | /// Stores a value if the current value is the same as the `old` value. |
74b04a01 | 84 | /// |
476ff2be | 85 | /// The stabilized version of this intrinsic is available on the |
3dfed10e XL |
86 | /// [`atomic`] types via the `compare_exchange` method by passing |
87 | /// [`Ordering::Acquire`] as both the `success` and `failure` parameters. | |
88 | /// For example, [`AtomicBool::compare_exchange`]. | |
ba9703b0 | 89 | pub fn atomic_cxchg_acq<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool); |
476ff2be | 90 | /// Stores a value if the current value is the same as the `old` value. |
74b04a01 | 91 | /// |
476ff2be | 92 | /// The stabilized version of this intrinsic is available on the |
3dfed10e XL |
93 | /// [`atomic`] types via the `compare_exchange` method by passing |
94 | /// [`Ordering::Release`] as the `success` and [`Ordering::Relaxed`] as the | |
95 | /// `failure` parameters. For example, [`AtomicBool::compare_exchange`]. | |
ba9703b0 | 96 | pub fn atomic_cxchg_rel<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool); |
476ff2be | 97 | /// Stores a value if the current value is the same as the `old` value. |
74b04a01 | 98 | /// |
476ff2be | 99 | /// The stabilized version of this intrinsic is available on the |
3dfed10e XL |
100 | /// [`atomic`] types via the `compare_exchange` method by passing |
101 | /// [`Ordering::AcqRel`] as the `success` and [`Ordering::Acquire`] as the | |
102 | /// `failure` parameters. For example, [`AtomicBool::compare_exchange`]. | |
ba9703b0 | 103 | pub fn atomic_cxchg_acqrel<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool); |
476ff2be | 104 | /// Stores a value if the current value is the same as the `old` value. |
74b04a01 | 105 | /// |
476ff2be | 106 | /// The stabilized version of this intrinsic is available on the |
3dfed10e XL |
107 | /// [`atomic`] types via the `compare_exchange` method by passing |
108 | /// [`Ordering::Relaxed`] as both the `success` and `failure` parameters. | |
109 | /// For example, [`AtomicBool::compare_exchange`]. | |
ba9703b0 | 110 | pub fn atomic_cxchg_relaxed<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool); |
476ff2be | 111 | /// Stores a value if the current value is the same as the `old` value. |
74b04a01 | 112 | /// |
476ff2be | 113 | /// The stabilized version of this intrinsic is available on the |
3dfed10e XL |
114 | /// [`atomic`] types via the `compare_exchange` method by passing |
115 | /// [`Ordering::SeqCst`] as the `success` and [`Ordering::Relaxed`] as the | |
116 | /// `failure` parameters. For example, [`AtomicBool::compare_exchange`]. | |
ba9703b0 | 117 | pub fn atomic_cxchg_failrelaxed<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool); |
476ff2be | 118 | /// Stores a value if the current value is the same as the `old` value. |
74b04a01 | 119 | /// |
476ff2be | 120 | /// The stabilized version of this intrinsic is available on the |
3dfed10e XL |
121 | /// [`atomic`] types via the `compare_exchange` method by passing |
122 | /// [`Ordering::SeqCst`] as the `success` and [`Ordering::Acquire`] as the | |
123 | /// `failure` parameters. For example, [`AtomicBool::compare_exchange`]. | |
ba9703b0 | 124 | pub fn atomic_cxchg_failacq<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool); |
476ff2be | 125 | /// Stores a value if the current value is the same as the `old` value. |
74b04a01 | 126 | /// |
476ff2be | 127 | /// The stabilized version of this intrinsic is available on the |
3dfed10e XL |
128 | /// [`atomic`] types via the `compare_exchange` method by passing |
129 | /// [`Ordering::Acquire`] as the `success` and [`Ordering::Relaxed`] as the | |
130 | /// `failure` parameters. For example, [`AtomicBool::compare_exchange`]. | |
ba9703b0 | 131 | pub fn atomic_cxchg_acq_failrelaxed<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool); |
476ff2be | 132 | /// Stores a value if the current value is the same as the `old` value. |
74b04a01 | 133 | /// |
476ff2be | 134 | /// The stabilized version of this intrinsic is available on the |
3dfed10e XL |
135 | /// [`atomic`] types via the `compare_exchange` method by passing |
136 | /// [`Ordering::AcqRel`] as the `success` and [`Ordering::Relaxed`] as the | |
137 | /// `failure` parameters. For example, [`AtomicBool::compare_exchange`]. | |
ba9703b0 | 138 | pub fn atomic_cxchg_acqrel_failrelaxed<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool); |
54a0048b | 139 | |
476ff2be | 140 | /// Stores a value if the current value is the same as the `old` value. |
74b04a01 | 141 | /// |
476ff2be | 142 | /// The stabilized version of this intrinsic is available on the |
3dfed10e XL |
143 | /// [`atomic`] types via the `compare_exchange_weak` method by passing |
144 | /// [`Ordering::SeqCst`] as both the `success` and `failure` parameters. | |
145 | /// For example, [`AtomicBool::compare_exchange_weak`]. | |
ba9703b0 | 146 | pub fn atomic_cxchgweak<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool); |
476ff2be | 147 | /// Stores a value if the current value is the same as the `old` value. |
74b04a01 | 148 | /// |
476ff2be | 149 | /// The stabilized version of this intrinsic is available on the |
3dfed10e XL |
150 | /// [`atomic`] types via the `compare_exchange_weak` method by passing |
151 | /// [`Ordering::Acquire`] as both the `success` and `failure` parameters. | |
152 | /// For example, [`AtomicBool::compare_exchange_weak`]. | |
ba9703b0 | 153 | pub fn atomic_cxchgweak_acq<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool); |
476ff2be | 154 | /// Stores a value if the current value is the same as the `old` value. |
74b04a01 | 155 | /// |
476ff2be | 156 | /// The stabilized version of this intrinsic is available on the |
3dfed10e XL |
157 | /// [`atomic`] types via the `compare_exchange_weak` method by passing |
158 | /// [`Ordering::Release`] as the `success` and [`Ordering::Relaxed`] as the | |
159 | /// `failure` parameters. For example, [`AtomicBool::compare_exchange_weak`]. | |
ba9703b0 | 160 | pub fn atomic_cxchgweak_rel<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool); |
476ff2be | 161 | /// Stores a value if the current value is the same as the `old` value. |
74b04a01 | 162 | /// |
476ff2be | 163 | /// The stabilized version of this intrinsic is available on the |
3dfed10e XL |
164 | /// [`atomic`] types via the `compare_exchange_weak` method by passing |
165 | /// [`Ordering::AcqRel`] as the `success` and [`Ordering::Acquire`] as the | |
166 | /// `failure` parameters. For example, [`AtomicBool::compare_exchange_weak`]. | |
ba9703b0 | 167 | pub fn atomic_cxchgweak_acqrel<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool); |
476ff2be | 168 | /// Stores a value if the current value is the same as the `old` value. |
74b04a01 | 169 | /// |
476ff2be | 170 | /// The stabilized version of this intrinsic is available on the |
3dfed10e XL |
171 | /// [`atomic`] types via the `compare_exchange_weak` method by passing |
172 | /// [`Ordering::Relaxed`] as both the `success` and `failure` parameters. | |
173 | /// For example, [`AtomicBool::compare_exchange_weak`]. | |
ba9703b0 | 174 | pub fn atomic_cxchgweak_relaxed<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool); |
476ff2be | 175 | /// Stores a value if the current value is the same as the `old` value. |
74b04a01 | 176 | /// |
476ff2be | 177 | /// The stabilized version of this intrinsic is available on the |
3dfed10e XL |
178 | /// [`atomic`] types via the `compare_exchange_weak` method by passing |
179 | /// [`Ordering::SeqCst`] as the `success` and [`Ordering::Relaxed`] as the | |
180 | /// `failure` parameters. For example, [`AtomicBool::compare_exchange_weak`]. | |
ba9703b0 | 181 | pub fn atomic_cxchgweak_failrelaxed<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool); |
476ff2be | 182 | /// Stores a value if the current value is the same as the `old` value. |
74b04a01 | 183 | /// |
476ff2be | 184 | /// The stabilized version of this intrinsic is available on the |
3dfed10e XL |
185 | /// [`atomic`] types via the `compare_exchange_weak` method by passing |
186 | /// [`Ordering::SeqCst`] as the `success` and [`Ordering::Acquire`] as the | |
187 | /// `failure` parameters. For example, [`AtomicBool::compare_exchange_weak`]. | |
ba9703b0 | 188 | pub fn atomic_cxchgweak_failacq<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool); |
476ff2be | 189 | /// Stores a value if the current value is the same as the `old` value. |
74b04a01 | 190 | /// |
476ff2be | 191 | /// The stabilized version of this intrinsic is available on the |
3dfed10e XL |
192 | /// [`atomic`] types via the `compare_exchange_weak` method by passing |
193 | /// [`Ordering::Acquire`] as the `success` and [`Ordering::Relaxed`] as the | |
194 | /// `failure` parameters. For example, [`AtomicBool::compare_exchange_weak`]. | |
ba9703b0 | 195 | pub fn atomic_cxchgweak_acq_failrelaxed<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool); |
476ff2be | 196 | /// Stores a value if the current value is the same as the `old` value. |
74b04a01 | 197 | /// |
476ff2be | 198 | /// The stabilized version of this intrinsic is available on the |
3dfed10e XL |
199 | /// [`atomic`] types via the `compare_exchange_weak` method by passing |
200 | /// [`Ordering::AcqRel`] as the `success` and [`Ordering::Relaxed`] as the | |
201 | /// `failure` parameters. For example, [`AtomicBool::compare_exchange_weak`]. | |
ba9703b0 | 202 | pub fn atomic_cxchgweak_acqrel_failrelaxed<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool); |
1a4d82fc | 203 | |
476ff2be | 204 | /// Loads the current value of the pointer. |
74b04a01 | 205 | /// |
476ff2be | 206 | /// The stabilized version of this intrinsic is available on the |
3dfed10e XL |
207 | /// [`atomic`] types via the `load` method by passing |
208 | /// [`Ordering::SeqCst`] as the `order`. For example, [`AtomicBool::load`]. | |
ba9703b0 | 209 | pub fn atomic_load<T: Copy>(src: *const T) -> T; |
476ff2be | 210 | /// Loads the current value of the pointer. |
74b04a01 | 211 | /// |
476ff2be | 212 | /// The stabilized version of this intrinsic is available on the |
3dfed10e XL |
213 | /// [`atomic`] types via the `load` method by passing |
214 | /// [`Ordering::Acquire`] as the `order`. For example, [`AtomicBool::load`]. | |
ba9703b0 | 215 | pub fn atomic_load_acq<T: Copy>(src: *const T) -> T; |
476ff2be | 216 | /// Loads the current value of the pointer. |
74b04a01 | 217 | /// |
476ff2be | 218 | /// The stabilized version of this intrinsic is available on the |
3dfed10e XL |
219 | /// [`atomic`] types via the `load` method by passing |
220 | /// [`Ordering::Relaxed`] as the `order`. For example, [`AtomicBool::load`]. | |
ba9703b0 XL |
221 | pub fn atomic_load_relaxed<T: Copy>(src: *const T) -> T; |
222 | pub fn atomic_load_unordered<T: Copy>(src: *const T) -> T; | |
1a4d82fc | 223 | |
476ff2be | 224 | /// Stores the value at the specified memory location. |
74b04a01 | 225 | /// |
476ff2be | 226 | /// The stabilized version of this intrinsic is available on the |
3dfed10e XL |
227 | /// [`atomic`] types via the `store` method by passing |
228 | /// [`Ordering::SeqCst`] as the `order`. For example, [`AtomicBool::store`]. | |
ba9703b0 | 229 | pub fn atomic_store<T: Copy>(dst: *mut T, val: T); |
476ff2be | 230 | /// Stores the value at the specified memory location. |
74b04a01 | 231 | /// |
476ff2be | 232 | /// The stabilized version of this intrinsic is available on the |
3dfed10e XL |
233 | /// [`atomic`] types via the `store` method by passing |
234 | /// [`Ordering::Release`] as the `order`. For example, [`AtomicBool::store`]. | |
ba9703b0 | 235 | pub fn atomic_store_rel<T: Copy>(dst: *mut T, val: T); |
476ff2be | 236 | /// Stores the value at the specified memory location. |
74b04a01 | 237 | /// |
476ff2be | 238 | /// The stabilized version of this intrinsic is available on the |
3dfed10e XL |
239 | /// [`atomic`] types via the `store` method by passing |
240 | /// [`Ordering::Relaxed`] as the `order`. For example, [`AtomicBool::store`]. | |
ba9703b0 XL |
241 | pub fn atomic_store_relaxed<T: Copy>(dst: *mut T, val: T); |
242 | pub fn atomic_store_unordered<T: Copy>(dst: *mut T, val: T); | |
1a4d82fc | 243 | |
476ff2be | 244 | /// Stores the value at the specified memory location, returning the old value. |
74b04a01 | 245 | /// |
476ff2be | 246 | /// The stabilized version of this intrinsic is available on the |
3dfed10e XL |
247 | /// [`atomic`] types via the `swap` method by passing |
248 | /// [`Ordering::SeqCst`] as the `order`. For example, [`AtomicBool::swap`]. | |
ba9703b0 | 249 | pub fn atomic_xchg<T: Copy>(dst: *mut T, src: T) -> T; |
476ff2be | 250 | /// Stores the value at the specified memory location, returning the old value. |
74b04a01 | 251 | /// |
476ff2be | 252 | /// The stabilized version of this intrinsic is available on the |
3dfed10e XL |
253 | /// [`atomic`] types via the `swap` method by passing |
254 | /// [`Ordering::Acquire`] as the `order`. For example, [`AtomicBool::swap`]. | |
ba9703b0 | 255 | pub fn atomic_xchg_acq<T: Copy>(dst: *mut T, src: T) -> T; |
476ff2be | 256 | /// Stores the value at the specified memory location, returning the old value. |
74b04a01 | 257 | /// |
476ff2be | 258 | /// The stabilized version of this intrinsic is available on the |
3dfed10e XL |
259 | /// [`atomic`] types via the `swap` method by passing |
260 | /// [`Ordering::Release`] as the `order`. For example, [`AtomicBool::swap`]. | |
ba9703b0 | 261 | pub fn atomic_xchg_rel<T: Copy>(dst: *mut T, src: T) -> T; |
476ff2be | 262 | /// Stores the value at the specified memory location, returning the old value. |
74b04a01 | 263 | /// |
476ff2be | 264 | /// The stabilized version of this intrinsic is available on the |
3dfed10e XL |
265 | /// [`atomic`] types via the `swap` method by passing |
266 | /// [`Ordering::AcqRel`] as the `order`. For example, [`AtomicBool::swap`]. | |
ba9703b0 | 267 | pub fn atomic_xchg_acqrel<T: Copy>(dst: *mut T, src: T) -> T; |
476ff2be | 268 | /// Stores the value at the specified memory location, returning the old value. |
74b04a01 | 269 | /// |
476ff2be | 270 | /// The stabilized version of this intrinsic is available on the |
3dfed10e XL |
271 | /// [`atomic`] types via the `swap` method by passing |
272 | /// [`Ordering::Relaxed`] as the `order`. For example, [`AtomicBool::swap`]. | |
ba9703b0 | 273 | pub fn atomic_xchg_relaxed<T: Copy>(dst: *mut T, src: T) -> T; |
1a4d82fc | 274 | |
9fa01778 | 275 | /// Adds to the current value, returning the previous value. |
74b04a01 | 276 | /// |
476ff2be | 277 | /// The stabilized version of this intrinsic is available on the |
3dfed10e XL |
278 | /// [`atomic`] types via the `fetch_add` method by passing |
279 | /// [`Ordering::SeqCst`] as the `order`. For example, [`AtomicIsize::fetch_add`]. | |
ba9703b0 | 280 | pub fn atomic_xadd<T: Copy>(dst: *mut T, src: T) -> T; |
9fa01778 | 281 | /// Adds to the current value, returning the previous value. |
74b04a01 | 282 | /// |
476ff2be | 283 | /// The stabilized version of this intrinsic is available on the |
3dfed10e XL |
284 | /// [`atomic`] types via the `fetch_add` method by passing |
285 | /// [`Ordering::Acquire`] as the `order`. For example, [`AtomicIsize::fetch_add`]. | |
ba9703b0 | 286 | pub fn atomic_xadd_acq<T: Copy>(dst: *mut T, src: T) -> T; |
9fa01778 | 287 | /// Adds to the current value, returning the previous value. |
74b04a01 | 288 | /// |
476ff2be | 289 | /// The stabilized version of this intrinsic is available on the |
3dfed10e XL |
290 | /// [`atomic`] types via the `fetch_add` method by passing |
291 | /// [`Ordering::Release`] as the `order`. For example, [`AtomicIsize::fetch_add`]. | |
ba9703b0 | 292 | pub fn atomic_xadd_rel<T: Copy>(dst: *mut T, src: T) -> T; |
9fa01778 | 293 | /// Adds to the current value, returning the previous value. |
74b04a01 | 294 | /// |
476ff2be | 295 | /// The stabilized version of this intrinsic is available on the |
3dfed10e XL |
296 | /// [`atomic`] types via the `fetch_add` method by passing |
297 | /// [`Ordering::AcqRel`] as the `order`. For example, [`AtomicIsize::fetch_add`]. | |
ba9703b0 | 298 | pub fn atomic_xadd_acqrel<T: Copy>(dst: *mut T, src: T) -> T; |
9fa01778 | 299 | /// Adds to the current value, returning the previous value. |
74b04a01 | 300 | /// |
476ff2be | 301 | /// The stabilized version of this intrinsic is available on the |
3dfed10e XL |
302 | /// [`atomic`] types via the `fetch_add` method by passing |
303 | /// [`Ordering::Relaxed`] as the `order`. For example, [`AtomicIsize::fetch_add`]. | |
ba9703b0 | 304 | pub fn atomic_xadd_relaxed<T: Copy>(dst: *mut T, src: T) -> T; |
1a4d82fc | 305 | |
476ff2be | 306 | /// Subtract from the current value, returning the previous value. |
74b04a01 | 307 | /// |
476ff2be | 308 | /// The stabilized version of this intrinsic is available on the |
3dfed10e XL |
309 | /// [`atomic`] types via the `fetch_sub` method by passing |
310 | /// [`Ordering::SeqCst`] as the `order`. For example, [`AtomicIsize::fetch_sub`]. | |
ba9703b0 | 311 | pub fn atomic_xsub<T: Copy>(dst: *mut T, src: T) -> T; |
476ff2be | 312 | /// Subtract from the current value, returning the previous value. |
74b04a01 | 313 | /// |
476ff2be | 314 | /// The stabilized version of this intrinsic is available on the |
3dfed10e XL |
315 | /// [`atomic`] types via the `fetch_sub` method by passing |
316 | /// [`Ordering::Acquire`] as the `order`. For example, [`AtomicIsize::fetch_sub`]. | |
ba9703b0 | 317 | pub fn atomic_xsub_acq<T: Copy>(dst: *mut T, src: T) -> T; |
476ff2be | 318 | /// Subtract from the current value, returning the previous value. |
74b04a01 | 319 | /// |
476ff2be | 320 | /// The stabilized version of this intrinsic is available on the |
3dfed10e XL |
321 | /// [`atomic`] types via the `fetch_sub` method by passing |
322 | /// [`Ordering::Release`] as the `order`. For example, [`AtomicIsize::fetch_sub`]. | |
ba9703b0 | 323 | pub fn atomic_xsub_rel<T: Copy>(dst: *mut T, src: T) -> T; |
476ff2be | 324 | /// Subtract from the current value, returning the previous value. |
74b04a01 | 325 | /// |
476ff2be | 326 | /// The stabilized version of this intrinsic is available on the |
3dfed10e XL |
327 | /// [`atomic`] types via the `fetch_sub` method by passing |
328 | /// [`Ordering::AcqRel`] as the `order`. For example, [`AtomicIsize::fetch_sub`]. | |
ba9703b0 | 329 | pub fn atomic_xsub_acqrel<T: Copy>(dst: *mut T, src: T) -> T; |
476ff2be | 330 | /// Subtract from the current value, returning the previous value. |
74b04a01 | 331 | /// |
476ff2be | 332 | /// The stabilized version of this intrinsic is available on the |
3dfed10e XL |
333 | /// [`atomic`] types via the `fetch_sub` method by passing |
334 | /// [`Ordering::Relaxed`] as the `order`. For example, [`AtomicIsize::fetch_sub`]. | |
ba9703b0 | 335 | pub fn atomic_xsub_relaxed<T: Copy>(dst: *mut T, src: T) -> T; |
1a4d82fc | 336 | |
476ff2be | 337 | /// Bitwise and with the current value, returning the previous value. |
74b04a01 | 338 | /// |
476ff2be | 339 | /// The stabilized version of this intrinsic is available on the |
3dfed10e XL |
340 | /// [`atomic`] types via the `fetch_and` method by passing |
341 | /// [`Ordering::SeqCst`] as the `order`. For example, [`AtomicBool::fetch_and`]. | |
ba9703b0 | 342 | pub fn atomic_and<T: Copy>(dst: *mut T, src: T) -> T; |
476ff2be | 343 | /// Bitwise and with the current value, returning the previous value. |
74b04a01 | 344 | /// |
476ff2be | 345 | /// The stabilized version of this intrinsic is available on the |
3dfed10e XL |
346 | /// [`atomic`] types via the `fetch_and` method by passing |
347 | /// [`Ordering::Acquire`] as the `order`. For example, [`AtomicBool::fetch_and`]. | |
ba9703b0 | 348 | pub fn atomic_and_acq<T: Copy>(dst: *mut T, src: T) -> T; |
476ff2be | 349 | /// Bitwise and with the current value, returning the previous value. |
74b04a01 | 350 | /// |
476ff2be | 351 | /// The stabilized version of this intrinsic is available on the |
3dfed10e XL |
352 | /// [`atomic`] types via the `fetch_and` method by passing |
353 | /// [`Ordering::Release`] as the `order`. For example, [`AtomicBool::fetch_and`]. | |
ba9703b0 | 354 | pub fn atomic_and_rel<T: Copy>(dst: *mut T, src: T) -> T; |
476ff2be | 355 | /// Bitwise and with the current value, returning the previous value. |
74b04a01 | 356 | /// |
476ff2be | 357 | /// The stabilized version of this intrinsic is available on the |
3dfed10e XL |
358 | /// [`atomic`] types via the `fetch_and` method by passing |
359 | /// [`Ordering::AcqRel`] as the `order`. For example, [`AtomicBool::fetch_and`]. | |
ba9703b0 | 360 | pub fn atomic_and_acqrel<T: Copy>(dst: *mut T, src: T) -> T; |
476ff2be | 361 | /// Bitwise and with the current value, returning the previous value. |
74b04a01 | 362 | /// |
476ff2be | 363 | /// The stabilized version of this intrinsic is available on the |
3dfed10e XL |
364 | /// [`atomic`] types via the `fetch_and` method by passing |
365 | /// [`Ordering::Relaxed`] as the `order`. For example, [`AtomicBool::fetch_and`]. | |
ba9703b0 | 366 | pub fn atomic_and_relaxed<T: Copy>(dst: *mut T, src: T) -> T; |
1a4d82fc | 367 | |
476ff2be | 368 | /// Bitwise nand with the current value, returning the previous value. |
74b04a01 | 369 | /// |
476ff2be | 370 | /// The stabilized version of this intrinsic is available on the |
3dfed10e XL |
371 | /// [`AtomicBool`] type via the `fetch_nand` method by passing |
372 | /// [`Ordering::SeqCst`] as the `order`. For example, [`AtomicBool::fetch_nand`]. | |
ba9703b0 | 373 | pub fn atomic_nand<T: Copy>(dst: *mut T, src: T) -> T; |
476ff2be | 374 | /// Bitwise nand with the current value, returning the previous value. |
74b04a01 | 375 | /// |
476ff2be | 376 | /// The stabilized version of this intrinsic is available on the |
3dfed10e XL |
377 | /// [`AtomicBool`] type via the `fetch_nand` method by passing |
378 | /// [`Ordering::Acquire`] as the `order`. For example, [`AtomicBool::fetch_nand`]. | |
ba9703b0 | 379 | pub fn atomic_nand_acq<T: Copy>(dst: *mut T, src: T) -> T; |
476ff2be | 380 | /// Bitwise nand with the current value, returning the previous value. |
74b04a01 | 381 | /// |
476ff2be | 382 | /// The stabilized version of this intrinsic is available on the |
3dfed10e XL |
383 | /// [`AtomicBool`] type via the `fetch_nand` method by passing |
384 | /// [`Ordering::Release`] as the `order`. For example, [`AtomicBool::fetch_nand`]. | |
ba9703b0 | 385 | pub fn atomic_nand_rel<T: Copy>(dst: *mut T, src: T) -> T; |
476ff2be | 386 | /// Bitwise nand with the current value, returning the previous value. |
74b04a01 | 387 | /// |
476ff2be | 388 | /// The stabilized version of this intrinsic is available on the |
3dfed10e XL |
389 | /// [`AtomicBool`] type via the `fetch_nand` method by passing |
390 | /// [`Ordering::AcqRel`] as the `order`. For example, [`AtomicBool::fetch_nand`]. | |
ba9703b0 | 391 | pub fn atomic_nand_acqrel<T: Copy>(dst: *mut T, src: T) -> T; |
476ff2be | 392 | /// Bitwise nand with the current value, returning the previous value. |
74b04a01 | 393 | /// |
476ff2be | 394 | /// The stabilized version of this intrinsic is available on the |
3dfed10e XL |
395 | /// [`AtomicBool`] type via the `fetch_nand` method by passing |
396 | /// [`Ordering::Relaxed`] as the `order`. For example, [`AtomicBool::fetch_nand`]. | |
ba9703b0 | 397 | pub fn atomic_nand_relaxed<T: Copy>(dst: *mut T, src: T) -> T; |
1a4d82fc | 398 | |
476ff2be | 399 | /// Bitwise or with the current value, returning the previous value. |
74b04a01 | 400 | /// |
476ff2be | 401 | /// The stabilized version of this intrinsic is available on the |
3dfed10e XL |
402 | /// [`atomic`] types via the `fetch_or` method by passing |
403 | /// [`Ordering::SeqCst`] as the `order`. For example, [`AtomicBool::fetch_or`]. | |
ba9703b0 | 404 | pub fn atomic_or<T: Copy>(dst: *mut T, src: T) -> T; |
476ff2be | 405 | /// Bitwise or with the current value, returning the previous value. |
74b04a01 | 406 | /// |
476ff2be | 407 | /// The stabilized version of this intrinsic is available on the |
3dfed10e XL |
408 | /// [`atomic`] types via the `fetch_or` method by passing |
409 | /// [`Ordering::Acquire`] as the `order`. For example, [`AtomicBool::fetch_or`]. | |
ba9703b0 | 410 | pub fn atomic_or_acq<T: Copy>(dst: *mut T, src: T) -> T; |
476ff2be | 411 | /// Bitwise or with the current value, returning the previous value. |
74b04a01 | 412 | /// |
476ff2be | 413 | /// The stabilized version of this intrinsic is available on the |
3dfed10e XL |
414 | /// [`atomic`] types via the `fetch_or` method by passing |
415 | /// [`Ordering::Release`] as the `order`. For example, [`AtomicBool::fetch_or`]. | |
ba9703b0 | 416 | pub fn atomic_or_rel<T: Copy>(dst: *mut T, src: T) -> T; |
476ff2be | 417 | /// Bitwise or with the current value, returning the previous value. |
74b04a01 | 418 | /// |
476ff2be | 419 | /// The stabilized version of this intrinsic is available on the |
3dfed10e XL |
420 | /// [`atomic`] types via the `fetch_or` method by passing |
421 | /// [`Ordering::AcqRel`] as the `order`. For example, [`AtomicBool::fetch_or`]. | |
ba9703b0 | 422 | pub fn atomic_or_acqrel<T: Copy>(dst: *mut T, src: T) -> T; |
476ff2be | 423 | /// Bitwise or with the current value, returning the previous value. |
74b04a01 | 424 | /// |
476ff2be | 425 | /// The stabilized version of this intrinsic is available on the |
3dfed10e XL |
426 | /// [`atomic`] types via the `fetch_or` method by passing |
427 | /// [`Ordering::Relaxed`] as the `order`. For example, [`AtomicBool::fetch_or`]. | |
ba9703b0 | 428 | pub fn atomic_or_relaxed<T: Copy>(dst: *mut T, src: T) -> T; |
1a4d82fc | 429 | |
476ff2be | 430 | /// Bitwise xor with the current value, returning the previous value. |
74b04a01 | 431 | /// |
476ff2be | 432 | /// The stabilized version of this intrinsic is available on the |
3dfed10e XL |
433 | /// [`atomic`] types via the `fetch_xor` method by passing |
434 | /// [`Ordering::SeqCst`] as the `order`. For example, [`AtomicBool::fetch_xor`]. | |
ba9703b0 | 435 | pub fn atomic_xor<T: Copy>(dst: *mut T, src: T) -> T; |
476ff2be | 436 | /// Bitwise xor with the current value, returning the previous value. |
74b04a01 | 437 | /// |
476ff2be | 438 | /// The stabilized version of this intrinsic is available on the |
3dfed10e XL |
439 | /// [`atomic`] types via the `fetch_xor` method by passing |
440 | /// [`Ordering::Acquire`] as the `order`. For example, [`AtomicBool::fetch_xor`]. | |
ba9703b0 | 441 | pub fn atomic_xor_acq<T: Copy>(dst: *mut T, src: T) -> T; |
476ff2be | 442 | /// Bitwise xor with the current value, returning the previous value. |
74b04a01 | 443 | /// |
476ff2be | 444 | /// The stabilized version of this intrinsic is available on the |
3dfed10e XL |
445 | /// [`atomic`] types via the `fetch_xor` method by passing |
446 | /// [`Ordering::Release`] as the `order`. For example, [`AtomicBool::fetch_xor`]. | |
ba9703b0 | 447 | pub fn atomic_xor_rel<T: Copy>(dst: *mut T, src: T) -> T; |
476ff2be | 448 | /// Bitwise xor with the current value, returning the previous value. |
74b04a01 | 449 | /// |
476ff2be | 450 | /// The stabilized version of this intrinsic is available on the |
3dfed10e XL |
451 | /// [`atomic`] types via the `fetch_xor` method by passing |
452 | /// [`Ordering::AcqRel`] as the `order`. For example, [`AtomicBool::fetch_xor`]. | |
ba9703b0 | 453 | pub fn atomic_xor_acqrel<T: Copy>(dst: *mut T, src: T) -> T; |
476ff2be | 454 | /// Bitwise xor with the current value, returning the previous value. |
74b04a01 | 455 | /// |
476ff2be | 456 | /// The stabilized version of this intrinsic is available on the |
3dfed10e XL |
457 | /// [`atomic`] types via the `fetch_xor` method by passing |
458 | /// [`Ordering::Relaxed`] as the `order`. For example, [`AtomicBool::fetch_xor`]. | |
ba9703b0 | 459 | pub fn atomic_xor_relaxed<T: Copy>(dst: *mut T, src: T) -> T; |
1a4d82fc | 460 | |
74b04a01 XL |
461 | /// Maximum with the current value using a signed comparison. |
462 | /// | |
463 | /// The stabilized version of this intrinsic is available on the | |
3dfed10e XL |
464 | /// [`atomic`] signed integer types via the `fetch_max` method by passing |
465 | /// [`Ordering::SeqCst`] as the `order`. For example, [`AtomicI32::fetch_max`]. | |
ba9703b0 | 466 | pub fn atomic_max<T: Copy>(dst: *mut T, src: T) -> T; |
74b04a01 XL |
467 | /// Maximum with the current value using a signed comparison. |
468 | /// | |
469 | /// The stabilized version of this intrinsic is available on the | |
3dfed10e XL |
470 | /// [`atomic`] signed integer types via the `fetch_max` method by passing |
471 | /// [`Ordering::Acquire`] as the `order`. For example, [`AtomicI32::fetch_max`]. | |
ba9703b0 | 472 | pub fn atomic_max_acq<T: Copy>(dst: *mut T, src: T) -> T; |
74b04a01 XL |
473 | /// Maximum with the current value using a signed comparison. |
474 | /// | |
475 | /// The stabilized version of this intrinsic is available on the | |
3dfed10e XL |
476 | /// [`atomic`] signed integer types via the `fetch_max` method by passing |
477 | /// [`Ordering::Release`] as the `order`. For example, [`AtomicI32::fetch_max`]. | |
ba9703b0 | 478 | pub fn atomic_max_rel<T: Copy>(dst: *mut T, src: T) -> T; |
74b04a01 XL |
479 | /// Maximum with the current value using a signed comparison. |
480 | /// | |
481 | /// The stabilized version of this intrinsic is available on the | |
3dfed10e XL |
482 | /// [`atomic`] signed integer types via the `fetch_max` method by passing |
483 | /// [`Ordering::AcqRel`] as the `order`. For example, [`AtomicI32::fetch_max`]. | |
ba9703b0 | 484 | pub fn atomic_max_acqrel<T: Copy>(dst: *mut T, src: T) -> T; |
74b04a01 XL |
485 | /// Maximum with the current value. |
486 | /// | |
487 | /// The stabilized version of this intrinsic is available on the | |
3dfed10e XL |
488 | /// [`atomic`] signed integer types via the `fetch_max` method by passing |
489 | /// [`Ordering::Relaxed`] as the `order`. For example, [`AtomicI32::fetch_max`]. | |
ba9703b0 | 490 | pub fn atomic_max_relaxed<T: Copy>(dst: *mut T, src: T) -> T; |
1a4d82fc | 491 | |
74b04a01 XL |
492 | /// Minimum with the current value using a signed comparison. |
493 | /// | |
494 | /// The stabilized version of this intrinsic is available on the | |
3dfed10e XL |
495 | /// [`atomic`] signed integer types via the `fetch_min` method by passing |
496 | /// [`Ordering::SeqCst`] as the `order`. For example, [`AtomicI32::fetch_min`]. | |
ba9703b0 | 497 | pub fn atomic_min<T: Copy>(dst: *mut T, src: T) -> T; |
74b04a01 XL |
498 | /// Minimum with the current value using a signed comparison. |
499 | /// | |
500 | /// The stabilized version of this intrinsic is available on the | |
3dfed10e XL |
501 | /// [`atomic`] signed integer types via the `fetch_min` method by passing |
502 | /// [`Ordering::Acquire`] as the `order`. For example, [`AtomicI32::fetch_min`]. | |
ba9703b0 | 503 | pub fn atomic_min_acq<T: Copy>(dst: *mut T, src: T) -> T; |
74b04a01 XL |
504 | /// Minimum with the current value using a signed comparison. |
505 | /// | |
506 | /// The stabilized version of this intrinsic is available on the | |
3dfed10e XL |
507 | /// [`atomic`] signed integer types via the `fetch_min` method by passing |
508 | /// [`Ordering::Release`] as the `order`. For example, [`AtomicI32::fetch_min`]. | |
ba9703b0 | 509 | pub fn atomic_min_rel<T: Copy>(dst: *mut T, src: T) -> T; |
74b04a01 XL |
510 | /// Minimum with the current value using a signed comparison. |
511 | /// | |
512 | /// The stabilized version of this intrinsic is available on the | |
3dfed10e XL |
513 | /// [`atomic`] signed integer types via the `fetch_min` method by passing |
514 | /// [`Ordering::AcqRel`] as the `order`. For example, [`AtomicI32::fetch_min`]. | |
ba9703b0 | 515 | pub fn atomic_min_acqrel<T: Copy>(dst: *mut T, src: T) -> T; |
74b04a01 XL |
516 | /// Minimum with the current value using a signed comparison. |
517 | /// | |
518 | /// The stabilized version of this intrinsic is available on the | |
3dfed10e XL |
519 | /// [`atomic`] signed integer types via the `fetch_min` method by passing |
520 | /// [`Ordering::Relaxed`] as the `order`. For example, [`AtomicI32::fetch_min`]. | |
ba9703b0 | 521 | pub fn atomic_min_relaxed<T: Copy>(dst: *mut T, src: T) -> T; |
1a4d82fc | 522 | |
74b04a01 XL |
523 | /// Minimum with the current value using an unsigned comparison. |
524 | /// | |
525 | /// The stabilized version of this intrinsic is available on the | |
3dfed10e XL |
526 | /// [`atomic`] unsigned integer types via the `fetch_min` method by passing |
527 | /// [`Ordering::SeqCst`] as the `order`. For example, [`AtomicU32::fetch_min`]. | |
ba9703b0 | 528 | pub fn atomic_umin<T: Copy>(dst: *mut T, src: T) -> T; |
74b04a01 XL |
529 | /// Minimum with the current value using an unsigned comparison. |
530 | /// | |
531 | /// The stabilized version of this intrinsic is available on the | |
3dfed10e XL |
532 | /// [`atomic`] unsigned integer types via the `fetch_min` method by passing |
533 | /// [`Ordering::Acquire`] as the `order`. For example, [`AtomicU32::fetch_min`]. | |
ba9703b0 | 534 | pub fn atomic_umin_acq<T: Copy>(dst: *mut T, src: T) -> T; |
74b04a01 XL |
535 | /// Minimum with the current value using an unsigned comparison. |
536 | /// | |
537 | /// The stabilized version of this intrinsic is available on the | |
3dfed10e XL |
538 | /// [`atomic`] unsigned integer types via the `fetch_min` method by passing |
539 | /// [`Ordering::Release`] as the `order`. For example, [`AtomicU32::fetch_min`]. | |
ba9703b0 | 540 | pub fn atomic_umin_rel<T: Copy>(dst: *mut T, src: T) -> T; |
74b04a01 XL |
541 | /// Minimum with the current value using an unsigned comparison. |
542 | /// | |
543 | /// The stabilized version of this intrinsic is available on the | |
3dfed10e XL |
544 | /// [`atomic`] unsigned integer types via the `fetch_min` method by passing |
545 | /// [`Ordering::AcqRel`] as the `order`. For example, [`AtomicU32::fetch_min`]. | |
ba9703b0 | 546 | pub fn atomic_umin_acqrel<T: Copy>(dst: *mut T, src: T) -> T; |
74b04a01 XL |
547 | /// Minimum with the current value using an unsigned comparison. |
548 | /// | |
549 | /// The stabilized version of this intrinsic is available on the | |
3dfed10e XL |
550 | /// [`atomic`] unsigned integer types via the `fetch_min` method by passing |
551 | /// [`Ordering::Relaxed`] as the `order`. For example, [`AtomicU32::fetch_min`]. | |
ba9703b0 | 552 | pub fn atomic_umin_relaxed<T: Copy>(dst: *mut T, src: T) -> T; |
1a4d82fc | 553 | |
74b04a01 XL |
554 | /// Maximum with the current value using an unsigned comparison. |
555 | /// | |
556 | /// The stabilized version of this intrinsic is available on the | |
3dfed10e XL |
557 | /// [`atomic`] unsigned integer types via the `fetch_max` method by passing |
558 | /// [`Ordering::SeqCst`] as the `order`. For example, [`AtomicU32::fetch_max`]. | |
ba9703b0 | 559 | pub fn atomic_umax<T: Copy>(dst: *mut T, src: T) -> T; |
74b04a01 XL |
560 | /// Maximum with the current value using an unsigned comparison. |
561 | /// | |
562 | /// The stabilized version of this intrinsic is available on the | |
3dfed10e XL |
563 | /// [`atomic`] unsigned integer types via the `fetch_max` method by passing |
564 | /// [`Ordering::Acquire`] as the `order`. For example, [`AtomicU32::fetch_max`]. | |
ba9703b0 | 565 | pub fn atomic_umax_acq<T: Copy>(dst: *mut T, src: T) -> T; |
74b04a01 XL |
566 | /// Maximum with the current value using an unsigned comparison. |
567 | /// | |
568 | /// The stabilized version of this intrinsic is available on the | |
3dfed10e XL |
569 | /// [`atomic`] unsigned integer types via the `fetch_max` method by passing |
570 | /// [`Ordering::Release`] as the `order`. For example, [`AtomicU32::fetch_max`]. | |
ba9703b0 | 571 | pub fn atomic_umax_rel<T: Copy>(dst: *mut T, src: T) -> T; |
74b04a01 XL |
572 | /// Maximum with the current value using an unsigned comparison. |
573 | /// | |
574 | /// The stabilized version of this intrinsic is available on the | |
3dfed10e XL |
575 | /// [`atomic`] unsigned integer types via the `fetch_max` method by passing |
576 | /// [`Ordering::AcqRel`] as the `order`. For example, [`AtomicU32::fetch_max`]. | |
ba9703b0 | 577 | pub fn atomic_umax_acqrel<T: Copy>(dst: *mut T, src: T) -> T; |
74b04a01 XL |
578 | /// Maximum with the current value using an unsigned comparison. |
579 | /// | |
580 | /// The stabilized version of this intrinsic is available on the | |
3dfed10e XL |
581 | /// [`atomic`] unsigned integer types via the `fetch_max` method by passing |
582 | /// [`Ordering::Relaxed`] as the `order`. For example, [`AtomicU32::fetch_max`]. | |
ba9703b0 | 583 | pub fn atomic_umax_relaxed<T: Copy>(dst: *mut T, src: T) -> T; |
7cac9316 XL |
584 | |
585 | /// The `prefetch` intrinsic is a hint to the code generator to insert a prefetch instruction | |
9fa01778 | 586 | /// if supported; otherwise, it is a no-op. |
7cac9316 XL |
587 | /// Prefetches have no effect on the behavior of the program but can change its performance |
588 | /// characteristics. | |
589 | /// | |
590 | /// The `locality` argument must be a constant integer and is a temporal locality specifier | |
f9f354fc XL |
591 | /// ranging from (0) - no locality, to (3) - extremely local keep in cache. |
592 | /// | |
593 | /// This intrinsic does not have a stable counterpart. | |
7cac9316 XL |
594 | pub fn prefetch_read_data<T>(data: *const T, locality: i32); |
595 | /// The `prefetch` intrinsic is a hint to the code generator to insert a prefetch instruction | |
9fa01778 | 596 | /// if supported; otherwise, it is a no-op. |
7cac9316 XL |
597 | /// Prefetches have no effect on the behavior of the program but can change its performance |
598 | /// characteristics. | |
599 | /// | |
600 | /// The `locality` argument must be a constant integer and is a temporal locality specifier | |
f9f354fc XL |
601 | /// ranging from (0) - no locality, to (3) - extremely local keep in cache. |
602 | /// | |
603 | /// This intrinsic does not have a stable counterpart. | |
7cac9316 XL |
604 | pub fn prefetch_write_data<T>(data: *const T, locality: i32); |
605 | /// The `prefetch` intrinsic is a hint to the code generator to insert a prefetch instruction | |
9fa01778 | 606 | /// if supported; otherwise, it is a no-op. |
7cac9316 XL |
607 | /// Prefetches have no effect on the behavior of the program but can change its performance |
608 | /// characteristics. | |
609 | /// | |
610 | /// The `locality` argument must be a constant integer and is a temporal locality specifier | |
f9f354fc XL |
611 | /// ranging from (0) - no locality, to (3) - extremely local keep in cache. |
612 | /// | |
613 | /// This intrinsic does not have a stable counterpart. | |
7cac9316 XL |
614 | pub fn prefetch_read_instruction<T>(data: *const T, locality: i32); |
615 | /// The `prefetch` intrinsic is a hint to the code generator to insert a prefetch instruction | |
9fa01778 | 616 | /// if supported; otherwise, it is a no-op. |
7cac9316 XL |
617 | /// Prefetches have no effect on the behavior of the program but can change its performance |
618 | /// characteristics. | |
619 | /// | |
620 | /// The `locality` argument must be a constant integer and is a temporal locality specifier | |
f9f354fc XL |
621 | /// ranging from (0) - no locality, to (3) - extremely local keep in cache. |
622 | /// | |
623 | /// This intrinsic does not have a stable counterpart. | |
7cac9316 | 624 | pub fn prefetch_write_instruction<T>(data: *const T, locality: i32); |
1a4d82fc JJ |
625 | } |
626 | ||
627 | extern "rust-intrinsic" { | |
74b04a01 XL |
628 | /// An atomic fence. |
629 | /// | |
630 | /// The stabilized version of this intrinsic is available in | |
3dfed10e | 631 | /// [`atomic::fence`] by passing [`Ordering::SeqCst`] |
74b04a01 | 632 | /// as the `order`. |
1a4d82fc | 633 | pub fn atomic_fence(); |
74b04a01 XL |
634 | /// An atomic fence. |
635 | /// | |
636 | /// The stabilized version of this intrinsic is available in | |
3dfed10e | 637 | /// [`atomic::fence`] by passing [`Ordering::Acquire`] |
74b04a01 | 638 | /// as the `order`. |
1a4d82fc | 639 | pub fn atomic_fence_acq(); |
74b04a01 XL |
640 | /// An atomic fence. |
641 | /// | |
642 | /// The stabilized version of this intrinsic is available in | |
3dfed10e | 643 | /// [`atomic::fence`] by passing [`Ordering::Release`] |
74b04a01 | 644 | /// as the `order`. |
1a4d82fc | 645 | pub fn atomic_fence_rel(); |
74b04a01 XL |
646 | /// An atomic fence. |
647 | /// | |
648 | /// The stabilized version of this intrinsic is available in | |
3dfed10e | 649 | /// [`atomic::fence`] by passing [`Ordering::AcqRel`] |
74b04a01 | 650 | /// as the `order`. |
1a4d82fc JJ |
651 | pub fn atomic_fence_acqrel(); |
652 | ||
d9579d0f AL |
653 | /// A compiler-only memory barrier. |
654 | /// | |
62682a34 SL |
655 | /// Memory accesses will never be reordered across this barrier by the |
656 | /// compiler, but no instructions will be emitted for it. This is | |
657 | /// appropriate for operations on the same thread that may be preempted, | |
658 | /// such as when interacting with signal handlers. | |
74b04a01 XL |
659 | /// |
660 | /// The stabilized version of this intrinsic is available in | |
3dfed10e | 661 | /// [`atomic::compiler_fence`] by passing [`Ordering::SeqCst`] |
74b04a01 | 662 | /// as the `order`. |
d9579d0f | 663 | pub fn atomic_singlethreadfence(); |
74b04a01 XL |
664 | /// A compiler-only memory barrier. |
665 | /// | |
666 | /// Memory accesses will never be reordered across this barrier by the | |
667 | /// compiler, but no instructions will be emitted for it. This is | |
668 | /// appropriate for operations on the same thread that may be preempted, | |
669 | /// such as when interacting with signal handlers. | |
670 | /// | |
671 | /// The stabilized version of this intrinsic is available in | |
3dfed10e | 672 | /// [`atomic::compiler_fence`] by passing [`Ordering::Acquire`] |
74b04a01 | 673 | /// as the `order`. |
d9579d0f | 674 | pub fn atomic_singlethreadfence_acq(); |
74b04a01 XL |
675 | /// A compiler-only memory barrier. |
676 | /// | |
677 | /// Memory accesses will never be reordered across this barrier by the | |
678 | /// compiler, but no instructions will be emitted for it. This is | |
679 | /// appropriate for operations on the same thread that may be preempted, | |
680 | /// such as when interacting with signal handlers. | |
681 | /// | |
682 | /// The stabilized version of this intrinsic is available in | |
3dfed10e | 683 | /// [`atomic::compiler_fence`] by passing [`Ordering::Release`] |
74b04a01 | 684 | /// as the `order`. |
d9579d0f | 685 | pub fn atomic_singlethreadfence_rel(); |
74b04a01 XL |
686 | /// A compiler-only memory barrier. |
687 | /// | |
688 | /// Memory accesses will never be reordered across this barrier by the | |
689 | /// compiler, but no instructions will be emitted for it. This is | |
690 | /// appropriate for operations on the same thread that may be preempted, | |
691 | /// such as when interacting with signal handlers. | |
692 | /// | |
693 | /// The stabilized version of this intrinsic is available in | |
3dfed10e | 694 | /// [`atomic::compiler_fence`] by passing [`Ordering::AcqRel`] |
74b04a01 | 695 | /// as the `order`. |
d9579d0f AL |
696 | pub fn atomic_singlethreadfence_acqrel(); |
697 | ||
3157f602 XL |
698 | /// Magic intrinsic that derives its meaning from attributes |
699 | /// attached to the function. | |
700 | /// | |
701 | /// For example, dataflow uses this to inject static assertions so | |
702 | /// that `rustc_peek(potentially_uninitialized)` would actually | |
703 | /// double-check that dataflow did indeed compute that it is | |
704 | /// uninitialized at that point in the control flow. | |
f9f354fc XL |
705 | /// |
706 | /// This intrinsic should not be used outside of the compiler. | |
3157f602 XL |
707 | pub fn rustc_peek<T>(_: T) -> T; |
708 | ||
9346a6ac | 709 | /// Aborts the execution of the process. |
abe05a73 | 710 | /// |
f9f354fc XL |
711 | /// A more user-friendly and stable version of this operation is |
712 | /// [`std::process::abort`](../../std/process/fn.abort.html). | |
1a4d82fc JJ |
713 | pub fn abort() -> !; |
714 | ||
3b2f2976 XL |
715 | /// Tells LLVM that this point in the code is not reachable, enabling |
716 | /// further optimizations. | |
1a4d82fc | 717 | /// |
0731742a | 718 | /// N.B., this is very different from the `unreachable!()` macro: Unlike the |
3b2f2976 XL |
719 | /// macro, which panics when it is executed, it is *undefined behavior* to |
720 | /// reach code marked with this function. | |
83c7162d | 721 | /// |
29967ef6 | 722 | /// The stabilized version of this intrinsic is [`core::hint::unreachable_unchecked`](crate::hint::unreachable_unchecked). |
3dfed10e | 723 | #[rustc_const_unstable(feature = "const_unreachable_unchecked", issue = "53188")] |
1a4d82fc JJ |
724 | pub fn unreachable() -> !; |
725 | ||
9346a6ac | 726 | /// Informs the optimizer that a condition is always true. |
1a4d82fc JJ |
727 | /// If the condition is false, the behavior is undefined. |
728 | /// | |
729 | /// No code is generated for this intrinsic, but the optimizer will try | |
730 | /// to preserve it (and its condition) between passes, which may interfere | |
731 | /// with optimization of surrounding code and reduce performance. It should | |
732 | /// not be used if the invariant can be discovered by the optimizer on its | |
733 | /// own, or if it does not enable any significant optimizations. | |
f9f354fc XL |
734 | /// |
735 | /// This intrinsic does not have a stable counterpart. | |
1b1a35ee | 736 | #[rustc_const_unstable(feature = "const_assume", issue = "76972")] |
1a4d82fc JJ |
737 | pub fn assume(b: bool); |
738 | ||
9e0c209e SL |
739 | /// Hints to the compiler that branch condition is likely to be true. |
740 | /// Returns the value passed to it. | |
741 | /// | |
742 | /// Any use other than with `if` statements will probably not have an effect. | |
f9f354fc XL |
743 | /// |
744 | /// This intrinsic does not have a stable counterpart. | |
f035d41b | 745 | #[rustc_const_unstable(feature = "const_likely", issue = "none")] |
9e0c209e SL |
746 | pub fn likely(b: bool) -> bool; |
747 | ||
9e0c209e SL |
748 | /// Hints to the compiler that branch condition is likely to be false. |
749 | /// Returns the value passed to it. | |
750 | /// | |
751 | /// Any use other than with `if` statements will probably not have an effect. | |
f9f354fc XL |
752 | /// |
753 | /// This intrinsic does not have a stable counterpart. | |
f035d41b | 754 | #[rustc_const_unstable(feature = "const_likely", issue = "none")] |
9e0c209e SL |
755 | pub fn unlikely(b: bool) -> bool; |
756 | ||
9346a6ac | 757 | /// Executes a breakpoint trap, for inspection by a debugger. |
f9f354fc XL |
758 | /// |
759 | /// This intrinsic does not have a stable counterpart. | |
1a4d82fc JJ |
760 | pub fn breakpoint(); |
761 | ||
762 | /// The size of a type in bytes. | |
763 | /// | |
a7813a04 XL |
764 | /// More specifically, this is the offset in bytes between successive |
765 | /// items of the same type, including alignment padding. | |
a1dfa0c6 | 766 | /// |
29967ef6 | 767 | /// The stabilized version of this intrinsic is [`core::mem::size_of`](crate::mem::size_of). |
dfeec247 | 768 | #[rustc_const_stable(feature = "const_size_of", since = "1.40.0")] |
85aaf69f | 769 | pub fn size_of<T>() -> usize; |
1a4d82fc | 770 | |
9346a6ac | 771 | /// Moves a value to an uninitialized memory location. |
1a4d82fc JJ |
772 | /// |
773 | /// Drop glue is not run on the destination. | |
74b04a01 | 774 | /// |
29967ef6 | 775 | /// The stabilized version of this intrinsic is [`core::ptr::write`](crate::ptr::write). |
c1a9b12d | 776 | pub fn move_val_init<T>(dst: *mut T, src: T); |
1a4d82fc | 777 | |
74b04a01 XL |
778 | /// The minimum alignment of a type. |
779 | /// | |
29967ef6 | 780 | /// The stabilized version of this intrinsic is [`core::mem::align_of`](crate::mem::align_of). |
dfeec247 | 781 | #[rustc_const_stable(feature = "const_min_align_of", since = "1.40.0")] |
85aaf69f | 782 | pub fn min_align_of<T>() -> usize; |
3dfed10e | 783 | /// The preferred alignment of a type. |
f9f354fc XL |
784 | /// |
785 | /// This intrinsic does not have a stable counterpart. | |
dfeec247 | 786 | #[rustc_const_unstable(feature = "const_pref_align_of", issue = "none")] |
85aaf69f | 787 | pub fn pref_align_of<T>() -> usize; |
1a4d82fc | 788 | |
abe05a73 XL |
789 | /// The size of the referenced value in bytes. |
790 | /// | |
29967ef6 | 791 | /// The stabilized version of this intrinsic is [`mem::size_of_val`]. |
3dfed10e | 792 | #[rustc_const_unstable(feature = "const_size_of_val", issue = "46571")] |
f9f354fc XL |
793 | pub fn size_of_val<T: ?Sized>(_: *const T) -> usize; |
794 | /// The required alignment of the referenced value. | |
ba9703b0 | 795 | /// |
29967ef6 | 796 | /// The stabilized version of this intrinsic is [`core::mem::align_of_val`](crate::mem::align_of_val). |
3dfed10e | 797 | #[rustc_const_unstable(feature = "const_align_of_val", issue = "46571")] |
ba9703b0 XL |
798 | pub fn min_align_of_val<T: ?Sized>(_: *const T) -> usize; |
799 | ||
c34b1796 | 800 | /// Gets a static string slice containing the name of a type. |
74b04a01 | 801 | /// |
29967ef6 | 802 | /// The stabilized version of this intrinsic is [`core::any::type_name`](crate::any::type_name). |
f035d41b | 803 | #[rustc_const_unstable(feature = "const_type_name", issue = "63084")] |
c34b1796 | 804 | pub fn type_name<T: ?Sized>() -> &'static str; |
1a4d82fc JJ |
805 | |
806 | /// Gets an identifier which is globally unique to the specified type. This | |
807 | /// function will return the same value for a type regardless of whichever | |
808 | /// crate it is invoked in. | |
74b04a01 | 809 | /// |
29967ef6 | 810 | /// The stabilized version of this intrinsic is [`core::any::TypeId::of`](crate::any::TypeId::of). |
6c58768f | 811 | #[rustc_const_unstable(feature = "const_type_id", issue = "77125")] |
85aaf69f | 812 | pub fn type_id<T: ?Sized + 'static>() -> u64; |
1a4d82fc | 813 | |
0731742a XL |
814 | /// A guard for unsafe functions that cannot ever be executed if `T` is uninhabited: |
815 | /// This will statically either panic, or do nothing. | |
f9f354fc XL |
816 | /// |
817 | /// This intrinsic does not have a stable counterpart. | |
fc512014 | 818 | #[rustc_const_unstable(feature = "const_assert_type", issue = "none")] |
ba9703b0 XL |
819 | pub fn assert_inhabited<T>(); |
820 | ||
821 | /// A guard for unsafe functions that cannot ever be executed if `T` does not permit | |
822 | /// zero-initialization: This will statically either panic, or do nothing. | |
f9f354fc XL |
823 | /// |
824 | /// This intrinsic does not have a stable counterpart. | |
ba9703b0 XL |
825 | pub fn assert_zero_valid<T>(); |
826 | ||
827 | /// A guard for unsafe functions that cannot ever be executed if `T` has invalid | |
828 | /// bit patterns: This will statically either panic, or do nothing. | |
f9f354fc XL |
829 | /// |
830 | /// This intrinsic does not have a stable counterpart. | |
ba9703b0 XL |
831 | pub fn assert_uninit_valid<T>(); |
832 | ||
e74abb32 | 833 | /// Gets a reference to a static `Location` indicating where it was called. |
f9f354fc | 834 | /// |
29967ef6 | 835 | /// Consider using [`core::panic::Location::caller`](crate::panic::Location::caller) instead. |
1b1a35ee | 836 | #[rustc_const_unstable(feature = "const_caller_location", issue = "76156")] |
e74abb32 XL |
837 | pub fn caller_location() -> &'static crate::panic::Location<'static>; |
838 | ||
a1dfa0c6 | 839 | /// Moves a value out of scope without running drop glue. |
f9f354fc | 840 | /// |
3dfed10e XL |
841 | /// This exists solely for [`mem::forget_unsized`]; normal `forget` uses |
842 | /// `ManuallyDrop` instead. | |
a1dfa0c6 XL |
843 | pub fn forget<T: ?Sized>(_: T); |
844 | ||
9e0c209e SL |
845 | /// Reinterprets the bits of a value of one type as another type. |
846 | /// | |
847 | /// Both types must have the same size. Neither the original, nor the result, | |
94b46f34 | 848 | /// may be an [invalid value](../../nomicon/what-unsafe-does.html). |
1a4d82fc | 849 | /// |
5bcae85e | 850 | /// `transmute` is semantically equivalent to a bitwise move of one type |
9e0c209e SL |
851 | /// into another. It copies the bits from the source value into the |
852 | /// destination value, then forgets the original. It's equivalent to C's | |
853 | /// `memcpy` under the hood, just like `transmute_copy`. | |
5bcae85e | 854 | /// |
9e0c209e SL |
855 | /// `transmute` is **incredibly** unsafe. There are a vast number of ways to |
856 | /// cause [undefined behavior][ub] with this function. `transmute` should be | |
5bcae85e SL |
857 | /// the absolute last resort. |
858 | /// | |
859 | /// The [nomicon](../../nomicon/transmutes.html) has additional | |
860 | /// documentation. | |
1a4d82fc | 861 | /// |
8bb4bdeb | 862 | /// [ub]: ../../reference/behavior-considered-undefined.html |
9e0c209e | 863 | /// |
1a4d82fc JJ |
864 | /// # Examples |
865 | /// | |
5bcae85e SL |
866 | /// There are a few things that `transmute` is really useful for. |
867 | /// | |
9e0c209e SL |
868 | /// Turning a pointer into a function pointer. This is *not* portable to |
869 | /// machines where function pointers and data pointers have different sizes. | |
5bcae85e SL |
870 | /// |
871 | /// ``` | |
872 | /// fn foo() -> i32 { | |
873 | /// 0 | |
874 | /// } | |
875 | /// let pointer = foo as *const (); | |
876 | /// let function = unsafe { | |
877 | /// std::mem::transmute::<*const (), fn() -> i32>(pointer) | |
878 | /// }; | |
879 | /// assert_eq!(function(), 0); | |
880 | /// ``` | |
881 | /// | |
9e0c209e SL |
882 | /// Extending a lifetime, or shortening an invariant lifetime. This is |
883 | /// advanced, very unsafe Rust! | |
5bcae85e SL |
884 | /// |
885 | /// ``` | |
886 | /// struct R<'a>(&'a i32); | |
887 | /// unsafe fn extend_lifetime<'b>(r: R<'b>) -> R<'static> { | |
888 | /// std::mem::transmute::<R<'b>, R<'static>>(r) | |
889 | /// } | |
890 | /// | |
891 | /// unsafe fn shorten_invariant_lifetime<'b, 'c>(r: &'b mut R<'static>) | |
892 | /// -> &'b mut R<'c> { | |
893 | /// std::mem::transmute::<&'b mut R<'static>, &'b mut R<'c>>(r) | |
894 | /// } | |
895 | /// ``` | |
896 | /// | |
897 | /// # Alternatives | |
898 | /// | |
9e0c209e SL |
899 | /// Don't despair: many uses of `transmute` can be achieved through other means. |
900 | /// Below are common applications of `transmute` which can be replaced with safer | |
901 | /// constructs. | |
5bcae85e | 902 | /// |
ba9703b0 XL |
903 | /// Turning raw bytes(`&[u8]`) to `u32`, `f64`, etc.: |
904 | /// | |
905 | /// ``` | |
906 | /// let raw_bytes = [0x78, 0x56, 0x34, 0x12]; | |
907 | /// | |
908 | /// let num = unsafe { | |
1b1a35ee | 909 | /// std::mem::transmute::<[u8; 4], u32>(raw_bytes) |
ba9703b0 XL |
910 | /// }; |
911 | /// | |
912 | /// // use `u32::from_ne_bytes` instead | |
913 | /// let num = u32::from_ne_bytes(raw_bytes); | |
3dfed10e | 914 | /// // or use `u32::from_le_bytes` or `u32::from_be_bytes` to specify the endianness |
ba9703b0 XL |
915 | /// let num = u32::from_le_bytes(raw_bytes); |
916 | /// assert_eq!(num, 0x12345678); | |
917 | /// let num = u32::from_be_bytes(raw_bytes); | |
918 | /// assert_eq!(num, 0x78563412); | |
919 | /// ``` | |
920 | /// | |
5bcae85e SL |
921 | /// Turning a pointer into a `usize`: |
922 | /// | |
923 | /// ``` | |
924 | /// let ptr = &0; | |
925 | /// let ptr_num_transmute = unsafe { | |
926 | /// std::mem::transmute::<&i32, usize>(ptr) | |
927 | /// }; | |
9e0c209e | 928 | /// |
5bcae85e SL |
929 | /// // Use an `as` cast instead |
930 | /// let ptr_num_cast = ptr as *const i32 as usize; | |
931 | /// ``` | |
932 | /// | |
933 | /// Turning a `*mut T` into an `&mut T`: | |
934 | /// | |
935 | /// ``` | |
936 | /// let ptr: *mut i32 = &mut 0; | |
937 | /// let ref_transmuted = unsafe { | |
938 | /// std::mem::transmute::<*mut i32, &mut i32>(ptr) | |
939 | /// }; | |
9e0c209e | 940 | /// |
5bcae85e SL |
941 | /// // Use a reborrow instead |
942 | /// let ref_casted = unsafe { &mut *ptr }; | |
943 | /// ``` | |
944 | /// | |
945 | /// Turning an `&mut T` into an `&mut U`: | |
946 | /// | |
947 | /// ``` | |
948 | /// let ptr = &mut 0; | |
949 | /// let val_transmuted = unsafe { | |
950 | /// std::mem::transmute::<&mut i32, &mut u32>(ptr) | |
951 | /// }; | |
9e0c209e | 952 | /// |
5bcae85e SL |
953 | /// // Now, put together `as` and reborrowing - note the chaining of `as` |
954 | /// // `as` is not transitive | |
955 | /// let val_casts = unsafe { &mut *(ptr as *mut i32 as *mut u32) }; | |
956 | /// ``` | |
957 | /// | |
958 | /// Turning an `&str` into an `&[u8]`: | |
959 | /// | |
960 | /// ``` | |
961 | /// // this is not a good way to do this. | |
962 | /// let slice = unsafe { std::mem::transmute::<&str, &[u8]>("Rust") }; | |
963 | /// assert_eq!(slice, &[82, 117, 115, 116]); | |
9e0c209e | 964 | /// |
5bcae85e SL |
965 | /// // You could use `str::as_bytes` |
966 | /// let slice = "Rust".as_bytes(); | |
967 | /// assert_eq!(slice, &[82, 117, 115, 116]); | |
9e0c209e | 968 | /// |
5bcae85e SL |
969 | /// // Or, just use a byte string, if you have control over the string |
970 | /// // literal | |
971 | /// assert_eq!(b"Rust", &[82, 117, 115, 116]); | |
972 | /// ``` | |
973 | /// | |
974 | /// Turning a `Vec<&T>` into a `Vec<Option<&T>>`: | |
975 | /// | |
85aaf69f | 976 | /// ``` |
5bcae85e | 977 | /// let store = [0, 1, 2, 3]; |
e1599b0c XL |
978 | /// let v_orig = store.iter().collect::<Vec<&i32>>(); |
979 | /// | |
980 | /// // clone the vector as we will reuse them later | |
981 | /// let v_clone = v_orig.clone(); | |
9e0c209e | 982 | /// |
74b04a01 XL |
983 | /// // Using transmute: this relies on the unspecified data layout of `Vec`, which is a |
984 | /// // bad idea and could cause Undefined Behavior. | |
5bcae85e SL |
985 | /// // However, it is no-copy. |
986 | /// let v_transmuted = unsafe { | |
e1599b0c | 987 | /// std::mem::transmute::<Vec<&i32>, Vec<Option<&i32>>>(v_clone) |
5bcae85e | 988 | /// }; |
9e0c209e | 989 | /// |
e1599b0c XL |
990 | /// let v_clone = v_orig.clone(); |
991 | /// | |
5bcae85e | 992 | /// // This is the suggested, safe way. |
9e0c209e | 993 | /// // It does copy the entire vector, though, into a new array. |
e1599b0c XL |
994 | /// let v_collected = v_clone.into_iter() |
995 | /// .map(Some) | |
996 | /// .collect::<Vec<Option<&i32>>>(); | |
997 | /// | |
998 | /// let v_clone = v_orig.clone(); | |
9e0c209e | 999 | /// |
74b04a01 XL |
1000 | /// // The no-copy, unsafe way, still using transmute, but not relying on the data layout. |
1001 | /// // Like the first approach, this reuses the `Vec` internals. | |
1002 | /// // Therefore, the new inner type must have the | |
1003 | /// // exact same size, *and the same alignment*, as the old type. | |
ea8adc8c | 1004 | /// // The same caveats exist for this method as transmute, for |
5bcae85e | 1005 | /// // the original inner type (`&i32`) to the converted inner type |
74b04a01 XL |
1006 | /// // (`Option<&i32>`), so read the nomicon pages linked above and also |
1007 | /// // consult the [`from_raw_parts`] documentation. | |
5bcae85e | 1008 | /// let v_from_raw = unsafe { |
e74abb32 | 1009 | // FIXME Update this when vec_into_raw_parts is stabilized |
e1599b0c XL |
1010 | /// // Ensure the original vector is not dropped. |
1011 | /// let mut v_clone = std::mem::ManuallyDrop::new(v_clone); | |
1012 | /// Vec::from_raw_parts(v_clone.as_mut_ptr() as *mut Option<&i32>, | |
1013 | /// v_clone.len(), | |
1014 | /// v_clone.capacity()) | |
5bcae85e | 1015 | /// }; |
5bcae85e SL |
1016 | /// ``` |
1017 | /// | |
74b04a01 XL |
1018 | /// [`from_raw_parts`]: ../../std/vec/struct.Vec.html#method.from_raw_parts |
1019 | /// | |
5bcae85e | 1020 | /// Implementing `split_at_mut`: |
1a4d82fc | 1021 | /// |
5bcae85e SL |
1022 | /// ``` |
1023 | /// use std::{slice, mem}; | |
9e0c209e | 1024 | /// |
9fa01778 XL |
1025 | /// // There are multiple ways to do this, and there are multiple problems |
1026 | /// // with the following (transmute) way. | |
5bcae85e SL |
1027 | /// fn split_at_mut_transmute<T>(slice: &mut [T], mid: usize) |
1028 | /// -> (&mut [T], &mut [T]) { | |
1029 | /// let len = slice.len(); | |
1030 | /// assert!(mid <= len); | |
1031 | /// unsafe { | |
1032 | /// let slice2 = mem::transmute::<&mut [T], &mut [T]>(slice); | |
3dfed10e | 1033 | /// // first: transmute is not type safe; all it checks is that T and |
5bcae85e SL |
1034 | /// // U are of the same size. Second, right here, you have two |
1035 | /// // mutable references pointing to the same memory. | |
1036 | /// (&mut slice[0..mid], &mut slice2[mid..len]) | |
1037 | /// } | |
1038 | /// } | |
9e0c209e | 1039 | /// |
3dfed10e | 1040 | /// // This gets rid of the type safety problems; `&mut *` will *only* give |
5bcae85e SL |
1041 | /// // you an `&mut T` from an `&mut T` or `*mut T`. |
1042 | /// fn split_at_mut_casts<T>(slice: &mut [T], mid: usize) | |
1043 | /// -> (&mut [T], &mut [T]) { | |
1044 | /// let len = slice.len(); | |
1045 | /// assert!(mid <= len); | |
1046 | /// unsafe { | |
1047 | /// let slice2 = &mut *(slice as *mut [T]); | |
1048 | /// // however, you still have two mutable references pointing to | |
1049 | /// // the same memory. | |
1050 | /// (&mut slice[0..mid], &mut slice2[mid..len]) | |
1051 | /// } | |
1052 | /// } | |
9e0c209e | 1053 | /// |
5bcae85e SL |
1054 | /// // This is how the standard library does it. This is the best method, if |
1055 | /// // you need to do something like this | |
1056 | /// fn split_at_stdlib<T>(slice: &mut [T], mid: usize) | |
1057 | /// -> (&mut [T], &mut [T]) { | |
1058 | /// let len = slice.len(); | |
1059 | /// assert!(mid <= len); | |
1060 | /// unsafe { | |
1061 | /// let ptr = slice.as_mut_ptr(); | |
1062 | /// // This now has three mutable references pointing at the same | |
1063 | /// // memory. `slice`, the rvalue ret.0, and the rvalue ret.1. | |
1064 | /// // `slice` is never used after `let ptr = ...`, and so one can | |
1065 | /// // treat it as "dead", and therefore, you only have two real | |
1066 | /// // mutable slices. | |
1067 | /// (slice::from_raw_parts_mut(ptr, mid), | |
b7449926 | 1068 | /// slice::from_raw_parts_mut(ptr.add(mid), len - mid)) |
5bcae85e SL |
1069 | /// } |
1070 | /// } | |
1a4d82fc | 1071 | /// ``` |
85aaf69f | 1072 | #[stable(feature = "rust1", since = "1.0.0")] |
f035d41b XL |
1073 | // NOTE: While this makes the intrinsic const stable, we have some custom code in const fn |
1074 | // checks that prevent its use within `const fn`. | |
3dfed10e | 1075 | #[rustc_const_stable(feature = "const_transmute", since = "1.46.0")] |
29967ef6 | 1076 | #[rustc_diagnostic_item = "transmute"] |
e9174d1e | 1077 | pub fn transmute<T, U>(e: T) -> U; |
1a4d82fc | 1078 | |
c34b1796 AL |
1079 | /// Returns `true` if the actual type given as `T` requires drop |
1080 | /// glue; returns `false` if the actual type provided for `T` | |
1081 | /// implements `Copy`. | |
1082 | /// | |
1083 | /// If the actual type neither requires drop glue nor implements | |
f035d41b | 1084 | /// `Copy`, then the return value of this function is unspecified. |
abe05a73 | 1085 | /// |
29967ef6 | 1086 | /// The stabilized version of this intrinsic is [`mem::needs_drop`](crate::mem::needs_drop). |
dfeec247 | 1087 | #[rustc_const_stable(feature = "const_needs_drop", since = "1.40.0")] |
1a4d82fc JJ |
1088 | pub fn needs_drop<T>() -> bool; |
1089 | ||
d9579d0f | 1090 | /// Calculates the offset from a pointer. |
1a4d82fc JJ |
1091 | /// |
1092 | /// This is implemented as an intrinsic to avoid converting to and from an | |
1093 | /// integer, since the conversion would throw away aliasing information. | |
d9579d0f AL |
1094 | /// |
1095 | /// # Safety | |
1096 | /// | |
1097 | /// Both the starting and resulting pointer must be either in bounds or one | |
1098 | /// byte past the end of an allocated object. If either pointer is out of | |
1099 | /// bounds or arithmetic overflow occurs then any further use of the | |
1100 | /// returned value will result in undefined behavior. | |
74b04a01 XL |
1101 | /// |
1102 | /// The stabilized version of this intrinsic is | |
1103 | /// [`std::pointer::offset`](../../std/primitive.pointer.html#method.offset). | |
f9f354fc XL |
1104 | #[must_use = "returns a new pointer rather than modifying its argument"] |
1105 | #[rustc_const_unstable(feature = "const_ptr_offset", issue = "71499")] | |
85aaf69f | 1106 | pub fn offset<T>(dst: *const T, offset: isize) -> *const T; |
1a4d82fc | 1107 | |
62682a34 SL |
1108 | /// Calculates the offset from a pointer, potentially wrapping. |
1109 | /// | |
1110 | /// This is implemented as an intrinsic to avoid converting to and from an | |
1111 | /// integer, since the conversion inhibits certain optimizations. | |
1112 | /// | |
1113 | /// # Safety | |
1114 | /// | |
1115 | /// Unlike the `offset` intrinsic, this intrinsic does not restrict the | |
1116 | /// resulting pointer to point into or one byte past the end of an allocated | |
1117 | /// object, and it wraps with two's complement arithmetic. The resulting | |
1118 | /// value is not necessarily valid to be used to actually access memory. | |
74b04a01 XL |
1119 | /// |
1120 | /// The stabilized version of this intrinsic is | |
1121 | /// [`std::pointer::wrapping_offset`](../../std/primitive.pointer.html#method.wrapping_offset). | |
f9f354fc XL |
1122 | #[must_use = "returns a new pointer rather than modifying its argument"] |
1123 | #[rustc_const_unstable(feature = "const_ptr_offset", issue = "71499")] | |
62682a34 SL |
1124 | pub fn arith_offset<T>(dst: *const T, offset: isize) -> *const T; |
1125 | ||
1a4d82fc JJ |
1126 | /// Equivalent to the appropriate `llvm.memcpy.p0i8.0i8.*` intrinsic, with |
1127 | /// a size of `count` * `size_of::<T>()` and an alignment of | |
1128 | /// `min_align_of::<T>()` | |
1129 | /// | |
3b2f2976 XL |
1130 | /// The volatile parameter is set to `true`, so it will not be optimized out |
1131 | /// unless size is equal to zero. | |
f9f354fc XL |
1132 | /// |
1133 | /// This intrinsic does not have a stable counterpart. | |
dfeec247 | 1134 | pub fn volatile_copy_nonoverlapping_memory<T>(dst: *mut T, src: *const T, count: usize); |
1a4d82fc JJ |
1135 | /// Equivalent to the appropriate `llvm.memmove.p0i8.0i8.*` intrinsic, with |
1136 | /// a size of `count` * `size_of::<T>()` and an alignment of | |
1137 | /// `min_align_of::<T>()` | |
1138 | /// | |
3b2f2976 | 1139 | /// The volatile parameter is set to `true`, so it will not be optimized out |
0bf4aa26 | 1140 | /// unless size is equal to zero. |
f9f354fc XL |
1141 | /// |
1142 | /// This intrinsic does not have a stable counterpart. | |
85aaf69f | 1143 | pub fn volatile_copy_memory<T>(dst: *mut T, src: *const T, count: usize); |
1a4d82fc JJ |
1144 | /// Equivalent to the appropriate `llvm.memset.p0i8.*` intrinsic, with a |
1145 | /// size of `count` * `size_of::<T>()` and an alignment of | |
1146 | /// `min_align_of::<T>()`. | |
1147 | /// | |
3b2f2976 XL |
1148 | /// The volatile parameter is set to `true`, so it will not be optimized out |
1149 | /// unless size is equal to zero. | |
f9f354fc XL |
1150 | /// |
1151 | /// This intrinsic does not have a stable counterpart. | |
85aaf69f | 1152 | pub fn volatile_set_memory<T>(dst: *mut T, val: u8, count: usize); |
1a4d82fc | 1153 | |
9fa01778 | 1154 | /// Performs a volatile load from the `src` pointer. |
74b04a01 | 1155 | /// |
29967ef6 | 1156 | /// The stabilized version of this intrinsic is [`core::ptr::read_volatile`](crate::ptr::read_volatile). |
1a4d82fc | 1157 | pub fn volatile_load<T>(src: *const T) -> T; |
9fa01778 | 1158 | /// Performs a volatile store to the `dst` pointer. |
74b04a01 | 1159 | /// |
29967ef6 | 1160 | /// The stabilized version of this intrinsic is [`core::ptr::write_volatile`](crate::ptr::write_volatile). |
1a4d82fc JJ |
1161 | pub fn volatile_store<T>(dst: *mut T, val: T); |
1162 | ||
9fa01778 | 1163 | /// Performs a volatile load from the `src` pointer |
8faf50e0 | 1164 | /// The pointer is not required to be aligned. |
f9f354fc XL |
1165 | /// |
1166 | /// This intrinsic does not have a stable counterpart. | |
8faf50e0 | 1167 | pub fn unaligned_volatile_load<T>(src: *const T) -> T; |
9fa01778 | 1168 | /// Performs a volatile store to the `dst` pointer. |
8faf50e0 | 1169 | /// The pointer is not required to be aligned. |
f9f354fc XL |
1170 | /// |
1171 | /// This intrinsic does not have a stable counterpart. | |
8faf50e0 XL |
1172 | pub fn unaligned_volatile_store<T>(dst: *mut T, val: T); |
1173 | ||
1a4d82fc | 1174 | /// Returns the square root of an `f32` |
74b04a01 XL |
1175 | /// |
1176 | /// The stabilized version of this intrinsic is | |
fc512014 | 1177 | /// [`f32::sqrt`](../../std/primitive.f32.html#method.sqrt) |
1a4d82fc JJ |
1178 | pub fn sqrtf32(x: f32) -> f32; |
1179 | /// Returns the square root of an `f64` | |
74b04a01 XL |
1180 | /// |
1181 | /// The stabilized version of this intrinsic is | |
fc512014 | 1182 | /// [`f64::sqrt`](../../std/primitive.f64.html#method.sqrt) |
1a4d82fc JJ |
1183 | pub fn sqrtf64(x: f64) -> f64; |
1184 | ||
1185 | /// Raises an `f32` to an integer power. | |
74b04a01 XL |
1186 | /// |
1187 | /// The stabilized version of this intrinsic is | |
fc512014 | 1188 | /// [`f32::powi`](../../std/primitive.f32.html#method.powi) |
1a4d82fc JJ |
1189 | pub fn powif32(a: f32, x: i32) -> f32; |
1190 | /// Raises an `f64` to an integer power. | |
74b04a01 XL |
1191 | /// |
1192 | /// The stabilized version of this intrinsic is | |
fc512014 | 1193 | /// [`f64::powi`](../../std/primitive.f64.html#method.powi) |
1a4d82fc JJ |
1194 | pub fn powif64(a: f64, x: i32) -> f64; |
1195 | ||
1196 | /// Returns the sine of an `f32`. | |
74b04a01 XL |
1197 | /// |
1198 | /// The stabilized version of this intrinsic is | |
fc512014 | 1199 | /// [`f32::sin`](../../std/primitive.f32.html#method.sin) |
1a4d82fc JJ |
1200 | pub fn sinf32(x: f32) -> f32; |
1201 | /// Returns the sine of an `f64`. | |
74b04a01 XL |
1202 | /// |
1203 | /// The stabilized version of this intrinsic is | |
fc512014 | 1204 | /// [`f64::sin`](../../std/primitive.f64.html#method.sin) |
1a4d82fc JJ |
1205 | pub fn sinf64(x: f64) -> f64; |
1206 | ||
1207 | /// Returns the cosine of an `f32`. | |
74b04a01 XL |
1208 | /// |
1209 | /// The stabilized version of this intrinsic is | |
fc512014 | 1210 | /// [`f32::cos`](../../std/primitive.f32.html#method.cos) |
1a4d82fc JJ |
1211 | pub fn cosf32(x: f32) -> f32; |
1212 | /// Returns the cosine of an `f64`. | |
74b04a01 XL |
1213 | /// |
1214 | /// The stabilized version of this intrinsic is | |
fc512014 | 1215 | /// [`f64::cos`](../../std/primitive.f64.html#method.cos) |
1a4d82fc JJ |
1216 | pub fn cosf64(x: f64) -> f64; |
1217 | ||
1218 | /// Raises an `f32` to an `f32` power. | |
74b04a01 XL |
1219 | /// |
1220 | /// The stabilized version of this intrinsic is | |
fc512014 | 1221 | /// [`f32::powf`](../../std/primitive.f32.html#method.powf) |
1a4d82fc JJ |
1222 | pub fn powf32(a: f32, x: f32) -> f32; |
1223 | /// Raises an `f64` to an `f64` power. | |
74b04a01 XL |
1224 | /// |
1225 | /// The stabilized version of this intrinsic is | |
fc512014 | 1226 | /// [`f64::powf`](../../std/primitive.f64.html#method.powf) |
1a4d82fc JJ |
1227 | pub fn powf64(a: f64, x: f64) -> f64; |
1228 | ||
1229 | /// Returns the exponential of an `f32`. | |
74b04a01 XL |
1230 | /// |
1231 | /// The stabilized version of this intrinsic is | |
fc512014 | 1232 | /// [`f32::exp`](../../std/primitive.f32.html#method.exp) |
1a4d82fc JJ |
1233 | pub fn expf32(x: f32) -> f32; |
1234 | /// Returns the exponential of an `f64`. | |
74b04a01 XL |
1235 | /// |
1236 | /// The stabilized version of this intrinsic is | |
fc512014 | 1237 | /// [`f64::exp`](../../std/primitive.f64.html#method.exp) |
1a4d82fc JJ |
1238 | pub fn expf64(x: f64) -> f64; |
1239 | ||
1240 | /// Returns 2 raised to the power of an `f32`. | |
74b04a01 XL |
1241 | /// |
1242 | /// The stabilized version of this intrinsic is | |
fc512014 | 1243 | /// [`f32::exp2`](../../std/primitive.f32.html#method.exp2) |
1a4d82fc JJ |
1244 | pub fn exp2f32(x: f32) -> f32; |
1245 | /// Returns 2 raised to the power of an `f64`. | |
74b04a01 XL |
1246 | /// |
1247 | /// The stabilized version of this intrinsic is | |
fc512014 | 1248 | /// [`f64::exp2`](../../std/primitive.f64.html#method.exp2) |
1a4d82fc JJ |
1249 | pub fn exp2f64(x: f64) -> f64; |
1250 | ||
1251 | /// Returns the natural logarithm of an `f32`. | |
74b04a01 XL |
1252 | /// |
1253 | /// The stabilized version of this intrinsic is | |
fc512014 | 1254 | /// [`f32::ln`](../../std/primitive.f32.html#method.ln) |
1a4d82fc JJ |
1255 | pub fn logf32(x: f32) -> f32; |
1256 | /// Returns the natural logarithm of an `f64`. | |
74b04a01 XL |
1257 | /// |
1258 | /// The stabilized version of this intrinsic is | |
fc512014 | 1259 | /// [`f64::ln`](../../std/primitive.f64.html#method.ln) |
1a4d82fc JJ |
1260 | pub fn logf64(x: f64) -> f64; |
1261 | ||
1262 | /// Returns the base 10 logarithm of an `f32`. | |
74b04a01 XL |
1263 | /// |
1264 | /// The stabilized version of this intrinsic is | |
fc512014 | 1265 | /// [`f32::log10`](../../std/primitive.f32.html#method.log10) |
1a4d82fc JJ |
1266 | pub fn log10f32(x: f32) -> f32; |
1267 | /// Returns the base 10 logarithm of an `f64`. | |
74b04a01 XL |
1268 | /// |
1269 | /// The stabilized version of this intrinsic is | |
fc512014 | 1270 | /// [`f64::log10`](../../std/primitive.f64.html#method.log10) |
1a4d82fc JJ |
1271 | pub fn log10f64(x: f64) -> f64; |
1272 | ||
1273 | /// Returns the base 2 logarithm of an `f32`. | |
74b04a01 XL |
1274 | /// |
1275 | /// The stabilized version of this intrinsic is | |
fc512014 | 1276 | /// [`f32::log2`](../../std/primitive.f32.html#method.log2) |
1a4d82fc JJ |
1277 | pub fn log2f32(x: f32) -> f32; |
1278 | /// Returns the base 2 logarithm of an `f64`. | |
74b04a01 XL |
1279 | /// |
1280 | /// The stabilized version of this intrinsic is | |
fc512014 | 1281 | /// [`f64::log2`](../../std/primitive.f64.html#method.log2) |
1a4d82fc JJ |
1282 | pub fn log2f64(x: f64) -> f64; |
1283 | ||
1284 | /// Returns `a * b + c` for `f32` values. | |
74b04a01 XL |
1285 | /// |
1286 | /// The stabilized version of this intrinsic is | |
fc512014 | 1287 | /// [`f32::mul_add`](../../std/primitive.f32.html#method.mul_add) |
1a4d82fc JJ |
1288 | pub fn fmaf32(a: f32, b: f32, c: f32) -> f32; |
1289 | /// Returns `a * b + c` for `f64` values. | |
74b04a01 XL |
1290 | /// |
1291 | /// The stabilized version of this intrinsic is | |
fc512014 | 1292 | /// [`f64::mul_add`](../../std/primitive.f64.html#method.mul_add) |
1a4d82fc JJ |
1293 | pub fn fmaf64(a: f64, b: f64, c: f64) -> f64; |
1294 | ||
1295 | /// Returns the absolute value of an `f32`. | |
74b04a01 XL |
1296 | /// |
1297 | /// The stabilized version of this intrinsic is | |
fc512014 | 1298 | /// [`f32::abs`](../../std/primitive.f32.html#method.abs) |
1a4d82fc JJ |
1299 | pub fn fabsf32(x: f32) -> f32; |
1300 | /// Returns the absolute value of an `f64`. | |
74b04a01 XL |
1301 | /// |
1302 | /// The stabilized version of this intrinsic is | |
fc512014 | 1303 | /// [`f64::abs`](../../std/primitive.f64.html#method.abs) |
1a4d82fc JJ |
1304 | pub fn fabsf64(x: f64) -> f64; |
1305 | ||
dc9dc135 | 1306 | /// Returns the minimum of two `f32` values. |
74b04a01 XL |
1307 | /// |
1308 | /// The stabilized version of this intrinsic is | |
3dfed10e | 1309 | /// [`f32::min`] |
dc9dc135 XL |
1310 | pub fn minnumf32(x: f32, y: f32) -> f32; |
1311 | /// Returns the minimum of two `f64` values. | |
74b04a01 XL |
1312 | /// |
1313 | /// The stabilized version of this intrinsic is | |
3dfed10e | 1314 | /// [`f64::min`] |
dc9dc135 XL |
1315 | pub fn minnumf64(x: f64, y: f64) -> f64; |
1316 | /// Returns the maximum of two `f32` values. | |
74b04a01 XL |
1317 | /// |
1318 | /// The stabilized version of this intrinsic is | |
3dfed10e | 1319 | /// [`f32::max`] |
dc9dc135 XL |
1320 | pub fn maxnumf32(x: f32, y: f32) -> f32; |
1321 | /// Returns the maximum of two `f64` values. | |
74b04a01 XL |
1322 | /// |
1323 | /// The stabilized version of this intrinsic is | |
3dfed10e | 1324 | /// [`f64::max`] |
dc9dc135 XL |
1325 | pub fn maxnumf64(x: f64, y: f64) -> f64; |
1326 | ||
1a4d82fc | 1327 | /// Copies the sign from `y` to `x` for `f32` values. |
74b04a01 XL |
1328 | /// |
1329 | /// The stabilized version of this intrinsic is | |
fc512014 | 1330 | /// [`f32::copysign`](../../std/primitive.f32.html#method.copysign) |
1a4d82fc JJ |
1331 | pub fn copysignf32(x: f32, y: f32) -> f32; |
1332 | /// Copies the sign from `y` to `x` for `f64` values. | |
74b04a01 XL |
1333 | /// |
1334 | /// The stabilized version of this intrinsic is | |
fc512014 | 1335 | /// [`f64::copysign`](../../std/primitive.f64.html#method.copysign) |
1a4d82fc JJ |
1336 | pub fn copysignf64(x: f64, y: f64) -> f64; |
1337 | ||
1338 | /// Returns the largest integer less than or equal to an `f32`. | |
74b04a01 XL |
1339 | /// |
1340 | /// The stabilized version of this intrinsic is | |
fc512014 | 1341 | /// [`f32::floor`](../../std/primitive.f32.html#method.floor) |
1a4d82fc JJ |
1342 | pub fn floorf32(x: f32) -> f32; |
1343 | /// Returns the largest integer less than or equal to an `f64`. | |
74b04a01 XL |
1344 | /// |
1345 | /// The stabilized version of this intrinsic is | |
fc512014 | 1346 | /// [`f64::floor`](../../std/primitive.f64.html#method.floor) |
1a4d82fc JJ |
1347 | pub fn floorf64(x: f64) -> f64; |
1348 | ||
1349 | /// Returns the smallest integer greater than or equal to an `f32`. | |
74b04a01 XL |
1350 | /// |
1351 | /// The stabilized version of this intrinsic is | |
fc512014 | 1352 | /// [`f32::ceil`](../../std/primitive.f32.html#method.ceil) |
1a4d82fc JJ |
1353 | pub fn ceilf32(x: f32) -> f32; |
1354 | /// Returns the smallest integer greater than or equal to an `f64`. | |
74b04a01 XL |
1355 | /// |
1356 | /// The stabilized version of this intrinsic is | |
fc512014 | 1357 | /// [`f64::ceil`](../../std/primitive.f64.html#method.ceil) |
1a4d82fc JJ |
1358 | pub fn ceilf64(x: f64) -> f64; |
1359 | ||
1360 | /// Returns the integer part of an `f32`. | |
74b04a01 XL |
1361 | /// |
1362 | /// The stabilized version of this intrinsic is | |
fc512014 | 1363 | /// [`f32::trunc`](../../std/primitive.f32.html#method.trunc) |
1a4d82fc JJ |
1364 | pub fn truncf32(x: f32) -> f32; |
1365 | /// Returns the integer part of an `f64`. | |
74b04a01 XL |
1366 | /// |
1367 | /// The stabilized version of this intrinsic is | |
fc512014 | 1368 | /// [`f64::trunc`](../../std/primitive.f64.html#method.trunc) |
1a4d82fc JJ |
1369 | pub fn truncf64(x: f64) -> f64; |
1370 | ||
1371 | /// Returns the nearest integer to an `f32`. May raise an inexact floating-point exception | |
1372 | /// if the argument is not an integer. | |
1373 | pub fn rintf32(x: f32) -> f32; | |
1374 | /// Returns the nearest integer to an `f64`. May raise an inexact floating-point exception | |
1375 | /// if the argument is not an integer. | |
1376 | pub fn rintf64(x: f64) -> f64; | |
1377 | ||
1378 | /// Returns the nearest integer to an `f32`. | |
f9f354fc XL |
1379 | /// |
1380 | /// This intrinsic does not have a stable counterpart. | |
1a4d82fc JJ |
1381 | pub fn nearbyintf32(x: f32) -> f32; |
1382 | /// Returns the nearest integer to an `f64`. | |
f9f354fc XL |
1383 | /// |
1384 | /// This intrinsic does not have a stable counterpart. | |
1a4d82fc JJ |
1385 | pub fn nearbyintf64(x: f64) -> f64; |
1386 | ||
1387 | /// Returns the nearest integer to an `f32`. Rounds half-way cases away from zero. | |
74b04a01 XL |
1388 | /// |
1389 | /// The stabilized version of this intrinsic is | |
fc512014 | 1390 | /// [`f32::round`](../../std/primitive.f32.html#method.round) |
1a4d82fc JJ |
1391 | pub fn roundf32(x: f32) -> f32; |
1392 | /// Returns the nearest integer to an `f64`. Rounds half-way cases away from zero. | |
74b04a01 XL |
1393 | /// |
1394 | /// The stabilized version of this intrinsic is | |
fc512014 | 1395 | /// [`f64::round`](../../std/primitive.f64.html#method.round) |
1a4d82fc JJ |
1396 | pub fn roundf64(x: f64) -> f64; |
1397 | ||
54a0048b SL |
1398 | /// Float addition that allows optimizations based on algebraic rules. |
1399 | /// May assume inputs are finite. | |
f9f354fc XL |
1400 | /// |
1401 | /// This intrinsic does not have a stable counterpart. | |
ba9703b0 | 1402 | pub fn fadd_fast<T: Copy>(a: T, b: T) -> T; |
54a0048b SL |
1403 | |
1404 | /// Float subtraction that allows optimizations based on algebraic rules. | |
1405 | /// May assume inputs are finite. | |
f9f354fc XL |
1406 | /// |
1407 | /// This intrinsic does not have a stable counterpart. | |
ba9703b0 | 1408 | pub fn fsub_fast<T: Copy>(a: T, b: T) -> T; |
54a0048b SL |
1409 | |
1410 | /// Float multiplication that allows optimizations based on algebraic rules. | |
1411 | /// May assume inputs are finite. | |
f9f354fc XL |
1412 | /// |
1413 | /// This intrinsic does not have a stable counterpart. | |
ba9703b0 | 1414 | pub fn fmul_fast<T: Copy>(a: T, b: T) -> T; |
54a0048b SL |
1415 | |
1416 | /// Float division that allows optimizations based on algebraic rules. | |
1417 | /// May assume inputs are finite. | |
f9f354fc XL |
1418 | /// |
1419 | /// This intrinsic does not have a stable counterpart. | |
ba9703b0 | 1420 | pub fn fdiv_fast<T: Copy>(a: T, b: T) -> T; |
54a0048b SL |
1421 | |
1422 | /// Float remainder that allows optimizations based on algebraic rules. | |
1423 | /// May assume inputs are finite. | |
f9f354fc XL |
1424 | /// |
1425 | /// This intrinsic does not have a stable counterpart. | |
ba9703b0 | 1426 | pub fn frem_fast<T: Copy>(a: T, b: T) -> T; |
54a0048b | 1427 | |
ba9703b0 XL |
1428 | /// Convert with LLVM’s fptoui/fptosi, which may return undef for values out of range |
1429 | /// (<https://github.com/rust-lang/rust/issues/10184>) | |
1430 | /// | |
3dfed10e | 1431 | /// Stabilized as [`f32::to_int_unchecked`] and [`f64::to_int_unchecked`]. |
ba9703b0 | 1432 | pub fn float_to_int_unchecked<Float: Copy, Int: Copy>(value: Float) -> Int; |
60c5eb7d | 1433 | |
92a42be0 | 1434 | /// Returns the number of bits set in an integer type `T` |
74b04a01 XL |
1435 | /// |
1436 | /// The stabilized versions of this intrinsic are available on the integer | |
1437 | /// primitives via the `count_ones` method. For example, | |
3dfed10e | 1438 | /// [`u32::count_ones`] |
dfeec247 | 1439 | #[rustc_const_stable(feature = "const_ctpop", since = "1.40.0")] |
ba9703b0 | 1440 | pub fn ctpop<T: Copy>(x: T) -> T; |
1a4d82fc | 1441 | |
32a655c1 SL |
1442 | /// Returns the number of leading unset bits (zeroes) in an integer type `T`. |
1443 | /// | |
74b04a01 XL |
1444 | /// The stabilized versions of this intrinsic are available on the integer |
1445 | /// primitives via the `leading_zeros` method. For example, | |
3dfed10e | 1446 | /// [`u32::leading_zeros`] |
74b04a01 | 1447 | /// |
32a655c1 SL |
1448 | /// # Examples |
1449 | /// | |
1450 | /// ``` | |
1451 | /// #![feature(core_intrinsics)] | |
1452 | /// | |
1453 | /// use std::intrinsics::ctlz; | |
1454 | /// | |
1455 | /// let x = 0b0001_1100_u8; | |
0731742a | 1456 | /// let num_leading = ctlz(x); |
32a655c1 SL |
1457 | /// assert_eq!(num_leading, 3); |
1458 | /// ``` | |
1459 | /// | |
1460 | /// An `x` with value `0` will return the bit width of `T`. | |
1461 | /// | |
1462 | /// ``` | |
1463 | /// #![feature(core_intrinsics)] | |
1464 | /// | |
1465 | /// use std::intrinsics::ctlz; | |
1466 | /// | |
1467 | /// let x = 0u16; | |
0731742a | 1468 | /// let num_leading = ctlz(x); |
32a655c1 SL |
1469 | /// assert_eq!(num_leading, 16); |
1470 | /// ``` | |
dfeec247 | 1471 | #[rustc_const_stable(feature = "const_ctlz", since = "1.40.0")] |
ba9703b0 | 1472 | pub fn ctlz<T: Copy>(x: T) -> T; |
1a4d82fc | 1473 | |
041b39d2 XL |
1474 | /// Like `ctlz`, but extra-unsafe as it returns `undef` when |
1475 | /// given an `x` with value `0`. | |
1476 | /// | |
f9f354fc XL |
1477 | /// This intrinsic does not have a stable counterpart. |
1478 | /// | |
041b39d2 XL |
1479 | /// # Examples |
1480 | /// | |
1481 | /// ``` | |
1482 | /// #![feature(core_intrinsics)] | |
1483 | /// | |
1484 | /// use std::intrinsics::ctlz_nonzero; | |
1485 | /// | |
1486 | /// let x = 0b0001_1100_u8; | |
1487 | /// let num_leading = unsafe { ctlz_nonzero(x) }; | |
1488 | /// assert_eq!(num_leading, 3); | |
1489 | /// ``` | |
fc512014 | 1490 | #[rustc_const_stable(feature = "constctlz", since = "1.50.0")] |
ba9703b0 | 1491 | pub fn ctlz_nonzero<T: Copy>(x: T) -> T; |
041b39d2 | 1492 | |
32a655c1 SL |
1493 | /// Returns the number of trailing unset bits (zeroes) in an integer type `T`. |
1494 | /// | |
74b04a01 XL |
1495 | /// The stabilized versions of this intrinsic are available on the integer |
1496 | /// primitives via the `trailing_zeros` method. For example, | |
3dfed10e | 1497 | /// [`u32::trailing_zeros`] |
74b04a01 | 1498 | /// |
32a655c1 SL |
1499 | /// # Examples |
1500 | /// | |
1501 | /// ``` | |
1502 | /// #![feature(core_intrinsics)] | |
1503 | /// | |
1504 | /// use std::intrinsics::cttz; | |
1505 | /// | |
1506 | /// let x = 0b0011_1000_u8; | |
0731742a | 1507 | /// let num_trailing = cttz(x); |
32a655c1 SL |
1508 | /// assert_eq!(num_trailing, 3); |
1509 | /// ``` | |
1510 | /// | |
1511 | /// An `x` with value `0` will return the bit width of `T`: | |
1512 | /// | |
1513 | /// ``` | |
1514 | /// #![feature(core_intrinsics)] | |
1515 | /// | |
1516 | /// use std::intrinsics::cttz; | |
1517 | /// | |
1518 | /// let x = 0u16; | |
0731742a | 1519 | /// let num_trailing = cttz(x); |
32a655c1 SL |
1520 | /// assert_eq!(num_trailing, 16); |
1521 | /// ``` | |
dfeec247 | 1522 | #[rustc_const_stable(feature = "const_cttz", since = "1.40.0")] |
ba9703b0 | 1523 | pub fn cttz<T: Copy>(x: T) -> T; |
1a4d82fc | 1524 | |
041b39d2 XL |
1525 | /// Like `cttz`, but extra-unsafe as it returns `undef` when |
1526 | /// given an `x` with value `0`. | |
1527 | /// | |
f9f354fc XL |
1528 | /// This intrinsic does not have a stable counterpart. |
1529 | /// | |
041b39d2 XL |
1530 | /// # Examples |
1531 | /// | |
1532 | /// ``` | |
1533 | /// #![feature(core_intrinsics)] | |
1534 | /// | |
1535 | /// use std::intrinsics::cttz_nonzero; | |
1536 | /// | |
1537 | /// let x = 0b0011_1000_u8; | |
1538 | /// let num_trailing = unsafe { cttz_nonzero(x) }; | |
1539 | /// assert_eq!(num_trailing, 3); | |
1540 | /// ``` | |
dfeec247 | 1541 | #[rustc_const_unstable(feature = "const_cttz", issue = "none")] |
ba9703b0 | 1542 | pub fn cttz_nonzero<T: Copy>(x: T) -> T; |
041b39d2 | 1543 | |
92a42be0 | 1544 | /// Reverses the bytes in an integer type `T`. |
74b04a01 XL |
1545 | /// |
1546 | /// The stabilized versions of this intrinsic are available on the integer | |
1547 | /// primitives via the `swap_bytes` method. For example, | |
3dfed10e | 1548 | /// [`u32::swap_bytes`] |
dfeec247 | 1549 | #[rustc_const_stable(feature = "const_bswap", since = "1.40.0")] |
ba9703b0 | 1550 | pub fn bswap<T: Copy>(x: T) -> T; |
1a4d82fc | 1551 | |
0531ce1d | 1552 | /// Reverses the bits in an integer type `T`. |
74b04a01 XL |
1553 | /// |
1554 | /// The stabilized versions of this intrinsic are available on the integer | |
1555 | /// primitives via the `reverse_bits` method. For example, | |
3dfed10e | 1556 | /// [`u32::reverse_bits`] |
dfeec247 | 1557 | #[rustc_const_stable(feature = "const_bitreverse", since = "1.40.0")] |
ba9703b0 | 1558 | pub fn bitreverse<T: Copy>(x: T) -> T; |
0531ce1d | 1559 | |
92a42be0 | 1560 | /// Performs checked integer addition. |
74b04a01 | 1561 | /// |
476ff2be SL |
1562 | /// The stabilized versions of this intrinsic are available on the integer |
1563 | /// primitives via the `overflowing_add` method. For example, | |
3dfed10e | 1564 | /// [`u32::overflowing_add`] |
dfeec247 | 1565 | #[rustc_const_stable(feature = "const_int_overflow", since = "1.40.0")] |
ba9703b0 | 1566 | pub fn add_with_overflow<T: Copy>(x: T, y: T) -> (T, bool); |
92a42be0 | 1567 | |
92a42be0 | 1568 | /// Performs checked integer subtraction |
74b04a01 | 1569 | /// |
476ff2be SL |
1570 | /// The stabilized versions of this intrinsic are available on the integer |
1571 | /// primitives via the `overflowing_sub` method. For example, | |
3dfed10e | 1572 | /// [`u32::overflowing_sub`] |
dfeec247 | 1573 | #[rustc_const_stable(feature = "const_int_overflow", since = "1.40.0")] |
ba9703b0 | 1574 | pub fn sub_with_overflow<T: Copy>(x: T, y: T) -> (T, bool); |
92a42be0 | 1575 | |
92a42be0 | 1576 | /// Performs checked integer multiplication |
74b04a01 | 1577 | /// |
476ff2be SL |
1578 | /// The stabilized versions of this intrinsic are available on the integer |
1579 | /// primitives via the `overflowing_mul` method. For example, | |
3dfed10e | 1580 | /// [`u32::overflowing_mul`] |
dfeec247 | 1581 | #[rustc_const_stable(feature = "const_int_overflow", since = "1.40.0")] |
ba9703b0 | 1582 | pub fn mul_with_overflow<T: Copy>(x: T, y: T) -> (T, bool); |
92a42be0 | 1583 | |
0531ce1d | 1584 | /// Performs an exact division, resulting in undefined behavior where |
ba9703b0 | 1585 | /// `x % y != 0` or `y == 0` or `x == T::MIN && y == -1` |
f9f354fc XL |
1586 | /// |
1587 | /// This intrinsic does not have a stable counterpart. | |
ba9703b0 | 1588 | pub fn exact_div<T: Copy>(x: T, y: T) -> T; |
0531ce1d | 1589 | |
92a42be0 | 1590 | /// Performs an unchecked division, resulting in undefined behavior |
ba9703b0 | 1591 | /// where y = 0 or x = `T::MIN` and y = -1 |
74b04a01 | 1592 | /// |
f9f354fc | 1593 | /// Safe wrappers for this intrinsic are available on the integer |
74b04a01 | 1594 | /// primitives via the `checked_div` method. For example, |
3dfed10e | 1595 | /// [`u32::checked_div`] |
74b04a01 | 1596 | #[rustc_const_unstable(feature = "const_int_unchecked_arith", issue = "none")] |
ba9703b0 | 1597 | pub fn unchecked_div<T: Copy>(x: T, y: T) -> T; |
92a42be0 | 1598 | /// Returns the remainder of an unchecked division, resulting in |
ba9703b0 | 1599 | /// undefined behavior where y = 0 or x = `T::MIN` and y = -1 |
74b04a01 | 1600 | /// |
f9f354fc | 1601 | /// Safe wrappers for this intrinsic are available on the integer |
74b04a01 | 1602 | /// primitives via the `checked_rem` method. For example, |
3dfed10e | 1603 | /// [`u32::checked_rem`] |
74b04a01 | 1604 | #[rustc_const_unstable(feature = "const_int_unchecked_arith", issue = "none")] |
ba9703b0 | 1605 | pub fn unchecked_rem<T: Copy>(x: T, y: T) -> T; |
92a42be0 | 1606 | |
cc61c64b XL |
1607 | /// Performs an unchecked left shift, resulting in undefined behavior when |
1608 | /// y < 0 or y >= N, where N is the width of T in bits. | |
74b04a01 | 1609 | /// |
f9f354fc | 1610 | /// Safe wrappers for this intrinsic are available on the integer |
74b04a01 | 1611 | /// primitives via the `checked_shl` method. For example, |
3dfed10e | 1612 | /// [`u32::checked_shl`] |
dfeec247 | 1613 | #[rustc_const_stable(feature = "const_int_unchecked", since = "1.40.0")] |
ba9703b0 | 1614 | pub fn unchecked_shl<T: Copy>(x: T, y: T) -> T; |
cc61c64b XL |
1615 | /// Performs an unchecked right shift, resulting in undefined behavior when |
1616 | /// y < 0 or y >= N, where N is the width of T in bits. | |
74b04a01 | 1617 | /// |
f9f354fc | 1618 | /// Safe wrappers for this intrinsic are available on the integer |
74b04a01 | 1619 | /// primitives via the `checked_shr` method. For example, |
3dfed10e | 1620 | /// [`u32::checked_shr`] |
dfeec247 | 1621 | #[rustc_const_stable(feature = "const_int_unchecked", since = "1.40.0")] |
ba9703b0 | 1622 | pub fn unchecked_shr<T: Copy>(x: T, y: T) -> T; |
cc61c64b | 1623 | |
dc9dc135 | 1624 | /// Returns the result of an unchecked addition, resulting in |
ba9703b0 | 1625 | /// undefined behavior when `x + y > T::MAX` or `x + y < T::MIN`. |
f9f354fc XL |
1626 | /// |
1627 | /// This intrinsic does not have a stable counterpart. | |
74b04a01 | 1628 | #[rustc_const_unstable(feature = "const_int_unchecked_arith", issue = "none")] |
ba9703b0 | 1629 | pub fn unchecked_add<T: Copy>(x: T, y: T) -> T; |
dc9dc135 | 1630 | |
60c5eb7d | 1631 | /// Returns the result of an unchecked subtraction, resulting in |
ba9703b0 | 1632 | /// undefined behavior when `x - y > T::MAX` or `x - y < T::MIN`. |
f9f354fc XL |
1633 | /// |
1634 | /// This intrinsic does not have a stable counterpart. | |
74b04a01 | 1635 | #[rustc_const_unstable(feature = "const_int_unchecked_arith", issue = "none")] |
ba9703b0 | 1636 | pub fn unchecked_sub<T: Copy>(x: T, y: T) -> T; |
dc9dc135 XL |
1637 | |
1638 | /// Returns the result of an unchecked multiplication, resulting in | |
ba9703b0 | 1639 | /// undefined behavior when `x * y > T::MAX` or `x * y < T::MIN`. |
f9f354fc XL |
1640 | /// |
1641 | /// This intrinsic does not have a stable counterpart. | |
74b04a01 | 1642 | #[rustc_const_unstable(feature = "const_int_unchecked_arith", issue = "none")] |
ba9703b0 | 1643 | pub fn unchecked_mul<T: Copy>(x: T, y: T) -> T; |
dc9dc135 | 1644 | |
a1dfa0c6 | 1645 | /// Performs rotate left. |
74b04a01 | 1646 | /// |
a1dfa0c6 XL |
1647 | /// The stabilized versions of this intrinsic are available on the integer |
1648 | /// primitives via the `rotate_left` method. For example, | |
3dfed10e | 1649 | /// [`u32::rotate_left`] |
dfeec247 | 1650 | #[rustc_const_stable(feature = "const_int_rotate", since = "1.40.0")] |
ba9703b0 | 1651 | pub fn rotate_left<T: Copy>(x: T, y: T) -> T; |
a1dfa0c6 XL |
1652 | |
1653 | /// Performs rotate right. | |
74b04a01 | 1654 | /// |
a1dfa0c6 XL |
1655 | /// The stabilized versions of this intrinsic are available on the integer |
1656 | /// primitives via the `rotate_right` method. For example, | |
3dfed10e | 1657 | /// [`u32::rotate_right`] |
dfeec247 | 1658 | #[rustc_const_stable(feature = "const_int_rotate", since = "1.40.0")] |
ba9703b0 | 1659 | pub fn rotate_right<T: Copy>(x: T, y: T) -> T; |
a1dfa0c6 | 1660 | |
cc61c64b | 1661 | /// Returns (a + b) mod 2<sup>N</sup>, where N is the width of T in bits. |
74b04a01 | 1662 | /// |
476ff2be | 1663 | /// The stabilized versions of this intrinsic are available on the integer |
29967ef6 XL |
1664 | /// primitives via the `wrapping_add` method. For example, |
1665 | /// [`u32::wrapping_add`] | |
dfeec247 | 1666 | #[rustc_const_stable(feature = "const_int_wrapping", since = "1.40.0")] |
ba9703b0 | 1667 | pub fn wrapping_add<T: Copy>(a: T, b: T) -> T; |
e1599b0c | 1668 | /// Returns (a - b) mod 2<sup>N</sup>, where N is the width of T in bits. |
74b04a01 | 1669 | /// |
e1599b0c | 1670 | /// The stabilized versions of this intrinsic are available on the integer |
29967ef6 XL |
1671 | /// primitives via the `wrapping_sub` method. For example, |
1672 | /// [`u32::wrapping_sub`] | |
dfeec247 | 1673 | #[rustc_const_stable(feature = "const_int_wrapping", since = "1.40.0")] |
ba9703b0 | 1674 | pub fn wrapping_sub<T: Copy>(a: T, b: T) -> T; |
e1599b0c | 1675 | /// Returns (a * b) mod 2<sup>N</sup>, where N is the width of T in bits. |
74b04a01 | 1676 | /// |
e1599b0c | 1677 | /// The stabilized versions of this intrinsic are available on the integer |
29967ef6 XL |
1678 | /// primitives via the `wrapping_mul` method. For example, |
1679 | /// [`u32::wrapping_mul`] | |
dfeec247 | 1680 | #[rustc_const_stable(feature = "const_int_wrapping", since = "1.40.0")] |
ba9703b0 | 1681 | pub fn wrapping_mul<T: Copy>(a: T, b: T) -> T; |
e1599b0c | 1682 | |
9fa01778 | 1683 | /// Computes `a + b`, while saturating at numeric bounds. |
74b04a01 | 1684 | /// |
9fa01778 XL |
1685 | /// The stabilized versions of this intrinsic are available on the integer |
1686 | /// primitives via the `saturating_add` method. For example, | |
3dfed10e | 1687 | /// [`u32::saturating_add`] |
dfeec247 | 1688 | #[rustc_const_stable(feature = "const_int_saturating", since = "1.40.0")] |
ba9703b0 | 1689 | pub fn saturating_add<T: Copy>(a: T, b: T) -> T; |
9fa01778 | 1690 | /// Computes `a - b`, while saturating at numeric bounds. |
74b04a01 | 1691 | /// |
9fa01778 XL |
1692 | /// The stabilized versions of this intrinsic are available on the integer |
1693 | /// primitives via the `saturating_sub` method. For example, | |
3dfed10e | 1694 | /// [`u32::saturating_sub`] |
dfeec247 | 1695 | #[rustc_const_stable(feature = "const_int_saturating", since = "1.40.0")] |
ba9703b0 | 1696 | pub fn saturating_sub<T: Copy>(a: T, b: T) -> T; |
9fa01778 | 1697 | |
62682a34 SL |
1698 | /// Returns the value of the discriminant for the variant in 'v', |
1699 | /// cast to a `u64`; if `T` has no discriminant, returns 0. | |
74b04a01 | 1700 | /// |
29967ef6 | 1701 | /// The stabilized version of this intrinsic is [`core::mem::discriminant`](crate::mem::discriminant). |
ba9703b0 | 1702 | #[rustc_const_unstable(feature = "const_discriminant", issue = "69821")] |
f9f354fc | 1703 | pub fn discriminant_value<T>(v: &T) -> <T as DiscriminantKind>::Discriminant; |
f035d41b XL |
1704 | |
1705 | /// Returns the number of variants of the type `T` cast to a `usize`; | |
1706 | /// if `T` has no variants, returns 0. Uninhabited variants will be counted. | |
1707 | /// | |
29967ef6 | 1708 | /// The to-be-stabilized version of this intrinsic is [`mem::variant_count`]. |
f035d41b | 1709 | #[rustc_const_unstable(feature = "variant_count", issue = "73662")] |
f035d41b | 1710 | pub fn variant_count<T>() -> usize; |
c1a9b12d | 1711 | |
ba9703b0 XL |
1712 | /// Rust's "try catch" construct which invokes the function pointer `try_fn` |
1713 | /// with the data pointer `data`. | |
7453a54e | 1714 | /// |
ba9703b0 XL |
1715 | /// The third argument is a function called if a panic occurs. This function |
1716 | /// takes the data pointer and a pointer to the target-specific exception | |
1717 | /// object that was caught. For more information see the compiler's | |
7453a54e | 1718 | /// source as well as std's catch implementation. |
ba9703b0 | 1719 | pub fn r#try(try_fn: fn(*mut u8), data: *mut u8, catch_fn: fn(*mut u8, *mut u8)) -> i32; |
ea8adc8c | 1720 | |
ff7c6d11 XL |
1721 | /// Emits a `!nontemporal` store according to LLVM (see their docs). |
1722 | /// Probably will never become stable. | |
ff7c6d11 | 1723 | pub fn nontemporal_store<T>(ptr: *mut T, val: T); |
e74abb32 XL |
1724 | |
1725 | /// See documentation of `<*const T>::offset_from` for details. | |
f035d41b | 1726 | #[rustc_const_unstable(feature = "const_ptr_offset_from", issue = "41079")] |
e74abb32 | 1727 | pub fn ptr_offset_from<T>(ptr: *const T, base: *const T) -> isize; |
60c5eb7d | 1728 | |
f035d41b XL |
1729 | /// See documentation of `<*const T>::guaranteed_eq` for details. |
1730 | #[rustc_const_unstable(feature = "const_raw_ptr_comparison", issue = "53020")] | |
f035d41b XL |
1731 | pub fn ptr_guaranteed_eq<T>(ptr: *const T, other: *const T) -> bool; |
1732 | ||
1733 | /// See documentation of `<*const T>::guaranteed_ne` for details. | |
1734 | #[rustc_const_unstable(feature = "const_raw_ptr_comparison", issue = "53020")] | |
f035d41b | 1735 | pub fn ptr_guaranteed_ne<T>(ptr: *const T, other: *const T) -> bool; |
fc512014 XL |
1736 | |
1737 | /// Allocate at compile time. Should not be called at runtime. | |
1738 | #[rustc_const_unstable(feature = "const_heap", issue = "79597")] | |
1739 | #[cfg(not(bootstrap))] | |
1740 | pub fn const_allocate(size: usize, align: usize) -> *mut u8; | |
ea8adc8c | 1741 | } |
9fa01778 | 1742 | |
dc9dc135 XL |
1743 | // Some functions are defined here because they accidentally got made |
1744 | // available in this module on stable. See <https://github.com/rust-lang/rust/issues/15702>. | |
1745 | // (`transmute` also falls into this category, but it cannot be wrapped due to the | |
1746 | // check that `T` and `U` have the same size.) | |
9fa01778 | 1747 | |
416331ca XL |
1748 | /// Checks whether `ptr` is properly aligned with respect to |
1749 | /// `align_of::<T>()`. | |
1750 | pub(crate) fn is_aligned_and_not_null<T>(ptr: *const T) -> bool { | |
1751 | !ptr.is_null() && ptr as usize % mem::align_of::<T>() == 0 | |
1752 | } | |
1753 | ||
1754 | /// Checks whether the regions of memory starting at `src` and `dst` of size | |
74b04a01 XL |
1755 | /// `count * size_of::<T>()` do *not* overlap. |
1756 | pub(crate) fn is_nonoverlapping<T>(src: *const T, dst: *const T, count: usize) -> bool { | |
416331ca XL |
1757 | let src_usize = src as usize; |
1758 | let dst_usize = dst as usize; | |
1759 | let size = mem::size_of::<T>().checked_mul(count).unwrap(); | |
dfeec247 | 1760 | let diff = if src_usize > dst_usize { src_usize - dst_usize } else { dst_usize - src_usize }; |
74b04a01 XL |
1761 | // If the absolute distance between the ptrs is at least as big as the size of the buffer, |
1762 | // they do not overlap. | |
1763 | diff >= size | |
416331ca XL |
1764 | } |
1765 | ||
9fa01778 XL |
1766 | /// Copies `count * size_of::<T>()` bytes from `src` to `dst`. The source |
1767 | /// and destination must *not* overlap. | |
1768 | /// | |
1769 | /// For regions of memory which might overlap, use [`copy`] instead. | |
1770 | /// | |
1771 | /// `copy_nonoverlapping` is semantically equivalent to C's [`memcpy`], but | |
1772 | /// with the argument order swapped. | |
1773 | /// | |
9fa01778 XL |
1774 | /// [`memcpy`]: https://en.cppreference.com/w/c/string/byte/memcpy |
1775 | /// | |
1776 | /// # Safety | |
1777 | /// | |
1778 | /// Behavior is undefined if any of the following conditions are violated: | |
1779 | /// | |
1780 | /// * `src` must be [valid] for reads of `count * size_of::<T>()` bytes. | |
1781 | /// | |
1782 | /// * `dst` must be [valid] for writes of `count * size_of::<T>()` bytes. | |
1783 | /// | |
1784 | /// * Both `src` and `dst` must be properly aligned. | |
1785 | /// | |
1786 | /// * The region of memory beginning at `src` with a size of `count * | |
1787 | /// size_of::<T>()` bytes must *not* overlap with the region of memory | |
1788 | /// beginning at `dst` with the same size. | |
1789 | /// | |
1790 | /// Like [`read`], `copy_nonoverlapping` creates a bitwise copy of `T`, regardless of | |
1791 | /// whether `T` is [`Copy`]. If `T` is not [`Copy`], using *both* the values | |
1792 | /// in the region beginning at `*src` and the region beginning at `*dst` can | |
1793 | /// [violate memory safety][read-ownership]. | |
1794 | /// | |
1795 | /// Note that even if the effectively copied size (`count * size_of::<T>()`) is | |
1796 | /// `0`, the pointers must be non-NULL and properly aligned. | |
1797 | /// | |
3dfed10e XL |
1798 | /// [`read`]: crate::ptr::read |
1799 | /// [read-ownership]: crate::ptr::read#ownership-of-the-returned-value | |
1800 | /// [valid]: crate::ptr#safety | |
9fa01778 XL |
1801 | /// |
1802 | /// # Examples | |
1803 | /// | |
1804 | /// Manually implement [`Vec::append`]: | |
1805 | /// | |
1806 | /// ``` | |
1807 | /// use std::ptr; | |
1808 | /// | |
1809 | /// /// Moves all the elements of `src` into `dst`, leaving `src` empty. | |
1810 | /// fn append<T>(dst: &mut Vec<T>, src: &mut Vec<T>) { | |
1811 | /// let src_len = src.len(); | |
1812 | /// let dst_len = dst.len(); | |
1813 | /// | |
1814 | /// // Ensure that `dst` has enough capacity to hold all of `src`. | |
1815 | /// dst.reserve(src_len); | |
1816 | /// | |
1817 | /// unsafe { | |
1818 | /// // The call to offset is always safe because `Vec` will never | |
1819 | /// // allocate more than `isize::MAX` bytes. | |
1820 | /// let dst_ptr = dst.as_mut_ptr().offset(dst_len as isize); | |
1821 | /// let src_ptr = src.as_ptr(); | |
1822 | /// | |
1823 | /// // Truncate `src` without dropping its contents. We do this first, | |
1824 | /// // to avoid problems in case something further down panics. | |
1825 | /// src.set_len(0); | |
1826 | /// | |
1827 | /// // The two regions cannot overlap because mutable references do | |
1828 | /// // not alias, and two different vectors cannot own the same | |
1829 | /// // memory. | |
1830 | /// ptr::copy_nonoverlapping(src_ptr, dst_ptr, src_len); | |
1831 | /// | |
1832 | /// // Notify `dst` that it now holds the contents of `src`. | |
1833 | /// dst.set_len(dst_len + src_len); | |
1834 | /// } | |
1835 | /// } | |
1836 | /// | |
1837 | /// let mut a = vec!['r']; | |
1838 | /// let mut b = vec!['u', 's', 't']; | |
1839 | /// | |
1840 | /// append(&mut a, &mut b); | |
1841 | /// | |
1842 | /// assert_eq!(a, &['r', 'u', 's', 't']); | |
1843 | /// assert!(b.is_empty()); | |
1844 | /// ``` | |
1845 | /// | |
1846 | /// [`Vec::append`]: ../../std/vec/struct.Vec.html#method.append | |
74b04a01 | 1847 | #[doc(alias = "memcpy")] |
9fa01778 XL |
1848 | #[stable(feature = "rust1", since = "1.0.0")] |
1849 | #[inline] | |
1850 | pub unsafe fn copy_nonoverlapping<T>(src: *const T, dst: *mut T, count: usize) { | |
dc9dc135 XL |
1851 | extern "rust-intrinsic" { |
1852 | fn copy_nonoverlapping<T>(src: *const T, dst: *mut T, count: usize); | |
1853 | } | |
416331ca | 1854 | |
f035d41b XL |
1855 | if cfg!(debug_assertions) |
1856 | && !(is_aligned_and_not_null(src) | |
1857 | && is_aligned_and_not_null(dst) | |
1858 | && is_nonoverlapping(src, dst, count)) | |
1859 | { | |
1860 | // Not panicking to keep codegen impact smaller. | |
1861 | abort(); | |
1862 | } | |
1863 | ||
1864 | // SAFETY: the safety contract for `copy_nonoverlapping` must be | |
1865 | // upheld by the caller. | |
1866 | unsafe { copy_nonoverlapping(src, dst, count) } | |
9fa01778 XL |
1867 | } |
1868 | ||
1869 | /// Copies `count * size_of::<T>()` bytes from `src` to `dst`. The source | |
1870 | /// and destination may overlap. | |
1871 | /// | |
1872 | /// If the source and destination will *never* overlap, | |
1873 | /// [`copy_nonoverlapping`] can be used instead. | |
1874 | /// | |
1875 | /// `copy` is semantically equivalent to C's [`memmove`], but with the argument | |
1876 | /// order swapped. Copying takes place as if the bytes were copied from `src` | |
1877 | /// to a temporary array and then copied from the array to `dst`. | |
1878 | /// | |
9fa01778 XL |
1879 | /// [`memmove`]: https://en.cppreference.com/w/c/string/byte/memmove |
1880 | /// | |
1881 | /// # Safety | |
1882 | /// | |
1883 | /// Behavior is undefined if any of the following conditions are violated: | |
1884 | /// | |
1885 | /// * `src` must be [valid] for reads of `count * size_of::<T>()` bytes. | |
1886 | /// | |
1887 | /// * `dst` must be [valid] for writes of `count * size_of::<T>()` bytes. | |
1888 | /// | |
1889 | /// * Both `src` and `dst` must be properly aligned. | |
1890 | /// | |
1891 | /// Like [`read`], `copy` creates a bitwise copy of `T`, regardless of | |
1892 | /// whether `T` is [`Copy`]. If `T` is not [`Copy`], using both the values | |
1893 | /// in the region beginning at `*src` and the region beginning at `*dst` can | |
1894 | /// [violate memory safety][read-ownership]. | |
1895 | /// | |
1896 | /// Note that even if the effectively copied size (`count * size_of::<T>()`) is | |
1897 | /// `0`, the pointers must be non-NULL and properly aligned. | |
1898 | /// | |
3dfed10e XL |
1899 | /// [`read`]: crate::ptr::read |
1900 | /// [read-ownership]: crate::ptr::read#ownership-of-the-returned-value | |
1901 | /// [valid]: crate::ptr#safety | |
9fa01778 XL |
1902 | /// |
1903 | /// # Examples | |
1904 | /// | |
1905 | /// Efficiently create a Rust vector from an unsafe buffer: | |
1906 | /// | |
1907 | /// ``` | |
1908 | /// use std::ptr; | |
1909 | /// | |
1b1a35ee XL |
1910 | /// /// # Safety |
1911 | /// /// | |
1912 | /// /// * `ptr` must be correctly aligned for its type and non-zero. | |
1913 | /// /// * `ptr` must be valid for reads of `elts` contiguous elements of type `T`. | |
1914 | /// /// * Those elements must not be used after calling this function unless `T: Copy`. | |
9fa01778 XL |
1915 | /// # #[allow(dead_code)] |
1916 | /// unsafe fn from_buf_raw<T>(ptr: *const T, elts: usize) -> Vec<T> { | |
1917 | /// let mut dst = Vec::with_capacity(elts); | |
1b1a35ee XL |
1918 | /// |
1919 | /// // SAFETY: Our precondition ensures the source is aligned and valid, | |
1920 | /// // and `Vec::with_capacity` ensures that we have usable space to write them. | |
9fa01778 | 1921 | /// ptr::copy(ptr, dst.as_mut_ptr(), elts); |
1b1a35ee XL |
1922 | /// |
1923 | /// // SAFETY: We created it with this much capacity earlier, | |
1924 | /// // and the previous `copy` has initialized these elements. | |
1925 | /// dst.set_len(elts); | |
9fa01778 XL |
1926 | /// dst |
1927 | /// } | |
1928 | /// ``` | |
74b04a01 | 1929 | #[doc(alias = "memmove")] |
9fa01778 XL |
1930 | #[stable(feature = "rust1", since = "1.0.0")] |
1931 | #[inline] | |
1932 | pub unsafe fn copy<T>(src: *const T, dst: *mut T, count: usize) { | |
dc9dc135 XL |
1933 | extern "rust-intrinsic" { |
1934 | fn copy<T>(src: *const T, dst: *mut T, count: usize); | |
1935 | } | |
416331ca | 1936 | |
f035d41b XL |
1937 | if cfg!(debug_assertions) && !(is_aligned_and_not_null(src) && is_aligned_and_not_null(dst)) { |
1938 | // Not panicking to keep codegen impact smaller. | |
1939 | abort(); | |
1940 | } | |
1941 | ||
1942 | // SAFETY: the safety contract for `copy` must be upheld by the caller. | |
1943 | unsafe { copy(src, dst, count) } | |
9fa01778 XL |
1944 | } |
1945 | ||
1946 | /// Sets `count * size_of::<T>()` bytes of memory starting at `dst` to | |
1947 | /// `val`. | |
1948 | /// | |
1949 | /// `write_bytes` is similar to C's [`memset`], but sets `count * | |
1950 | /// size_of::<T>()` bytes to `val`. | |
1951 | /// | |
1952 | /// [`memset`]: https://en.cppreference.com/w/c/string/byte/memset | |
1953 | /// | |
1954 | /// # Safety | |
1955 | /// | |
1956 | /// Behavior is undefined if any of the following conditions are violated: | |
1957 | /// | |
1958 | /// * `dst` must be [valid] for writes of `count * size_of::<T>()` bytes. | |
1959 | /// | |
1960 | /// * `dst` must be properly aligned. | |
1961 | /// | |
1962 | /// Additionally, the caller must ensure that writing `count * | |
1963 | /// size_of::<T>()` bytes to the given region of memory results in a valid | |
1964 | /// value of `T`. Using a region of memory typed as a `T` that contains an | |
1965 | /// invalid value of `T` is undefined behavior. | |
1966 | /// | |
1967 | /// Note that even if the effectively copied size (`count * size_of::<T>()`) is | |
1968 | /// `0`, the pointer must be non-NULL and properly aligned. | |
1969 | /// | |
3dfed10e | 1970 | /// [valid]: crate::ptr#safety |
9fa01778 XL |
1971 | /// |
1972 | /// # Examples | |
1973 | /// | |
1974 | /// Basic usage: | |
1975 | /// | |
1976 | /// ``` | |
1977 | /// use std::ptr; | |
1978 | /// | |
1979 | /// let mut vec = vec![0u32; 4]; | |
1980 | /// unsafe { | |
1981 | /// let vec_ptr = vec.as_mut_ptr(); | |
1982 | /// ptr::write_bytes(vec_ptr, 0xfe, 2); | |
1983 | /// } | |
1984 | /// assert_eq!(vec, [0xfefefefe, 0xfefefefe, 0, 0]); | |
1985 | /// ``` | |
1986 | /// | |
1987 | /// Creating an invalid value: | |
1988 | /// | |
1989 | /// ``` | |
1990 | /// use std::ptr; | |
1991 | /// | |
1992 | /// let mut v = Box::new(0i32); | |
1993 | /// | |
1994 | /// unsafe { | |
1995 | /// // Leaks the previously held value by overwriting the `Box<T>` with | |
1996 | /// // a null pointer. | |
1997 | /// ptr::write_bytes(&mut v as *mut Box<i32>, 0, 1); | |
1998 | /// } | |
1999 | /// | |
2000 | /// // At this point, using or dropping `v` results in undefined behavior. | |
2001 | /// // drop(v); // ERROR | |
2002 | /// | |
2003 | /// // Even leaking `v` "uses" it, and hence is undefined behavior. | |
2004 | /// // mem::forget(v); // ERROR | |
2005 | /// | |
2006 | /// // In fact, `v` is invalid according to basic type layout invariants, so *any* | |
2007 | /// // operation touching it is undefined behavior. | |
2008 | /// // let v2 = v; // ERROR | |
2009 | /// | |
2010 | /// unsafe { | |
2011 | /// // Let us instead put in a valid value | |
2012 | /// ptr::write(&mut v as *mut Box<i32>, Box::new(42i32)); | |
2013 | /// } | |
2014 | /// | |
2015 | /// // Now the box is fine | |
2016 | /// assert_eq!(*v, 42); | |
2017 | /// ``` | |
2018 | #[stable(feature = "rust1", since = "1.0.0")] | |
2019 | #[inline] | |
2020 | pub unsafe fn write_bytes<T>(dst: *mut T, val: u8, count: usize) { | |
dc9dc135 XL |
2021 | extern "rust-intrinsic" { |
2022 | fn write_bytes<T>(dst: *mut T, val: u8, count: usize); | |
2023 | } | |
dc9dc135 | 2024 | |
416331ca | 2025 | debug_assert!(is_aligned_and_not_null(dst), "attempt to write to unaligned or null pointer"); |
f035d41b XL |
2026 | |
2027 | // SAFETY: the safety contract for `write_bytes` must be upheld by the caller. | |
2028 | unsafe { write_bytes(dst, val, count) } | |
9fa01778 | 2029 | } |