1 //! Compiler intrinsics.
3 //! The corresponding definitions are in <https://github.com/rust-lang/rust/blob/master/compiler/rustc_codegen_llvm/src/intrinsic.rs>.
4 //! The corresponding const implementations are in <https://github.com/rust-lang/rust/blob/master/compiler/rustc_const_eval/src/interpret/intrinsics.rs>.
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.
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
13 //! <https://github.com/rust-lang/rust/blob/master/compiler/rustc_const_eval/src/interpret/intrinsics.rs> and add a
14 //! `#[rustc_const_unstable(feature = "const_such_and_such", issue = "01234")]` to the intrinsic declaration.
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
18 //! without T-lang consultation, because it bakes a feature into the language that cannot be
19 //! replicated in user code without compiler support.
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
28 //! [volatile]: https://llvm.org/docs/LangRef.html#volatile-memory-accesses
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]].
36 //! [atomics]: https://llvm.org/docs/Atomics.html
38 //! A quick refresher on memory ordering:
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`.
49 feature = "core_intrinsics",
50 reason = "intrinsics are unlikely to ever be stabilized, instead \
51 they should be used through stabilized interfaces \
52 in the rest of the standard library",
55 #![allow(missing_docs)]
57 use crate::marker::DiscriminantKind;
58 use crate::marker::Tuple;
63 // These imports are used for simplifying intra-doc links
64 #[allow(unused_imports)]
65 #[cfg(all(target_has_atomic = "8", target_has_atomic = "32", target_has_atomic = "ptr"))]
66 use crate::sync::atomic::{self, AtomicBool, AtomicI32, AtomicIsize, AtomicU32, Ordering};
68 #[stable(feature = "drop_in_place", since = "1.8.0")]
69 #[rustc_allowed_through_unstable_modules]
70 #[deprecated(note = "no longer an intrinsic - use `ptr::drop_in_place` directly", since = "1.52.0")]
72 pub unsafe fn drop_in_place<T: ?Sized>(to_drop: *mut T) {
73 // SAFETY: see `ptr::drop_in_place`
74 unsafe { crate::ptr::drop_in_place(to_drop) }
77 extern "rust-intrinsic" {
78 // N.B., these intrinsics take raw pointers because they mutate aliased
79 // memory, which is not valid for either `&` or `&mut`.
81 /// Stores a value if the current value is the same as the `old` value.
83 /// The stabilized version of this intrinsic is available on the
84 /// [`atomic`] types via the `compare_exchange` method by passing
85 /// [`Ordering::Relaxed`] as both the success and failure parameters.
86 /// For example, [`AtomicBool::compare_exchange`].
87 pub fn atomic_cxchg_relaxed_relaxed<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
88 /// Stores a value if the current value is the same as the `old` value.
90 /// The stabilized version of this intrinsic is available on the
91 /// [`atomic`] types via the `compare_exchange` method by passing
92 /// [`Ordering::Relaxed`] and [`Ordering::Acquire`] as the success and failure parameters.
93 /// For example, [`AtomicBool::compare_exchange`].
94 pub fn atomic_cxchg_relaxed_acquire<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
95 /// Stores a value if the current value is the same as the `old` value.
97 /// The stabilized version of this intrinsic is available on the
98 /// [`atomic`] types via the `compare_exchange` method by passing
99 /// [`Ordering::Relaxed`] and [`Ordering::SeqCst`] as the success and failure parameters.
100 /// For example, [`AtomicBool::compare_exchange`].
101 pub fn atomic_cxchg_relaxed_seqcst<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
102 /// Stores a value if the current value is the same as the `old` value.
104 /// The stabilized version of this intrinsic is available on the
105 /// [`atomic`] types via the `compare_exchange` method by passing
106 /// [`Ordering::Acquire`] and [`Ordering::Relaxed`] as the success and failure parameters.
107 /// For example, [`AtomicBool::compare_exchange`].
108 pub fn atomic_cxchg_acquire_relaxed<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
109 /// Stores a value if the current value is the same as the `old` value.
111 /// The stabilized version of this intrinsic is available on the
112 /// [`atomic`] types via the `compare_exchange` method by passing
113 /// [`Ordering::Acquire`] as both the success and failure parameters.
114 /// For example, [`AtomicBool::compare_exchange`].
115 pub fn atomic_cxchg_acquire_acquire<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
116 /// Stores a value if the current value is the same as the `old` value.
118 /// The stabilized version of this intrinsic is available on the
119 /// [`atomic`] types via the `compare_exchange` method by passing
120 /// [`Ordering::Acquire`] and [`Ordering::SeqCst`] as the success and failure parameters.
121 /// For example, [`AtomicBool::compare_exchange`].
122 pub fn atomic_cxchg_acquire_seqcst<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
123 /// Stores a value if the current value is the same as the `old` value.
125 /// The stabilized version of this intrinsic is available on the
126 /// [`atomic`] types via the `compare_exchange` method by passing
127 /// [`Ordering::Release`] and [`Ordering::Relaxed`] as the success and failure parameters.
128 /// For example, [`AtomicBool::compare_exchange`].
129 pub fn atomic_cxchg_release_relaxed<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
130 /// Stores a value if the current value is the same as the `old` value.
132 /// The stabilized version of this intrinsic is available on the
133 /// [`atomic`] types via the `compare_exchange` method by passing
134 /// [`Ordering::Release`] and [`Ordering::Acquire`] as the success and failure parameters.
135 /// For example, [`AtomicBool::compare_exchange`].
136 pub fn atomic_cxchg_release_acquire<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
137 /// Stores a value if the current value is the same as the `old` value.
139 /// The stabilized version of this intrinsic is available on the
140 /// [`atomic`] types via the `compare_exchange` method by passing
141 /// [`Ordering::Release`] and [`Ordering::SeqCst`] as the success and failure parameters.
142 /// For example, [`AtomicBool::compare_exchange`].
143 pub fn atomic_cxchg_release_seqcst<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
144 /// Stores a value if the current value is the same as the `old` value.
146 /// The stabilized version of this intrinsic is available on the
147 /// [`atomic`] types via the `compare_exchange` method by passing
148 /// [`Ordering::AcqRel`] and [`Ordering::Relaxed`] as the success and failure parameters.
149 /// For example, [`AtomicBool::compare_exchange`].
150 pub fn atomic_cxchg_acqrel_relaxed<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
151 /// Stores a value if the current value is the same as the `old` value.
153 /// The stabilized version of this intrinsic is available on the
154 /// [`atomic`] types via the `compare_exchange` method by passing
155 /// [`Ordering::AcqRel`] and [`Ordering::Acquire`] as the success and failure parameters.
156 /// For example, [`AtomicBool::compare_exchange`].
157 pub fn atomic_cxchg_acqrel_acquire<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
158 /// Stores a value if the current value is the same as the `old` value.
160 /// The stabilized version of this intrinsic is available on the
161 /// [`atomic`] types via the `compare_exchange` method by passing
162 /// [`Ordering::AcqRel`] and [`Ordering::SeqCst`] as the success and failure parameters.
163 /// For example, [`AtomicBool::compare_exchange`].
164 pub fn atomic_cxchg_acqrel_seqcst<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
165 /// Stores a value if the current value is the same as the `old` value.
167 /// The stabilized version of this intrinsic is available on the
168 /// [`atomic`] types via the `compare_exchange` method by passing
169 /// [`Ordering::SeqCst`] and [`Ordering::Relaxed`] as the success and failure parameters.
170 /// For example, [`AtomicBool::compare_exchange`].
171 pub fn atomic_cxchg_seqcst_relaxed<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
172 /// Stores a value if the current value is the same as the `old` value.
174 /// The stabilized version of this intrinsic is available on the
175 /// [`atomic`] types via the `compare_exchange` method by passing
176 /// [`Ordering::SeqCst`] and [`Ordering::Acquire`] as the success and failure parameters.
177 /// For example, [`AtomicBool::compare_exchange`].
178 pub fn atomic_cxchg_seqcst_acquire<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
179 /// Stores a value if the current value is the same as the `old` value.
181 /// The stabilized version of this intrinsic is available on the
182 /// [`atomic`] types via the `compare_exchange` method by passing
183 /// [`Ordering::SeqCst`] as both the success and failure parameters.
184 /// For example, [`AtomicBool::compare_exchange`].
185 pub fn atomic_cxchg_seqcst_seqcst<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
187 /// Stores a value if the current value is the same as the `old` value.
189 /// The stabilized version of this intrinsic is available on the
190 /// [`atomic`] types via the `compare_exchange_weak` method by passing
191 /// [`Ordering::Relaxed`] as both the success and failure parameters.
192 /// For example, [`AtomicBool::compare_exchange_weak`].
193 pub fn atomic_cxchgweak_relaxed_relaxed<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
194 /// Stores a value if the current value is the same as the `old` value.
196 /// The stabilized version of this intrinsic is available on the
197 /// [`atomic`] types via the `compare_exchange_weak` method by passing
198 /// [`Ordering::Relaxed`] and [`Ordering::Acquire`] as the success and failure parameters.
199 /// For example, [`AtomicBool::compare_exchange_weak`].
200 pub fn atomic_cxchgweak_relaxed_acquire<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
201 /// Stores a value if the current value is the same as the `old` value.
203 /// The stabilized version of this intrinsic is available on the
204 /// [`atomic`] types via the `compare_exchange_weak` method by passing
205 /// [`Ordering::Relaxed`] and [`Ordering::SeqCst`] as the success and failure parameters.
206 /// For example, [`AtomicBool::compare_exchange_weak`].
207 pub fn atomic_cxchgweak_relaxed_seqcst<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
208 /// Stores a value if the current value is the same as the `old` value.
210 /// The stabilized version of this intrinsic is available on the
211 /// [`atomic`] types via the `compare_exchange_weak` method by passing
212 /// [`Ordering::Acquire`] and [`Ordering::Relaxed`] as the success and failure parameters.
213 /// For example, [`AtomicBool::compare_exchange_weak`].
214 pub fn atomic_cxchgweak_acquire_relaxed<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
215 /// Stores a value if the current value is the same as the `old` value.
217 /// The stabilized version of this intrinsic is available on the
218 /// [`atomic`] types via the `compare_exchange_weak` method by passing
219 /// [`Ordering::Acquire`] as both the success and failure parameters.
220 /// For example, [`AtomicBool::compare_exchange_weak`].
221 pub fn atomic_cxchgweak_acquire_acquire<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
222 /// Stores a value if the current value is the same as the `old` value.
224 /// The stabilized version of this intrinsic is available on the
225 /// [`atomic`] types via the `compare_exchange_weak` method by passing
226 /// [`Ordering::Acquire`] and [`Ordering::SeqCst`] as the success and failure parameters.
227 /// For example, [`AtomicBool::compare_exchange_weak`].
228 pub fn atomic_cxchgweak_acquire_seqcst<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
229 /// Stores a value if the current value is the same as the `old` value.
231 /// The stabilized version of this intrinsic is available on the
232 /// [`atomic`] types via the `compare_exchange_weak` method by passing
233 /// [`Ordering::Release`] and [`Ordering::Relaxed`] as the success and failure parameters.
234 /// For example, [`AtomicBool::compare_exchange_weak`].
235 pub fn atomic_cxchgweak_release_relaxed<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
236 /// Stores a value if the current value is the same as the `old` value.
238 /// The stabilized version of this intrinsic is available on the
239 /// [`atomic`] types via the `compare_exchange_weak` method by passing
240 /// [`Ordering::Release`] and [`Ordering::Acquire`] as the success and failure parameters.
241 /// For example, [`AtomicBool::compare_exchange_weak`].
242 pub fn atomic_cxchgweak_release_acquire<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
243 /// Stores a value if the current value is the same as the `old` value.
245 /// The stabilized version of this intrinsic is available on the
246 /// [`atomic`] types via the `compare_exchange_weak` method by passing
247 /// [`Ordering::Release`] and [`Ordering::SeqCst`] as the success and failure parameters.
248 /// For example, [`AtomicBool::compare_exchange_weak`].
249 pub fn atomic_cxchgweak_release_seqcst<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
250 /// Stores a value if the current value is the same as the `old` value.
252 /// The stabilized version of this intrinsic is available on the
253 /// [`atomic`] types via the `compare_exchange_weak` method by passing
254 /// [`Ordering::AcqRel`] and [`Ordering::Relaxed`] as the success and failure parameters.
255 /// For example, [`AtomicBool::compare_exchange_weak`].
256 pub fn atomic_cxchgweak_acqrel_relaxed<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
257 /// Stores a value if the current value is the same as the `old` value.
259 /// The stabilized version of this intrinsic is available on the
260 /// [`atomic`] types via the `compare_exchange_weak` method by passing
261 /// [`Ordering::AcqRel`] and [`Ordering::Acquire`] as the success and failure parameters.
262 /// For example, [`AtomicBool::compare_exchange_weak`].
263 pub fn atomic_cxchgweak_acqrel_acquire<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
264 /// Stores a value if the current value is the same as the `old` value.
266 /// The stabilized version of this intrinsic is available on the
267 /// [`atomic`] types via the `compare_exchange_weak` method by passing
268 /// [`Ordering::AcqRel`] and [`Ordering::SeqCst`] as the success and failure parameters.
269 /// For example, [`AtomicBool::compare_exchange_weak`].
270 pub fn atomic_cxchgweak_acqrel_seqcst<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
271 /// Stores a value if the current value is the same as the `old` value.
273 /// The stabilized version of this intrinsic is available on the
274 /// [`atomic`] types via the `compare_exchange_weak` method by passing
275 /// [`Ordering::SeqCst`] and [`Ordering::Relaxed`] as the success and failure parameters.
276 /// For example, [`AtomicBool::compare_exchange_weak`].
277 pub fn atomic_cxchgweak_seqcst_relaxed<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
278 /// Stores a value if the current value is the same as the `old` value.
280 /// The stabilized version of this intrinsic is available on the
281 /// [`atomic`] types via the `compare_exchange_weak` method by passing
282 /// [`Ordering::SeqCst`] and [`Ordering::Acquire`] as the success and failure parameters.
283 /// For example, [`AtomicBool::compare_exchange_weak`].
284 pub fn atomic_cxchgweak_seqcst_acquire<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
285 /// Stores a value if the current value is the same as the `old` value.
287 /// The stabilized version of this intrinsic is available on the
288 /// [`atomic`] types via the `compare_exchange_weak` method by passing
289 /// [`Ordering::SeqCst`] as both the success and failure parameters.
290 /// For example, [`AtomicBool::compare_exchange_weak`].
291 pub fn atomic_cxchgweak_seqcst_seqcst<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
293 /// Loads the current value of the pointer.
295 /// The stabilized version of this intrinsic is available on the
296 /// [`atomic`] types via the `load` method by passing
297 /// [`Ordering::SeqCst`] as the `order`. For example, [`AtomicBool::load`].
298 pub fn atomic_load_seqcst<T: Copy>(src: *const T) -> T;
299 /// Loads the current value of the pointer.
301 /// The stabilized version of this intrinsic is available on the
302 /// [`atomic`] types via the `load` method by passing
303 /// [`Ordering::Acquire`] as the `order`. For example, [`AtomicBool::load`].
304 pub fn atomic_load_acquire<T: Copy>(src: *const T) -> T;
305 /// Loads the current value of the pointer.
307 /// The stabilized version of this intrinsic is available on the
308 /// [`atomic`] types via the `load` method by passing
309 /// [`Ordering::Relaxed`] as the `order`. For example, [`AtomicBool::load`].
310 pub fn atomic_load_relaxed<T: Copy>(src: *const T) -> T;
311 pub fn atomic_load_unordered<T: Copy>(src: *const T) -> T;
313 /// Stores the value at the specified memory location.
315 /// The stabilized version of this intrinsic is available on the
316 /// [`atomic`] types via the `store` method by passing
317 /// [`Ordering::SeqCst`] as the `order`. For example, [`AtomicBool::store`].
318 pub fn atomic_store_seqcst<T: Copy>(dst: *mut T, val: T);
319 /// Stores the value at the specified memory location.
321 /// The stabilized version of this intrinsic is available on the
322 /// [`atomic`] types via the `store` method by passing
323 /// [`Ordering::Release`] as the `order`. For example, [`AtomicBool::store`].
324 pub fn atomic_store_release<T: Copy>(dst: *mut T, val: T);
325 /// Stores the value at the specified memory location.
327 /// The stabilized version of this intrinsic is available on the
328 /// [`atomic`] types via the `store` method by passing
329 /// [`Ordering::Relaxed`] as the `order`. For example, [`AtomicBool::store`].
330 pub fn atomic_store_relaxed<T: Copy>(dst: *mut T, val: T);
331 pub fn atomic_store_unordered<T: Copy>(dst: *mut T, val: T);
333 /// Stores the value at the specified memory location, returning the old value.
335 /// The stabilized version of this intrinsic is available on the
336 /// [`atomic`] types via the `swap` method by passing
337 /// [`Ordering::SeqCst`] as the `order`. For example, [`AtomicBool::swap`].
338 pub fn atomic_xchg_seqcst<T: Copy>(dst: *mut T, src: T) -> T;
339 /// Stores the value at the specified memory location, returning the old value.
341 /// The stabilized version of this intrinsic is available on the
342 /// [`atomic`] types via the `swap` method by passing
343 /// [`Ordering::Acquire`] as the `order`. For example, [`AtomicBool::swap`].
344 pub fn atomic_xchg_acquire<T: Copy>(dst: *mut T, src: T) -> T;
345 /// Stores the value at the specified memory location, returning the old value.
347 /// The stabilized version of this intrinsic is available on the
348 /// [`atomic`] types via the `swap` method by passing
349 /// [`Ordering::Release`] as the `order`. For example, [`AtomicBool::swap`].
350 pub fn atomic_xchg_release<T: Copy>(dst: *mut T, src: T) -> T;
351 /// Stores the value at the specified memory location, returning the old value.
353 /// The stabilized version of this intrinsic is available on the
354 /// [`atomic`] types via the `swap` method by passing
355 /// [`Ordering::AcqRel`] as the `order`. For example, [`AtomicBool::swap`].
356 pub fn atomic_xchg_acqrel<T: Copy>(dst: *mut T, src: T) -> T;
357 /// Stores the value at the specified memory location, returning the old value.
359 /// The stabilized version of this intrinsic is available on the
360 /// [`atomic`] types via the `swap` method by passing
361 /// [`Ordering::Relaxed`] as the `order`. For example, [`AtomicBool::swap`].
362 pub fn atomic_xchg_relaxed<T: Copy>(dst: *mut T, src: T) -> T;
364 /// Adds to the current value, returning the previous value.
366 /// The stabilized version of this intrinsic is available on the
367 /// [`atomic`] types via the `fetch_add` method by passing
368 /// [`Ordering::SeqCst`] as the `order`. For example, [`AtomicIsize::fetch_add`].
369 pub fn atomic_xadd_seqcst<T: Copy>(dst: *mut T, src: T) -> T;
370 /// Adds to the current value, returning the previous value.
372 /// The stabilized version of this intrinsic is available on the
373 /// [`atomic`] types via the `fetch_add` method by passing
374 /// [`Ordering::Acquire`] as the `order`. For example, [`AtomicIsize::fetch_add`].
375 pub fn atomic_xadd_acquire<T: Copy>(dst: *mut T, src: T) -> T;
376 /// Adds to the current value, returning the previous value.
378 /// The stabilized version of this intrinsic is available on the
379 /// [`atomic`] types via the `fetch_add` method by passing
380 /// [`Ordering::Release`] as the `order`. For example, [`AtomicIsize::fetch_add`].
381 pub fn atomic_xadd_release<T: Copy>(dst: *mut T, src: T) -> T;
382 /// Adds to the current value, returning the previous value.
384 /// The stabilized version of this intrinsic is available on the
385 /// [`atomic`] types via the `fetch_add` method by passing
386 /// [`Ordering::AcqRel`] as the `order`. For example, [`AtomicIsize::fetch_add`].
387 pub fn atomic_xadd_acqrel<T: Copy>(dst: *mut T, src: T) -> T;
388 /// Adds to the current value, returning the previous value.
390 /// The stabilized version of this intrinsic is available on the
391 /// [`atomic`] types via the `fetch_add` method by passing
392 /// [`Ordering::Relaxed`] as the `order`. For example, [`AtomicIsize::fetch_add`].
393 pub fn atomic_xadd_relaxed<T: Copy>(dst: *mut T, src: T) -> T;
395 /// Subtract from the current value, returning the previous value.
397 /// The stabilized version of this intrinsic is available on the
398 /// [`atomic`] types via the `fetch_sub` method by passing
399 /// [`Ordering::SeqCst`] as the `order`. For example, [`AtomicIsize::fetch_sub`].
400 pub fn atomic_xsub_seqcst<T: Copy>(dst: *mut T, src: T) -> T;
401 /// Subtract from the current value, returning the previous value.
403 /// The stabilized version of this intrinsic is available on the
404 /// [`atomic`] types via the `fetch_sub` method by passing
405 /// [`Ordering::Acquire`] as the `order`. For example, [`AtomicIsize::fetch_sub`].
406 pub fn atomic_xsub_acquire<T: Copy>(dst: *mut T, src: T) -> T;
407 /// Subtract from the current value, returning the previous value.
409 /// The stabilized version of this intrinsic is available on the
410 /// [`atomic`] types via the `fetch_sub` method by passing
411 /// [`Ordering::Release`] as the `order`. For example, [`AtomicIsize::fetch_sub`].
412 pub fn atomic_xsub_release<T: Copy>(dst: *mut T, src: T) -> T;
413 /// Subtract from the current value, returning the previous value.
415 /// The stabilized version of this intrinsic is available on the
416 /// [`atomic`] types via the `fetch_sub` method by passing
417 /// [`Ordering::AcqRel`] as the `order`. For example, [`AtomicIsize::fetch_sub`].
418 pub fn atomic_xsub_acqrel<T: Copy>(dst: *mut T, src: T) -> T;
419 /// Subtract from the current value, returning the previous value.
421 /// The stabilized version of this intrinsic is available on the
422 /// [`atomic`] types via the `fetch_sub` method by passing
423 /// [`Ordering::Relaxed`] as the `order`. For example, [`AtomicIsize::fetch_sub`].
424 pub fn atomic_xsub_relaxed<T: Copy>(dst: *mut T, src: T) -> T;
426 /// Bitwise and with the current value, returning the previous value.
428 /// The stabilized version of this intrinsic is available on the
429 /// [`atomic`] types via the `fetch_and` method by passing
430 /// [`Ordering::SeqCst`] as the `order`. For example, [`AtomicBool::fetch_and`].
431 pub fn atomic_and_seqcst<T: Copy>(dst: *mut T, src: T) -> T;
432 /// Bitwise and with the current value, returning the previous value.
434 /// The stabilized version of this intrinsic is available on the
435 /// [`atomic`] types via the `fetch_and` method by passing
436 /// [`Ordering::Acquire`] as the `order`. For example, [`AtomicBool::fetch_and`].
437 pub fn atomic_and_acquire<T: Copy>(dst: *mut T, src: T) -> T;
438 /// Bitwise and with the current value, returning the previous value.
440 /// The stabilized version of this intrinsic is available on the
441 /// [`atomic`] types via the `fetch_and` method by passing
442 /// [`Ordering::Release`] as the `order`. For example, [`AtomicBool::fetch_and`].
443 pub fn atomic_and_release<T: Copy>(dst: *mut T, src: T) -> T;
444 /// Bitwise and with the current value, returning the previous value.
446 /// The stabilized version of this intrinsic is available on the
447 /// [`atomic`] types via the `fetch_and` method by passing
448 /// [`Ordering::AcqRel`] as the `order`. For example, [`AtomicBool::fetch_and`].
449 pub fn atomic_and_acqrel<T: Copy>(dst: *mut T, src: T) -> T;
450 /// Bitwise and with the current value, returning the previous value.
452 /// The stabilized version of this intrinsic is available on the
453 /// [`atomic`] types via the `fetch_and` method by passing
454 /// [`Ordering::Relaxed`] as the `order`. For example, [`AtomicBool::fetch_and`].
455 pub fn atomic_and_relaxed<T: Copy>(dst: *mut T, src: T) -> T;
457 /// Bitwise nand with the current value, returning the previous value.
459 /// The stabilized version of this intrinsic is available on the
460 /// [`AtomicBool`] type via the `fetch_nand` method by passing
461 /// [`Ordering::SeqCst`] as the `order`. For example, [`AtomicBool::fetch_nand`].
462 pub fn atomic_nand_seqcst<T: Copy>(dst: *mut T, src: T) -> T;
463 /// Bitwise nand with the current value, returning the previous value.
465 /// The stabilized version of this intrinsic is available on the
466 /// [`AtomicBool`] type via the `fetch_nand` method by passing
467 /// [`Ordering::Acquire`] as the `order`. For example, [`AtomicBool::fetch_nand`].
468 pub fn atomic_nand_acquire<T: Copy>(dst: *mut T, src: T) -> T;
469 /// Bitwise nand with the current value, returning the previous value.
471 /// The stabilized version of this intrinsic is available on the
472 /// [`AtomicBool`] type via the `fetch_nand` method by passing
473 /// [`Ordering::Release`] as the `order`. For example, [`AtomicBool::fetch_nand`].
474 pub fn atomic_nand_release<T: Copy>(dst: *mut T, src: T) -> T;
475 /// Bitwise nand with the current value, returning the previous value.
477 /// The stabilized version of this intrinsic is available on the
478 /// [`AtomicBool`] type via the `fetch_nand` method by passing
479 /// [`Ordering::AcqRel`] as the `order`. For example, [`AtomicBool::fetch_nand`].
480 pub fn atomic_nand_acqrel<T: Copy>(dst: *mut T, src: T) -> T;
481 /// Bitwise nand with the current value, returning the previous value.
483 /// The stabilized version of this intrinsic is available on the
484 /// [`AtomicBool`] type via the `fetch_nand` method by passing
485 /// [`Ordering::Relaxed`] as the `order`. For example, [`AtomicBool::fetch_nand`].
486 pub fn atomic_nand_relaxed<T: Copy>(dst: *mut T, src: T) -> T;
488 /// Bitwise or with the current value, returning the previous value.
490 /// The stabilized version of this intrinsic is available on the
491 /// [`atomic`] types via the `fetch_or` method by passing
492 /// [`Ordering::SeqCst`] as the `order`. For example, [`AtomicBool::fetch_or`].
493 pub fn atomic_or_seqcst<T: Copy>(dst: *mut T, src: T) -> T;
494 /// Bitwise or with the current value, returning the previous value.
496 /// The stabilized version of this intrinsic is available on the
497 /// [`atomic`] types via the `fetch_or` method by passing
498 /// [`Ordering::Acquire`] as the `order`. For example, [`AtomicBool::fetch_or`].
499 pub fn atomic_or_acquire<T: Copy>(dst: *mut T, src: T) -> T;
500 /// Bitwise or with the current value, returning the previous value.
502 /// The stabilized version of this intrinsic is available on the
503 /// [`atomic`] types via the `fetch_or` method by passing
504 /// [`Ordering::Release`] as the `order`. For example, [`AtomicBool::fetch_or`].
505 pub fn atomic_or_release<T: Copy>(dst: *mut T, src: T) -> T;
506 /// Bitwise or with the current value, returning the previous value.
508 /// The stabilized version of this intrinsic is available on the
509 /// [`atomic`] types via the `fetch_or` method by passing
510 /// [`Ordering::AcqRel`] as the `order`. For example, [`AtomicBool::fetch_or`].
511 pub fn atomic_or_acqrel<T: Copy>(dst: *mut T, src: T) -> T;
512 /// Bitwise or with the current value, returning the previous value.
514 /// The stabilized version of this intrinsic is available on the
515 /// [`atomic`] types via the `fetch_or` method by passing
516 /// [`Ordering::Relaxed`] as the `order`. For example, [`AtomicBool::fetch_or`].
517 pub fn atomic_or_relaxed<T: Copy>(dst: *mut T, src: T) -> T;
519 /// Bitwise xor with the current value, returning the previous value.
521 /// The stabilized version of this intrinsic is available on the
522 /// [`atomic`] types via the `fetch_xor` method by passing
523 /// [`Ordering::SeqCst`] as the `order`. For example, [`AtomicBool::fetch_xor`].
524 pub fn atomic_xor_seqcst<T: Copy>(dst: *mut T, src: T) -> T;
525 /// Bitwise xor with the current value, returning the previous value.
527 /// The stabilized version of this intrinsic is available on the
528 /// [`atomic`] types via the `fetch_xor` method by passing
529 /// [`Ordering::Acquire`] as the `order`. For example, [`AtomicBool::fetch_xor`].
530 pub fn atomic_xor_acquire<T: Copy>(dst: *mut T, src: T) -> T;
531 /// Bitwise xor with the current value, returning the previous value.
533 /// The stabilized version of this intrinsic is available on the
534 /// [`atomic`] types via the `fetch_xor` method by passing
535 /// [`Ordering::Release`] as the `order`. For example, [`AtomicBool::fetch_xor`].
536 pub fn atomic_xor_release<T: Copy>(dst: *mut T, src: T) -> T;
537 /// Bitwise xor with the current value, returning the previous value.
539 /// The stabilized version of this intrinsic is available on the
540 /// [`atomic`] types via the `fetch_xor` method by passing
541 /// [`Ordering::AcqRel`] as the `order`. For example, [`AtomicBool::fetch_xor`].
542 pub fn atomic_xor_acqrel<T: Copy>(dst: *mut T, src: T) -> T;
543 /// Bitwise xor with the current value, returning the previous value.
545 /// The stabilized version of this intrinsic is available on the
546 /// [`atomic`] types via the `fetch_xor` method by passing
547 /// [`Ordering::Relaxed`] as the `order`. For example, [`AtomicBool::fetch_xor`].
548 pub fn atomic_xor_relaxed<T: Copy>(dst: *mut T, src: T) -> T;
550 /// Maximum with the current value using a signed comparison.
552 /// The stabilized version of this intrinsic is available on the
553 /// [`atomic`] signed integer types via the `fetch_max` method by passing
554 /// [`Ordering::SeqCst`] as the `order`. For example, [`AtomicI32::fetch_max`].
555 pub fn atomic_max_seqcst<T: Copy>(dst: *mut T, src: T) -> T;
556 /// Maximum with the current value using a signed comparison.
558 /// The stabilized version of this intrinsic is available on the
559 /// [`atomic`] signed integer types via the `fetch_max` method by passing
560 /// [`Ordering::Acquire`] as the `order`. For example, [`AtomicI32::fetch_max`].
561 pub fn atomic_max_acquire<T: Copy>(dst: *mut T, src: T) -> T;
562 /// Maximum with the current value using a signed comparison.
564 /// The stabilized version of this intrinsic is available on the
565 /// [`atomic`] signed integer types via the `fetch_max` method by passing
566 /// [`Ordering::Release`] as the `order`. For example, [`AtomicI32::fetch_max`].
567 pub fn atomic_max_release<T: Copy>(dst: *mut T, src: T) -> T;
568 /// Maximum with the current value using a signed comparison.
570 /// The stabilized version of this intrinsic is available on the
571 /// [`atomic`] signed integer types via the `fetch_max` method by passing
572 /// [`Ordering::AcqRel`] as the `order`. For example, [`AtomicI32::fetch_max`].
573 pub fn atomic_max_acqrel<T: Copy>(dst: *mut T, src: T) -> T;
574 /// Maximum with the current value.
576 /// The stabilized version of this intrinsic is available on the
577 /// [`atomic`] signed integer types via the `fetch_max` method by passing
578 /// [`Ordering::Relaxed`] as the `order`. For example, [`AtomicI32::fetch_max`].
579 pub fn atomic_max_relaxed<T: Copy>(dst: *mut T, src: T) -> T;
581 /// Minimum with the current value using a signed comparison.
583 /// The stabilized version of this intrinsic is available on the
584 /// [`atomic`] signed integer types via the `fetch_min` method by passing
585 /// [`Ordering::SeqCst`] as the `order`. For example, [`AtomicI32::fetch_min`].
586 pub fn atomic_min_seqcst<T: Copy>(dst: *mut T, src: T) -> T;
587 /// Minimum with the current value using a signed comparison.
589 /// The stabilized version of this intrinsic is available on the
590 /// [`atomic`] signed integer types via the `fetch_min` method by passing
591 /// [`Ordering::Acquire`] as the `order`. For example, [`AtomicI32::fetch_min`].
592 pub fn atomic_min_acquire<T: Copy>(dst: *mut T, src: T) -> T;
593 /// Minimum with the current value using a signed comparison.
595 /// The stabilized version of this intrinsic is available on the
596 /// [`atomic`] signed integer types via the `fetch_min` method by passing
597 /// [`Ordering::Release`] as the `order`. For example, [`AtomicI32::fetch_min`].
598 pub fn atomic_min_release<T: Copy>(dst: *mut T, src: T) -> T;
599 /// Minimum with the current value using a signed comparison.
601 /// The stabilized version of this intrinsic is available on the
602 /// [`atomic`] signed integer types via the `fetch_min` method by passing
603 /// [`Ordering::AcqRel`] as the `order`. For example, [`AtomicI32::fetch_min`].
604 pub fn atomic_min_acqrel<T: Copy>(dst: *mut T, src: T) -> T;
605 /// Minimum with the current value using a signed comparison.
607 /// The stabilized version of this intrinsic is available on the
608 /// [`atomic`] signed integer types via the `fetch_min` method by passing
609 /// [`Ordering::Relaxed`] as the `order`. For example, [`AtomicI32::fetch_min`].
610 pub fn atomic_min_relaxed<T: Copy>(dst: *mut T, src: T) -> T;
612 /// Minimum with the current value using an unsigned comparison.
614 /// The stabilized version of this intrinsic is available on the
615 /// [`atomic`] unsigned integer types via the `fetch_min` method by passing
616 /// [`Ordering::SeqCst`] as the `order`. For example, [`AtomicU32::fetch_min`].
617 pub fn atomic_umin_seqcst<T: Copy>(dst: *mut T, src: T) -> T;
618 /// Minimum with the current value using an unsigned comparison.
620 /// The stabilized version of this intrinsic is available on the
621 /// [`atomic`] unsigned integer types via the `fetch_min` method by passing
622 /// [`Ordering::Acquire`] as the `order`. For example, [`AtomicU32::fetch_min`].
623 pub fn atomic_umin_acquire<T: Copy>(dst: *mut T, src: T) -> T;
624 /// Minimum with the current value using an unsigned comparison.
626 /// The stabilized version of this intrinsic is available on the
627 /// [`atomic`] unsigned integer types via the `fetch_min` method by passing
628 /// [`Ordering::Release`] as the `order`. For example, [`AtomicU32::fetch_min`].
629 pub fn atomic_umin_release<T: Copy>(dst: *mut T, src: T) -> T;
630 /// Minimum with the current value using an unsigned comparison.
632 /// The stabilized version of this intrinsic is available on the
633 /// [`atomic`] unsigned integer types via the `fetch_min` method by passing
634 /// [`Ordering::AcqRel`] as the `order`. For example, [`AtomicU32::fetch_min`].
635 pub fn atomic_umin_acqrel<T: Copy>(dst: *mut T, src: T) -> T;
636 /// Minimum with the current value using an unsigned comparison.
638 /// The stabilized version of this intrinsic is available on the
639 /// [`atomic`] unsigned integer types via the `fetch_min` method by passing
640 /// [`Ordering::Relaxed`] as the `order`. For example, [`AtomicU32::fetch_min`].
641 pub fn atomic_umin_relaxed<T: Copy>(dst: *mut T, src: T) -> T;
643 /// Maximum with the current value using an unsigned comparison.
645 /// The stabilized version of this intrinsic is available on the
646 /// [`atomic`] unsigned integer types via the `fetch_max` method by passing
647 /// [`Ordering::SeqCst`] as the `order`. For example, [`AtomicU32::fetch_max`].
648 pub fn atomic_umax_seqcst<T: Copy>(dst: *mut T, src: T) -> T;
649 /// Maximum with the current value using an unsigned comparison.
651 /// The stabilized version of this intrinsic is available on the
652 /// [`atomic`] unsigned integer types via the `fetch_max` method by passing
653 /// [`Ordering::Acquire`] as the `order`. For example, [`AtomicU32::fetch_max`].
654 pub fn atomic_umax_acquire<T: Copy>(dst: *mut T, src: T) -> T;
655 /// Maximum with the current value using an unsigned comparison.
657 /// The stabilized version of this intrinsic is available on the
658 /// [`atomic`] unsigned integer types via the `fetch_max` method by passing
659 /// [`Ordering::Release`] as the `order`. For example, [`AtomicU32::fetch_max`].
660 pub fn atomic_umax_release<T: Copy>(dst: *mut T, src: T) -> T;
661 /// Maximum with the current value using an unsigned comparison.
663 /// The stabilized version of this intrinsic is available on the
664 /// [`atomic`] unsigned integer types via the `fetch_max` method by passing
665 /// [`Ordering::AcqRel`] as the `order`. For example, [`AtomicU32::fetch_max`].
666 pub fn atomic_umax_acqrel<T: Copy>(dst: *mut T, src: T) -> T;
667 /// Maximum with the current value using an unsigned comparison.
669 /// The stabilized version of this intrinsic is available on the
670 /// [`atomic`] unsigned integer types via the `fetch_max` method by passing
671 /// [`Ordering::Relaxed`] as the `order`. For example, [`AtomicU32::fetch_max`].
672 pub fn atomic_umax_relaxed<T: Copy>(dst: *mut T, src: T) -> T;
676 /// The stabilized version of this intrinsic is available in
677 /// [`atomic::fence`] by passing [`Ordering::SeqCst`]
679 pub fn atomic_fence_seqcst();
682 /// The stabilized version of this intrinsic is available in
683 /// [`atomic::fence`] by passing [`Ordering::Acquire`]
685 pub fn atomic_fence_acquire();
688 /// The stabilized version of this intrinsic is available in
689 /// [`atomic::fence`] by passing [`Ordering::Release`]
691 pub fn atomic_fence_release();
694 /// The stabilized version of this intrinsic is available in
695 /// [`atomic::fence`] by passing [`Ordering::AcqRel`]
697 pub fn atomic_fence_acqrel();
699 /// A compiler-only memory barrier.
701 /// Memory accesses will never be reordered across this barrier by the
702 /// compiler, but no instructions will be emitted for it. This is
703 /// appropriate for operations on the same thread that may be preempted,
704 /// such as when interacting with signal handlers.
706 /// The stabilized version of this intrinsic is available in
707 /// [`atomic::compiler_fence`] by passing [`Ordering::SeqCst`]
709 pub fn atomic_singlethreadfence_seqcst();
710 /// A compiler-only memory barrier.
712 /// Memory accesses will never be reordered across this barrier by the
713 /// compiler, but no instructions will be emitted for it. This is
714 /// appropriate for operations on the same thread that may be preempted,
715 /// such as when interacting with signal handlers.
717 /// The stabilized version of this intrinsic is available in
718 /// [`atomic::compiler_fence`] by passing [`Ordering::Acquire`]
720 pub fn atomic_singlethreadfence_acquire();
721 /// A compiler-only memory barrier.
723 /// Memory accesses will never be reordered across this barrier by the
724 /// compiler, but no instructions will be emitted for it. This is
725 /// appropriate for operations on the same thread that may be preempted,
726 /// such as when interacting with signal handlers.
728 /// The stabilized version of this intrinsic is available in
729 /// [`atomic::compiler_fence`] by passing [`Ordering::Release`]
731 pub fn atomic_singlethreadfence_release();
732 /// A compiler-only memory barrier.
734 /// Memory accesses will never be reordered across this barrier by the
735 /// compiler, but no instructions will be emitted for it. This is
736 /// appropriate for operations on the same thread that may be preempted,
737 /// such as when interacting with signal handlers.
739 /// The stabilized version of this intrinsic is available in
740 /// [`atomic::compiler_fence`] by passing [`Ordering::AcqRel`]
742 pub fn atomic_singlethreadfence_acqrel();
744 /// The `prefetch` intrinsic is a hint to the code generator to insert a prefetch instruction
745 /// if supported; otherwise, it is a no-op.
746 /// Prefetches have no effect on the behavior of the program but can change its performance
749 /// The `locality` argument must be a constant integer and is a temporal locality specifier
750 /// ranging from (0) - no locality, to (3) - extremely local keep in cache.
752 /// This intrinsic does not have a stable counterpart.
753 pub fn prefetch_read_data<T>(data: *const T, locality: i32);
754 /// The `prefetch` intrinsic is a hint to the code generator to insert a prefetch instruction
755 /// if supported; otherwise, it is a no-op.
756 /// Prefetches have no effect on the behavior of the program but can change its performance
759 /// The `locality` argument must be a constant integer and is a temporal locality specifier
760 /// ranging from (0) - no locality, to (3) - extremely local keep in cache.
762 /// This intrinsic does not have a stable counterpart.
763 pub fn prefetch_write_data<T>(data: *const T, locality: i32);
764 /// The `prefetch` intrinsic is a hint to the code generator to insert a prefetch instruction
765 /// if supported; otherwise, it is a no-op.
766 /// Prefetches have no effect on the behavior of the program but can change its performance
769 /// The `locality` argument must be a constant integer and is a temporal locality specifier
770 /// ranging from (0) - no locality, to (3) - extremely local keep in cache.
772 /// This intrinsic does not have a stable counterpart.
773 pub fn prefetch_read_instruction<T>(data: *const T, locality: i32);
774 /// The `prefetch` intrinsic is a hint to the code generator to insert a prefetch instruction
775 /// if supported; otherwise, it is a no-op.
776 /// Prefetches have no effect on the behavior of the program but can change its performance
779 /// The `locality` argument must be a constant integer and is a temporal locality specifier
780 /// ranging from (0) - no locality, to (3) - extremely local keep in cache.
782 /// This intrinsic does not have a stable counterpart.
783 pub fn prefetch_write_instruction<T>(data: *const T, locality: i32);
785 /// Magic intrinsic that derives its meaning from attributes
786 /// attached to the function.
788 /// For example, dataflow uses this to inject static assertions so
789 /// that `rustc_peek(potentially_uninitialized)` would actually
790 /// double-check that dataflow did indeed compute that it is
791 /// uninitialized at that point in the control flow.
793 /// This intrinsic should not be used outside of the compiler.
794 #[rustc_safe_intrinsic]
795 pub fn rustc_peek<T>(_: T) -> T;
797 /// Aborts the execution of the process.
799 /// Note that, unlike most intrinsics, this is safe to call;
800 /// it does not require an `unsafe` block.
801 /// Therefore, implementations must not require the user to uphold
802 /// any safety invariants.
804 /// [`std::process::abort`](../../std/process/fn.abort.html) is to be preferred if possible,
805 /// as its behavior is more user-friendly and more stable.
807 /// The current implementation of `intrinsics::abort` is to invoke an invalid instruction,
808 /// on most platforms.
810 /// process will probably terminate with a signal like `SIGABRT`, `SIGILL`, `SIGTRAP`, `SIGSEGV` or
811 /// `SIGBUS`. The precise behaviour is not guaranteed and not stable.
812 #[rustc_safe_intrinsic]
815 /// Informs the optimizer that this point in the code is not reachable,
816 /// enabling further optimizations.
818 /// N.B., this is very different from the `unreachable!()` macro: Unlike the
819 /// macro, which panics when it is executed, it is *undefined behavior* to
820 /// reach code marked with this function.
822 /// The stabilized version of this intrinsic is [`core::hint::unreachable_unchecked`].
823 #[rustc_const_stable(feature = "const_unreachable_unchecked", since = "1.57.0")]
824 pub fn unreachable() -> !;
826 /// Informs the optimizer that a condition is always true.
827 /// If the condition is false, the behavior is undefined.
829 /// No code is generated for this intrinsic, but the optimizer will try
830 /// to preserve it (and its condition) between passes, which may interfere
831 /// with optimization of surrounding code and reduce performance. It should
832 /// not be used if the invariant can be discovered by the optimizer on its
833 /// own, or if it does not enable any significant optimizations.
835 /// This intrinsic does not have a stable counterpart.
836 #[rustc_const_unstable(feature = "const_assume", issue = "76972")]
837 pub fn assume(b: bool);
839 /// Hints to the compiler that branch condition is likely to be true.
840 /// Returns the value passed to it.
842 /// Any use other than with `if` statements will probably not have an effect.
844 /// Note that, unlike most intrinsics, this is safe to call;
845 /// it does not require an `unsafe` block.
846 /// Therefore, implementations must not require the user to uphold
847 /// any safety invariants.
849 /// This intrinsic does not have a stable counterpart.
850 #[rustc_const_unstable(feature = "const_likely", issue = "none")]
851 #[rustc_safe_intrinsic]
852 pub fn likely(b: bool) -> bool;
854 /// Hints to the compiler that branch condition is likely to be false.
855 /// Returns the value passed to it.
857 /// Any use other than with `if` statements will probably not have an effect.
859 /// Note that, unlike most intrinsics, this is safe to call;
860 /// it does not require an `unsafe` block.
861 /// Therefore, implementations must not require the user to uphold
862 /// any safety invariants.
864 /// This intrinsic does not have a stable counterpart.
865 #[rustc_const_unstable(feature = "const_likely", issue = "none")]
866 #[rustc_safe_intrinsic]
867 pub fn unlikely(b: bool) -> bool;
869 /// Executes a breakpoint trap, for inspection by a debugger.
871 /// This intrinsic does not have a stable counterpart.
874 /// The size of a type in bytes.
876 /// Note that, unlike most intrinsics, this is safe to call;
877 /// it does not require an `unsafe` block.
878 /// Therefore, implementations must not require the user to uphold
879 /// any safety invariants.
881 /// More specifically, this is the offset in bytes between successive
882 /// items of the same type, including alignment padding.
884 /// The stabilized version of this intrinsic is [`core::mem::size_of`].
885 #[rustc_const_stable(feature = "const_size_of", since = "1.40.0")]
886 #[rustc_safe_intrinsic]
887 pub fn size_of<T>() -> usize;
889 /// The minimum alignment of a type.
891 /// Note that, unlike most intrinsics, this is safe to call;
892 /// it does not require an `unsafe` block.
893 /// Therefore, implementations must not require the user to uphold
894 /// any safety invariants.
896 /// The stabilized version of this intrinsic is [`core::mem::align_of`].
897 #[rustc_const_stable(feature = "const_min_align_of", since = "1.40.0")]
898 #[rustc_safe_intrinsic]
899 pub fn min_align_of<T>() -> usize;
900 /// The preferred alignment of a type.
902 /// This intrinsic does not have a stable counterpart.
903 /// It's "tracking issue" is [#91971](https://github.com/rust-lang/rust/issues/91971).
904 #[rustc_const_unstable(feature = "const_pref_align_of", issue = "91971")]
905 pub fn pref_align_of<T>() -> usize;
907 /// The size of the referenced value in bytes.
909 /// The stabilized version of this intrinsic is [`mem::size_of_val`].
910 #[rustc_const_unstable(feature = "const_size_of_val", issue = "46571")]
911 pub fn size_of_val<T: ?Sized>(_: *const T) -> usize;
912 /// The required alignment of the referenced value.
914 /// The stabilized version of this intrinsic is [`core::mem::align_of_val`].
915 #[rustc_const_unstable(feature = "const_align_of_val", issue = "46571")]
916 pub fn min_align_of_val<T: ?Sized>(_: *const T) -> usize;
918 /// Gets a static string slice containing the name of a type.
920 /// Note that, unlike most intrinsics, this is safe to call;
921 /// it does not require an `unsafe` block.
922 /// Therefore, implementations must not require the user to uphold
923 /// any safety invariants.
925 /// The stabilized version of this intrinsic is [`core::any::type_name`].
926 #[rustc_const_unstable(feature = "const_type_name", issue = "63084")]
927 #[rustc_safe_intrinsic]
928 pub fn type_name<T: ?Sized>() -> &'static str;
930 /// Gets an identifier which is globally unique to the specified type. This
931 /// function will return the same value for a type regardless of whichever
932 /// crate it is invoked in.
934 /// Note that, unlike most intrinsics, this is safe to call;
935 /// it does not require an `unsafe` block.
936 /// Therefore, implementations must not require the user to uphold
937 /// any safety invariants.
939 /// The stabilized version of this intrinsic is [`core::any::TypeId::of`].
940 #[rustc_const_unstable(feature = "const_type_id", issue = "77125")]
941 #[rustc_safe_intrinsic]
942 pub fn type_id<T: ?Sized + 'static>() -> u64;
944 /// A guard for unsafe functions that cannot ever be executed if `T` is uninhabited:
945 /// This will statically either panic, or do nothing.
947 /// This intrinsic does not have a stable counterpart.
948 #[rustc_const_stable(feature = "const_assert_type", since = "1.59.0")]
949 #[rustc_safe_intrinsic]
950 pub fn assert_inhabited<T>();
952 /// A guard for unsafe functions that cannot ever be executed if `T` does not permit
953 /// zero-initialization: This will statically either panic, or do nothing.
955 /// This intrinsic does not have a stable counterpart.
956 #[rustc_const_unstable(feature = "const_assert_type2", issue = "none")]
957 #[rustc_safe_intrinsic]
958 pub fn assert_zero_valid<T>();
960 /// A guard for `std::mem::uninitialized`. This will statically either panic, or do nothing.
962 /// This intrinsic does not have a stable counterpart.
963 #[rustc_const_unstable(feature = "const_assert_type2", issue = "none")]
964 #[rustc_safe_intrinsic]
965 pub fn assert_mem_uninitialized_valid<T>();
967 /// Gets a reference to a static `Location` indicating where it was called.
969 /// Note that, unlike most intrinsics, this is safe to call;
970 /// it does not require an `unsafe` block.
971 /// Therefore, implementations must not require the user to uphold
972 /// any safety invariants.
974 /// Consider using [`core::panic::Location::caller`] instead.
975 #[rustc_const_unstable(feature = "const_caller_location", issue = "76156")]
976 #[rustc_safe_intrinsic]
977 pub fn caller_location() -> &'static crate::panic::Location<'static>;
979 /// Moves a value out of scope without running drop glue.
981 /// This exists solely for [`mem::forget_unsized`]; normal `forget` uses
982 /// `ManuallyDrop` instead.
984 /// Note that, unlike most intrinsics, this is safe to call;
985 /// it does not require an `unsafe` block.
986 /// Therefore, implementations must not require the user to uphold
987 /// any safety invariants.
988 #[rustc_const_unstable(feature = "const_intrinsic_forget", issue = "none")]
989 #[rustc_safe_intrinsic]
990 pub fn forget<T: ?Sized>(_: T);
992 /// Reinterprets the bits of a value of one type as another type.
994 /// Both types must have the same size. Compilation will fail if this is not guaranteed.
996 /// `transmute` is semantically equivalent to a bitwise move of one type
997 /// into another. It copies the bits from the source value into the
998 /// destination value, then forgets the original. Note that source and destination
999 /// are passed by-value, which means if `Src` or `Dst` contain padding, that padding
1000 /// is *not* guaranteed to be preserved by `transmute`.
1002 /// Both the argument and the result must be [valid](../../nomicon/what-unsafe-does.html) at
1003 /// their given type. Violating this condition leads to [undefined behavior][ub]. The compiler
1004 /// will generate code *assuming that you, the programmer, ensure that there will never be
1005 /// undefined behavior*. It is therefore your responsibility to guarantee that every value
1006 /// passed to `transmute` is valid at both types `Src` and `Dst`. Failing to uphold this condition
1007 /// may lead to unexpected and unstable compilation results. This makes `transmute` **incredibly
1008 /// unsafe**. `transmute` should be the absolute last resort.
1010 /// Transmuting pointers to integers in a `const` context is [undefined behavior][ub].
1011 /// Any attempt to use the resulting value for integer operations will abort const-evaluation.
1012 /// (And even outside `const`, such transmutation is touching on many unspecified aspects of the
1013 /// Rust memory model and should be avoided. See below for alternatives.)
1015 /// Because `transmute` is a by-value operation, alignment of the *transmuted values
1016 /// themselves* is not a concern. As with any other function, the compiler already ensures
1017 /// both `Src` and `Dst` are properly aligned. However, when transmuting values that *point
1018 /// elsewhere* (such as pointers, references, boxes…), the caller has to ensure proper
1019 /// alignment of the pointed-to values.
1021 /// The [nomicon](../../nomicon/transmutes.html) has additional documentation.
1023 /// [ub]: ../../reference/behavior-considered-undefined.html
1027 /// There are a few things that `transmute` is really useful for.
1029 /// Turning a pointer into a function pointer. This is *not* portable to
1030 /// machines where function pointers and data pointers have different sizes.
1033 /// fn foo() -> i32 {
1036 /// // Crucially, we `as`-cast to a raw pointer before `transmute`ing to a function pointer.
1037 /// // This avoids an integer-to-pointer `transmute`, which can be problematic.
1038 /// // Transmuting between raw pointers and function pointers (i.e., two pointer types) is fine.
1039 /// let pointer = foo as *const ();
1040 /// let function = unsafe {
1041 /// std::mem::transmute::<*const (), fn() -> i32>(pointer)
1043 /// assert_eq!(function(), 0);
1046 /// Extending a lifetime, or shortening an invariant lifetime. This is
1047 /// advanced, very unsafe Rust!
1050 /// struct R<'a>(&'a i32);
1051 /// unsafe fn extend_lifetime<'b>(r: R<'b>) -> R<'static> {
1052 /// std::mem::transmute::<R<'b>, R<'static>>(r)
1055 /// unsafe fn shorten_invariant_lifetime<'b, 'c>(r: &'b mut R<'static>)
1056 /// -> &'b mut R<'c> {
1057 /// std::mem::transmute::<&'b mut R<'static>, &'b mut R<'c>>(r)
1063 /// Don't despair: many uses of `transmute` can be achieved through other means.
1064 /// Below are common applications of `transmute` which can be replaced with safer
1067 /// Turning raw bytes (`&[u8]`) into `u32`, `f64`, etc.:
1070 /// let raw_bytes = [0x78, 0x56, 0x34, 0x12];
1072 /// let num = unsafe {
1073 /// std::mem::transmute::<[u8; 4], u32>(raw_bytes)
1076 /// // use `u32::from_ne_bytes` instead
1077 /// let num = u32::from_ne_bytes(raw_bytes);
1078 /// // or use `u32::from_le_bytes` or `u32::from_be_bytes` to specify the endianness
1079 /// let num = u32::from_le_bytes(raw_bytes);
1080 /// assert_eq!(num, 0x12345678);
1081 /// let num = u32::from_be_bytes(raw_bytes);
1082 /// assert_eq!(num, 0x78563412);
1085 /// Turning a pointer into a `usize`:
1089 /// let ptr_num_transmute = unsafe {
1090 /// std::mem::transmute::<&i32, usize>(ptr)
1093 /// // Use an `as` cast instead
1094 /// let ptr_num_cast = ptr as *const i32 as usize;
1097 /// Note that using `transmute` to turn a pointer to a `usize` is (as noted above) [undefined
1098 /// behavior][ub] in `const` contexts. Also outside of consts, this operation might not behave
1099 /// as expected -- this is touching on many unspecified aspects of the Rust memory model.
1100 /// Depending on what the code is doing, the following alternatives are preferable to
1101 /// pointer-to-integer transmutation:
1102 /// - If the code just wants to store data of arbitrary type in some buffer and needs to pick a
1103 /// type for that buffer, it can use [`MaybeUninit`][mem::MaybeUninit].
1104 /// - If the code actually wants to work on the address the pointer points to, it can use `as`
1105 /// casts or [`ptr.addr()`][pointer::addr].
1107 /// Turning a `*mut T` into an `&mut T`:
1110 /// let ptr: *mut i32 = &mut 0;
1111 /// let ref_transmuted = unsafe {
1112 /// std::mem::transmute::<*mut i32, &mut i32>(ptr)
1115 /// // Use a reborrow instead
1116 /// let ref_casted = unsafe { &mut *ptr };
1119 /// Turning an `&mut T` into an `&mut U`:
1122 /// let ptr = &mut 0;
1123 /// let val_transmuted = unsafe {
1124 /// std::mem::transmute::<&mut i32, &mut u32>(ptr)
1127 /// // Now, put together `as` and reborrowing - note the chaining of `as`
1128 /// // `as` is not transitive
1129 /// let val_casts = unsafe { &mut *(ptr as *mut i32 as *mut u32) };
1132 /// Turning an `&str` into a `&[u8]`:
1135 /// // this is not a good way to do this.
1136 /// let slice = unsafe { std::mem::transmute::<&str, &[u8]>("Rust") };
1137 /// assert_eq!(slice, &[82, 117, 115, 116]);
1139 /// // You could use `str::as_bytes`
1140 /// let slice = "Rust".as_bytes();
1141 /// assert_eq!(slice, &[82, 117, 115, 116]);
1143 /// // Or, just use a byte string, if you have control over the string
1145 /// assert_eq!(b"Rust", &[82, 117, 115, 116]);
1148 /// Turning a `Vec<&T>` into a `Vec<Option<&T>>`.
1150 /// To transmute the inner type of the contents of a container, you must make sure to not
1151 /// violate any of the container's invariants. For `Vec`, this means that both the size
1152 /// *and alignment* of the inner types have to match. Other containers might rely on the
1153 /// size of the type, alignment, or even the `TypeId`, in which case transmuting wouldn't
1154 /// be possible at all without violating the container invariants.
1157 /// let store = [0, 1, 2, 3];
1158 /// let v_orig = store.iter().collect::<Vec<&i32>>();
1160 /// // clone the vector as we will reuse them later
1161 /// let v_clone = v_orig.clone();
1163 /// // Using transmute: this relies on the unspecified data layout of `Vec`, which is a
1164 /// // bad idea and could cause Undefined Behavior.
1165 /// // However, it is no-copy.
1166 /// let v_transmuted = unsafe {
1167 /// std::mem::transmute::<Vec<&i32>, Vec<Option<&i32>>>(v_clone)
1170 /// let v_clone = v_orig.clone();
1172 /// // This is the suggested, safe way.
1173 /// // It does copy the entire vector, though, into a new array.
1174 /// let v_collected = v_clone.into_iter()
1176 /// .collect::<Vec<Option<&i32>>>();
1178 /// let v_clone = v_orig.clone();
1180 /// // This is the proper no-copy, unsafe way of "transmuting" a `Vec`, without relying on the
1181 /// // data layout. Instead of literally calling `transmute`, we perform a pointer cast, but
1182 /// // in terms of converting the original inner type (`&i32`) to the new one (`Option<&i32>`),
1183 /// // this has all the same caveats. Besides the information provided above, also consult the
1184 /// // [`from_raw_parts`] documentation.
1185 /// let v_from_raw = unsafe {
1186 // FIXME Update this when vec_into_raw_parts is stabilized
1187 /// // Ensure the original vector is not dropped.
1188 /// let mut v_clone = std::mem::ManuallyDrop::new(v_clone);
1189 /// Vec::from_raw_parts(v_clone.as_mut_ptr() as *mut Option<&i32>,
1191 /// v_clone.capacity())
1195 /// [`from_raw_parts`]: ../../std/vec/struct.Vec.html#method.from_raw_parts
1197 /// Implementing `split_at_mut`:
1200 /// use std::{slice, mem};
1202 /// // There are multiple ways to do this, and there are multiple problems
1203 /// // with the following (transmute) way.
1204 /// fn split_at_mut_transmute<T>(slice: &mut [T], mid: usize)
1205 /// -> (&mut [T], &mut [T]) {
1206 /// let len = slice.len();
1207 /// assert!(mid <= len);
1209 /// let slice2 = mem::transmute::<&mut [T], &mut [T]>(slice);
1210 /// // first: transmute is not type safe; all it checks is that T and
1211 /// // U are of the same size. Second, right here, you have two
1212 /// // mutable references pointing to the same memory.
1213 /// (&mut slice[0..mid], &mut slice2[mid..len])
1217 /// // This gets rid of the type safety problems; `&mut *` will *only* give
1218 /// // you an `&mut T` from an `&mut T` or `*mut T`.
1219 /// fn split_at_mut_casts<T>(slice: &mut [T], mid: usize)
1220 /// -> (&mut [T], &mut [T]) {
1221 /// let len = slice.len();
1222 /// assert!(mid <= len);
1224 /// let slice2 = &mut *(slice as *mut [T]);
1225 /// // however, you still have two mutable references pointing to
1226 /// // the same memory.
1227 /// (&mut slice[0..mid], &mut slice2[mid..len])
1231 /// // This is how the standard library does it. This is the best method, if
1232 /// // you need to do something like this
1233 /// fn split_at_stdlib<T>(slice: &mut [T], mid: usize)
1234 /// -> (&mut [T], &mut [T]) {
1235 /// let len = slice.len();
1236 /// assert!(mid <= len);
1238 /// let ptr = slice.as_mut_ptr();
1239 /// // This now has three mutable references pointing at the same
1240 /// // memory. `slice`, the rvalue ret.0, and the rvalue ret.1.
1241 /// // `slice` is never used after `let ptr = ...`, and so one can
1242 /// // treat it as "dead", and therefore, you only have two real
1243 /// // mutable slices.
1244 /// (slice::from_raw_parts_mut(ptr, mid),
1245 /// slice::from_raw_parts_mut(ptr.add(mid), len - mid))
1249 #[stable(feature = "rust1", since = "1.0.0")]
1250 #[rustc_allowed_through_unstable_modules]
1251 #[rustc_const_stable(feature = "const_transmute", since = "1.56.0")]
1252 #[rustc_diagnostic_item = "transmute"]
1253 pub fn transmute<Src, Dst>(src: Src) -> Dst;
1255 /// Returns `true` if the actual type given as `T` requires drop
1256 /// glue; returns `false` if the actual type provided for `T`
1257 /// implements `Copy`.
1259 /// If the actual type neither requires drop glue nor implements
1260 /// `Copy`, then the return value of this function is unspecified.
1262 /// Note that, unlike most intrinsics, this is safe to call;
1263 /// it does not require an `unsafe` block.
1264 /// Therefore, implementations must not require the user to uphold
1265 /// any safety invariants.
1267 /// The stabilized version of this intrinsic is [`mem::needs_drop`](crate::mem::needs_drop).
1268 #[rustc_const_stable(feature = "const_needs_drop", since = "1.40.0")]
1269 #[rustc_safe_intrinsic]
1270 pub fn needs_drop<T: ?Sized>() -> bool;
1272 /// Calculates the offset from a pointer.
1274 /// This is implemented as an intrinsic to avoid converting to and from an
1275 /// integer, since the conversion would throw away aliasing information.
1279 /// Both the starting and resulting pointer must be either in bounds or one
1280 /// byte past the end of an allocated object. If either pointer is out of
1281 /// bounds or arithmetic overflow occurs then any further use of the
1282 /// returned value will result in undefined behavior.
1284 /// The stabilized version of this intrinsic is [`pointer::offset`].
1285 #[must_use = "returns a new pointer rather than modifying its argument"]
1286 #[rustc_const_stable(feature = "const_ptr_offset", since = "1.61.0")]
1287 pub fn offset<T>(dst: *const T, offset: isize) -> *const T;
1289 /// Calculates the offset from a pointer, potentially wrapping.
1291 /// This is implemented as an intrinsic to avoid converting to and from an
1292 /// integer, since the conversion inhibits certain optimizations.
1296 /// Unlike the `offset` intrinsic, this intrinsic does not restrict the
1297 /// resulting pointer to point into or one byte past the end of an allocated
1298 /// object, and it wraps with two's complement arithmetic. The resulting
1299 /// value is not necessarily valid to be used to actually access memory.
1301 /// The stabilized version of this intrinsic is [`pointer::wrapping_offset`].
1302 #[must_use = "returns a new pointer rather than modifying its argument"]
1303 #[rustc_const_stable(feature = "const_ptr_offset", since = "1.61.0")]
1304 pub fn arith_offset<T>(dst: *const T, offset: isize) -> *const T;
1306 /// Masks out bits of the pointer according to a mask.
1308 /// Note that, unlike most intrinsics, this is safe to call;
1309 /// it does not require an `unsafe` block.
1310 /// Therefore, implementations must not require the user to uphold
1311 /// any safety invariants.
1313 /// Consider using [`pointer::mask`] instead.
1314 #[rustc_safe_intrinsic]
1315 pub fn ptr_mask<T>(ptr: *const T, mask: usize) -> *const T;
1317 /// Equivalent to the appropriate `llvm.memcpy.p0i8.0i8.*` intrinsic, with
1318 /// a size of `count` * `size_of::<T>()` and an alignment of
1319 /// `min_align_of::<T>()`
1321 /// The volatile parameter is set to `true`, so it will not be optimized out
1322 /// unless size is equal to zero.
1324 /// This intrinsic does not have a stable counterpart.
1325 pub fn volatile_copy_nonoverlapping_memory<T>(dst: *mut T, src: *const T, count: usize);
1326 /// Equivalent to the appropriate `llvm.memmove.p0i8.0i8.*` intrinsic, with
1327 /// a size of `count * size_of::<T>()` and an alignment of
1328 /// `min_align_of::<T>()`
1330 /// The volatile parameter is set to `true`, so it will not be optimized out
1331 /// unless size is equal to zero.
1333 /// This intrinsic does not have a stable counterpart.
1334 pub fn volatile_copy_memory<T>(dst: *mut T, src: *const T, count: usize);
1335 /// Equivalent to the appropriate `llvm.memset.p0i8.*` intrinsic, with a
1336 /// size of `count * size_of::<T>()` and an alignment of
1337 /// `min_align_of::<T>()`.
1339 /// The volatile parameter is set to `true`, so it will not be optimized out
1340 /// unless size is equal to zero.
1342 /// This intrinsic does not have a stable counterpart.
1343 pub fn volatile_set_memory<T>(dst: *mut T, val: u8, count: usize);
1345 /// Performs a volatile load from the `src` pointer.
1347 /// The stabilized version of this intrinsic is [`core::ptr::read_volatile`].
1348 pub fn volatile_load<T>(src: *const T) -> T;
1349 /// Performs a volatile store to the `dst` pointer.
1351 /// The stabilized version of this intrinsic is [`core::ptr::write_volatile`].
1352 pub fn volatile_store<T>(dst: *mut T, val: T);
1354 /// Performs a volatile load from the `src` pointer
1355 /// The pointer is not required to be aligned.
1357 /// This intrinsic does not have a stable counterpart.
1358 pub fn unaligned_volatile_load<T>(src: *const T) -> T;
1359 /// Performs a volatile store to the `dst` pointer.
1360 /// The pointer is not required to be aligned.
1362 /// This intrinsic does not have a stable counterpart.
1363 pub fn unaligned_volatile_store<T>(dst: *mut T, val: T);
1365 /// Returns the square root of an `f32`
1367 /// The stabilized version of this intrinsic is
1368 /// [`f32::sqrt`](../../std/primitive.f32.html#method.sqrt)
1369 pub fn sqrtf32(x: f32) -> f32;
1370 /// Returns the square root of an `f64`
1372 /// The stabilized version of this intrinsic is
1373 /// [`f64::sqrt`](../../std/primitive.f64.html#method.sqrt)
1374 pub fn sqrtf64(x: f64) -> f64;
1376 /// Raises an `f32` to an integer power.
1378 /// The stabilized version of this intrinsic is
1379 /// [`f32::powi`](../../std/primitive.f32.html#method.powi)
1380 pub fn powif32(a: f32, x: i32) -> f32;
1381 /// Raises an `f64` to an integer power.
1383 /// The stabilized version of this intrinsic is
1384 /// [`f64::powi`](../../std/primitive.f64.html#method.powi)
1385 pub fn powif64(a: f64, x: i32) -> f64;
1387 /// Returns the sine of an `f32`.
1389 /// The stabilized version of this intrinsic is
1390 /// [`f32::sin`](../../std/primitive.f32.html#method.sin)
1391 pub fn sinf32(x: f32) -> f32;
1392 /// Returns the sine of an `f64`.
1394 /// The stabilized version of this intrinsic is
1395 /// [`f64::sin`](../../std/primitive.f64.html#method.sin)
1396 pub fn sinf64(x: f64) -> f64;
1398 /// Returns the cosine of an `f32`.
1400 /// The stabilized version of this intrinsic is
1401 /// [`f32::cos`](../../std/primitive.f32.html#method.cos)
1402 pub fn cosf32(x: f32) -> f32;
1403 /// Returns the cosine of an `f64`.
1405 /// The stabilized version of this intrinsic is
1406 /// [`f64::cos`](../../std/primitive.f64.html#method.cos)
1407 pub fn cosf64(x: f64) -> f64;
1409 /// Raises an `f32` to an `f32` power.
1411 /// The stabilized version of this intrinsic is
1412 /// [`f32::powf`](../../std/primitive.f32.html#method.powf)
1413 pub fn powf32(a: f32, x: f32) -> f32;
1414 /// Raises an `f64` to an `f64` power.
1416 /// The stabilized version of this intrinsic is
1417 /// [`f64::powf`](../../std/primitive.f64.html#method.powf)
1418 pub fn powf64(a: f64, x: f64) -> f64;
1420 /// Returns the exponential of an `f32`.
1422 /// The stabilized version of this intrinsic is
1423 /// [`f32::exp`](../../std/primitive.f32.html#method.exp)
1424 pub fn expf32(x: f32) -> f32;
1425 /// Returns the exponential of an `f64`.
1427 /// The stabilized version of this intrinsic is
1428 /// [`f64::exp`](../../std/primitive.f64.html#method.exp)
1429 pub fn expf64(x: f64) -> f64;
1431 /// Returns 2 raised to the power of an `f32`.
1433 /// The stabilized version of this intrinsic is
1434 /// [`f32::exp2`](../../std/primitive.f32.html#method.exp2)
1435 pub fn exp2f32(x: f32) -> f32;
1436 /// Returns 2 raised to the power of an `f64`.
1438 /// The stabilized version of this intrinsic is
1439 /// [`f64::exp2`](../../std/primitive.f64.html#method.exp2)
1440 pub fn exp2f64(x: f64) -> f64;
1442 /// Returns the natural logarithm of an `f32`.
1444 /// The stabilized version of this intrinsic is
1445 /// [`f32::ln`](../../std/primitive.f32.html#method.ln)
1446 pub fn logf32(x: f32) -> f32;
1447 /// Returns the natural logarithm of an `f64`.
1449 /// The stabilized version of this intrinsic is
1450 /// [`f64::ln`](../../std/primitive.f64.html#method.ln)
1451 pub fn logf64(x: f64) -> f64;
1453 /// Returns the base 10 logarithm of an `f32`.
1455 /// The stabilized version of this intrinsic is
1456 /// [`f32::log10`](../../std/primitive.f32.html#method.log10)
1457 pub fn log10f32(x: f32) -> f32;
1458 /// Returns the base 10 logarithm of an `f64`.
1460 /// The stabilized version of this intrinsic is
1461 /// [`f64::log10`](../../std/primitive.f64.html#method.log10)
1462 pub fn log10f64(x: f64) -> f64;
1464 /// Returns the base 2 logarithm of an `f32`.
1466 /// The stabilized version of this intrinsic is
1467 /// [`f32::log2`](../../std/primitive.f32.html#method.log2)
1468 pub fn log2f32(x: f32) -> f32;
1469 /// Returns the base 2 logarithm of an `f64`.
1471 /// The stabilized version of this intrinsic is
1472 /// [`f64::log2`](../../std/primitive.f64.html#method.log2)
1473 pub fn log2f64(x: f64) -> f64;
1475 /// Returns `a * b + c` for `f32` values.
1477 /// The stabilized version of this intrinsic is
1478 /// [`f32::mul_add`](../../std/primitive.f32.html#method.mul_add)
1479 pub fn fmaf32(a: f32, b: f32, c: f32) -> f32;
1480 /// Returns `a * b + c` for `f64` values.
1482 /// The stabilized version of this intrinsic is
1483 /// [`f64::mul_add`](../../std/primitive.f64.html#method.mul_add)
1484 pub fn fmaf64(a: f64, b: f64, c: f64) -> f64;
1486 /// Returns the absolute value of an `f32`.
1488 /// The stabilized version of this intrinsic is
1489 /// [`f32::abs`](../../std/primitive.f32.html#method.abs)
1490 pub fn fabsf32(x: f32) -> f32;
1491 /// Returns the absolute value of an `f64`.
1493 /// The stabilized version of this intrinsic is
1494 /// [`f64::abs`](../../std/primitive.f64.html#method.abs)
1495 pub fn fabsf64(x: f64) -> f64;
1497 /// Returns the minimum of two `f32` values.
1499 /// Note that, unlike most intrinsics, this is safe to call;
1500 /// it does not require an `unsafe` block.
1501 /// Therefore, implementations must not require the user to uphold
1502 /// any safety invariants.
1504 /// The stabilized version of this intrinsic is
1506 #[rustc_safe_intrinsic]
1507 pub fn minnumf32(x: f32, y: f32) -> f32;
1508 /// Returns the minimum of two `f64` values.
1510 /// Note that, unlike most intrinsics, this is safe to call;
1511 /// it does not require an `unsafe` block.
1512 /// Therefore, implementations must not require the user to uphold
1513 /// any safety invariants.
1515 /// The stabilized version of this intrinsic is
1517 #[rustc_safe_intrinsic]
1518 pub fn minnumf64(x: f64, y: f64) -> f64;
1519 /// Returns the maximum of two `f32` values.
1521 /// Note that, unlike most intrinsics, this is safe to call;
1522 /// it does not require an `unsafe` block.
1523 /// Therefore, implementations must not require the user to uphold
1524 /// any safety invariants.
1526 /// The stabilized version of this intrinsic is
1528 #[rustc_safe_intrinsic]
1529 pub fn maxnumf32(x: f32, y: f32) -> f32;
1530 /// Returns the maximum of two `f64` values.
1532 /// Note that, unlike most intrinsics, this is safe to call;
1533 /// it does not require an `unsafe` block.
1534 /// Therefore, implementations must not require the user to uphold
1535 /// any safety invariants.
1537 /// The stabilized version of this intrinsic is
1539 #[rustc_safe_intrinsic]
1540 pub fn maxnumf64(x: f64, y: f64) -> f64;
1542 /// Copies the sign from `y` to `x` for `f32` values.
1544 /// The stabilized version of this intrinsic is
1545 /// [`f32::copysign`](../../std/primitive.f32.html#method.copysign)
1546 pub fn copysignf32(x: f32, y: f32) -> f32;
1547 /// Copies the sign from `y` to `x` for `f64` values.
1549 /// The stabilized version of this intrinsic is
1550 /// [`f64::copysign`](../../std/primitive.f64.html#method.copysign)
1551 pub fn copysignf64(x: f64, y: f64) -> f64;
1553 /// Returns the largest integer less than or equal to an `f32`.
1555 /// The stabilized version of this intrinsic is
1556 /// [`f32::floor`](../../std/primitive.f32.html#method.floor)
1557 pub fn floorf32(x: f32) -> f32;
1558 /// Returns the largest integer less than or equal to an `f64`.
1560 /// The stabilized version of this intrinsic is
1561 /// [`f64::floor`](../../std/primitive.f64.html#method.floor)
1562 pub fn floorf64(x: f64) -> f64;
1564 /// Returns the smallest integer greater than or equal to an `f32`.
1566 /// The stabilized version of this intrinsic is
1567 /// [`f32::ceil`](../../std/primitive.f32.html#method.ceil)
1568 pub fn ceilf32(x: f32) -> f32;
1569 /// Returns the smallest integer greater than or equal to an `f64`.
1571 /// The stabilized version of this intrinsic is
1572 /// [`f64::ceil`](../../std/primitive.f64.html#method.ceil)
1573 pub fn ceilf64(x: f64) -> f64;
1575 /// Returns the integer part of an `f32`.
1577 /// The stabilized version of this intrinsic is
1578 /// [`f32::trunc`](../../std/primitive.f32.html#method.trunc)
1579 pub fn truncf32(x: f32) -> f32;
1580 /// Returns the integer part of an `f64`.
1582 /// The stabilized version of this intrinsic is
1583 /// [`f64::trunc`](../../std/primitive.f64.html#method.trunc)
1584 pub fn truncf64(x: f64) -> f64;
1586 /// Returns the nearest integer to an `f32`. May raise an inexact floating-point exception
1587 /// if the argument is not an integer.
1588 pub fn rintf32(x: f32) -> f32;
1589 /// Returns the nearest integer to an `f64`. May raise an inexact floating-point exception
1590 /// if the argument is not an integer.
1591 pub fn rintf64(x: f64) -> f64;
1593 /// Returns the nearest integer to an `f32`.
1595 /// This intrinsic does not have a stable counterpart.
1596 pub fn nearbyintf32(x: f32) -> f32;
1597 /// Returns the nearest integer to an `f64`.
1599 /// This intrinsic does not have a stable counterpart.
1600 pub fn nearbyintf64(x: f64) -> f64;
1602 /// Returns the nearest integer to an `f32`. Rounds half-way cases away from zero.
1604 /// The stabilized version of this intrinsic is
1605 /// [`f32::round`](../../std/primitive.f32.html#method.round)
1606 pub fn roundf32(x: f32) -> f32;
1607 /// Returns the nearest integer to an `f64`. Rounds half-way cases away from zero.
1609 /// The stabilized version of this intrinsic is
1610 /// [`f64::round`](../../std/primitive.f64.html#method.round)
1611 pub fn roundf64(x: f64) -> f64;
1613 /// Float addition that allows optimizations based on algebraic rules.
1614 /// May assume inputs are finite.
1616 /// This intrinsic does not have a stable counterpart.
1617 pub fn fadd_fast<T: Copy>(a: T, b: T) -> T;
1619 /// Float subtraction that allows optimizations based on algebraic rules.
1620 /// May assume inputs are finite.
1622 /// This intrinsic does not have a stable counterpart.
1623 pub fn fsub_fast<T: Copy>(a: T, b: T) -> T;
1625 /// Float multiplication that allows optimizations based on algebraic rules.
1626 /// May assume inputs are finite.
1628 /// This intrinsic does not have a stable counterpart.
1629 pub fn fmul_fast<T: Copy>(a: T, b: T) -> T;
1631 /// Float division that allows optimizations based on algebraic rules.
1632 /// May assume inputs are finite.
1634 /// This intrinsic does not have a stable counterpart.
1635 pub fn fdiv_fast<T: Copy>(a: T, b: T) -> T;
1637 /// Float remainder that allows optimizations based on algebraic rules.
1638 /// May assume inputs are finite.
1640 /// This intrinsic does not have a stable counterpart.
1641 pub fn frem_fast<T: Copy>(a: T, b: T) -> T;
1643 /// Convert with LLVM’s fptoui/fptosi, which may return undef for values out of range
1644 /// (<https://github.com/rust-lang/rust/issues/10184>)
1646 /// Stabilized as [`f32::to_int_unchecked`] and [`f64::to_int_unchecked`].
1647 pub fn float_to_int_unchecked<Float: Copy, Int: Copy>(value: Float) -> Int;
1649 /// Returns the number of bits set in an integer type `T`
1651 /// Note that, unlike most intrinsics, this is safe to call;
1652 /// it does not require an `unsafe` block.
1653 /// Therefore, implementations must not require the user to uphold
1654 /// any safety invariants.
1656 /// The stabilized versions of this intrinsic are available on the integer
1657 /// primitives via the `count_ones` method. For example,
1658 /// [`u32::count_ones`]
1659 #[rustc_const_stable(feature = "const_ctpop", since = "1.40.0")]
1660 #[rustc_safe_intrinsic]
1661 pub fn ctpop<T: Copy>(x: T) -> T;
1663 /// Returns the number of leading unset bits (zeroes) in an integer type `T`.
1665 /// Note that, unlike most intrinsics, this is safe to call;
1666 /// it does not require an `unsafe` block.
1667 /// Therefore, implementations must not require the user to uphold
1668 /// any safety invariants.
1670 /// The stabilized versions of this intrinsic are available on the integer
1671 /// primitives via the `leading_zeros` method. For example,
1672 /// [`u32::leading_zeros`]
1677 /// #![feature(core_intrinsics)]
1679 /// use std::intrinsics::ctlz;
1681 /// let x = 0b0001_1100_u8;
1682 /// let num_leading = ctlz(x);
1683 /// assert_eq!(num_leading, 3);
1686 /// An `x` with value `0` will return the bit width of `T`.
1689 /// #![feature(core_intrinsics)]
1691 /// use std::intrinsics::ctlz;
1694 /// let num_leading = ctlz(x);
1695 /// assert_eq!(num_leading, 16);
1697 #[rustc_const_stable(feature = "const_ctlz", since = "1.40.0")]
1698 #[rustc_safe_intrinsic]
1699 pub fn ctlz<T: Copy>(x: T) -> T;
1701 /// Like `ctlz`, but extra-unsafe as it returns `undef` when
1702 /// given an `x` with value `0`.
1704 /// This intrinsic does not have a stable counterpart.
1709 /// #![feature(core_intrinsics)]
1711 /// use std::intrinsics::ctlz_nonzero;
1713 /// let x = 0b0001_1100_u8;
1714 /// let num_leading = unsafe { ctlz_nonzero(x) };
1715 /// assert_eq!(num_leading, 3);
1717 #[rustc_const_stable(feature = "constctlz", since = "1.50.0")]
1718 pub fn ctlz_nonzero<T: Copy>(x: T) -> T;
1720 /// Returns the number of trailing unset bits (zeroes) in an integer type `T`.
1722 /// Note that, unlike most intrinsics, this is safe to call;
1723 /// it does not require an `unsafe` block.
1724 /// Therefore, implementations must not require the user to uphold
1725 /// any safety invariants.
1727 /// The stabilized versions of this intrinsic are available on the integer
1728 /// primitives via the `trailing_zeros` method. For example,
1729 /// [`u32::trailing_zeros`]
1734 /// #![feature(core_intrinsics)]
1736 /// use std::intrinsics::cttz;
1738 /// let x = 0b0011_1000_u8;
1739 /// let num_trailing = cttz(x);
1740 /// assert_eq!(num_trailing, 3);
1743 /// An `x` with value `0` will return the bit width of `T`:
1746 /// #![feature(core_intrinsics)]
1748 /// use std::intrinsics::cttz;
1751 /// let num_trailing = cttz(x);
1752 /// assert_eq!(num_trailing, 16);
1754 #[rustc_const_stable(feature = "const_cttz", since = "1.40.0")]
1755 #[rustc_safe_intrinsic]
1756 pub fn cttz<T: Copy>(x: T) -> T;
1758 /// Like `cttz`, but extra-unsafe as it returns `undef` when
1759 /// given an `x` with value `0`.
1761 /// This intrinsic does not have a stable counterpart.
1766 /// #![feature(core_intrinsics)]
1768 /// use std::intrinsics::cttz_nonzero;
1770 /// let x = 0b0011_1000_u8;
1771 /// let num_trailing = unsafe { cttz_nonzero(x) };
1772 /// assert_eq!(num_trailing, 3);
1774 #[rustc_const_stable(feature = "const_cttz_nonzero", since = "1.53.0")]
1775 pub fn cttz_nonzero<T: Copy>(x: T) -> T;
1777 /// Reverses the bytes in an integer type `T`.
1779 /// Note that, unlike most intrinsics, this is safe to call;
1780 /// it does not require an `unsafe` block.
1781 /// Therefore, implementations must not require the user to uphold
1782 /// any safety invariants.
1784 /// The stabilized versions of this intrinsic are available on the integer
1785 /// primitives via the `swap_bytes` method. For example,
1786 /// [`u32::swap_bytes`]
1787 #[rustc_const_stable(feature = "const_bswap", since = "1.40.0")]
1788 #[rustc_safe_intrinsic]
1789 pub fn bswap<T: Copy>(x: T) -> T;
1791 /// Reverses the bits in an integer type `T`.
1793 /// Note that, unlike most intrinsics, this is safe to call;
1794 /// it does not require an `unsafe` block.
1795 /// Therefore, implementations must not require the user to uphold
1796 /// any safety invariants.
1798 /// The stabilized versions of this intrinsic are available on the integer
1799 /// primitives via the `reverse_bits` method. For example,
1800 /// [`u32::reverse_bits`]
1801 #[rustc_const_stable(feature = "const_bitreverse", since = "1.40.0")]
1802 #[rustc_safe_intrinsic]
1803 pub fn bitreverse<T: Copy>(x: T) -> T;
1805 /// Performs checked integer addition.
1807 /// Note that, unlike most intrinsics, this is safe to call;
1808 /// it does not require an `unsafe` block.
1809 /// Therefore, implementations must not require the user to uphold
1810 /// any safety invariants.
1812 /// The stabilized versions of this intrinsic are available on the integer
1813 /// primitives via the `overflowing_add` method. For example,
1814 /// [`u32::overflowing_add`]
1815 #[rustc_const_stable(feature = "const_int_overflow", since = "1.40.0")]
1816 #[rustc_safe_intrinsic]
1817 pub fn add_with_overflow<T: Copy>(x: T, y: T) -> (T, bool);
1819 /// Performs checked integer subtraction
1821 /// Note that, unlike most intrinsics, this is safe to call;
1822 /// it does not require an `unsafe` block.
1823 /// Therefore, implementations must not require the user to uphold
1824 /// any safety invariants.
1826 /// The stabilized versions of this intrinsic are available on the integer
1827 /// primitives via the `overflowing_sub` method. For example,
1828 /// [`u32::overflowing_sub`]
1829 #[rustc_const_stable(feature = "const_int_overflow", since = "1.40.0")]
1830 #[rustc_safe_intrinsic]
1831 pub fn sub_with_overflow<T: Copy>(x: T, y: T) -> (T, bool);
1833 /// Performs checked integer multiplication
1835 /// Note that, unlike most intrinsics, this is safe to call;
1836 /// it does not require an `unsafe` block.
1837 /// Therefore, implementations must not require the user to uphold
1838 /// any safety invariants.
1840 /// The stabilized versions of this intrinsic are available on the integer
1841 /// primitives via the `overflowing_mul` method. For example,
1842 /// [`u32::overflowing_mul`]
1843 #[rustc_const_stable(feature = "const_int_overflow", since = "1.40.0")]
1844 #[rustc_safe_intrinsic]
1845 pub fn mul_with_overflow<T: Copy>(x: T, y: T) -> (T, bool);
1847 /// Performs an exact division, resulting in undefined behavior where
1848 /// `x % y != 0` or `y == 0` or `x == T::MIN && y == -1`
1850 /// This intrinsic does not have a stable counterpart.
1851 #[rustc_const_unstable(feature = "const_exact_div", issue = "none")]
1852 pub fn exact_div<T: Copy>(x: T, y: T) -> T;
1854 /// Performs an unchecked division, resulting in undefined behavior
1855 /// where `y == 0` or `x == T::MIN && y == -1`
1857 /// Safe wrappers for this intrinsic are available on the integer
1858 /// primitives via the `checked_div` method. For example,
1859 /// [`u32::checked_div`]
1860 #[rustc_const_stable(feature = "const_int_unchecked_div", since = "1.52.0")]
1861 pub fn unchecked_div<T: Copy>(x: T, y: T) -> T;
1862 /// Returns the remainder of an unchecked division, resulting in
1863 /// undefined behavior when `y == 0` or `x == T::MIN && y == -1`
1865 /// Safe wrappers for this intrinsic are available on the integer
1866 /// primitives via the `checked_rem` method. For example,
1867 /// [`u32::checked_rem`]
1868 #[rustc_const_stable(feature = "const_int_unchecked_rem", since = "1.52.0")]
1869 pub fn unchecked_rem<T: Copy>(x: T, y: T) -> T;
1871 /// Performs an unchecked left shift, resulting in undefined behavior when
1872 /// `y < 0` or `y >= N`, where N is the width of T in bits.
1874 /// Safe wrappers for this intrinsic are available on the integer
1875 /// primitives via the `checked_shl` method. For example,
1876 /// [`u32::checked_shl`]
1877 #[rustc_const_stable(feature = "const_int_unchecked", since = "1.40.0")]
1878 pub fn unchecked_shl<T: Copy>(x: T, y: T) -> T;
1879 /// Performs an unchecked right shift, resulting in undefined behavior when
1880 /// `y < 0` or `y >= N`, where N is the width of T in bits.
1882 /// Safe wrappers for this intrinsic are available on the integer
1883 /// primitives via the `checked_shr` method. For example,
1884 /// [`u32::checked_shr`]
1885 #[rustc_const_stable(feature = "const_int_unchecked", since = "1.40.0")]
1886 pub fn unchecked_shr<T: Copy>(x: T, y: T) -> T;
1888 /// Returns the result of an unchecked addition, resulting in
1889 /// undefined behavior when `x + y > T::MAX` or `x + y < T::MIN`.
1891 /// This intrinsic does not have a stable counterpart.
1892 #[rustc_const_unstable(feature = "const_int_unchecked_arith", issue = "none")]
1893 pub fn unchecked_add<T: Copy>(x: T, y: T) -> T;
1895 /// Returns the result of an unchecked subtraction, resulting in
1896 /// undefined behavior when `x - y > T::MAX` or `x - y < T::MIN`.
1898 /// This intrinsic does not have a stable counterpart.
1899 #[rustc_const_unstable(feature = "const_int_unchecked_arith", issue = "none")]
1900 pub fn unchecked_sub<T: Copy>(x: T, y: T) -> T;
1902 /// Returns the result of an unchecked multiplication, resulting in
1903 /// undefined behavior when `x * y > T::MAX` or `x * y < T::MIN`.
1905 /// This intrinsic does not have a stable counterpart.
1906 #[rustc_const_unstable(feature = "const_int_unchecked_arith", issue = "none")]
1907 pub fn unchecked_mul<T: Copy>(x: T, y: T) -> T;
1909 /// Performs rotate left.
1911 /// Note that, unlike most intrinsics, this is safe to call;
1912 /// it does not require an `unsafe` block.
1913 /// Therefore, implementations must not require the user to uphold
1914 /// any safety invariants.
1916 /// The stabilized versions of this intrinsic are available on the integer
1917 /// primitives via the `rotate_left` method. For example,
1918 /// [`u32::rotate_left`]
1919 #[rustc_const_stable(feature = "const_int_rotate", since = "1.40.0")]
1920 #[rustc_safe_intrinsic]
1921 pub fn rotate_left<T: Copy>(x: T, y: T) -> T;
1923 /// Performs rotate right.
1925 /// Note that, unlike most intrinsics, this is safe to call;
1926 /// it does not require an `unsafe` block.
1927 /// Therefore, implementations must not require the user to uphold
1928 /// any safety invariants.
1930 /// The stabilized versions of this intrinsic are available on the integer
1931 /// primitives via the `rotate_right` method. For example,
1932 /// [`u32::rotate_right`]
1933 #[rustc_const_stable(feature = "const_int_rotate", since = "1.40.0")]
1934 #[rustc_safe_intrinsic]
1935 pub fn rotate_right<T: Copy>(x: T, y: T) -> T;
1937 /// Returns (a + b) mod 2<sup>N</sup>, where N is the width of T in bits.
1939 /// Note that, unlike most intrinsics, this is safe to call;
1940 /// it does not require an `unsafe` block.
1941 /// Therefore, implementations must not require the user to uphold
1942 /// any safety invariants.
1944 /// The stabilized versions of this intrinsic are available on the integer
1945 /// primitives via the `wrapping_add` method. For example,
1946 /// [`u32::wrapping_add`]
1947 #[rustc_const_stable(feature = "const_int_wrapping", since = "1.40.0")]
1948 #[rustc_safe_intrinsic]
1949 pub fn wrapping_add<T: Copy>(a: T, b: T) -> T;
1950 /// Returns (a - b) mod 2<sup>N</sup>, where N is the width of T in bits.
1952 /// Note that, unlike most intrinsics, this is safe to call;
1953 /// it does not require an `unsafe` block.
1954 /// Therefore, implementations must not require the user to uphold
1955 /// any safety invariants.
1957 /// The stabilized versions of this intrinsic are available on the integer
1958 /// primitives via the `wrapping_sub` method. For example,
1959 /// [`u32::wrapping_sub`]
1960 #[rustc_const_stable(feature = "const_int_wrapping", since = "1.40.0")]
1961 #[rustc_safe_intrinsic]
1962 pub fn wrapping_sub<T: Copy>(a: T, b: T) -> T;
1963 /// Returns (a * b) mod 2<sup>N</sup>, where N is the width of T in bits.
1965 /// Note that, unlike most intrinsics, this is safe to call;
1966 /// it does not require an `unsafe` block.
1967 /// Therefore, implementations must not require the user to uphold
1968 /// any safety invariants.
1970 /// The stabilized versions of this intrinsic are available on the integer
1971 /// primitives via the `wrapping_mul` method. For example,
1972 /// [`u32::wrapping_mul`]
1973 #[rustc_const_stable(feature = "const_int_wrapping", since = "1.40.0")]
1974 #[rustc_safe_intrinsic]
1975 pub fn wrapping_mul<T: Copy>(a: T, b: T) -> T;
1977 /// Computes `a + b`, saturating at numeric bounds.
1979 /// Note that, unlike most intrinsics, this is safe to call;
1980 /// it does not require an `unsafe` block.
1981 /// Therefore, implementations must not require the user to uphold
1982 /// any safety invariants.
1984 /// The stabilized versions of this intrinsic are available on the integer
1985 /// primitives via the `saturating_add` method. For example,
1986 /// [`u32::saturating_add`]
1987 #[rustc_const_stable(feature = "const_int_saturating", since = "1.40.0")]
1988 #[rustc_safe_intrinsic]
1989 pub fn saturating_add<T: Copy>(a: T, b: T) -> T;
1990 /// Computes `a - b`, saturating at numeric bounds.
1992 /// Note that, unlike most intrinsics, this is safe to call;
1993 /// it does not require an `unsafe` block.
1994 /// Therefore, implementations must not require the user to uphold
1995 /// any safety invariants.
1997 /// The stabilized versions of this intrinsic are available on the integer
1998 /// primitives via the `saturating_sub` method. For example,
1999 /// [`u32::saturating_sub`]
2000 #[rustc_const_stable(feature = "const_int_saturating", since = "1.40.0")]
2001 #[rustc_safe_intrinsic]
2002 pub fn saturating_sub<T: Copy>(a: T, b: T) -> T;
2004 /// Returns the value of the discriminant for the variant in 'v';
2005 /// if `T` has no discriminant, returns `0`.
2007 /// Note that, unlike most intrinsics, this is safe to call;
2008 /// it does not require an `unsafe` block.
2009 /// Therefore, implementations must not require the user to uphold
2010 /// any safety invariants.
2012 /// The stabilized version of this intrinsic is [`core::mem::discriminant`].
2013 #[rustc_const_unstable(feature = "const_discriminant", issue = "69821")]
2014 #[rustc_safe_intrinsic]
2015 pub fn discriminant_value<T>(v: &T) -> <T as DiscriminantKind>::Discriminant;
2017 /// Returns the number of variants of the type `T` cast to a `usize`;
2018 /// if `T` has no variants, returns `0`. Uninhabited variants will be counted.
2020 /// Note that, unlike most intrinsics, this is safe to call;
2021 /// it does not require an `unsafe` block.
2022 /// Therefore, implementations must not require the user to uphold
2023 /// any safety invariants.
2025 /// The to-be-stabilized version of this intrinsic is [`mem::variant_count`].
2026 #[rustc_const_unstable(feature = "variant_count", issue = "73662")]
2027 #[rustc_safe_intrinsic]
2028 pub fn variant_count<T>() -> usize;
2030 /// Rust's "try catch" construct which invokes the function pointer `try_fn`
2031 /// with the data pointer `data`.
2033 /// The third argument is a function called if a panic occurs. This function
2034 /// takes the data pointer and a pointer to the target-specific exception
2035 /// object that was caught. For more information see the compiler's
2036 /// source as well as std's catch implementation.
2037 pub fn r#try(try_fn: fn(*mut u8), data: *mut u8, catch_fn: fn(*mut u8, *mut u8)) -> i32;
2039 /// Emits a `!nontemporal` store according to LLVM (see their docs).
2040 /// Probably will never become stable.
2041 pub fn nontemporal_store<T>(ptr: *mut T, val: T);
2043 /// See documentation of `<*const T>::offset_from` for details.
2044 #[rustc_const_stable(feature = "const_ptr_offset_from", since = "1.65.0")]
2045 pub fn ptr_offset_from<T>(ptr: *const T, base: *const T) -> isize;
2047 /// See documentation of `<*const T>::sub_ptr` for details.
2048 #[rustc_const_unstable(feature = "const_ptr_sub_ptr", issue = "95892")]
2049 pub fn ptr_offset_from_unsigned<T>(ptr: *const T, base: *const T) -> usize;
2051 /// See documentation of `<*const T>::guaranteed_eq` for details.
2052 /// Returns `2` if the result is unknown.
2053 /// Returns `1` if the pointers are guaranteed equal
2054 /// Returns `0` if the pointers are guaranteed inequal
2056 /// Note that, unlike most intrinsics, this is safe to call;
2057 /// it does not require an `unsafe` block.
2058 /// Therefore, implementations must not require the user to uphold
2059 /// any safety invariants.
2060 #[rustc_const_unstable(feature = "const_raw_ptr_comparison", issue = "53020")]
2061 #[rustc_safe_intrinsic]
2062 pub fn ptr_guaranteed_cmp<T>(ptr: *const T, other: *const T) -> u8;
2064 /// Allocates a block of memory at compile time.
2065 /// At runtime, just returns a null pointer.
2069 /// - The `align` argument must be a power of two.
2070 /// - At compile time, a compile error occurs if this constraint is violated.
2071 /// - At runtime, it is not checked.
2072 #[rustc_const_unstable(feature = "const_heap", issue = "79597")]
2073 pub fn const_allocate(size: usize, align: usize) -> *mut u8;
2075 /// Deallocates a memory which allocated by `intrinsics::const_allocate` at compile time.
2076 /// At runtime, does nothing.
2080 /// - The `align` argument must be a power of two.
2081 /// - At compile time, a compile error occurs if this constraint is violated.
2082 /// - At runtime, it is not checked.
2083 /// - If the `ptr` is created in an another const, this intrinsic doesn't deallocate it.
2084 /// - If the `ptr` is pointing to a local variable, this intrinsic doesn't deallocate it.
2085 #[rustc_const_unstable(feature = "const_heap", issue = "79597")]
2086 pub fn const_deallocate(ptr: *mut u8, size: usize, align: usize);
2088 /// Determines whether the raw bytes of the two values are equal.
2090 /// This is particularly handy for arrays, since it allows things like just
2091 /// comparing `i96`s instead of forcing `alloca`s for `[6 x i16]`.
2093 /// Above some backend-decided threshold this will emit calls to `memcmp`,
2094 /// like slice equality does, instead of causing massive code size.
2098 /// It's UB to call this if any of the *bytes* in `*a` or `*b` are uninitialized or carry a
2100 /// Note that this is a stricter criterion than just the *values* being
2101 /// fully-initialized: if `T` has padding, it's UB to call this intrinsic.
2103 /// (The implementation is allowed to branch on the results of comparisons,
2104 /// which is UB if any of their inputs are `undef`.)
2105 #[rustc_const_unstable(feature = "const_intrinsic_raw_eq", issue = "none")]
2106 pub fn raw_eq<T>(a: &T, b: &T) -> bool;
2108 /// See documentation of [`std::hint::black_box`] for details.
2110 /// [`std::hint::black_box`]: crate::hint::black_box
2111 #[rustc_const_unstable(feature = "const_black_box", issue = "none")]
2112 #[rustc_safe_intrinsic]
2113 pub fn black_box<T>(dummy: T) -> T;
2115 /// `ptr` must point to a vtable.
2116 /// The intrinsic will return the size stored in that vtable.
2117 pub fn vtable_size(ptr: *const ()) -> usize;
2119 /// `ptr` must point to a vtable.
2120 /// The intrinsic will return the alignment stored in that vtable.
2121 pub fn vtable_align(ptr: *const ()) -> usize;
2123 /// Selects which function to call depending on the context.
2125 /// If this function is evaluated at compile-time, then a call to this
2126 /// intrinsic will be replaced with a call to `called_in_const`. It gets
2127 /// replaced with a call to `called_at_rt` otherwise.
2129 /// # Type Requirements
2131 /// The two functions must be both function items. They cannot be function
2132 /// pointers or closures. The first function must be a `const fn`.
2134 /// `arg` will be the tupled arguments that will be passed to either one of
2135 /// the two functions, therefore, both functions must accept the same type of
2136 /// arguments. Both functions must return RET.
2140 /// The two functions must behave observably equivalent. Safe code in other
2141 /// crates may assume that calling a `const fn` at compile-time and at run-time
2142 /// produces the same result. A function that produces a different result when
2143 /// evaluated at run-time, or has any other observable side-effects, is
2146 /// Here is an example of how this could cause a problem:
2148 /// #![feature(const_eval_select)]
2149 /// #![feature(core_intrinsics)]
2150 /// use std::hint::unreachable_unchecked;
2151 /// use std::intrinsics::const_eval_select;
2154 /// pub const fn inconsistent() -> i32 {
2155 /// fn runtime() -> i32 { 1 }
2156 /// const fn compiletime() -> i32 { 2 }
2159 // // ⚠ This code violates the required equivalence of `compiletime`
2160 /// // and `runtime`.
2161 /// const_eval_select((), compiletime, runtime)
2166 /// const X: i32 = inconsistent();
2167 /// let x = inconsistent();
2168 /// if x != X { unsafe { unreachable_unchecked(); }}
2171 /// This code causes Undefined Behavior when being run, since the
2172 /// `unreachable_unchecked` is actually being reached. The bug is in *crate A*,
2173 /// which violates the principle that a `const fn` must behave the same at
2174 /// compile-time and at run-time. The unsafe code in crate B is fine.
2175 #[rustc_const_unstable(feature = "const_eval_select", issue = "none")]
2176 pub fn const_eval_select<ARG: Tuple, F, G, RET>(
2182 G: FnOnce<ARG, Output = RET>,
2183 F: FnOnce<ARG, Output = RET>;
2186 // Some functions are defined here because they accidentally got made
2187 // available in this module on stable. See <https://github.com/rust-lang/rust/issues/15702>.
2188 // (`transmute` also falls into this category, but it cannot be wrapped due to the
2189 // check that `T` and `U` have the same size.)
2191 /// Check that the preconditions of an unsafe function are followed, if debug_assertions are on,
2192 /// and only at runtime.
2194 /// This macro should be called as `assert_unsafe_precondition!([Generics](name: Type) => Expression)`
2195 /// where the names specified will be moved into the macro as captured variables, and defines an item
2196 /// to call `const_eval_select` on. The tokens inside the square brackets are used to denote generics
2197 /// for the function declaractions and can be omitted if there is no generics.
2201 /// Invoking this macro is only sound if the following code is already UB when the passed
2202 /// expression evaluates to false.
2204 /// This macro expands to a check at runtime if debug_assertions is set. It has no effect at
2205 /// compile time, but the semantics of the contained `const_eval_select` must be the same at
2206 /// runtime and at compile time. Thus if the expression evaluates to false, this macro produces
2207 /// different behavior at compile time and at runtime, and invoking it is incorrect.
2209 /// So in a sense it is UB if this macro is useful, but we expect callers of `unsafe fn` to make
2210 /// the occasional mistake, and this check should help them figure things out.
2211 #[allow_internal_unstable(const_eval_select)] // permit this to be called in stably-const fn
2212 macro_rules! assert_unsafe_precondition {
2213 ($name:expr, $([$($tt:tt)*])?($($i:ident:$ty:ty),*$(,)?) => $e:expr) => {
2214 if cfg!(debug_assertions) {
2215 // allow non_snake_case to allow capturing const generics
2216 #[allow(non_snake_case)]
2218 fn runtime$(<$($tt)*>)?($($i:$ty),*) {
2220 // don't unwind to reduce impact on code size
2221 ::core::panicking::panic_nounwind(
2222 concat!("unsafe precondition(s) violated: ", $name)
2226 #[allow(non_snake_case)]
2227 const fn comptime$(<$($tt)*>)?($(_:$ty),*) {}
2229 ::core::intrinsics::const_eval_select(($($i,)*), comptime, runtime);
2233 pub(crate) use assert_unsafe_precondition;
2235 /// Checks whether `ptr` is properly aligned with respect to
2236 /// `align_of::<T>()`.
2237 pub(crate) fn is_aligned_and_not_null<T>(ptr: *const T) -> bool {
2238 !ptr.is_null() && ptr.is_aligned()
2241 /// Checks whether an allocation of `len` instances of `T` exceeds
2242 /// the maximum allowed allocation size.
2243 pub(crate) fn is_valid_allocation_size<T>(len: usize) -> bool {
2244 let max_len = const {
2245 let size = crate::mem::size_of::<T>();
2246 if size == 0 { usize::MAX } else { isize::MAX as usize / size }
2251 /// Checks whether the regions of memory starting at `src` and `dst` of size
2252 /// `count * size_of::<T>()` do *not* overlap.
2253 pub(crate) fn is_nonoverlapping<T>(src: *const T, dst: *const T, count: usize) -> bool {
2254 let src_usize = src.addr();
2255 let dst_usize = dst.addr();
2256 let size = mem::size_of::<T>().checked_mul(count).unwrap();
2257 let diff = if src_usize > dst_usize { src_usize - dst_usize } else { dst_usize - src_usize };
2258 // If the absolute distance between the ptrs is at least as big as the size of the buffer,
2259 // they do not overlap.
2263 /// Copies `count * size_of::<T>()` bytes from `src` to `dst`. The source
2264 /// and destination must *not* overlap.
2266 /// For regions of memory which might overlap, use [`copy`] instead.
2268 /// `copy_nonoverlapping` is semantically equivalent to C's [`memcpy`], but
2269 /// with the argument order swapped.
2271 /// The copy is "untyped" in the sense that data may be uninitialized or otherwise violate the
2272 /// requirements of `T`. The initialization state is preserved exactly.
2274 /// [`memcpy`]: https://en.cppreference.com/w/c/string/byte/memcpy
2278 /// Behavior is undefined if any of the following conditions are violated:
2280 /// * `src` must be [valid] for reads of `count * size_of::<T>()` bytes.
2282 /// * `dst` must be [valid] for writes of `count * size_of::<T>()` bytes.
2284 /// * Both `src` and `dst` must be properly aligned.
2286 /// * The region of memory beginning at `src` with a size of `count *
2287 /// size_of::<T>()` bytes must *not* overlap with the region of memory
2288 /// beginning at `dst` with the same size.
2290 /// Like [`read`], `copy_nonoverlapping` creates a bitwise copy of `T`, regardless of
2291 /// whether `T` is [`Copy`]. If `T` is not [`Copy`], using *both* the values
2292 /// in the region beginning at `*src` and the region beginning at `*dst` can
2293 /// [violate memory safety][read-ownership].
2295 /// Note that even if the effectively copied size (`count * size_of::<T>()`) is
2296 /// `0`, the pointers must be non-null and properly aligned.
2298 /// [`read`]: crate::ptr::read
2299 /// [read-ownership]: crate::ptr::read#ownership-of-the-returned-value
2300 /// [valid]: crate::ptr#safety
2304 /// Manually implement [`Vec::append`]:
2309 /// /// Moves all the elements of `src` into `dst`, leaving `src` empty.
2310 /// fn append<T>(dst: &mut Vec<T>, src: &mut Vec<T>) {
2311 /// let src_len = src.len();
2312 /// let dst_len = dst.len();
2314 /// // Ensure that `dst` has enough capacity to hold all of `src`.
2315 /// dst.reserve(src_len);
2318 /// // The call to add is always safe because `Vec` will never
2319 /// // allocate more than `isize::MAX` bytes.
2320 /// let dst_ptr = dst.as_mut_ptr().add(dst_len);
2321 /// let src_ptr = src.as_ptr();
2323 /// // Truncate `src` without dropping its contents. We do this first,
2324 /// // to avoid problems in case something further down panics.
2327 /// // The two regions cannot overlap because mutable references do
2328 /// // not alias, and two different vectors cannot own the same
2330 /// ptr::copy_nonoverlapping(src_ptr, dst_ptr, src_len);
2332 /// // Notify `dst` that it now holds the contents of `src`.
2333 /// dst.set_len(dst_len + src_len);
2337 /// let mut a = vec!['r'];
2338 /// let mut b = vec!['u', 's', 't'];
2340 /// append(&mut a, &mut b);
2342 /// assert_eq!(a, &['r', 'u', 's', 't']);
2343 /// assert!(b.is_empty());
2346 /// [`Vec::append`]: ../../std/vec/struct.Vec.html#method.append
2347 #[doc(alias = "memcpy")]
2348 #[stable(feature = "rust1", since = "1.0.0")]
2349 #[rustc_allowed_through_unstable_modules]
2350 #[rustc_const_stable(feature = "const_intrinsic_copy", since = "1.63.0")]
2352 #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
2353 pub const unsafe fn copy_nonoverlapping<T>(src: *const T, dst: *mut T, count: usize) {
2354 extern "rust-intrinsic" {
2355 #[rustc_const_stable(feature = "const_intrinsic_copy", since = "1.63.0")]
2356 pub fn copy_nonoverlapping<T>(src: *const T, dst: *mut T, count: usize);
2359 // SAFETY: the safety contract for `copy_nonoverlapping` must be
2360 // upheld by the caller.
2362 assert_unsafe_precondition!(
2363 "ptr::copy_nonoverlapping requires that both pointer arguments are aligned and non-null \
2364 and the specified memory ranges do not overlap",
2365 [T](src: *const T, dst: *mut T, count: usize) =>
2366 is_aligned_and_not_null(src)
2367 && is_aligned_and_not_null(dst)
2368 && is_nonoverlapping(src, dst, count)
2370 copy_nonoverlapping(src, dst, count)
2374 /// Copies `count * size_of::<T>()` bytes from `src` to `dst`. The source
2375 /// and destination may overlap.
2377 /// If the source and destination will *never* overlap,
2378 /// [`copy_nonoverlapping`] can be used instead.
2380 /// `copy` is semantically equivalent to C's [`memmove`], but with the argument
2381 /// order swapped. Copying takes place as if the bytes were copied from `src`
2382 /// to a temporary array and then copied from the array to `dst`.
2384 /// The copy is "untyped" in the sense that data may be uninitialized or otherwise violate the
2385 /// requirements of `T`. The initialization state is preserved exactly.
2387 /// [`memmove`]: https://en.cppreference.com/w/c/string/byte/memmove
2391 /// Behavior is undefined if any of the following conditions are violated:
2393 /// * `src` must be [valid] for reads of `count * size_of::<T>()` bytes.
2395 /// * `dst` must be [valid] for writes of `count * size_of::<T>()` bytes.
2397 /// * Both `src` and `dst` must be properly aligned.
2399 /// Like [`read`], `copy` creates a bitwise copy of `T`, regardless of
2400 /// whether `T` is [`Copy`]. If `T` is not [`Copy`], using both the values
2401 /// in the region beginning at `*src` and the region beginning at `*dst` can
2402 /// [violate memory safety][read-ownership].
2404 /// Note that even if the effectively copied size (`count * size_of::<T>()`) is
2405 /// `0`, the pointers must be non-null and properly aligned.
2407 /// [`read`]: crate::ptr::read
2408 /// [read-ownership]: crate::ptr::read#ownership-of-the-returned-value
2409 /// [valid]: crate::ptr#safety
2413 /// Efficiently create a Rust vector from an unsafe buffer:
2420 /// /// * `ptr` must be correctly aligned for its type and non-zero.
2421 /// /// * `ptr` must be valid for reads of `elts` contiguous elements of type `T`.
2422 /// /// * Those elements must not be used after calling this function unless `T: Copy`.
2423 /// # #[allow(dead_code)]
2424 /// unsafe fn from_buf_raw<T>(ptr: *const T, elts: usize) -> Vec<T> {
2425 /// let mut dst = Vec::with_capacity(elts);
2427 /// // SAFETY: Our precondition ensures the source is aligned and valid,
2428 /// // and `Vec::with_capacity` ensures that we have usable space to write them.
2429 /// ptr::copy(ptr, dst.as_mut_ptr(), elts);
2431 /// // SAFETY: We created it with this much capacity earlier,
2432 /// // and the previous `copy` has initialized these elements.
2433 /// dst.set_len(elts);
2437 #[doc(alias = "memmove")]
2438 #[stable(feature = "rust1", since = "1.0.0")]
2439 #[rustc_allowed_through_unstable_modules]
2440 #[rustc_const_stable(feature = "const_intrinsic_copy", since = "1.63.0")]
2442 #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
2443 pub const unsafe fn copy<T>(src: *const T, dst: *mut T, count: usize) {
2444 extern "rust-intrinsic" {
2445 #[rustc_const_stable(feature = "const_intrinsic_copy", since = "1.63.0")]
2446 fn copy<T>(src: *const T, dst: *mut T, count: usize);
2449 // SAFETY: the safety contract for `copy` must be upheld by the caller.
2451 assert_unsafe_precondition!(
2452 "ptr::copy requires that both pointer arguments are aligned aligned and non-null",
2453 [T](src: *const T, dst: *mut T) =>
2454 is_aligned_and_not_null(src) && is_aligned_and_not_null(dst)
2456 copy(src, dst, count)
2460 /// Sets `count * size_of::<T>()` bytes of memory starting at `dst` to
2463 /// `write_bytes` is similar to C's [`memset`], but sets `count *
2464 /// size_of::<T>()` bytes to `val`.
2466 /// [`memset`]: https://en.cppreference.com/w/c/string/byte/memset
2470 /// Behavior is undefined if any of the following conditions are violated:
2472 /// * `dst` must be [valid] for writes of `count * size_of::<T>()` bytes.
2474 /// * `dst` must be properly aligned.
2476 /// Note that even if the effectively copied size (`count * size_of::<T>()`) is
2477 /// `0`, the pointer must be non-null and properly aligned.
2479 /// Additionally, note that changing `*dst` in this way can easily lead to undefined behavior (UB)
2480 /// later if the written bytes are not a valid representation of some `T`. For instance, the
2481 /// following is an **incorrect** use of this function:
2485 /// let mut value: u8 = 0;
2486 /// let ptr: *mut bool = &mut value as *mut u8 as *mut bool;
2487 /// let _bool = ptr.read(); // This is fine, `ptr` points to a valid `bool`.
2488 /// ptr.write_bytes(42u8, 1); // This function itself does not cause UB...
2489 /// let _bool = ptr.read(); // ...but it makes this operation UB! ⚠️
2493 /// [valid]: crate::ptr#safety
2502 /// let mut vec = vec![0u32; 4];
2504 /// let vec_ptr = vec.as_mut_ptr();
2505 /// ptr::write_bytes(vec_ptr, 0xfe, 2);
2507 /// assert_eq!(vec, [0xfefefefe, 0xfefefefe, 0, 0]);
2509 #[doc(alias = "memset")]
2510 #[stable(feature = "rust1", since = "1.0.0")]
2511 #[rustc_allowed_through_unstable_modules]
2512 #[rustc_const_unstable(feature = "const_ptr_write", issue = "86302")]
2514 #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
2515 pub const unsafe fn write_bytes<T>(dst: *mut T, val: u8, count: usize) {
2516 extern "rust-intrinsic" {
2517 #[rustc_const_unstable(feature = "const_ptr_write", issue = "86302")]
2518 fn write_bytes<T>(dst: *mut T, val: u8, count: usize);
2521 // SAFETY: the safety contract for `write_bytes` must be upheld by the caller.
2523 assert_unsafe_precondition!(
2524 "ptr::write_bytes requires that the destination pointer is aligned and non-null",
2525 [T](dst: *mut T) => is_aligned_and_not_null(dst)
2527 write_bytes(dst, val, count)