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