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::{Destruct, DiscriminantKind};
60 // These imports are used for simplifying intra-doc links
61 #[allow(unused_imports)]
62 #[cfg(all(target_has_atomic = "8", target_has_atomic = "32", target_has_atomic = "ptr"))]
63 use crate::sync::atomic::{self, AtomicBool, AtomicI32, AtomicIsize, AtomicU32, Ordering};
65 #[stable(feature = "drop_in_place", since = "1.8.0")]
66 #[cfg_attr(not(bootstrap), rustc_allowed_through_unstable_modules)]
67 #[deprecated(note = "no longer an intrinsic - use `ptr::drop_in_place` directly", since = "1.52.0")]
69 pub unsafe fn drop_in_place<T: ?Sized>(to_drop: *mut T) {
70 // SAFETY: see `ptr::drop_in_place`
71 unsafe { crate::ptr::drop_in_place(to_drop) }
74 // These have been renamed.
76 extern "rust-intrinsic" {
77 pub fn atomic_cxchg<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
78 pub fn atomic_cxchg_acq<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
79 pub fn atomic_cxchg_rel<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
80 pub fn atomic_cxchg_acqrel<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
81 pub fn atomic_cxchg_relaxed<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
82 pub fn atomic_cxchg_failrelaxed<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
83 pub fn atomic_cxchg_failacq<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
84 pub fn atomic_cxchg_acq_failrelaxed<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
85 pub fn atomic_cxchg_acqrel_failrelaxed<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
86 pub fn atomic_cxchgweak<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
87 pub fn atomic_cxchgweak_acq<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
88 pub fn atomic_cxchgweak_rel<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
89 pub fn atomic_cxchgweak_acqrel<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
90 pub fn atomic_cxchgweak_relaxed<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
91 pub fn atomic_cxchgweak_failrelaxed<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
92 pub fn atomic_cxchgweak_failacq<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
93 pub fn atomic_cxchgweak_acq_failrelaxed<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
94 pub fn atomic_cxchgweak_acqrel_failrelaxed<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
95 pub fn atomic_load<T: Copy>(src: *const T) -> T;
96 pub fn atomic_load_acq<T: Copy>(src: *const T) -> T;
97 pub fn atomic_load_relaxed<T: Copy>(src: *const T) -> T;
98 pub fn atomic_load_unordered<T: Copy>(src: *const T) -> T;
99 pub fn atomic_store<T: Copy>(dst: *mut T, val: T);
100 pub fn atomic_store_rel<T: Copy>(dst: *mut T, val: T);
101 pub fn atomic_store_relaxed<T: Copy>(dst: *mut T, val: T);
102 pub fn atomic_store_unordered<T: Copy>(dst: *mut T, val: T);
103 pub fn atomic_xchg<T: Copy>(dst: *mut T, src: T) -> T;
104 pub fn atomic_xchg_acq<T: Copy>(dst: *mut T, src: T) -> T;
105 pub fn atomic_xchg_rel<T: Copy>(dst: *mut T, src: T) -> T;
106 pub fn atomic_xchg_acqrel<T: Copy>(dst: *mut T, src: T) -> T;
107 pub fn atomic_xchg_relaxed<T: Copy>(dst: *mut T, src: T) -> T;
108 pub fn atomic_xadd<T: Copy>(dst: *mut T, src: T) -> T;
109 pub fn atomic_xadd_acq<T: Copy>(dst: *mut T, src: T) -> T;
110 pub fn atomic_xadd_rel<T: Copy>(dst: *mut T, src: T) -> T;
111 pub fn atomic_xadd_acqrel<T: Copy>(dst: *mut T, src: T) -> T;
112 pub fn atomic_xadd_relaxed<T: Copy>(dst: *mut T, src: T) -> T;
113 pub fn atomic_xsub<T: Copy>(dst: *mut T, src: T) -> T;
114 pub fn atomic_xsub_acq<T: Copy>(dst: *mut T, src: T) -> T;
115 pub fn atomic_xsub_rel<T: Copy>(dst: *mut T, src: T) -> T;
116 pub fn atomic_xsub_acqrel<T: Copy>(dst: *mut T, src: T) -> T;
117 pub fn atomic_xsub_relaxed<T: Copy>(dst: *mut T, src: T) -> T;
118 pub fn atomic_and<T: Copy>(dst: *mut T, src: T) -> T;
119 pub fn atomic_and_acq<T: Copy>(dst: *mut T, src: T) -> T;
120 pub fn atomic_and_rel<T: Copy>(dst: *mut T, src: T) -> T;
121 pub fn atomic_and_acqrel<T: Copy>(dst: *mut T, src: T) -> T;
122 pub fn atomic_and_relaxed<T: Copy>(dst: *mut T, src: T) -> T;
123 pub fn atomic_nand<T: Copy>(dst: *mut T, src: T) -> T;
124 pub fn atomic_nand_acq<T: Copy>(dst: *mut T, src: T) -> T;
125 pub fn atomic_nand_rel<T: Copy>(dst: *mut T, src: T) -> T;
126 pub fn atomic_nand_acqrel<T: Copy>(dst: *mut T, src: T) -> T;
127 pub fn atomic_nand_relaxed<T: Copy>(dst: *mut T, src: T) -> T;
128 pub fn atomic_or<T: Copy>(dst: *mut T, src: T) -> T;
129 pub fn atomic_or_acq<T: Copy>(dst: *mut T, src: T) -> T;
130 pub fn atomic_or_rel<T: Copy>(dst: *mut T, src: T) -> T;
131 pub fn atomic_or_acqrel<T: Copy>(dst: *mut T, src: T) -> T;
132 pub fn atomic_or_relaxed<T: Copy>(dst: *mut T, src: T) -> T;
133 pub fn atomic_xor<T: Copy>(dst: *mut T, src: T) -> T;
134 pub fn atomic_xor_acq<T: Copy>(dst: *mut T, src: T) -> T;
135 pub fn atomic_xor_rel<T: Copy>(dst: *mut T, src: T) -> T;
136 pub fn atomic_xor_acqrel<T: Copy>(dst: *mut T, src: T) -> T;
137 pub fn atomic_xor_relaxed<T: Copy>(dst: *mut T, src: T) -> T;
138 pub fn atomic_max<T: Copy>(dst: *mut T, src: T) -> T;
139 pub fn atomic_max_acq<T: Copy>(dst: *mut T, src: T) -> T;
140 pub fn atomic_max_rel<T: Copy>(dst: *mut T, src: T) -> T;
141 pub fn atomic_max_acqrel<T: Copy>(dst: *mut T, src: T) -> T;
142 pub fn atomic_max_relaxed<T: Copy>(dst: *mut T, src: T) -> T;
143 pub fn atomic_min<T: Copy>(dst: *mut T, src: T) -> T;
144 pub fn atomic_min_acq<T: Copy>(dst: *mut T, src: T) -> T;
145 pub fn atomic_min_rel<T: Copy>(dst: *mut T, src: T) -> T;
146 pub fn atomic_min_acqrel<T: Copy>(dst: *mut T, src: T) -> T;
147 pub fn atomic_min_relaxed<T: Copy>(dst: *mut T, src: T) -> T;
148 pub fn atomic_umin<T: Copy>(dst: *mut T, src: T) -> T;
149 pub fn atomic_umin_acq<T: Copy>(dst: *mut T, src: T) -> T;
150 pub fn atomic_umin_rel<T: Copy>(dst: *mut T, src: T) -> T;
151 pub fn atomic_umin_acqrel<T: Copy>(dst: *mut T, src: T) -> T;
152 pub fn atomic_umin_relaxed<T: Copy>(dst: *mut T, src: T) -> T;
153 pub fn atomic_umax<T: Copy>(dst: *mut T, src: T) -> T;
154 pub fn atomic_umax_acq<T: Copy>(dst: *mut T, src: T) -> T;
155 pub fn atomic_umax_rel<T: Copy>(dst: *mut T, src: T) -> T;
156 pub fn atomic_umax_acqrel<T: Copy>(dst: *mut T, src: T) -> T;
157 pub fn atomic_umax_relaxed<T: Copy>(dst: *mut T, src: T) -> T;
158 pub fn atomic_fence();
159 pub fn atomic_fence_acq();
160 pub fn atomic_fence_rel();
161 pub fn atomic_fence_acqrel();
162 pub fn atomic_singlethreadfence();
163 pub fn atomic_singlethreadfence_acq();
164 pub fn atomic_singlethreadfence_rel();
165 pub fn atomic_singlethreadfence_acqrel();
168 // These have been renamed.
171 pub use super::atomic_cxchg as atomic_cxchg_seqcst_seqcst;
172 pub use super::atomic_cxchg_acq as atomic_cxchg_acquire_acquire;
173 pub use super::atomic_cxchg_acq_failrelaxed as atomic_cxchg_acquire_relaxed;
174 pub use super::atomic_cxchg_acqrel as atomic_cxchg_acqrel_acquire;
175 pub use super::atomic_cxchg_acqrel_failrelaxed as atomic_cxchg_acqrel_relaxed;
176 pub use super::atomic_cxchg_failacq as atomic_cxchg_seqcst_acquire;
177 pub use super::atomic_cxchg_failrelaxed as atomic_cxchg_seqcst_relaxed;
178 pub use super::atomic_cxchg_rel as atomic_cxchg_release_relaxed;
179 pub use super::atomic_cxchg_relaxed as atomic_cxchg_relaxed_relaxed;
181 pub use super::atomic_cxchgweak as atomic_cxchgweak_seqcst_seqcst;
182 pub use super::atomic_cxchgweak_acq as atomic_cxchgweak_acquire_acquire;
183 pub use super::atomic_cxchgweak_acq_failrelaxed as atomic_cxchgweak_acquire_relaxed;
184 pub use super::atomic_cxchgweak_acqrel as atomic_cxchgweak_acqrel_acquire;
185 pub use super::atomic_cxchgweak_acqrel_failrelaxed as atomic_cxchgweak_acqrel_relaxed;
186 pub use super::atomic_cxchgweak_failacq as atomic_cxchgweak_seqcst_acquire;
187 pub use super::atomic_cxchgweak_failrelaxed as atomic_cxchgweak_seqcst_relaxed;
188 pub use super::atomic_cxchgweak_rel as atomic_cxchgweak_release_relaxed;
189 pub use super::atomic_cxchgweak_relaxed as atomic_cxchgweak_relaxed_relaxed;
191 pub use super::atomic_load as atomic_load_seqcst;
192 pub use super::atomic_load_acq as atomic_load_acquire;
193 pub use super::atomic_load_relaxed;
194 pub use super::atomic_load_unordered;
196 pub use super::atomic_store as atomic_store_seqcst;
197 pub use super::atomic_store_rel as atomic_store_release;
198 pub use super::atomic_store_relaxed;
199 pub use super::atomic_store_unordered;
201 pub use super::atomic_xchg as atomic_xchg_seqcst;
202 pub use super::atomic_xchg_acq as atomic_xchg_acquire;
203 pub use super::atomic_xchg_acqrel;
204 pub use super::atomic_xchg_rel as atomic_xchg_release;
205 pub use super::atomic_xchg_relaxed;
207 pub use super::atomic_xadd as atomic_xadd_seqcst;
208 pub use super::atomic_xadd_acq as atomic_xadd_acquire;
209 pub use super::atomic_xadd_acqrel;
210 pub use super::atomic_xadd_rel as atomic_xadd_release;
211 pub use super::atomic_xadd_relaxed;
213 pub use super::atomic_xsub as atomic_xsub_seqcst;
214 pub use super::atomic_xsub_acq as atomic_xsub_acquire;
215 pub use super::atomic_xsub_acqrel;
216 pub use super::atomic_xsub_rel as atomic_xsub_release;
217 pub use super::atomic_xsub_relaxed;
219 pub use super::atomic_and as atomic_and_seqcst;
220 pub use super::atomic_and_acq as atomic_and_acquire;
221 pub use super::atomic_and_acqrel;
222 pub use super::atomic_and_rel as atomic_and_release;
223 pub use super::atomic_and_relaxed;
225 pub use super::atomic_nand as atomic_nand_seqcst;
226 pub use super::atomic_nand_acq as atomic_nand_acquire;
227 pub use super::atomic_nand_acqrel;
228 pub use super::atomic_nand_rel as atomic_nand_release;
229 pub use super::atomic_nand_relaxed;
231 pub use super::atomic_or as atomic_or_seqcst;
232 pub use super::atomic_or_acq as atomic_or_acquire;
233 pub use super::atomic_or_acqrel;
234 pub use super::atomic_or_rel as atomic_or_release;
235 pub use super::atomic_or_relaxed;
237 pub use super::atomic_xor as atomic_xor_seqcst;
238 pub use super::atomic_xor_acq as atomic_xor_acquire;
239 pub use super::atomic_xor_acqrel;
240 pub use super::atomic_xor_rel as atomic_xor_release;
241 pub use super::atomic_xor_relaxed;
243 pub use super::atomic_max as atomic_max_seqcst;
244 pub use super::atomic_max_acq as atomic_max_acquire;
245 pub use super::atomic_max_acqrel;
246 pub use super::atomic_max_rel as atomic_max_release;
247 pub use super::atomic_max_relaxed;
249 pub use super::atomic_min as atomic_min_seqcst;
250 pub use super::atomic_min_acq as atomic_min_acquire;
251 pub use super::atomic_min_acqrel;
252 pub use super::atomic_min_rel as atomic_min_release;
253 pub use super::atomic_min_relaxed;
255 pub use super::atomic_umin as atomic_umin_seqcst;
256 pub use super::atomic_umin_acq as atomic_umin_acquire;
257 pub use super::atomic_umin_acqrel;
258 pub use super::atomic_umin_rel as atomic_umin_release;
259 pub use super::atomic_umin_relaxed;
261 pub use super::atomic_umax as atomic_umax_seqcst;
262 pub use super::atomic_umax_acq as atomic_umax_acquire;
263 pub use super::atomic_umax_acqrel;
264 pub use super::atomic_umax_rel as atomic_umax_release;
265 pub use super::atomic_umax_relaxed;
267 pub use super::atomic_fence as atomic_fence_seqcst;
268 pub use super::atomic_fence_acq as atomic_fence_acquire;
269 pub use super::atomic_fence_acqrel;
270 pub use super::atomic_fence_rel as atomic_fence_release;
272 pub use super::atomic_singlethreadfence as atomic_singlethreadfence_seqcst;
273 pub use super::atomic_singlethreadfence_acq as atomic_singlethreadfence_acquire;
274 pub use super::atomic_singlethreadfence_acqrel;
275 pub use super::atomic_singlethreadfence_rel as atomic_singlethreadfence_release;
281 #[cfg(not(bootstrap))]
282 extern "rust-intrinsic" {
283 // N.B., these intrinsics take raw pointers because they mutate aliased
284 // memory, which is not valid for either `&` or `&mut`.
286 /// Stores a value if the current value is the same as the `old` value.
288 /// The stabilized version of this intrinsic is available on the
289 /// [`atomic`] types via the `compare_exchange` method by passing
290 /// [`Ordering::Relaxed`] as both the success and failure parameters.
291 /// For example, [`AtomicBool::compare_exchange`].
292 pub fn atomic_cxchg_relaxed_relaxed<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
293 /// Stores a value if the current value is the same as the `old` value.
295 /// The stabilized version of this intrinsic is available on the
296 /// [`atomic`] types via the `compare_exchange` method by passing
297 /// [`Ordering::Relaxed`] and [`Ordering::Acquire`] as the success and failure parameters.
298 /// For example, [`AtomicBool::compare_exchange`].
299 pub fn atomic_cxchg_relaxed_acquire<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
300 /// Stores a value if the current value is the same as the `old` value.
302 /// The stabilized version of this intrinsic is available on the
303 /// [`atomic`] types via the `compare_exchange` method by passing
304 /// [`Ordering::Relaxed`] and [`Ordering::SeqCst`] as the success and failure parameters.
305 /// For example, [`AtomicBool::compare_exchange`].
306 pub fn atomic_cxchg_relaxed_seqcst<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
307 /// Stores a value if the current value is the same as the `old` value.
309 /// The stabilized version of this intrinsic is available on the
310 /// [`atomic`] types via the `compare_exchange` method by passing
311 /// [`Ordering::Acquire`] and [`Ordering::Relaxed`] as the success and failure parameters.
312 /// For example, [`AtomicBool::compare_exchange`].
313 pub fn atomic_cxchg_acquire_relaxed<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
314 /// Stores a value if the current value is the same as the `old` value.
316 /// The stabilized version of this intrinsic is available on the
317 /// [`atomic`] types via the `compare_exchange` method by passing
318 /// [`Ordering::Acquire`] as both the success and failure parameters.
319 /// For example, [`AtomicBool::compare_exchange`].
320 pub fn atomic_cxchg_acquire_acquire<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
321 /// Stores a value if the current value is the same as the `old` value.
323 /// The stabilized version of this intrinsic is available on the
324 /// [`atomic`] types via the `compare_exchange` method by passing
325 /// [`Ordering::Acquire`] and [`Ordering::SeqCst`] as the success and failure parameters.
326 /// For example, [`AtomicBool::compare_exchange`].
327 pub fn atomic_cxchg_acquire_seqcst<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
328 /// Stores a value if the current value is the same as the `old` value.
330 /// The stabilized version of this intrinsic is available on the
331 /// [`atomic`] types via the `compare_exchange` method by passing
332 /// [`Ordering::Release`] and [`Ordering::Relaxed`] as the success and failure parameters.
333 /// For example, [`AtomicBool::compare_exchange`].
334 pub fn atomic_cxchg_release_relaxed<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
335 /// Stores a value if the current value is the same as the `old` value.
337 /// The stabilized version of this intrinsic is available on the
338 /// [`atomic`] types via the `compare_exchange` method by passing
339 /// [`Ordering::Release`] and [`Ordering::Acquire`] as the success and failure parameters.
340 /// For example, [`AtomicBool::compare_exchange`].
341 pub fn atomic_cxchg_release_acquire<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
342 /// Stores a value if the current value is the same as the `old` value.
344 /// The stabilized version of this intrinsic is available on the
345 /// [`atomic`] types via the `compare_exchange` method by passing
346 /// [`Ordering::Release`] and [`Ordering::SeqCst`] as the success and failure parameters.
347 /// For example, [`AtomicBool::compare_exchange`].
348 pub fn atomic_cxchg_release_seqcst<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
349 /// Stores a value if the current value is the same as the `old` value.
351 /// The stabilized version of this intrinsic is available on the
352 /// [`atomic`] types via the `compare_exchange` method by passing
353 /// [`Ordering::AcqRel`] and [`Ordering::Relaxed`] as the success and failure parameters.
354 /// For example, [`AtomicBool::compare_exchange`].
355 pub fn atomic_cxchg_acqrel_relaxed<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
356 /// Stores a value if the current value is the same as the `old` value.
358 /// The stabilized version of this intrinsic is available on the
359 /// [`atomic`] types via the `compare_exchange` method by passing
360 /// [`Ordering::AcqRel`] and [`Ordering::Acquire`] as the success and failure parameters.
361 /// For example, [`AtomicBool::compare_exchange`].
362 pub fn atomic_cxchg_acqrel_acquire<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
363 /// Stores a value if the current value is the same as the `old` value.
365 /// The stabilized version of this intrinsic is available on the
366 /// [`atomic`] types via the `compare_exchange` method by passing
367 /// [`Ordering::AcqRel`] and [`Ordering::SeqCst`] as the success and failure parameters.
368 /// For example, [`AtomicBool::compare_exchange`].
369 pub fn atomic_cxchg_acqrel_seqcst<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
370 /// Stores a value if the current value is the same as the `old` value.
372 /// The stabilized version of this intrinsic is available on the
373 /// [`atomic`] types via the `compare_exchange` method by passing
374 /// [`Ordering::SeqCst`] and [`Ordering::Relaxed`] as the success and failure parameters.
375 /// For example, [`AtomicBool::compare_exchange`].
376 pub fn atomic_cxchg_seqcst_relaxed<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
377 /// Stores a value if the current value is the same as the `old` value.
379 /// The stabilized version of this intrinsic is available on the
380 /// [`atomic`] types via the `compare_exchange` method by passing
381 /// [`Ordering::SeqCst`] and [`Ordering::Acquire`] as the success and failure parameters.
382 /// For example, [`AtomicBool::compare_exchange`].
383 pub fn atomic_cxchg_seqcst_acquire<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
384 /// Stores a value if the current value is the same as the `old` value.
386 /// The stabilized version of this intrinsic is available on the
387 /// [`atomic`] types via the `compare_exchange` method by passing
388 /// [`Ordering::SeqCst`] as both the success and failure parameters.
389 /// For example, [`AtomicBool::compare_exchange`].
390 pub fn atomic_cxchg_seqcst_seqcst<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
392 /// Stores a value if the current value is the same as the `old` value.
394 /// The stabilized version of this intrinsic is available on the
395 /// [`atomic`] types via the `compare_exchange_weak` method by passing
396 /// [`Ordering::Relaxed`] as both the success and failure parameters.
397 /// For example, [`AtomicBool::compare_exchange_weak`].
398 pub fn atomic_cxchgweak_relaxed_relaxed<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
399 /// Stores a value if the current value is the same as the `old` value.
401 /// The stabilized version of this intrinsic is available on the
402 /// [`atomic`] types via the `compare_exchange_weak` method by passing
403 /// [`Ordering::Relaxed`] and [`Ordering::Acquire`] as the success and failure parameters.
404 /// For example, [`AtomicBool::compare_exchange_weak`].
405 pub fn atomic_cxchgweak_relaxed_acquire<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
406 /// Stores a value if the current value is the same as the `old` value.
408 /// The stabilized version of this intrinsic is available on the
409 /// [`atomic`] types via the `compare_exchange_weak` method by passing
410 /// [`Ordering::Relaxed`] and [`Ordering::SeqCst`] as the success and failure parameters.
411 /// For example, [`AtomicBool::compare_exchange_weak`].
412 pub fn atomic_cxchgweak_relaxed_seqcst<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
413 /// Stores a value if the current value is the same as the `old` value.
415 /// The stabilized version of this intrinsic is available on the
416 /// [`atomic`] types via the `compare_exchange_weak` method by passing
417 /// [`Ordering::Acquire`] and [`Ordering::Relaxed`] as the success and failure parameters.
418 /// For example, [`AtomicBool::compare_exchange_weak`].
419 pub fn atomic_cxchgweak_acquire_relaxed<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
420 /// Stores a value if the current value is the same as the `old` value.
422 /// The stabilized version of this intrinsic is available on the
423 /// [`atomic`] types via the `compare_exchange_weak` method by passing
424 /// [`Ordering::Acquire`] as both the success and failure parameters.
425 /// For example, [`AtomicBool::compare_exchange_weak`].
426 pub fn atomic_cxchgweak_acquire_acquire<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
427 /// Stores a value if the current value is the same as the `old` value.
429 /// The stabilized version of this intrinsic is available on the
430 /// [`atomic`] types via the `compare_exchange_weak` method by passing
431 /// [`Ordering::Acquire`] and [`Ordering::SeqCst`] as the success and failure parameters.
432 /// For example, [`AtomicBool::compare_exchange_weak`].
433 pub fn atomic_cxchgweak_acquire_seqcst<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
434 /// Stores a value if the current value is the same as the `old` value.
436 /// The stabilized version of this intrinsic is available on the
437 /// [`atomic`] types via the `compare_exchange_weak` method by passing
438 /// [`Ordering::Release`] and [`Ordering::Relaxed`] as the success and failure parameters.
439 /// For example, [`AtomicBool::compare_exchange_weak`].
440 pub fn atomic_cxchgweak_release_relaxed<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
441 /// Stores a value if the current value is the same as the `old` value.
443 /// The stabilized version of this intrinsic is available on the
444 /// [`atomic`] types via the `compare_exchange_weak` method by passing
445 /// [`Ordering::Release`] and [`Ordering::Acquire`] as the success and failure parameters.
446 /// For example, [`AtomicBool::compare_exchange_weak`].
447 pub fn atomic_cxchgweak_release_acquire<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
448 /// Stores a value if the current value is the same as the `old` value.
450 /// The stabilized version of this intrinsic is available on the
451 /// [`atomic`] types via the `compare_exchange_weak` method by passing
452 /// [`Ordering::Release`] and [`Ordering::SeqCst`] as the success and failure parameters.
453 /// For example, [`AtomicBool::compare_exchange_weak`].
454 pub fn atomic_cxchgweak_release_seqcst<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
455 /// Stores a value if the current value is the same as the `old` value.
457 /// The stabilized version of this intrinsic is available on the
458 /// [`atomic`] types via the `compare_exchange_weak` method by passing
459 /// [`Ordering::AcqRel`] and [`Ordering::Relaxed`] as the success and failure parameters.
460 /// For example, [`AtomicBool::compare_exchange_weak`].
461 pub fn atomic_cxchgweak_acqrel_relaxed<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
462 /// Stores a value if the current value is the same as the `old` value.
464 /// The stabilized version of this intrinsic is available on the
465 /// [`atomic`] types via the `compare_exchange_weak` method by passing
466 /// [`Ordering::AcqRel`] and [`Ordering::Acquire`] as the success and failure parameters.
467 /// For example, [`AtomicBool::compare_exchange_weak`].
468 pub fn atomic_cxchgweak_acqrel_acquire<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
469 /// Stores a value if the current value is the same as the `old` value.
471 /// The stabilized version of this intrinsic is available on the
472 /// [`atomic`] types via the `compare_exchange_weak` method by passing
473 /// [`Ordering::AcqRel`] and [`Ordering::SeqCst`] as the success and failure parameters.
474 /// For example, [`AtomicBool::compare_exchange_weak`].
475 pub fn atomic_cxchgweak_acqrel_seqcst<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
476 /// Stores a value if the current value is the same as the `old` value.
478 /// The stabilized version of this intrinsic is available on the
479 /// [`atomic`] types via the `compare_exchange_weak` method by passing
480 /// [`Ordering::SeqCst`] and [`Ordering::Relaxed`] as the success and failure parameters.
481 /// For example, [`AtomicBool::compare_exchange_weak`].
482 pub fn atomic_cxchgweak_seqcst_relaxed<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
483 /// Stores a value if the current value is the same as the `old` value.
485 /// The stabilized version of this intrinsic is available on the
486 /// [`atomic`] types via the `compare_exchange_weak` method by passing
487 /// [`Ordering::SeqCst`] and [`Ordering::Acquire`] as the success and failure parameters.
488 /// For example, [`AtomicBool::compare_exchange_weak`].
489 pub fn atomic_cxchgweak_seqcst_acquire<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
490 /// Stores a value if the current value is the same as the `old` value.
492 /// The stabilized version of this intrinsic is available on the
493 /// [`atomic`] types via the `compare_exchange_weak` method by passing
494 /// [`Ordering::SeqCst`] as both the success and failure parameters.
495 /// For example, [`AtomicBool::compare_exchange_weak`].
496 pub fn atomic_cxchgweak_seqcst_seqcst<T: Copy>(dst: *mut T, old: T, src: T) -> (T, bool);
498 /// Loads the current value of the pointer.
500 /// The stabilized version of this intrinsic is available on the
501 /// [`atomic`] types via the `load` method by passing
502 /// [`Ordering::SeqCst`] as the `order`. For example, [`AtomicBool::load`].
503 pub fn atomic_load_seqcst<T: Copy>(src: *const T) -> T;
504 /// Loads the current value of the pointer.
506 /// The stabilized version of this intrinsic is available on the
507 /// [`atomic`] types via the `load` method by passing
508 /// [`Ordering::Acquire`] as the `order`. For example, [`AtomicBool::load`].
509 pub fn atomic_load_acquire<T: Copy>(src: *const T) -> T;
510 /// Loads the current value of the pointer.
512 /// The stabilized version of this intrinsic is available on the
513 /// [`atomic`] types via the `load` method by passing
514 /// [`Ordering::Relaxed`] as the `order`. For example, [`AtomicBool::load`].
515 pub fn atomic_load_relaxed<T: Copy>(src: *const T) -> T;
516 pub fn atomic_load_unordered<T: Copy>(src: *const T) -> T;
518 /// Stores the value at the specified memory location.
520 /// The stabilized version of this intrinsic is available on the
521 /// [`atomic`] types via the `store` method by passing
522 /// [`Ordering::SeqCst`] as the `order`. For example, [`AtomicBool::store`].
523 pub fn atomic_store_seqcst<T: Copy>(dst: *mut T, val: T);
524 /// Stores the value at the specified memory location.
526 /// The stabilized version of this intrinsic is available on the
527 /// [`atomic`] types via the `store` method by passing
528 /// [`Ordering::Release`] as the `order`. For example, [`AtomicBool::store`].
529 pub fn atomic_store_release<T: Copy>(dst: *mut T, val: T);
530 /// Stores the value at the specified memory location.
532 /// The stabilized version of this intrinsic is available on the
533 /// [`atomic`] types via the `store` method by passing
534 /// [`Ordering::Relaxed`] as the `order`. For example, [`AtomicBool::store`].
535 pub fn atomic_store_relaxed<T: Copy>(dst: *mut T, val: T);
536 pub fn atomic_store_unordered<T: Copy>(dst: *mut T, val: T);
538 /// Stores the value at the specified memory location, returning the old value.
540 /// The stabilized version of this intrinsic is available on the
541 /// [`atomic`] types via the `swap` method by passing
542 /// [`Ordering::SeqCst`] as the `order`. For example, [`AtomicBool::swap`].
543 pub fn atomic_xchg_seqcst<T: Copy>(dst: *mut T, src: T) -> T;
544 /// Stores the value at the specified memory location, returning the old value.
546 /// The stabilized version of this intrinsic is available on the
547 /// [`atomic`] types via the `swap` method by passing
548 /// [`Ordering::Acquire`] as the `order`. For example, [`AtomicBool::swap`].
549 pub fn atomic_xchg_acquire<T: Copy>(dst: *mut T, src: T) -> T;
550 /// Stores the value at the specified memory location, returning the old value.
552 /// The stabilized version of this intrinsic is available on the
553 /// [`atomic`] types via the `swap` method by passing
554 /// [`Ordering::Release`] as the `order`. For example, [`AtomicBool::swap`].
555 pub fn atomic_xchg_release<T: Copy>(dst: *mut T, src: T) -> T;
556 /// Stores the value at the specified memory location, returning the old value.
558 /// The stabilized version of this intrinsic is available on the
559 /// [`atomic`] types via the `swap` method by passing
560 /// [`Ordering::AcqRel`] as the `order`. For example, [`AtomicBool::swap`].
561 pub fn atomic_xchg_acqrel<T: Copy>(dst: *mut T, src: T) -> T;
562 /// Stores the value at the specified memory location, returning the old value.
564 /// The stabilized version of this intrinsic is available on the
565 /// [`atomic`] types via the `swap` method by passing
566 /// [`Ordering::Relaxed`] as the `order`. For example, [`AtomicBool::swap`].
567 pub fn atomic_xchg_relaxed<T: Copy>(dst: *mut T, src: T) -> T;
569 /// Adds to the current value, returning the previous value.
571 /// The stabilized version of this intrinsic is available on the
572 /// [`atomic`] types via the `fetch_add` method by passing
573 /// [`Ordering::SeqCst`] as the `order`. For example, [`AtomicIsize::fetch_add`].
574 pub fn atomic_xadd_seqcst<T: Copy>(dst: *mut T, src: T) -> T;
575 /// Adds to the current value, returning the previous value.
577 /// The stabilized version of this intrinsic is available on the
578 /// [`atomic`] types via the `fetch_add` method by passing
579 /// [`Ordering::Acquire`] as the `order`. For example, [`AtomicIsize::fetch_add`].
580 pub fn atomic_xadd_acquire<T: Copy>(dst: *mut T, src: T) -> T;
581 /// Adds to the current value, returning the previous value.
583 /// The stabilized version of this intrinsic is available on the
584 /// [`atomic`] types via the `fetch_add` method by passing
585 /// [`Ordering::Release`] as the `order`. For example, [`AtomicIsize::fetch_add`].
586 pub fn atomic_xadd_release<T: Copy>(dst: *mut T, src: T) -> T;
587 /// Adds to the current value, returning the previous value.
589 /// The stabilized version of this intrinsic is available on the
590 /// [`atomic`] types via the `fetch_add` method by passing
591 /// [`Ordering::AcqRel`] as the `order`. For example, [`AtomicIsize::fetch_add`].
592 pub fn atomic_xadd_acqrel<T: Copy>(dst: *mut T, src: T) -> T;
593 /// Adds to the current value, returning the previous value.
595 /// The stabilized version of this intrinsic is available on the
596 /// [`atomic`] types via the `fetch_add` method by passing
597 /// [`Ordering::Relaxed`] as the `order`. For example, [`AtomicIsize::fetch_add`].
598 pub fn atomic_xadd_relaxed<T: Copy>(dst: *mut T, src: T) -> T;
600 /// Subtract from the current value, returning the previous value.
602 /// The stabilized version of this intrinsic is available on the
603 /// [`atomic`] types via the `fetch_sub` method by passing
604 /// [`Ordering::SeqCst`] as the `order`. For example, [`AtomicIsize::fetch_sub`].
605 pub fn atomic_xsub_seqcst<T: Copy>(dst: *mut T, src: T) -> T;
606 /// Subtract from the current value, returning the previous value.
608 /// The stabilized version of this intrinsic is available on the
609 /// [`atomic`] types via the `fetch_sub` method by passing
610 /// [`Ordering::Acquire`] as the `order`. For example, [`AtomicIsize::fetch_sub`].
611 pub fn atomic_xsub_acquire<T: Copy>(dst: *mut T, src: T) -> T;
612 /// Subtract from the current value, returning the previous value.
614 /// The stabilized version of this intrinsic is available on the
615 /// [`atomic`] types via the `fetch_sub` method by passing
616 /// [`Ordering::Release`] as the `order`. For example, [`AtomicIsize::fetch_sub`].
617 pub fn atomic_xsub_release<T: Copy>(dst: *mut T, src: T) -> T;
618 /// Subtract from the current value, returning the previous value.
620 /// The stabilized version of this intrinsic is available on the
621 /// [`atomic`] types via the `fetch_sub` method by passing
622 /// [`Ordering::AcqRel`] as the `order`. For example, [`AtomicIsize::fetch_sub`].
623 pub fn atomic_xsub_acqrel<T: Copy>(dst: *mut T, src: T) -> T;
624 /// Subtract from the current value, returning the previous value.
626 /// The stabilized version of this intrinsic is available on the
627 /// [`atomic`] types via the `fetch_sub` method by passing
628 /// [`Ordering::Relaxed`] as the `order`. For example, [`AtomicIsize::fetch_sub`].
629 pub fn atomic_xsub_relaxed<T: Copy>(dst: *mut T, src: T) -> T;
631 /// Bitwise and with the current value, returning the previous value.
633 /// The stabilized version of this intrinsic is available on the
634 /// [`atomic`] types via the `fetch_and` method by passing
635 /// [`Ordering::SeqCst`] as the `order`. For example, [`AtomicBool::fetch_and`].
636 pub fn atomic_and_seqcst<T: Copy>(dst: *mut T, src: T) -> T;
637 /// Bitwise and with the current value, returning the previous value.
639 /// The stabilized version of this intrinsic is available on the
640 /// [`atomic`] types via the `fetch_and` method by passing
641 /// [`Ordering::Acquire`] as the `order`. For example, [`AtomicBool::fetch_and`].
642 pub fn atomic_and_acquire<T: Copy>(dst: *mut T, src: T) -> T;
643 /// Bitwise and with the current value, returning the previous value.
645 /// The stabilized version of this intrinsic is available on the
646 /// [`atomic`] types via the `fetch_and` method by passing
647 /// [`Ordering::Release`] as the `order`. For example, [`AtomicBool::fetch_and`].
648 pub fn atomic_and_release<T: Copy>(dst: *mut T, src: T) -> T;
649 /// Bitwise and with the current value, returning the previous value.
651 /// The stabilized version of this intrinsic is available on the
652 /// [`atomic`] types via the `fetch_and` method by passing
653 /// [`Ordering::AcqRel`] as the `order`. For example, [`AtomicBool::fetch_and`].
654 pub fn atomic_and_acqrel<T: Copy>(dst: *mut T, src: T) -> T;
655 /// Bitwise and with the current value, returning the previous value.
657 /// The stabilized version of this intrinsic is available on the
658 /// [`atomic`] types via the `fetch_and` method by passing
659 /// [`Ordering::Relaxed`] as the `order`. For example, [`AtomicBool::fetch_and`].
660 pub fn atomic_and_relaxed<T: Copy>(dst: *mut T, src: T) -> T;
662 /// Bitwise nand with the current value, returning the previous value.
664 /// The stabilized version of this intrinsic is available on the
665 /// [`AtomicBool`] type via the `fetch_nand` method by passing
666 /// [`Ordering::SeqCst`] as the `order`. For example, [`AtomicBool::fetch_nand`].
667 pub fn atomic_nand_seqcst<T: Copy>(dst: *mut T, src: T) -> T;
668 /// Bitwise nand with the current value, returning the previous value.
670 /// The stabilized version of this intrinsic is available on the
671 /// [`AtomicBool`] type via the `fetch_nand` method by passing
672 /// [`Ordering::Acquire`] as the `order`. For example, [`AtomicBool::fetch_nand`].
673 pub fn atomic_nand_acquire<T: Copy>(dst: *mut T, src: T) -> T;
674 /// Bitwise nand with the current value, returning the previous value.
676 /// The stabilized version of this intrinsic is available on the
677 /// [`AtomicBool`] type via the `fetch_nand` method by passing
678 /// [`Ordering::Release`] as the `order`. For example, [`AtomicBool::fetch_nand`].
679 pub fn atomic_nand_release<T: Copy>(dst: *mut T, src: T) -> T;
680 /// Bitwise nand with the current value, returning the previous value.
682 /// The stabilized version of this intrinsic is available on the
683 /// [`AtomicBool`] type via the `fetch_nand` method by passing
684 /// [`Ordering::AcqRel`] as the `order`. For example, [`AtomicBool::fetch_nand`].
685 pub fn atomic_nand_acqrel<T: Copy>(dst: *mut T, src: T) -> T;
686 /// Bitwise nand with the current value, returning the previous value.
688 /// The stabilized version of this intrinsic is available on the
689 /// [`AtomicBool`] type via the `fetch_nand` method by passing
690 /// [`Ordering::Relaxed`] as the `order`. For example, [`AtomicBool::fetch_nand`].
691 pub fn atomic_nand_relaxed<T: Copy>(dst: *mut T, src: T) -> T;
693 /// Bitwise or with the current value, returning the previous value.
695 /// The stabilized version of this intrinsic is available on the
696 /// [`atomic`] types via the `fetch_or` method by passing
697 /// [`Ordering::SeqCst`] as the `order`. For example, [`AtomicBool::fetch_or`].
698 pub fn atomic_or_seqcst<T: Copy>(dst: *mut T, src: T) -> T;
699 /// Bitwise or with the current value, returning the previous value.
701 /// The stabilized version of this intrinsic is available on the
702 /// [`atomic`] types via the `fetch_or` method by passing
703 /// [`Ordering::Acquire`] as the `order`. For example, [`AtomicBool::fetch_or`].
704 pub fn atomic_or_acquire<T: Copy>(dst: *mut T, src: T) -> T;
705 /// Bitwise or with the current value, returning the previous value.
707 /// The stabilized version of this intrinsic is available on the
708 /// [`atomic`] types via the `fetch_or` method by passing
709 /// [`Ordering::Release`] as the `order`. For example, [`AtomicBool::fetch_or`].
710 pub fn atomic_or_release<T: Copy>(dst: *mut T, src: T) -> T;
711 /// Bitwise or with the current value, returning the previous value.
713 /// The stabilized version of this intrinsic is available on the
714 /// [`atomic`] types via the `fetch_or` method by passing
715 /// [`Ordering::AcqRel`] as the `order`. For example, [`AtomicBool::fetch_or`].
716 pub fn atomic_or_acqrel<T: Copy>(dst: *mut T, src: T) -> T;
717 /// Bitwise or with the current value, returning the previous value.
719 /// The stabilized version of this intrinsic is available on the
720 /// [`atomic`] types via the `fetch_or` method by passing
721 /// [`Ordering::Relaxed`] as the `order`. For example, [`AtomicBool::fetch_or`].
722 pub fn atomic_or_relaxed<T: Copy>(dst: *mut T, src: T) -> T;
724 /// Bitwise xor with the current value, returning the previous value.
726 /// The stabilized version of this intrinsic is available on the
727 /// [`atomic`] types via the `fetch_xor` method by passing
728 /// [`Ordering::SeqCst`] as the `order`. For example, [`AtomicBool::fetch_xor`].
729 pub fn atomic_xor_seqcst<T: Copy>(dst: *mut T, src: T) -> T;
730 /// Bitwise xor with the current value, returning the previous value.
732 /// The stabilized version of this intrinsic is available on the
733 /// [`atomic`] types via the `fetch_xor` method by passing
734 /// [`Ordering::Acquire`] as the `order`. For example, [`AtomicBool::fetch_xor`].
735 pub fn atomic_xor_acquire<T: Copy>(dst: *mut T, src: T) -> T;
736 /// Bitwise xor with the current value, returning the previous value.
738 /// The stabilized version of this intrinsic is available on the
739 /// [`atomic`] types via the `fetch_xor` method by passing
740 /// [`Ordering::Release`] as the `order`. For example, [`AtomicBool::fetch_xor`].
741 pub fn atomic_xor_release<T: Copy>(dst: *mut T, src: T) -> T;
742 /// Bitwise xor with the current value, returning the previous value.
744 /// The stabilized version of this intrinsic is available on the
745 /// [`atomic`] types via the `fetch_xor` method by passing
746 /// [`Ordering::AcqRel`] as the `order`. For example, [`AtomicBool::fetch_xor`].
747 pub fn atomic_xor_acqrel<T: Copy>(dst: *mut T, src: T) -> T;
748 /// Bitwise xor with the current value, returning the previous value.
750 /// The stabilized version of this intrinsic is available on the
751 /// [`atomic`] types via the `fetch_xor` method by passing
752 /// [`Ordering::Relaxed`] as the `order`. For example, [`AtomicBool::fetch_xor`].
753 pub fn atomic_xor_relaxed<T: Copy>(dst: *mut T, src: T) -> T;
755 /// Maximum with the current value using a signed comparison.
757 /// The stabilized version of this intrinsic is available on the
758 /// [`atomic`] signed integer types via the `fetch_max` method by passing
759 /// [`Ordering::SeqCst`] as the `order`. For example, [`AtomicI32::fetch_max`].
760 pub fn atomic_max_seqcst<T: Copy>(dst: *mut T, src: T) -> T;
761 /// Maximum with the current value using a signed comparison.
763 /// The stabilized version of this intrinsic is available on the
764 /// [`atomic`] signed integer types via the `fetch_max` method by passing
765 /// [`Ordering::Acquire`] as the `order`. For example, [`AtomicI32::fetch_max`].
766 pub fn atomic_max_acquire<T: Copy>(dst: *mut T, src: T) -> T;
767 /// Maximum with the current value using a signed comparison.
769 /// The stabilized version of this intrinsic is available on the
770 /// [`atomic`] signed integer types via the `fetch_max` method by passing
771 /// [`Ordering::Release`] as the `order`. For example, [`AtomicI32::fetch_max`].
772 pub fn atomic_max_release<T: Copy>(dst: *mut T, src: T) -> T;
773 /// Maximum with the current value using a signed comparison.
775 /// The stabilized version of this intrinsic is available on the
776 /// [`atomic`] signed integer types via the `fetch_max` method by passing
777 /// [`Ordering::AcqRel`] as the `order`. For example, [`AtomicI32::fetch_max`].
778 pub fn atomic_max_acqrel<T: Copy>(dst: *mut T, src: T) -> T;
779 /// Maximum with the current value.
781 /// The stabilized version of this intrinsic is available on the
782 /// [`atomic`] signed integer types via the `fetch_max` method by passing
783 /// [`Ordering::Relaxed`] as the `order`. For example, [`AtomicI32::fetch_max`].
784 pub fn atomic_max_relaxed<T: Copy>(dst: *mut T, src: T) -> T;
786 /// Minimum with the current value using a signed comparison.
788 /// The stabilized version of this intrinsic is available on the
789 /// [`atomic`] signed integer types via the `fetch_min` method by passing
790 /// [`Ordering::SeqCst`] as the `order`. For example, [`AtomicI32::fetch_min`].
791 pub fn atomic_min_seqcst<T: Copy>(dst: *mut T, src: T) -> T;
792 /// Minimum with the current value using a signed comparison.
794 /// The stabilized version of this intrinsic is available on the
795 /// [`atomic`] signed integer types via the `fetch_min` method by passing
796 /// [`Ordering::Acquire`] as the `order`. For example, [`AtomicI32::fetch_min`].
797 pub fn atomic_min_acquire<T: Copy>(dst: *mut T, src: T) -> T;
798 /// Minimum with the current value using a signed comparison.
800 /// The stabilized version of this intrinsic is available on the
801 /// [`atomic`] signed integer types via the `fetch_min` method by passing
802 /// [`Ordering::Release`] as the `order`. For example, [`AtomicI32::fetch_min`].
803 pub fn atomic_min_release<T: Copy>(dst: *mut T, src: T) -> T;
804 /// Minimum with the current value using a signed comparison.
806 /// The stabilized version of this intrinsic is available on the
807 /// [`atomic`] signed integer types via the `fetch_min` method by passing
808 /// [`Ordering::AcqRel`] as the `order`. For example, [`AtomicI32::fetch_min`].
809 pub fn atomic_min_acqrel<T: Copy>(dst: *mut T, src: T) -> T;
810 /// Minimum with the current value using a signed comparison.
812 /// The stabilized version of this intrinsic is available on the
813 /// [`atomic`] signed integer types via the `fetch_min` method by passing
814 /// [`Ordering::Relaxed`] as the `order`. For example, [`AtomicI32::fetch_min`].
815 pub fn atomic_min_relaxed<T: Copy>(dst: *mut T, src: T) -> T;
817 /// Minimum with the current value using an unsigned comparison.
819 /// The stabilized version of this intrinsic is available on the
820 /// [`atomic`] unsigned integer types via the `fetch_min` method by passing
821 /// [`Ordering::SeqCst`] as the `order`. For example, [`AtomicU32::fetch_min`].
822 pub fn atomic_umin_seqcst<T: Copy>(dst: *mut T, src: T) -> T;
823 /// Minimum with the current value using an unsigned comparison.
825 /// The stabilized version of this intrinsic is available on the
826 /// [`atomic`] unsigned integer types via the `fetch_min` method by passing
827 /// [`Ordering::Acquire`] as the `order`. For example, [`AtomicU32::fetch_min`].
828 pub fn atomic_umin_acquire<T: Copy>(dst: *mut T, src: T) -> T;
829 /// Minimum with the current value using an unsigned comparison.
831 /// The stabilized version of this intrinsic is available on the
832 /// [`atomic`] unsigned integer types via the `fetch_min` method by passing
833 /// [`Ordering::Release`] as the `order`. For example, [`AtomicU32::fetch_min`].
834 pub fn atomic_umin_release<T: Copy>(dst: *mut T, src: T) -> T;
835 /// Minimum with the current value using an unsigned comparison.
837 /// The stabilized version of this intrinsic is available on the
838 /// [`atomic`] unsigned integer types via the `fetch_min` method by passing
839 /// [`Ordering::AcqRel`] as the `order`. For example, [`AtomicU32::fetch_min`].
840 pub fn atomic_umin_acqrel<T: Copy>(dst: *mut T, src: T) -> T;
841 /// Minimum with the current value using an unsigned comparison.
843 /// The stabilized version of this intrinsic is available on the
844 /// [`atomic`] unsigned integer types via the `fetch_min` method by passing
845 /// [`Ordering::Relaxed`] as the `order`. For example, [`AtomicU32::fetch_min`].
846 pub fn atomic_umin_relaxed<T: Copy>(dst: *mut T, src: T) -> T;
848 /// Maximum with the current value using an unsigned comparison.
850 /// The stabilized version of this intrinsic is available on the
851 /// [`atomic`] unsigned integer types via the `fetch_max` method by passing
852 /// [`Ordering::SeqCst`] as the `order`. For example, [`AtomicU32::fetch_max`].
853 pub fn atomic_umax_seqcst<T: Copy>(dst: *mut T, src: T) -> T;
854 /// Maximum with the current value using an unsigned comparison.
856 /// The stabilized version of this intrinsic is available on the
857 /// [`atomic`] unsigned integer types via the `fetch_max` method by passing
858 /// [`Ordering::Acquire`] as the `order`. For example, [`AtomicU32::fetch_max`].
859 pub fn atomic_umax_acquire<T: Copy>(dst: *mut T, src: T) -> T;
860 /// Maximum with the current value using an unsigned comparison.
862 /// The stabilized version of this intrinsic is available on the
863 /// [`atomic`] unsigned integer types via the `fetch_max` method by passing
864 /// [`Ordering::Release`] as the `order`. For example, [`AtomicU32::fetch_max`].
865 pub fn atomic_umax_release<T: Copy>(dst: *mut T, src: T) -> T;
866 /// Maximum with the current value using an unsigned comparison.
868 /// The stabilized version of this intrinsic is available on the
869 /// [`atomic`] unsigned integer types via the `fetch_max` method by passing
870 /// [`Ordering::AcqRel`] as the `order`. For example, [`AtomicU32::fetch_max`].
871 pub fn atomic_umax_acqrel<T: Copy>(dst: *mut T, src: T) -> T;
872 /// Maximum with the current value using an unsigned comparison.
874 /// The stabilized version of this intrinsic is available on the
875 /// [`atomic`] unsigned integer types via the `fetch_max` method by passing
876 /// [`Ordering::Relaxed`] as the `order`. For example, [`AtomicU32::fetch_max`].
877 pub fn atomic_umax_relaxed<T: Copy>(dst: *mut T, src: T) -> T;
881 /// The stabilized version of this intrinsic is available in
882 /// [`atomic::fence`] by passing [`Ordering::SeqCst`]
884 pub fn atomic_fence_seqcst();
887 /// The stabilized version of this intrinsic is available in
888 /// [`atomic::fence`] by passing [`Ordering::Acquire`]
890 pub fn atomic_fence_acquire();
893 /// The stabilized version of this intrinsic is available in
894 /// [`atomic::fence`] by passing [`Ordering::Release`]
896 pub fn atomic_fence_release();
899 /// The stabilized version of this intrinsic is available in
900 /// [`atomic::fence`] by passing [`Ordering::AcqRel`]
902 pub fn atomic_fence_acqrel();
904 /// A compiler-only memory barrier.
906 /// Memory accesses will never be reordered across this barrier by the
907 /// compiler, but no instructions will be emitted for it. This is
908 /// appropriate for operations on the same thread that may be preempted,
909 /// such as when interacting with signal handlers.
911 /// The stabilized version of this intrinsic is available in
912 /// [`atomic::compiler_fence`] by passing [`Ordering::SeqCst`]
914 pub fn atomic_singlethreadfence_seqcst();
915 /// A compiler-only memory barrier.
917 /// Memory accesses will never be reordered across this barrier by the
918 /// compiler, but no instructions will be emitted for it. This is
919 /// appropriate for operations on the same thread that may be preempted,
920 /// such as when interacting with signal handlers.
922 /// The stabilized version of this intrinsic is available in
923 /// [`atomic::compiler_fence`] by passing [`Ordering::Acquire`]
925 pub fn atomic_singlethreadfence_acquire();
926 /// A compiler-only memory barrier.
928 /// Memory accesses will never be reordered across this barrier by the
929 /// compiler, but no instructions will be emitted for it. This is
930 /// appropriate for operations on the same thread that may be preempted,
931 /// such as when interacting with signal handlers.
933 /// The stabilized version of this intrinsic is available in
934 /// [`atomic::compiler_fence`] by passing [`Ordering::Release`]
936 pub fn atomic_singlethreadfence_release();
937 /// A compiler-only memory barrier.
939 /// Memory accesses will never be reordered across this barrier by the
940 /// compiler, but no instructions will be emitted for it. This is
941 /// appropriate for operations on the same thread that may be preempted,
942 /// such as when interacting with signal handlers.
944 /// The stabilized version of this intrinsic is available in
945 /// [`atomic::compiler_fence`] by passing [`Ordering::AcqRel`]
947 pub fn atomic_singlethreadfence_acqrel();
950 // These have been renamed.
952 // These are the aliases for the old names.
953 // To be removed when stdarch and panic_unwind have been updated.
954 #[cfg(not(bootstrap))]
956 pub use super::atomic_cxchg_acqrel_acquire as atomic_cxchg_acqrel;
957 pub use super::atomic_cxchg_acqrel_relaxed as atomic_cxchg_acqrel_failrelaxed;
958 pub use super::atomic_cxchg_acquire_acquire as atomic_cxchg_acq;
959 pub use super::atomic_cxchg_acquire_relaxed as atomic_cxchg_acq_failrelaxed;
960 pub use super::atomic_cxchg_relaxed_relaxed as atomic_cxchg_relaxed;
961 pub use super::atomic_cxchg_release_relaxed as atomic_cxchg_rel;
962 pub use super::atomic_cxchg_seqcst_acquire as atomic_cxchg_failacq;
963 pub use super::atomic_cxchg_seqcst_relaxed as atomic_cxchg_failrelaxed;
964 pub use super::atomic_cxchg_seqcst_seqcst as atomic_cxchg;
965 pub use super::atomic_store_seqcst as atomic_store;
968 #[cfg(not(bootstrap))]
971 extern "rust-intrinsic" {
972 /// The `prefetch` intrinsic is a hint to the code generator to insert a prefetch instruction
973 /// if supported; otherwise, it is a no-op.
974 /// Prefetches have no effect on the behavior of the program but can change its performance
977 /// The `locality` argument must be a constant integer and is a temporal locality specifier
978 /// ranging from (0) - no locality, to (3) - extremely local keep in cache.
980 /// This intrinsic does not have a stable counterpart.
981 pub fn prefetch_read_data<T>(data: *const T, locality: i32);
982 /// The `prefetch` intrinsic is a hint to the code generator to insert a prefetch instruction
983 /// if supported; otherwise, it is a no-op.
984 /// Prefetches have no effect on the behavior of the program but can change its performance
987 /// The `locality` argument must be a constant integer and is a temporal locality specifier
988 /// ranging from (0) - no locality, to (3) - extremely local keep in cache.
990 /// This intrinsic does not have a stable counterpart.
991 pub fn prefetch_write_data<T>(data: *const T, locality: i32);
992 /// The `prefetch` intrinsic is a hint to the code generator to insert a prefetch instruction
993 /// if supported; otherwise, it is a no-op.
994 /// Prefetches have no effect on the behavior of the program but can change its performance
997 /// The `locality` argument must be a constant integer and is a temporal locality specifier
998 /// ranging from (0) - no locality, to (3) - extremely local keep in cache.
1000 /// This intrinsic does not have a stable counterpart.
1001 pub fn prefetch_read_instruction<T>(data: *const T, locality: i32);
1002 /// The `prefetch` intrinsic is a hint to the code generator to insert a prefetch instruction
1003 /// if supported; otherwise, it is a no-op.
1004 /// Prefetches have no effect on the behavior of the program but can change its performance
1005 /// characteristics.
1007 /// The `locality` argument must be a constant integer and is a temporal locality specifier
1008 /// ranging from (0) - no locality, to (3) - extremely local keep in cache.
1010 /// This intrinsic does not have a stable counterpart.
1011 pub fn prefetch_write_instruction<T>(data: *const T, locality: i32);
1013 /// Magic intrinsic that derives its meaning from attributes
1014 /// attached to the function.
1016 /// For example, dataflow uses this to inject static assertions so
1017 /// that `rustc_peek(potentially_uninitialized)` would actually
1018 /// double-check that dataflow did indeed compute that it is
1019 /// uninitialized at that point in the control flow.
1021 /// This intrinsic should not be used outside of the compiler.
1022 pub fn rustc_peek<T>(_: T) -> T;
1024 /// Aborts the execution of the process.
1026 /// Note that, unlike most intrinsics, this is safe to call;
1027 /// it does not require an `unsafe` block.
1028 /// Therefore, implementations must not require the user to uphold
1029 /// any safety invariants.
1031 /// [`std::process::abort`](../../std/process/fn.abort.html) is to be preferred if possible,
1032 /// as its behavior is more user-friendly and more stable.
1034 /// The current implementation of `intrinsics::abort` is to invoke an invalid instruction,
1035 /// on most platforms.
1037 /// process will probably terminate with a signal like `SIGABRT`, `SIGILL`, `SIGTRAP`, `SIGSEGV` or
1038 /// `SIGBUS`. The precise behaviour is not guaranteed and not stable.
1039 pub fn abort() -> !;
1041 /// Informs the optimizer that this point in the code is not reachable,
1042 /// enabling further optimizations.
1044 /// N.B., this is very different from the `unreachable!()` macro: Unlike the
1045 /// macro, which panics when it is executed, it is *undefined behavior* to
1046 /// reach code marked with this function.
1048 /// The stabilized version of this intrinsic is [`core::hint::unreachable_unchecked`].
1049 #[rustc_const_stable(feature = "const_unreachable_unchecked", since = "1.57.0")]
1050 pub fn unreachable() -> !;
1052 /// Informs the optimizer that a condition is always true.
1053 /// If the condition is false, the behavior is undefined.
1055 /// No code is generated for this intrinsic, but the optimizer will try
1056 /// to preserve it (and its condition) between passes, which may interfere
1057 /// with optimization of surrounding code and reduce performance. It should
1058 /// not be used if the invariant can be discovered by the optimizer on its
1059 /// own, or if it does not enable any significant optimizations.
1061 /// This intrinsic does not have a stable counterpart.
1062 #[rustc_const_unstable(feature = "const_assume", issue = "76972")]
1063 pub fn assume(b: bool);
1065 /// Hints to the compiler that branch condition is likely to be true.
1066 /// Returns the value passed to it.
1068 /// Any use other than with `if` statements will probably not have an effect.
1070 /// Note that, unlike most intrinsics, this is safe to call;
1071 /// it does not require an `unsafe` block.
1072 /// Therefore, implementations must not require the user to uphold
1073 /// any safety invariants.
1075 /// This intrinsic does not have a stable counterpart.
1076 #[rustc_const_unstable(feature = "const_likely", issue = "none")]
1077 pub fn likely(b: bool) -> bool;
1079 /// Hints to the compiler that branch condition is likely to be false.
1080 /// Returns the value passed to it.
1082 /// Any use other than with `if` statements will probably not have an effect.
1084 /// Note that, unlike most intrinsics, this is safe to call;
1085 /// it does not require an `unsafe` block.
1086 /// Therefore, implementations must not require the user to uphold
1087 /// any safety invariants.
1089 /// This intrinsic does not have a stable counterpart.
1090 #[rustc_const_unstable(feature = "const_likely", issue = "none")]
1091 pub fn unlikely(b: bool) -> bool;
1093 /// Executes a breakpoint trap, for inspection by a debugger.
1095 /// This intrinsic does not have a stable counterpart.
1096 pub fn breakpoint();
1098 /// The size of a type in bytes.
1100 /// Note that, unlike most intrinsics, this is safe to call;
1101 /// it does not require an `unsafe` block.
1102 /// Therefore, implementations must not require the user to uphold
1103 /// any safety invariants.
1105 /// More specifically, this is the offset in bytes between successive
1106 /// items of the same type, including alignment padding.
1108 /// The stabilized version of this intrinsic is [`core::mem::size_of`].
1109 #[rustc_const_stable(feature = "const_size_of", since = "1.40.0")]
1110 pub fn size_of<T>() -> usize;
1112 /// The minimum alignment of a type.
1114 /// Note that, unlike most intrinsics, this is safe to call;
1115 /// it does not require an `unsafe` block.
1116 /// Therefore, implementations must not require the user to uphold
1117 /// any safety invariants.
1119 /// The stabilized version of this intrinsic is [`core::mem::align_of`].
1120 #[rustc_const_stable(feature = "const_min_align_of", since = "1.40.0")]
1121 pub fn min_align_of<T>() -> usize;
1122 /// The preferred alignment of a type.
1124 /// This intrinsic does not have a stable counterpart.
1125 /// It's "tracking issue" is [#91971](https://github.com/rust-lang/rust/issues/91971).
1126 #[rustc_const_unstable(feature = "const_pref_align_of", issue = "91971")]
1127 pub fn pref_align_of<T>() -> usize;
1129 /// The size of the referenced value in bytes.
1131 /// The stabilized version of this intrinsic is [`mem::size_of_val`].
1132 #[rustc_const_unstable(feature = "const_size_of_val", issue = "46571")]
1133 pub fn size_of_val<T: ?Sized>(_: *const T) -> usize;
1134 /// The required alignment of the referenced value.
1136 /// The stabilized version of this intrinsic is [`core::mem::align_of_val`].
1137 #[rustc_const_unstable(feature = "const_align_of_val", issue = "46571")]
1138 pub fn min_align_of_val<T: ?Sized>(_: *const T) -> usize;
1140 /// Gets a static string slice containing the name of a type.
1142 /// Note that, unlike most intrinsics, this is safe to call;
1143 /// it does not require an `unsafe` block.
1144 /// Therefore, implementations must not require the user to uphold
1145 /// any safety invariants.
1147 /// The stabilized version of this intrinsic is [`core::any::type_name`].
1148 #[rustc_const_unstable(feature = "const_type_name", issue = "63084")]
1149 pub fn type_name<T: ?Sized>() -> &'static str;
1151 /// Gets an identifier which is globally unique to the specified type. This
1152 /// function will return the same value for a type regardless of whichever
1153 /// crate it is invoked in.
1155 /// Note that, unlike most intrinsics, this is safe to call;
1156 /// it does not require an `unsafe` block.
1157 /// Therefore, implementations must not require the user to uphold
1158 /// any safety invariants.
1160 /// The stabilized version of this intrinsic is [`core::any::TypeId::of`].
1161 #[rustc_const_unstable(feature = "const_type_id", issue = "77125")]
1162 pub fn type_id<T: ?Sized + 'static>() -> u64;
1164 /// A guard for unsafe functions that cannot ever be executed if `T` is uninhabited:
1165 /// This will statically either panic, or do nothing.
1167 /// This intrinsic does not have a stable counterpart.
1168 #[rustc_const_stable(feature = "const_assert_type", since = "1.59.0")]
1169 pub fn assert_inhabited<T>();
1171 /// A guard for unsafe functions that cannot ever be executed if `T` does not permit
1172 /// zero-initialization: This will statically either panic, or do nothing.
1174 /// This intrinsic does not have a stable counterpart.
1175 #[rustc_const_unstable(feature = "const_assert_type2", issue = "none")]
1176 pub fn assert_zero_valid<T>();
1178 /// A guard for unsafe functions that cannot ever be executed if `T` has invalid
1179 /// bit patterns: This will statically either panic, or do nothing.
1181 /// This intrinsic does not have a stable counterpart.
1182 #[rustc_const_unstable(feature = "const_assert_type2", issue = "none")]
1183 pub fn assert_uninit_valid<T>();
1185 /// Gets a reference to a static `Location` indicating where it was called.
1187 /// Note that, unlike most intrinsics, this is safe to call;
1188 /// it does not require an `unsafe` block.
1189 /// Therefore, implementations must not require the user to uphold
1190 /// any safety invariants.
1192 /// Consider using [`core::panic::Location::caller`] instead.
1193 #[rustc_const_unstable(feature = "const_caller_location", issue = "76156")]
1194 pub fn caller_location() -> &'static crate::panic::Location<'static>;
1196 /// Moves a value out of scope without running drop glue.
1198 /// This exists solely for [`mem::forget_unsized`]; normal `forget` uses
1199 /// `ManuallyDrop` instead.
1201 /// Note that, unlike most intrinsics, this is safe to call;
1202 /// it does not require an `unsafe` block.
1203 /// Therefore, implementations must not require the user to uphold
1204 /// any safety invariants.
1205 #[rustc_const_unstable(feature = "const_intrinsic_forget", issue = "none")]
1206 pub fn forget<T: ?Sized>(_: T);
1208 /// Reinterprets the bits of a value of one type as another type.
1210 /// Both types must have the same size. Neither the original, nor the result,
1211 /// may be an [invalid value](../../nomicon/what-unsafe-does.html).
1213 /// `transmute` is semantically equivalent to a bitwise move of one type
1214 /// into another. It copies the bits from the source value into the
1215 /// destination value, then forgets the original. It's equivalent to C's
1216 /// `memcpy` under the hood, just like `transmute_copy`.
1218 /// Because `transmute` is a by-value operation, alignment of the *transmuted values
1219 /// themselves* is not a concern. As with any other function, the compiler already ensures
1220 /// both `T` and `U` are properly aligned. However, when transmuting values that *point
1221 /// elsewhere* (such as pointers, references, boxes…), the caller has to ensure proper
1222 /// alignment of the pointed-to values.
1224 /// `transmute` is **incredibly** unsafe. There are a vast number of ways to
1225 /// cause [undefined behavior][ub] with this function. `transmute` should be
1226 /// the absolute last resort.
1228 /// Transmuting pointers to integers in a `const` context is [undefined behavior][ub].
1229 /// Any attempt to use the resulting value for integer operations will abort const-evaluation.
1231 /// The [nomicon](../../nomicon/transmutes.html) has additional
1234 /// [ub]: ../../reference/behavior-considered-undefined.html
1238 /// There are a few things that `transmute` is really useful for.
1240 /// Turning a pointer into a function pointer. This is *not* portable to
1241 /// machines where function pointers and data pointers have different sizes.
1244 /// fn foo() -> i32 {
1247 /// // Crucially, we `as`-cast to a raw pointer before `transmute`ing to a function pointer.
1248 /// // This avoids an integer-to-pointer `transmute`, which can be problematic.
1249 /// // Transmuting between raw pointers and function pointers (i.e., two pointer types) is fine.
1250 /// let pointer = foo as *const ();
1251 /// let function = unsafe {
1252 /// std::mem::transmute::<*const (), fn() -> i32>(pointer)
1254 /// assert_eq!(function(), 0);
1257 /// Extending a lifetime, or shortening an invariant lifetime. This is
1258 /// advanced, very unsafe Rust!
1261 /// struct R<'a>(&'a i32);
1262 /// unsafe fn extend_lifetime<'b>(r: R<'b>) -> R<'static> {
1263 /// std::mem::transmute::<R<'b>, R<'static>>(r)
1266 /// unsafe fn shorten_invariant_lifetime<'b, 'c>(r: &'b mut R<'static>)
1267 /// -> &'b mut R<'c> {
1268 /// std::mem::transmute::<&'b mut R<'static>, &'b mut R<'c>>(r)
1274 /// Don't despair: many uses of `transmute` can be achieved through other means.
1275 /// Below are common applications of `transmute` which can be replaced with safer
1278 /// Turning raw bytes (`&[u8]`) into `u32`, `f64`, etc.:
1281 /// let raw_bytes = [0x78, 0x56, 0x34, 0x12];
1283 /// let num = unsafe {
1284 /// std::mem::transmute::<[u8; 4], u32>(raw_bytes)
1287 /// // use `u32::from_ne_bytes` instead
1288 /// let num = u32::from_ne_bytes(raw_bytes);
1289 /// // or use `u32::from_le_bytes` or `u32::from_be_bytes` to specify the endianness
1290 /// let num = u32::from_le_bytes(raw_bytes);
1291 /// assert_eq!(num, 0x12345678);
1292 /// let num = u32::from_be_bytes(raw_bytes);
1293 /// assert_eq!(num, 0x78563412);
1296 /// Turning a pointer into a `usize`:
1300 /// let ptr_num_transmute = unsafe {
1301 /// std::mem::transmute::<&i32, usize>(ptr)
1304 /// // Use an `as` cast instead
1305 /// let ptr_num_cast = ptr as *const i32 as usize;
1308 /// Note that using `transmute` to turn a pointer to a `usize` is (as noted above) [undefined
1309 /// behavior][ub] in `const` contexts. Also outside of consts, this operation might not behave
1310 /// as expected -- this is touching on many unspecified aspects of the Rust memory model.
1311 /// Depending on what the code is doing, the following alternatives are preferrable to
1312 /// pointer-to-integer transmutation:
1313 /// - If the code just wants to store data of arbitrary type in some buffer and needs to pick a
1314 /// type for that buffer, it can use [`MaybeUninit`][mem::MaybeUninit].
1315 /// - If the code actually wants to work on the address the pointer points to, it can use `as`
1316 /// casts or [`ptr.addr()`][pointer::addr].
1318 /// Turning a `*mut T` into an `&mut T`:
1321 /// let ptr: *mut i32 = &mut 0;
1322 /// let ref_transmuted = unsafe {
1323 /// std::mem::transmute::<*mut i32, &mut i32>(ptr)
1326 /// // Use a reborrow instead
1327 /// let ref_casted = unsafe { &mut *ptr };
1330 /// Turning an `&mut T` into an `&mut U`:
1333 /// let ptr = &mut 0;
1334 /// let val_transmuted = unsafe {
1335 /// std::mem::transmute::<&mut i32, &mut u32>(ptr)
1338 /// // Now, put together `as` and reborrowing - note the chaining of `as`
1339 /// // `as` is not transitive
1340 /// let val_casts = unsafe { &mut *(ptr as *mut i32 as *mut u32) };
1343 /// Turning an `&str` into a `&[u8]`:
1346 /// // this is not a good way to do this.
1347 /// let slice = unsafe { std::mem::transmute::<&str, &[u8]>("Rust") };
1348 /// assert_eq!(slice, &[82, 117, 115, 116]);
1350 /// // You could use `str::as_bytes`
1351 /// let slice = "Rust".as_bytes();
1352 /// assert_eq!(slice, &[82, 117, 115, 116]);
1354 /// // Or, just use a byte string, if you have control over the string
1356 /// assert_eq!(b"Rust", &[82, 117, 115, 116]);
1359 /// Turning a `Vec<&T>` into a `Vec<Option<&T>>`.
1361 /// To transmute the inner type of the contents of a container, you must make sure to not
1362 /// violate any of the container's invariants. For `Vec`, this means that both the size
1363 /// *and alignment* of the inner types have to match. Other containers might rely on the
1364 /// size of the type, alignment, or even the `TypeId`, in which case transmuting wouldn't
1365 /// be possible at all without violating the container invariants.
1368 /// let store = [0, 1, 2, 3];
1369 /// let v_orig = store.iter().collect::<Vec<&i32>>();
1371 /// // clone the vector as we will reuse them later
1372 /// let v_clone = v_orig.clone();
1374 /// // Using transmute: this relies on the unspecified data layout of `Vec`, which is a
1375 /// // bad idea and could cause Undefined Behavior.
1376 /// // However, it is no-copy.
1377 /// let v_transmuted = unsafe {
1378 /// std::mem::transmute::<Vec<&i32>, Vec<Option<&i32>>>(v_clone)
1381 /// let v_clone = v_orig.clone();
1383 /// // This is the suggested, safe way.
1384 /// // It does copy the entire vector, though, into a new array.
1385 /// let v_collected = v_clone.into_iter()
1387 /// .collect::<Vec<Option<&i32>>>();
1389 /// let v_clone = v_orig.clone();
1391 /// // This is the proper no-copy, unsafe way of "transmuting" a `Vec`, without relying on the
1392 /// // data layout. Instead of literally calling `transmute`, we perform a pointer cast, but
1393 /// // in terms of converting the original inner type (`&i32`) to the new one (`Option<&i32>`),
1394 /// // this has all the same caveats. Besides the information provided above, also consult the
1395 /// // [`from_raw_parts`] documentation.
1396 /// let v_from_raw = unsafe {
1397 // FIXME Update this when vec_into_raw_parts is stabilized
1398 /// // Ensure the original vector is not dropped.
1399 /// let mut v_clone = std::mem::ManuallyDrop::new(v_clone);
1400 /// Vec::from_raw_parts(v_clone.as_mut_ptr() as *mut Option<&i32>,
1402 /// v_clone.capacity())
1406 /// [`from_raw_parts`]: ../../std/vec/struct.Vec.html#method.from_raw_parts
1408 /// Implementing `split_at_mut`:
1411 /// use std::{slice, mem};
1413 /// // There are multiple ways to do this, and there are multiple problems
1414 /// // with the following (transmute) way.
1415 /// fn split_at_mut_transmute<T>(slice: &mut [T], mid: usize)
1416 /// -> (&mut [T], &mut [T]) {
1417 /// let len = slice.len();
1418 /// assert!(mid <= len);
1420 /// let slice2 = mem::transmute::<&mut [T], &mut [T]>(slice);
1421 /// // first: transmute is not type safe; all it checks is that T and
1422 /// // U are of the same size. Second, right here, you have two
1423 /// // mutable references pointing to the same memory.
1424 /// (&mut slice[0..mid], &mut slice2[mid..len])
1428 /// // This gets rid of the type safety problems; `&mut *` will *only* give
1429 /// // you an `&mut T` from an `&mut T` or `*mut T`.
1430 /// fn split_at_mut_casts<T>(slice: &mut [T], mid: usize)
1431 /// -> (&mut [T], &mut [T]) {
1432 /// let len = slice.len();
1433 /// assert!(mid <= len);
1435 /// let slice2 = &mut *(slice as *mut [T]);
1436 /// // however, you still have two mutable references pointing to
1437 /// // the same memory.
1438 /// (&mut slice[0..mid], &mut slice2[mid..len])
1442 /// // This is how the standard library does it. This is the best method, if
1443 /// // you need to do something like this
1444 /// fn split_at_stdlib<T>(slice: &mut [T], mid: usize)
1445 /// -> (&mut [T], &mut [T]) {
1446 /// let len = slice.len();
1447 /// assert!(mid <= len);
1449 /// let ptr = slice.as_mut_ptr();
1450 /// // This now has three mutable references pointing at the same
1451 /// // memory. `slice`, the rvalue ret.0, and the rvalue ret.1.
1452 /// // `slice` is never used after `let ptr = ...`, and so one can
1453 /// // treat it as "dead", and therefore, you only have two real
1454 /// // mutable slices.
1455 /// (slice::from_raw_parts_mut(ptr, mid),
1456 /// slice::from_raw_parts_mut(ptr.add(mid), len - mid))
1460 #[stable(feature = "rust1", since = "1.0.0")]
1461 #[cfg_attr(not(bootstrap), rustc_allowed_through_unstable_modules)]
1462 #[rustc_const_stable(feature = "const_transmute", since = "1.56.0")]
1463 #[rustc_diagnostic_item = "transmute"]
1464 pub fn transmute<T, U>(e: T) -> U;
1466 /// Returns `true` if the actual type given as `T` requires drop
1467 /// glue; returns `false` if the actual type provided for `T`
1468 /// implements `Copy`.
1470 /// If the actual type neither requires drop glue nor implements
1471 /// `Copy`, then the return value of this function is unspecified.
1473 /// Note that, unlike most intrinsics, this is safe to call;
1474 /// it does not require an `unsafe` block.
1475 /// Therefore, implementations must not require the user to uphold
1476 /// any safety invariants.
1478 /// The stabilized version of this intrinsic is [`mem::needs_drop`](crate::mem::needs_drop).
1479 #[rustc_const_stable(feature = "const_needs_drop", since = "1.40.0")]
1480 pub fn needs_drop<T: ?Sized>() -> bool;
1482 /// Calculates the offset from a pointer.
1484 /// This is implemented as an intrinsic to avoid converting to and from an
1485 /// integer, since the conversion would throw away aliasing information.
1489 /// Both the starting and resulting pointer must be either in bounds or one
1490 /// byte past the end of an allocated object. If either pointer is out of
1491 /// bounds or arithmetic overflow occurs then any further use of the
1492 /// returned value will result in undefined behavior.
1494 /// The stabilized version of this intrinsic is [`pointer::offset`].
1495 #[must_use = "returns a new pointer rather than modifying its argument"]
1496 #[rustc_const_stable(feature = "const_ptr_offset", since = "1.61.0")]
1497 pub fn offset<T>(dst: *const T, offset: isize) -> *const T;
1499 /// Calculates the offset from a pointer, potentially wrapping.
1501 /// This is implemented as an intrinsic to avoid converting to and from an
1502 /// integer, since the conversion inhibits certain optimizations.
1506 /// Unlike the `offset` intrinsic, this intrinsic does not restrict the
1507 /// resulting pointer to point into or one byte past the end of an allocated
1508 /// object, and it wraps with two's complement arithmetic. The resulting
1509 /// value is not necessarily valid to be used to actually access memory.
1511 /// The stabilized version of this intrinsic is [`pointer::wrapping_offset`].
1512 #[must_use = "returns a new pointer rather than modifying its argument"]
1513 #[rustc_const_stable(feature = "const_ptr_offset", since = "1.61.0")]
1514 pub fn arith_offset<T>(dst: *const T, offset: isize) -> *const T;
1516 /// Equivalent to the appropriate `llvm.memcpy.p0i8.0i8.*` intrinsic, with
1517 /// a size of `count` * `size_of::<T>()` and an alignment of
1518 /// `min_align_of::<T>()`
1520 /// The volatile parameter is set to `true`, so it will not be optimized out
1521 /// unless size is equal to zero.
1523 /// This intrinsic does not have a stable counterpart.
1524 pub fn volatile_copy_nonoverlapping_memory<T>(dst: *mut T, src: *const T, count: usize);
1525 /// Equivalent to the appropriate `llvm.memmove.p0i8.0i8.*` intrinsic, with
1526 /// a size of `count * size_of::<T>()` and an alignment of
1527 /// `min_align_of::<T>()`
1529 /// The volatile parameter is set to `true`, so it will not be optimized out
1530 /// unless size is equal to zero.
1532 /// This intrinsic does not have a stable counterpart.
1533 pub fn volatile_copy_memory<T>(dst: *mut T, src: *const T, count: usize);
1534 /// Equivalent to the appropriate `llvm.memset.p0i8.*` intrinsic, with a
1535 /// size of `count * size_of::<T>()` and an alignment of
1536 /// `min_align_of::<T>()`.
1538 /// The volatile parameter is set to `true`, so it will not be optimized out
1539 /// unless size is equal to zero.
1541 /// This intrinsic does not have a stable counterpart.
1542 pub fn volatile_set_memory<T>(dst: *mut T, val: u8, count: usize);
1544 /// Performs a volatile load from the `src` pointer.
1546 /// The stabilized version of this intrinsic is [`core::ptr::read_volatile`].
1547 pub fn volatile_load<T>(src: *const T) -> T;
1548 /// Performs a volatile store to the `dst` pointer.
1550 /// The stabilized version of this intrinsic is [`core::ptr::write_volatile`].
1551 pub fn volatile_store<T>(dst: *mut T, val: T);
1553 /// Performs a volatile load from the `src` pointer
1554 /// The pointer is not required to be aligned.
1556 /// This intrinsic does not have a stable counterpart.
1557 pub fn unaligned_volatile_load<T>(src: *const T) -> T;
1558 /// Performs a volatile store to the `dst` pointer.
1559 /// The pointer is not required to be aligned.
1561 /// This intrinsic does not have a stable counterpart.
1562 pub fn unaligned_volatile_store<T>(dst: *mut T, val: T);
1564 /// Returns the square root of an `f32`
1566 /// The stabilized version of this intrinsic is
1567 /// [`f32::sqrt`](../../std/primitive.f32.html#method.sqrt)
1568 pub fn sqrtf32(x: f32) -> f32;
1569 /// Returns the square root of an `f64`
1571 /// The stabilized version of this intrinsic is
1572 /// [`f64::sqrt`](../../std/primitive.f64.html#method.sqrt)
1573 pub fn sqrtf64(x: f64) -> f64;
1575 /// Raises an `f32` to an integer power.
1577 /// The stabilized version of this intrinsic is
1578 /// [`f32::powi`](../../std/primitive.f32.html#method.powi)
1579 pub fn powif32(a: f32, x: i32) -> f32;
1580 /// Raises an `f64` to an integer power.
1582 /// The stabilized version of this intrinsic is
1583 /// [`f64::powi`](../../std/primitive.f64.html#method.powi)
1584 pub fn powif64(a: f64, x: i32) -> f64;
1586 /// Returns the sine of an `f32`.
1588 /// The stabilized version of this intrinsic is
1589 /// [`f32::sin`](../../std/primitive.f32.html#method.sin)
1590 pub fn sinf32(x: f32) -> f32;
1591 /// Returns the sine of an `f64`.
1593 /// The stabilized version of this intrinsic is
1594 /// [`f64::sin`](../../std/primitive.f64.html#method.sin)
1595 pub fn sinf64(x: f64) -> f64;
1597 /// Returns the cosine of an `f32`.
1599 /// The stabilized version of this intrinsic is
1600 /// [`f32::cos`](../../std/primitive.f32.html#method.cos)
1601 pub fn cosf32(x: f32) -> f32;
1602 /// Returns the cosine of an `f64`.
1604 /// The stabilized version of this intrinsic is
1605 /// [`f64::cos`](../../std/primitive.f64.html#method.cos)
1606 pub fn cosf64(x: f64) -> f64;
1608 /// Raises an `f32` to an `f32` power.
1610 /// The stabilized version of this intrinsic is
1611 /// [`f32::powf`](../../std/primitive.f32.html#method.powf)
1612 pub fn powf32(a: f32, x: f32) -> f32;
1613 /// Raises an `f64` to an `f64` power.
1615 /// The stabilized version of this intrinsic is
1616 /// [`f64::powf`](../../std/primitive.f64.html#method.powf)
1617 pub fn powf64(a: f64, x: f64) -> f64;
1619 /// Returns the exponential of an `f32`.
1621 /// The stabilized version of this intrinsic is
1622 /// [`f32::exp`](../../std/primitive.f32.html#method.exp)
1623 pub fn expf32(x: f32) -> f32;
1624 /// Returns the exponential of an `f64`.
1626 /// The stabilized version of this intrinsic is
1627 /// [`f64::exp`](../../std/primitive.f64.html#method.exp)
1628 pub fn expf64(x: f64) -> f64;
1630 /// Returns 2 raised to the power of an `f32`.
1632 /// The stabilized version of this intrinsic is
1633 /// [`f32::exp2`](../../std/primitive.f32.html#method.exp2)
1634 pub fn exp2f32(x: f32) -> f32;
1635 /// Returns 2 raised to the power of an `f64`.
1637 /// The stabilized version of this intrinsic is
1638 /// [`f64::exp2`](../../std/primitive.f64.html#method.exp2)
1639 pub fn exp2f64(x: f64) -> f64;
1641 /// Returns the natural logarithm of an `f32`.
1643 /// The stabilized version of this intrinsic is
1644 /// [`f32::ln`](../../std/primitive.f32.html#method.ln)
1645 pub fn logf32(x: f32) -> f32;
1646 /// Returns the natural logarithm of an `f64`.
1648 /// The stabilized version of this intrinsic is
1649 /// [`f64::ln`](../../std/primitive.f64.html#method.ln)
1650 pub fn logf64(x: f64) -> f64;
1652 /// Returns the base 10 logarithm of an `f32`.
1654 /// The stabilized version of this intrinsic is
1655 /// [`f32::log10`](../../std/primitive.f32.html#method.log10)
1656 pub fn log10f32(x: f32) -> f32;
1657 /// Returns the base 10 logarithm of an `f64`.
1659 /// The stabilized version of this intrinsic is
1660 /// [`f64::log10`](../../std/primitive.f64.html#method.log10)
1661 pub fn log10f64(x: f64) -> f64;
1663 /// Returns the base 2 logarithm of an `f32`.
1665 /// The stabilized version of this intrinsic is
1666 /// [`f32::log2`](../../std/primitive.f32.html#method.log2)
1667 pub fn log2f32(x: f32) -> f32;
1668 /// Returns the base 2 logarithm of an `f64`.
1670 /// The stabilized version of this intrinsic is
1671 /// [`f64::log2`](../../std/primitive.f64.html#method.log2)
1672 pub fn log2f64(x: f64) -> f64;
1674 /// Returns `a * b + c` for `f32` values.
1676 /// The stabilized version of this intrinsic is
1677 /// [`f32::mul_add`](../../std/primitive.f32.html#method.mul_add)
1678 pub fn fmaf32(a: f32, b: f32, c: f32) -> f32;
1679 /// Returns `a * b + c` for `f64` values.
1681 /// The stabilized version of this intrinsic is
1682 /// [`f64::mul_add`](../../std/primitive.f64.html#method.mul_add)
1683 pub fn fmaf64(a: f64, b: f64, c: f64) -> f64;
1685 /// Returns the absolute value of an `f32`.
1687 /// The stabilized version of this intrinsic is
1688 /// [`f32::abs`](../../std/primitive.f32.html#method.abs)
1689 pub fn fabsf32(x: f32) -> f32;
1690 /// Returns the absolute value of an `f64`.
1692 /// The stabilized version of this intrinsic is
1693 /// [`f64::abs`](../../std/primitive.f64.html#method.abs)
1694 pub fn fabsf64(x: f64) -> f64;
1696 /// Returns the minimum of two `f32` values.
1698 /// Note that, unlike most intrinsics, this is safe to call;
1699 /// it does not require an `unsafe` block.
1700 /// Therefore, implementations must not require the user to uphold
1701 /// any safety invariants.
1703 /// The stabilized version of this intrinsic is
1705 pub fn minnumf32(x: f32, y: f32) -> f32;
1706 /// Returns the minimum of two `f64` values.
1708 /// Note that, unlike most intrinsics, this is safe to call;
1709 /// it does not require an `unsafe` block.
1710 /// Therefore, implementations must not require the user to uphold
1711 /// any safety invariants.
1713 /// The stabilized version of this intrinsic is
1715 pub fn minnumf64(x: f64, y: f64) -> f64;
1716 /// Returns the maximum of two `f32` values.
1718 /// Note that, unlike most intrinsics, this is safe to call;
1719 /// it does not require an `unsafe` block.
1720 /// Therefore, implementations must not require the user to uphold
1721 /// any safety invariants.
1723 /// The stabilized version of this intrinsic is
1725 pub fn maxnumf32(x: f32, y: f32) -> f32;
1726 /// Returns the maximum of two `f64` values.
1728 /// Note that, unlike most intrinsics, this is safe to call;
1729 /// it does not require an `unsafe` block.
1730 /// Therefore, implementations must not require the user to uphold
1731 /// any safety invariants.
1733 /// The stabilized version of this intrinsic is
1735 pub fn maxnumf64(x: f64, y: f64) -> f64;
1737 /// Copies the sign from `y` to `x` for `f32` values.
1739 /// The stabilized version of this intrinsic is
1740 /// [`f32::copysign`](../../std/primitive.f32.html#method.copysign)
1741 pub fn copysignf32(x: f32, y: f32) -> f32;
1742 /// Copies the sign from `y` to `x` for `f64` values.
1744 /// The stabilized version of this intrinsic is
1745 /// [`f64::copysign`](../../std/primitive.f64.html#method.copysign)
1746 pub fn copysignf64(x: f64, y: f64) -> f64;
1748 /// Returns the largest integer less than or equal to an `f32`.
1750 /// The stabilized version of this intrinsic is
1751 /// [`f32::floor`](../../std/primitive.f32.html#method.floor)
1752 pub fn floorf32(x: f32) -> f32;
1753 /// Returns the largest integer less than or equal to an `f64`.
1755 /// The stabilized version of this intrinsic is
1756 /// [`f64::floor`](../../std/primitive.f64.html#method.floor)
1757 pub fn floorf64(x: f64) -> f64;
1759 /// Returns the smallest integer greater than or equal to an `f32`.
1761 /// The stabilized version of this intrinsic is
1762 /// [`f32::ceil`](../../std/primitive.f32.html#method.ceil)
1763 pub fn ceilf32(x: f32) -> f32;
1764 /// Returns the smallest integer greater than or equal to an `f64`.
1766 /// The stabilized version of this intrinsic is
1767 /// [`f64::ceil`](../../std/primitive.f64.html#method.ceil)
1768 pub fn ceilf64(x: f64) -> f64;
1770 /// Returns the integer part of an `f32`.
1772 /// The stabilized version of this intrinsic is
1773 /// [`f32::trunc`](../../std/primitive.f32.html#method.trunc)
1774 pub fn truncf32(x: f32) -> f32;
1775 /// Returns the integer part of an `f64`.
1777 /// The stabilized version of this intrinsic is
1778 /// [`f64::trunc`](../../std/primitive.f64.html#method.trunc)
1779 pub fn truncf64(x: f64) -> f64;
1781 /// Returns the nearest integer to an `f32`. May raise an inexact floating-point exception
1782 /// if the argument is not an integer.
1783 pub fn rintf32(x: f32) -> f32;
1784 /// Returns the nearest integer to an `f64`. May raise an inexact floating-point exception
1785 /// if the argument is not an integer.
1786 pub fn rintf64(x: f64) -> f64;
1788 /// Returns the nearest integer to an `f32`.
1790 /// This intrinsic does not have a stable counterpart.
1791 pub fn nearbyintf32(x: f32) -> f32;
1792 /// Returns the nearest integer to an `f64`.
1794 /// This intrinsic does not have a stable counterpart.
1795 pub fn nearbyintf64(x: f64) -> f64;
1797 /// Returns the nearest integer to an `f32`. Rounds half-way cases away from zero.
1799 /// The stabilized version of this intrinsic is
1800 /// [`f32::round`](../../std/primitive.f32.html#method.round)
1801 pub fn roundf32(x: f32) -> f32;
1802 /// Returns the nearest integer to an `f64`. Rounds half-way cases away from zero.
1804 /// The stabilized version of this intrinsic is
1805 /// [`f64::round`](../../std/primitive.f64.html#method.round)
1806 pub fn roundf64(x: f64) -> f64;
1808 /// Float addition that allows optimizations based on algebraic rules.
1809 /// May assume inputs are finite.
1811 /// This intrinsic does not have a stable counterpart.
1812 pub fn fadd_fast<T: Copy>(a: T, b: T) -> T;
1814 /// Float subtraction that allows optimizations based on algebraic rules.
1815 /// May assume inputs are finite.
1817 /// This intrinsic does not have a stable counterpart.
1818 pub fn fsub_fast<T: Copy>(a: T, b: T) -> T;
1820 /// Float multiplication that allows optimizations based on algebraic rules.
1821 /// May assume inputs are finite.
1823 /// This intrinsic does not have a stable counterpart.
1824 pub fn fmul_fast<T: Copy>(a: T, b: T) -> T;
1826 /// Float division that allows optimizations based on algebraic rules.
1827 /// May assume inputs are finite.
1829 /// This intrinsic does not have a stable counterpart.
1830 pub fn fdiv_fast<T: Copy>(a: T, b: T) -> T;
1832 /// Float remainder that allows optimizations based on algebraic rules.
1833 /// May assume inputs are finite.
1835 /// This intrinsic does not have a stable counterpart.
1836 pub fn frem_fast<T: Copy>(a: T, b: T) -> T;
1838 /// Convert with LLVM’s fptoui/fptosi, which may return undef for values out of range
1839 /// (<https://github.com/rust-lang/rust/issues/10184>)
1841 /// Stabilized as [`f32::to_int_unchecked`] and [`f64::to_int_unchecked`].
1842 pub fn float_to_int_unchecked<Float: Copy, Int: Copy>(value: Float) -> Int;
1844 /// Returns the number of bits set in an integer type `T`
1846 /// Note that, unlike most intrinsics, this is safe to call;
1847 /// it does not require an `unsafe` block.
1848 /// Therefore, implementations must not require the user to uphold
1849 /// any safety invariants.
1851 /// The stabilized versions of this intrinsic are available on the integer
1852 /// primitives via the `count_ones` method. For example,
1853 /// [`u32::count_ones`]
1854 #[rustc_const_stable(feature = "const_ctpop", since = "1.40.0")]
1855 pub fn ctpop<T: Copy>(x: T) -> T;
1857 /// Returns the number of leading unset bits (zeroes) in an integer type `T`.
1859 /// Note that, unlike most intrinsics, this is safe to call;
1860 /// it does not require an `unsafe` block.
1861 /// Therefore, implementations must not require the user to uphold
1862 /// any safety invariants.
1864 /// The stabilized versions of this intrinsic are available on the integer
1865 /// primitives via the `leading_zeros` method. For example,
1866 /// [`u32::leading_zeros`]
1871 /// #![feature(core_intrinsics)]
1873 /// use std::intrinsics::ctlz;
1875 /// let x = 0b0001_1100_u8;
1876 /// let num_leading = ctlz(x);
1877 /// assert_eq!(num_leading, 3);
1880 /// An `x` with value `0` will return the bit width of `T`.
1883 /// #![feature(core_intrinsics)]
1885 /// use std::intrinsics::ctlz;
1888 /// let num_leading = ctlz(x);
1889 /// assert_eq!(num_leading, 16);
1891 #[rustc_const_stable(feature = "const_ctlz", since = "1.40.0")]
1892 pub fn ctlz<T: Copy>(x: T) -> T;
1894 /// Like `ctlz`, but extra-unsafe as it returns `undef` when
1895 /// given an `x` with value `0`.
1897 /// This intrinsic does not have a stable counterpart.
1902 /// #![feature(core_intrinsics)]
1904 /// use std::intrinsics::ctlz_nonzero;
1906 /// let x = 0b0001_1100_u8;
1907 /// let num_leading = unsafe { ctlz_nonzero(x) };
1908 /// assert_eq!(num_leading, 3);
1910 #[rustc_const_stable(feature = "constctlz", since = "1.50.0")]
1911 pub fn ctlz_nonzero<T: Copy>(x: T) -> T;
1913 /// Returns the number of trailing unset bits (zeroes) in an integer type `T`.
1915 /// Note that, unlike most intrinsics, this is safe to call;
1916 /// it does not require an `unsafe` block.
1917 /// Therefore, implementations must not require the user to uphold
1918 /// any safety invariants.
1920 /// The stabilized versions of this intrinsic are available on the integer
1921 /// primitives via the `trailing_zeros` method. For example,
1922 /// [`u32::trailing_zeros`]
1927 /// #![feature(core_intrinsics)]
1929 /// use std::intrinsics::cttz;
1931 /// let x = 0b0011_1000_u8;
1932 /// let num_trailing = cttz(x);
1933 /// assert_eq!(num_trailing, 3);
1936 /// An `x` with value `0` will return the bit width of `T`:
1939 /// #![feature(core_intrinsics)]
1941 /// use std::intrinsics::cttz;
1944 /// let num_trailing = cttz(x);
1945 /// assert_eq!(num_trailing, 16);
1947 #[rustc_const_stable(feature = "const_cttz", since = "1.40.0")]
1948 pub fn cttz<T: Copy>(x: T) -> T;
1950 /// Like `cttz`, but extra-unsafe as it returns `undef` when
1951 /// given an `x` with value `0`.
1953 /// This intrinsic does not have a stable counterpart.
1958 /// #![feature(core_intrinsics)]
1960 /// use std::intrinsics::cttz_nonzero;
1962 /// let x = 0b0011_1000_u8;
1963 /// let num_trailing = unsafe { cttz_nonzero(x) };
1964 /// assert_eq!(num_trailing, 3);
1966 #[rustc_const_stable(feature = "const_cttz_nonzero", since = "1.53.0")]
1967 pub fn cttz_nonzero<T: Copy>(x: T) -> T;
1969 /// Reverses the bytes in an integer type `T`.
1971 /// Note that, unlike most intrinsics, this is safe to call;
1972 /// it does not require an `unsafe` block.
1973 /// Therefore, implementations must not require the user to uphold
1974 /// any safety invariants.
1976 /// The stabilized versions of this intrinsic are available on the integer
1977 /// primitives via the `swap_bytes` method. For example,
1978 /// [`u32::swap_bytes`]
1979 #[rustc_const_stable(feature = "const_bswap", since = "1.40.0")]
1980 pub fn bswap<T: Copy>(x: T) -> T;
1982 /// Reverses the bits in an integer type `T`.
1984 /// Note that, unlike most intrinsics, this is safe to call;
1985 /// it does not require an `unsafe` block.
1986 /// Therefore, implementations must not require the user to uphold
1987 /// any safety invariants.
1989 /// The stabilized versions of this intrinsic are available on the integer
1990 /// primitives via the `reverse_bits` method. For example,
1991 /// [`u32::reverse_bits`]
1992 #[rustc_const_stable(feature = "const_bitreverse", since = "1.40.0")]
1993 pub fn bitreverse<T: Copy>(x: T) -> T;
1995 /// Performs checked integer addition.
1997 /// Note that, unlike most intrinsics, this is safe to call;
1998 /// it does not require an `unsafe` block.
1999 /// Therefore, implementations must not require the user to uphold
2000 /// any safety invariants.
2002 /// The stabilized versions of this intrinsic are available on the integer
2003 /// primitives via the `overflowing_add` method. For example,
2004 /// [`u32::overflowing_add`]
2005 #[rustc_const_stable(feature = "const_int_overflow", since = "1.40.0")]
2006 pub fn add_with_overflow<T: Copy>(x: T, y: T) -> (T, bool);
2008 /// Performs checked integer subtraction
2010 /// Note that, unlike most intrinsics, this is safe to call;
2011 /// it does not require an `unsafe` block.
2012 /// Therefore, implementations must not require the user to uphold
2013 /// any safety invariants.
2015 /// The stabilized versions of this intrinsic are available on the integer
2016 /// primitives via the `overflowing_sub` method. For example,
2017 /// [`u32::overflowing_sub`]
2018 #[rustc_const_stable(feature = "const_int_overflow", since = "1.40.0")]
2019 pub fn sub_with_overflow<T: Copy>(x: T, y: T) -> (T, bool);
2021 /// Performs checked integer multiplication
2023 /// Note that, unlike most intrinsics, this is safe to call;
2024 /// it does not require an `unsafe` block.
2025 /// Therefore, implementations must not require the user to uphold
2026 /// any safety invariants.
2028 /// The stabilized versions of this intrinsic are available on the integer
2029 /// primitives via the `overflowing_mul` method. For example,
2030 /// [`u32::overflowing_mul`]
2031 #[rustc_const_stable(feature = "const_int_overflow", since = "1.40.0")]
2032 pub fn mul_with_overflow<T: Copy>(x: T, y: T) -> (T, bool);
2034 /// Performs an exact division, resulting in undefined behavior where
2035 /// `x % y != 0` or `y == 0` or `x == T::MIN && y == -1`
2037 /// This intrinsic does not have a stable counterpart.
2038 pub fn exact_div<T: Copy>(x: T, y: T) -> T;
2040 /// Performs an unchecked division, resulting in undefined behavior
2041 /// where `y == 0` or `x == T::MIN && y == -1`
2043 /// Safe wrappers for this intrinsic are available on the integer
2044 /// primitives via the `checked_div` method. For example,
2045 /// [`u32::checked_div`]
2046 #[rustc_const_stable(feature = "const_int_unchecked_div", since = "1.52.0")]
2047 pub fn unchecked_div<T: Copy>(x: T, y: T) -> T;
2048 /// Returns the remainder of an unchecked division, resulting in
2049 /// undefined behavior when `y == 0` or `x == T::MIN && y == -1`
2051 /// Safe wrappers for this intrinsic are available on the integer
2052 /// primitives via the `checked_rem` method. For example,
2053 /// [`u32::checked_rem`]
2054 #[rustc_const_stable(feature = "const_int_unchecked_rem", since = "1.52.0")]
2055 pub fn unchecked_rem<T: Copy>(x: T, y: T) -> T;
2057 /// Performs an unchecked left shift, resulting in undefined behavior when
2058 /// `y < 0` or `y >= N`, where N is the width of T in bits.
2060 /// Safe wrappers for this intrinsic are available on the integer
2061 /// primitives via the `checked_shl` method. For example,
2062 /// [`u32::checked_shl`]
2063 #[rustc_const_stable(feature = "const_int_unchecked", since = "1.40.0")]
2064 pub fn unchecked_shl<T: Copy>(x: T, y: T) -> T;
2065 /// Performs an unchecked right shift, resulting in undefined behavior when
2066 /// `y < 0` or `y >= N`, where N is the width of T in bits.
2068 /// Safe wrappers for this intrinsic are available on the integer
2069 /// primitives via the `checked_shr` method. For example,
2070 /// [`u32::checked_shr`]
2071 #[rustc_const_stable(feature = "const_int_unchecked", since = "1.40.0")]
2072 pub fn unchecked_shr<T: Copy>(x: T, y: T) -> T;
2074 /// Returns the result of an unchecked addition, resulting in
2075 /// undefined behavior when `x + y > T::MAX` or `x + y < T::MIN`.
2077 /// This intrinsic does not have a stable counterpart.
2078 #[rustc_const_unstable(feature = "const_int_unchecked_arith", issue = "none")]
2079 pub fn unchecked_add<T: Copy>(x: T, y: T) -> T;
2081 /// Returns the result of an unchecked subtraction, resulting in
2082 /// undefined behavior when `x - y > T::MAX` or `x - y < T::MIN`.
2084 /// This intrinsic does not have a stable counterpart.
2085 #[rustc_const_unstable(feature = "const_int_unchecked_arith", issue = "none")]
2086 pub fn unchecked_sub<T: Copy>(x: T, y: T) -> T;
2088 /// Returns the result of an unchecked multiplication, resulting in
2089 /// undefined behavior when `x * y > T::MAX` or `x * y < T::MIN`.
2091 /// This intrinsic does not have a stable counterpart.
2092 #[rustc_const_unstable(feature = "const_int_unchecked_arith", issue = "none")]
2093 pub fn unchecked_mul<T: Copy>(x: T, y: T) -> T;
2095 /// Performs rotate left.
2097 /// Note that, unlike most intrinsics, this is safe to call;
2098 /// it does not require an `unsafe` block.
2099 /// Therefore, implementations must not require the user to uphold
2100 /// any safety invariants.
2102 /// The stabilized versions of this intrinsic are available on the integer
2103 /// primitives via the `rotate_left` method. For example,
2104 /// [`u32::rotate_left`]
2105 #[rustc_const_stable(feature = "const_int_rotate", since = "1.40.0")]
2106 pub fn rotate_left<T: Copy>(x: T, y: T) -> T;
2108 /// Performs rotate right.
2110 /// Note that, unlike most intrinsics, this is safe to call;
2111 /// it does not require an `unsafe` block.
2112 /// Therefore, implementations must not require the user to uphold
2113 /// any safety invariants.
2115 /// The stabilized versions of this intrinsic are available on the integer
2116 /// primitives via the `rotate_right` method. For example,
2117 /// [`u32::rotate_right`]
2118 #[rustc_const_stable(feature = "const_int_rotate", since = "1.40.0")]
2119 pub fn rotate_right<T: Copy>(x: T, y: T) -> T;
2121 /// Returns (a + b) mod 2<sup>N</sup>, where N is the width of T in bits.
2123 /// Note that, unlike most intrinsics, this is safe to call;
2124 /// it does not require an `unsafe` block.
2125 /// Therefore, implementations must not require the user to uphold
2126 /// any safety invariants.
2128 /// The stabilized versions of this intrinsic are available on the integer
2129 /// primitives via the `wrapping_add` method. For example,
2130 /// [`u32::wrapping_add`]
2131 #[rustc_const_stable(feature = "const_int_wrapping", since = "1.40.0")]
2132 pub fn wrapping_add<T: Copy>(a: T, b: T) -> T;
2133 /// Returns (a - b) mod 2<sup>N</sup>, where N is the width of T in bits.
2135 /// Note that, unlike most intrinsics, this is safe to call;
2136 /// it does not require an `unsafe` block.
2137 /// Therefore, implementations must not require the user to uphold
2138 /// any safety invariants.
2140 /// The stabilized versions of this intrinsic are available on the integer
2141 /// primitives via the `wrapping_sub` method. For example,
2142 /// [`u32::wrapping_sub`]
2143 #[rustc_const_stable(feature = "const_int_wrapping", since = "1.40.0")]
2144 pub fn wrapping_sub<T: Copy>(a: T, b: T) -> T;
2145 /// Returns (a * b) mod 2<sup>N</sup>, where N is the width of T in bits.
2147 /// Note that, unlike most intrinsics, this is safe to call;
2148 /// it does not require an `unsafe` block.
2149 /// Therefore, implementations must not require the user to uphold
2150 /// any safety invariants.
2152 /// The stabilized versions of this intrinsic are available on the integer
2153 /// primitives via the `wrapping_mul` method. For example,
2154 /// [`u32::wrapping_mul`]
2155 #[rustc_const_stable(feature = "const_int_wrapping", since = "1.40.0")]
2156 pub fn wrapping_mul<T: Copy>(a: T, b: T) -> T;
2158 /// Computes `a + b`, saturating at numeric bounds.
2160 /// Note that, unlike most intrinsics, this is safe to call;
2161 /// it does not require an `unsafe` block.
2162 /// Therefore, implementations must not require the user to uphold
2163 /// any safety invariants.
2165 /// The stabilized versions of this intrinsic are available on the integer
2166 /// primitives via the `saturating_add` method. For example,
2167 /// [`u32::saturating_add`]
2168 #[rustc_const_stable(feature = "const_int_saturating", since = "1.40.0")]
2169 pub fn saturating_add<T: Copy>(a: T, b: T) -> T;
2170 /// Computes `a - b`, saturating at numeric bounds.
2172 /// Note that, unlike most intrinsics, this is safe to call;
2173 /// it does not require an `unsafe` block.
2174 /// Therefore, implementations must not require the user to uphold
2175 /// any safety invariants.
2177 /// The stabilized versions of this intrinsic are available on the integer
2178 /// primitives via the `saturating_sub` method. For example,
2179 /// [`u32::saturating_sub`]
2180 #[rustc_const_stable(feature = "const_int_saturating", since = "1.40.0")]
2181 pub fn saturating_sub<T: Copy>(a: T, b: T) -> T;
2183 /// Returns the value of the discriminant for the variant in 'v';
2184 /// if `T` has no discriminant, returns `0`.
2186 /// Note that, unlike most intrinsics, this is safe to call;
2187 /// it does not require an `unsafe` block.
2188 /// Therefore, implementations must not require the user to uphold
2189 /// any safety invariants.
2191 /// The stabilized version of this intrinsic is [`core::mem::discriminant`].
2192 #[rustc_const_unstable(feature = "const_discriminant", issue = "69821")]
2193 pub fn discriminant_value<T>(v: &T) -> <T as DiscriminantKind>::Discriminant;
2195 /// Returns the number of variants of the type `T` cast to a `usize`;
2196 /// if `T` has no variants, returns `0`. Uninhabited variants will be counted.
2198 /// Note that, unlike most intrinsics, this is safe to call;
2199 /// it does not require an `unsafe` block.
2200 /// Therefore, implementations must not require the user to uphold
2201 /// any safety invariants.
2203 /// The to-be-stabilized version of this intrinsic is [`mem::variant_count`].
2204 #[rustc_const_unstable(feature = "variant_count", issue = "73662")]
2205 pub fn variant_count<T>() -> usize;
2207 /// Rust's "try catch" construct which invokes the function pointer `try_fn`
2208 /// with the data pointer `data`.
2210 /// The third argument is a function called if a panic occurs. This function
2211 /// takes the data pointer and a pointer to the target-specific exception
2212 /// object that was caught. For more information see the compiler's
2213 /// source as well as std's catch implementation.
2214 pub fn r#try(try_fn: fn(*mut u8), data: *mut u8, catch_fn: fn(*mut u8, *mut u8)) -> i32;
2216 /// Emits a `!nontemporal` store according to LLVM (see their docs).
2217 /// Probably will never become stable.
2218 pub fn nontemporal_store<T>(ptr: *mut T, val: T);
2220 /// See documentation of `<*const T>::offset_from` for details.
2221 #[rustc_const_unstable(feature = "const_ptr_offset_from", issue = "92980")]
2222 pub fn ptr_offset_from<T>(ptr: *const T, base: *const T) -> isize;
2224 /// See documentation of `<*const T>::sub_ptr` for details.
2225 #[rustc_const_unstable(feature = "const_ptr_offset_from", issue = "92980")]
2226 pub fn ptr_offset_from_unsigned<T>(ptr: *const T, base: *const T) -> usize;
2228 /// See documentation of `<*const T>::guaranteed_eq` for details.
2230 /// Note that, unlike most intrinsics, this is safe to call;
2231 /// it does not require an `unsafe` block.
2232 /// Therefore, implementations must not require the user to uphold
2233 /// any safety invariants.
2234 #[rustc_const_unstable(feature = "const_raw_ptr_comparison", issue = "53020")]
2235 pub fn ptr_guaranteed_eq<T>(ptr: *const T, other: *const T) -> bool;
2237 /// See documentation of `<*const T>::guaranteed_ne` for details.
2239 /// Note that, unlike most intrinsics, this is safe to call;
2240 /// it does not require an `unsafe` block.
2241 /// Therefore, implementations must not require the user to uphold
2242 /// any safety invariants.
2243 #[rustc_const_unstable(feature = "const_raw_ptr_comparison", issue = "53020")]
2244 pub fn ptr_guaranteed_ne<T>(ptr: *const T, other: *const T) -> bool;
2246 /// Allocates a block of memory at compile time.
2247 /// At runtime, just returns a null pointer.
2251 /// - The `align` argument must be a power of two.
2252 /// - At compile time, a compile error occurs if this constraint is violated.
2253 /// - At runtime, it is not checked.
2254 #[rustc_const_unstable(feature = "const_heap", issue = "79597")]
2255 pub fn const_allocate(size: usize, align: usize) -> *mut u8;
2257 /// Deallocates a memory which allocated by `intrinsics::const_allocate` at compile time.
2258 /// At runtime, does nothing.
2262 /// - The `align` argument must be a power of two.
2263 /// - At compile time, a compile error occurs if this constraint is violated.
2264 /// - At runtime, it is not checked.
2265 /// - If the `ptr` is created in an another const, this intrinsic doesn't deallocate it.
2266 /// - If the `ptr` is pointing to a local variable, this intrinsic doesn't deallocate it.
2267 #[rustc_const_unstable(feature = "const_heap", issue = "79597")]
2268 pub fn const_deallocate(ptr: *mut u8, size: usize, align: usize);
2270 /// Determines whether the raw bytes of the two values are equal.
2272 /// This is particularly handy for arrays, since it allows things like just
2273 /// comparing `i96`s instead of forcing `alloca`s for `[6 x i16]`.
2275 /// Above some backend-decided threshold this will emit calls to `memcmp`,
2276 /// like slice equality does, instead of causing massive code size.
2280 /// It's UB to call this if any of the *bytes* in `*a` or `*b` are uninitialized.
2281 /// Note that this is a stricter criterion than just the *values* being
2282 /// fully-initialized: if `T` has padding, it's UB to call this intrinsic.
2284 /// (The implementation is allowed to branch on the results of comparisons,
2285 /// which is UB if any of their inputs are `undef`.)
2286 #[rustc_const_unstable(feature = "const_intrinsic_raw_eq", issue = "none")]
2287 pub fn raw_eq<T>(a: &T, b: &T) -> bool;
2289 /// See documentation of [`std::hint::black_box`] for details.
2291 /// [`std::hint::black_box`]: crate::hint::black_box
2292 #[rustc_const_unstable(feature = "const_black_box", issue = "none")]
2293 pub fn black_box<T>(dummy: T) -> T;
2295 /// `ptr` must point to a vtable.
2296 /// The intrinsic will return the size stored in that vtable.
2297 #[cfg(not(bootstrap))]
2298 pub fn vtable_size(ptr: *const ()) -> usize;
2300 /// `ptr` must point to a vtable.
2301 /// The intrinsic will return the alignment stored in that vtable.
2302 #[cfg(not(bootstrap))]
2303 pub fn vtable_align(ptr: *const ()) -> usize;
2306 // Some functions are defined here because they accidentally got made
2307 // available in this module on stable. See <https://github.com/rust-lang/rust/issues/15702>.
2308 // (`transmute` also falls into this category, but it cannot be wrapped due to the
2309 // check that `T` and `U` have the same size.)
2311 /// Check that the preconditions of an unsafe function are followed, if debug_assertions are on,
2312 /// and only at runtime.
2316 /// Invoking this macro is only sound if the following code is already UB when the passed
2317 /// expression evaluates to false.
2319 /// This macro expands to a check at runtime if debug_assertions is set. It has no effect at
2320 /// compile time, but the semantics of the contained `const_eval_select` must be the same at
2321 /// runtime and at compile time. Thus if the expression evaluates to false, this macro produces
2322 /// different behavior at compile time and at runtime, and invoking it is incorrect.
2324 /// So in a sense it is UB if this macro is useful, but we expect callers of `unsafe fn` to make
2325 /// the occasional mistake, and this check should help them figure things out.
2326 #[allow_internal_unstable(const_eval_select)] // permit this to be called in stably-const fn
2327 macro_rules! assert_unsafe_precondition {
2329 if cfg!(debug_assertions) {
2330 // Use a closure so that we can capture arbitrary expressions from the invocation
2333 // abort instead of panicking to reduce impact on code size
2334 ::core::intrinsics::abort();
2337 const fn comptime() {}
2339 ::core::intrinsics::const_eval_select((), comptime, runtime);
2343 pub(crate) use assert_unsafe_precondition;
2345 /// Checks whether `ptr` is properly aligned with respect to
2346 /// `align_of::<T>()`.
2347 pub(crate) fn is_aligned_and_not_null<T>(ptr: *const T) -> bool {
2348 !ptr.is_null() && ptr.addr() % mem::align_of::<T>() == 0
2351 /// Checks whether the regions of memory starting at `src` and `dst` of size
2352 /// `count * size_of::<T>()` do *not* overlap.
2353 pub(crate) fn is_nonoverlapping<T>(src: *const T, dst: *const T, count: usize) -> bool {
2354 let src_usize = src.addr();
2355 let dst_usize = dst.addr();
2356 let size = mem::size_of::<T>().checked_mul(count).unwrap();
2357 let diff = if src_usize > dst_usize { src_usize - dst_usize } else { dst_usize - src_usize };
2358 // If the absolute distance between the ptrs is at least as big as the size of the buffer,
2359 // they do not overlap.
2363 /// Copies `count * size_of::<T>()` bytes from `src` to `dst`. The source
2364 /// and destination must *not* overlap.
2366 /// For regions of memory which might overlap, use [`copy`] instead.
2368 /// `copy_nonoverlapping` is semantically equivalent to C's [`memcpy`], but
2369 /// with the argument order swapped.
2371 /// The copy is "untyped" in the sense that data may be uninitialized or otherwise violate the
2372 /// requirements of `T`. The initialization state is preserved exactly.
2374 /// [`memcpy`]: https://en.cppreference.com/w/c/string/byte/memcpy
2378 /// Behavior is undefined if any of the following conditions are violated:
2380 /// * `src` must be [valid] for reads of `count * size_of::<T>()` bytes.
2382 /// * `dst` must be [valid] for writes of `count * size_of::<T>()` bytes.
2384 /// * Both `src` and `dst` must be properly aligned.
2386 /// * The region of memory beginning at `src` with a size of `count *
2387 /// size_of::<T>()` bytes must *not* overlap with the region of memory
2388 /// beginning at `dst` with the same size.
2390 /// Like [`read`], `copy_nonoverlapping` creates a bitwise copy of `T`, regardless of
2391 /// whether `T` is [`Copy`]. If `T` is not [`Copy`], using *both* the values
2392 /// in the region beginning at `*src` and the region beginning at `*dst` can
2393 /// [violate memory safety][read-ownership].
2395 /// Note that even if the effectively copied size (`count * size_of::<T>()`) is
2396 /// `0`, the pointers must be non-null and properly aligned.
2398 /// [`read`]: crate::ptr::read
2399 /// [read-ownership]: crate::ptr::read#ownership-of-the-returned-value
2400 /// [valid]: crate::ptr#safety
2404 /// Manually implement [`Vec::append`]:
2409 /// /// Moves all the elements of `src` into `dst`, leaving `src` empty.
2410 /// fn append<T>(dst: &mut Vec<T>, src: &mut Vec<T>) {
2411 /// let src_len = src.len();
2412 /// let dst_len = dst.len();
2414 /// // Ensure that `dst` has enough capacity to hold all of `src`.
2415 /// dst.reserve(src_len);
2418 /// // The call to offset is always safe because `Vec` will never
2419 /// // allocate more than `isize::MAX` bytes.
2420 /// let dst_ptr = dst.as_mut_ptr().offset(dst_len as isize);
2421 /// let src_ptr = src.as_ptr();
2423 /// // Truncate `src` without dropping its contents. We do this first,
2424 /// // to avoid problems in case something further down panics.
2427 /// // The two regions cannot overlap because mutable references do
2428 /// // not alias, and two different vectors cannot own the same
2430 /// ptr::copy_nonoverlapping(src_ptr, dst_ptr, src_len);
2432 /// // Notify `dst` that it now holds the contents of `src`.
2433 /// dst.set_len(dst_len + src_len);
2437 /// let mut a = vec!['r'];
2438 /// let mut b = vec!['u', 's', 't'];
2440 /// append(&mut a, &mut b);
2442 /// assert_eq!(a, &['r', 'u', 's', 't']);
2443 /// assert!(b.is_empty());
2446 /// [`Vec::append`]: ../../std/vec/struct.Vec.html#method.append
2447 #[doc(alias = "memcpy")]
2448 #[stable(feature = "rust1", since = "1.0.0")]
2449 #[cfg_attr(not(bootstrap), rustc_allowed_through_unstable_modules)]
2450 #[rustc_const_stable(feature = "const_intrinsic_copy", since = "1.63.0")]
2452 pub const unsafe fn copy_nonoverlapping<T>(src: *const T, dst: *mut T, count: usize) {
2453 extern "rust-intrinsic" {
2454 #[rustc_const_stable(feature = "const_intrinsic_copy", since = "1.63.0")]
2455 pub fn copy_nonoverlapping<T>(src: *const T, dst: *mut T, count: usize);
2458 // SAFETY: the safety contract for `copy_nonoverlapping` must be
2459 // upheld by the caller.
2461 assert_unsafe_precondition!(
2462 is_aligned_and_not_null(src)
2463 && is_aligned_and_not_null(dst)
2464 && is_nonoverlapping(src, dst, count)
2466 copy_nonoverlapping(src, dst, count)
2470 /// Copies `count * size_of::<T>()` bytes from `src` to `dst`. The source
2471 /// and destination may overlap.
2473 /// If the source and destination will *never* overlap,
2474 /// [`copy_nonoverlapping`] can be used instead.
2476 /// `copy` is semantically equivalent to C's [`memmove`], but with the argument
2477 /// order swapped. Copying takes place as if the bytes were copied from `src`
2478 /// to a temporary array and then copied from the array to `dst`.
2480 /// The copy is "untyped" in the sense that data may be uninitialized or otherwise violate the
2481 /// requirements of `T`. The initialization state is preserved exactly.
2483 /// [`memmove`]: https://en.cppreference.com/w/c/string/byte/memmove
2487 /// Behavior is undefined if any of the following conditions are violated:
2489 /// * `src` must be [valid] for reads of `count * size_of::<T>()` bytes.
2491 /// * `dst` must be [valid] for writes of `count * size_of::<T>()` bytes.
2493 /// * Both `src` and `dst` must be properly aligned.
2495 /// Like [`read`], `copy` creates a bitwise copy of `T`, regardless of
2496 /// whether `T` is [`Copy`]. If `T` is not [`Copy`], using both the values
2497 /// in the region beginning at `*src` and the region beginning at `*dst` can
2498 /// [violate memory safety][read-ownership].
2500 /// Note that even if the effectively copied size (`count * size_of::<T>()`) is
2501 /// `0`, the pointers must be non-null and properly aligned.
2503 /// [`read`]: crate::ptr::read
2504 /// [read-ownership]: crate::ptr::read#ownership-of-the-returned-value
2505 /// [valid]: crate::ptr#safety
2509 /// Efficiently create a Rust vector from an unsafe buffer:
2516 /// /// * `ptr` must be correctly aligned for its type and non-zero.
2517 /// /// * `ptr` must be valid for reads of `elts` contiguous elements of type `T`.
2518 /// /// * Those elements must not be used after calling this function unless `T: Copy`.
2519 /// # #[allow(dead_code)]
2520 /// unsafe fn from_buf_raw<T>(ptr: *const T, elts: usize) -> Vec<T> {
2521 /// let mut dst = Vec::with_capacity(elts);
2523 /// // SAFETY: Our precondition ensures the source is aligned and valid,
2524 /// // and `Vec::with_capacity` ensures that we have usable space to write them.
2525 /// ptr::copy(ptr, dst.as_mut_ptr(), elts);
2527 /// // SAFETY: We created it with this much capacity earlier,
2528 /// // and the previous `copy` has initialized these elements.
2529 /// dst.set_len(elts);
2533 #[doc(alias = "memmove")]
2534 #[stable(feature = "rust1", since = "1.0.0")]
2535 #[cfg_attr(not(bootstrap), rustc_allowed_through_unstable_modules)]
2536 #[rustc_const_stable(feature = "const_intrinsic_copy", since = "1.63.0")]
2538 pub const unsafe fn copy<T>(src: *const T, dst: *mut T, count: usize) {
2539 extern "rust-intrinsic" {
2540 #[rustc_const_stable(feature = "const_intrinsic_copy", since = "1.63.0")]
2541 fn copy<T>(src: *const T, dst: *mut T, count: usize);
2544 // SAFETY: the safety contract for `copy` must be upheld by the caller.
2546 assert_unsafe_precondition!(is_aligned_and_not_null(src) && is_aligned_and_not_null(dst));
2547 copy(src, dst, count)
2551 /// Sets `count * size_of::<T>()` bytes of memory starting at `dst` to
2554 /// `write_bytes` is similar to C's [`memset`], but sets `count *
2555 /// size_of::<T>()` bytes to `val`.
2557 /// [`memset`]: https://en.cppreference.com/w/c/string/byte/memset
2561 /// Behavior is undefined if any of the following conditions are violated:
2563 /// * `dst` must be [valid] for writes of `count * size_of::<T>()` bytes.
2565 /// * `dst` must be properly aligned.
2567 /// Additionally, the caller must ensure that writing `count *
2568 /// size_of::<T>()` bytes to the given region of memory results in a valid
2569 /// value of `T`. Using a region of memory typed as a `T` that contains an
2570 /// invalid value of `T` is undefined behavior.
2572 /// Note that even if the effectively copied size (`count * size_of::<T>()`) is
2573 /// `0`, the pointer must be non-null and properly aligned.
2575 /// [valid]: crate::ptr#safety
2584 /// let mut vec = vec![0u32; 4];
2586 /// let vec_ptr = vec.as_mut_ptr();
2587 /// ptr::write_bytes(vec_ptr, 0xfe, 2);
2589 /// assert_eq!(vec, [0xfefefefe, 0xfefefefe, 0, 0]);
2592 /// Creating an invalid value:
2597 /// let mut v = Box::new(0i32);
2600 /// // Leaks the previously held value by overwriting the `Box<T>` with
2601 /// // a null pointer.
2602 /// ptr::write_bytes(&mut v as *mut Box<i32>, 0, 1);
2605 /// // At this point, using or dropping `v` results in undefined behavior.
2606 /// // drop(v); // ERROR
2608 /// // Even leaking `v` "uses" it, and hence is undefined behavior.
2609 /// // mem::forget(v); // ERROR
2611 /// // In fact, `v` is invalid according to basic type layout invariants, so *any*
2612 /// // operation touching it is undefined behavior.
2613 /// // let v2 = v; // ERROR
2616 /// // Let us instead put in a valid value
2617 /// ptr::write(&mut v as *mut Box<i32>, Box::new(42i32));
2620 /// // Now the box is fine
2621 /// assert_eq!(*v, 42);
2623 #[doc(alias = "memset")]
2624 #[stable(feature = "rust1", since = "1.0.0")]
2625 #[cfg_attr(not(bootstrap), rustc_allowed_through_unstable_modules)]
2626 #[rustc_const_unstable(feature = "const_ptr_write", issue = "86302")]
2628 pub const unsafe fn write_bytes<T>(dst: *mut T, val: u8, count: usize) {
2629 extern "rust-intrinsic" {
2630 #[rustc_const_unstable(feature = "const_ptr_write", issue = "86302")]
2631 fn write_bytes<T>(dst: *mut T, val: u8, count: usize);
2634 // SAFETY: the safety contract for `write_bytes` must be upheld by the caller.
2636 assert_unsafe_precondition!(is_aligned_and_not_null(dst));
2637 write_bytes(dst, val, count)
2641 /// Selects which function to call depending on the context.
2643 /// If this function is evaluated at compile-time, then a call to this
2644 /// intrinsic will be replaced with a call to `called_in_const`. It gets
2645 /// replaced with a call to `called_at_rt` otherwise.
2647 /// # Type Requirements
2649 /// The two functions must be both function items. They cannot be function
2650 /// pointers or closures.
2652 /// `arg` will be the arguments that will be passed to either one of the
2653 /// two functions, therefore, both functions must accept the same type of
2654 /// arguments. Both functions must return RET.
2658 /// The two functions must behave observably equivalent. Safe code in other
2659 /// crates may assume that calling a `const fn` at compile-time and at run-time
2660 /// produces the same result. A function that produces a different result when
2661 /// evaluated at run-time, or has any other observable side-effects, is
2664 /// Here is an example of how this could cause a problem:
2666 /// #![feature(const_eval_select)]
2667 /// #![feature(core_intrinsics)]
2668 /// use std::hint::unreachable_unchecked;
2669 /// use std::intrinsics::const_eval_select;
2672 /// pub const fn inconsistent() -> i32 {
2673 /// fn runtime() -> i32 { 1 }
2674 /// const fn compiletime() -> i32 { 2 }
2677 // // ⚠ This code violates the required equivalence of `compiletime`
2678 /// // and `runtime`.
2679 /// const_eval_select((), compiletime, runtime)
2684 /// const X: i32 = inconsistent();
2685 /// let x = inconsistent();
2686 /// if x != X { unsafe { unreachable_unchecked(); }}
2689 /// This code causes Undefined Behavior when being run, since the
2690 /// `unreachable_unchecked` is actually being reached. The bug is in *crate A*,
2691 /// which violates the principle that a `const fn` must behave the same at
2692 /// compile-time and at run-time. The unsafe code in crate B is fine.
2694 feature = "const_eval_select",
2696 reason = "const_eval_select will never be stable"
2698 #[rustc_const_unstable(feature = "const_eval_select", issue = "none")]
2699 #[lang = "const_eval_select"]
2700 #[rustc_do_not_const_check]
2702 pub const unsafe fn const_eval_select<ARG, F, G, RET>(
2704 _called_in_const: F,
2708 F: ~const FnOnce<ARG, Output = RET>,
2709 G: FnOnce<ARG, Output = RET> + ~const Destruct,
2711 called_at_rt.call_once(arg)
2715 feature = "const_eval_select",
2717 reason = "const_eval_select will never be stable"
2719 #[rustc_const_unstable(feature = "const_eval_select", issue = "none")]
2720 #[lang = "const_eval_select_ct"]
2721 pub const unsafe fn const_eval_select_ct<ARG, F, G, RET>(
2727 F: ~const FnOnce<ARG, Output = RET>,
2728 G: FnOnce<ARG, Output = RET> + ~const Destruct,
2730 called_in_const.call_once(arg)