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