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. Compilation will fail if this is not guaranteed.
1212 /// `transmute` is semantically equivalent to a bitwise move of one type
1213 /// into another. It copies the bits from the source value into the
1214 /// destination value, then forgets the original. Note that source and destination
1215 /// are passed by-value, which means if `T` or `U` contain padding, that padding
1216 /// is *not* guaranteed to be preserved by `transmute`.
1218 /// Both the argument and the result must be [valid](../../nomicon/what-unsafe-does.html) at
1219 /// their given type. Violating this condition leads to [undefined behavior][ub]. The compiler
1220 /// will generate code *assuming that you, the programmer, ensure that there will never be
1221 /// undefined behavior*. It is therefore your responsibility to guarantee that every value
1222 /// passed to `transmute` is valid at both types `T` and `U`. Failing to uphold this condition
1223 /// may lead to unexpected and unstable compilation results. This makes `transmute` **incredibly
1224 /// unsafe**. `transmute` should be the absolute last resort.
1226 /// Transmuting pointers to integers in a `const` context is [undefined behavior][ub].
1227 /// Any attempt to use the resulting value for integer operations will abort const-evaluation.
1228 /// (And even outside `const`, such transmutation is touching on many unspecified aspects of the
1229 /// Rust memory model and should be avoided. See below for alternatives.)
1231 /// Because `transmute` is a by-value operation, alignment of the *transmuted values
1232 /// themselves* is not a concern. As with any other function, the compiler already ensures
1233 /// both `T` and `U` are properly aligned. However, when transmuting values that *point
1234 /// elsewhere* (such as pointers, references, boxes…), the caller has to ensure proper
1235 /// alignment of the pointed-to values.
1237 /// The [nomicon](../../nomicon/transmutes.html) has additional documentation.
1239 /// [ub]: ../../reference/behavior-considered-undefined.html
1243 /// There are a few things that `transmute` is really useful for.
1245 /// Turning a pointer into a function pointer. This is *not* portable to
1246 /// machines where function pointers and data pointers have different sizes.
1249 /// fn foo() -> i32 {
1252 /// // Crucially, we `as`-cast to a raw pointer before `transmute`ing to a function pointer.
1253 /// // This avoids an integer-to-pointer `transmute`, which can be problematic.
1254 /// // Transmuting between raw pointers and function pointers (i.e., two pointer types) is fine.
1255 /// let pointer = foo as *const ();
1256 /// let function = unsafe {
1257 /// std::mem::transmute::<*const (), fn() -> i32>(pointer)
1259 /// assert_eq!(function(), 0);
1262 /// Extending a lifetime, or shortening an invariant lifetime. This is
1263 /// advanced, very unsafe Rust!
1266 /// struct R<'a>(&'a i32);
1267 /// unsafe fn extend_lifetime<'b>(r: R<'b>) -> R<'static> {
1268 /// std::mem::transmute::<R<'b>, R<'static>>(r)
1271 /// unsafe fn shorten_invariant_lifetime<'b, 'c>(r: &'b mut R<'static>)
1272 /// -> &'b mut R<'c> {
1273 /// std::mem::transmute::<&'b mut R<'static>, &'b mut R<'c>>(r)
1279 /// Don't despair: many uses of `transmute` can be achieved through other means.
1280 /// Below are common applications of `transmute` which can be replaced with safer
1283 /// Turning raw bytes (`&[u8]`) into `u32`, `f64`, etc.:
1286 /// let raw_bytes = [0x78, 0x56, 0x34, 0x12];
1288 /// let num = unsafe {
1289 /// std::mem::transmute::<[u8; 4], u32>(raw_bytes)
1292 /// // use `u32::from_ne_bytes` instead
1293 /// let num = u32::from_ne_bytes(raw_bytes);
1294 /// // or use `u32::from_le_bytes` or `u32::from_be_bytes` to specify the endianness
1295 /// let num = u32::from_le_bytes(raw_bytes);
1296 /// assert_eq!(num, 0x12345678);
1297 /// let num = u32::from_be_bytes(raw_bytes);
1298 /// assert_eq!(num, 0x78563412);
1301 /// Turning a pointer into a `usize`:
1305 /// let ptr_num_transmute = unsafe {
1306 /// std::mem::transmute::<&i32, usize>(ptr)
1309 /// // Use an `as` cast instead
1310 /// let ptr_num_cast = ptr as *const i32 as usize;
1313 /// Note that using `transmute` to turn a pointer to a `usize` is (as noted above) [undefined
1314 /// behavior][ub] in `const` contexts. Also outside of consts, this operation might not behave
1315 /// as expected -- this is touching on many unspecified aspects of the Rust memory model.
1316 /// Depending on what the code is doing, the following alternatives are preferrable to
1317 /// pointer-to-integer transmutation:
1318 /// - If the code just wants to store data of arbitrary type in some buffer and needs to pick a
1319 /// type for that buffer, it can use [`MaybeUninit`][mem::MaybeUninit].
1320 /// - If the code actually wants to work on the address the pointer points to, it can use `as`
1321 /// casts or [`ptr.addr()`][pointer::addr].
1323 /// Turning a `*mut T` into an `&mut T`:
1326 /// let ptr: *mut i32 = &mut 0;
1327 /// let ref_transmuted = unsafe {
1328 /// std::mem::transmute::<*mut i32, &mut i32>(ptr)
1331 /// // Use a reborrow instead
1332 /// let ref_casted = unsafe { &mut *ptr };
1335 /// Turning an `&mut T` into an `&mut U`:
1338 /// let ptr = &mut 0;
1339 /// let val_transmuted = unsafe {
1340 /// std::mem::transmute::<&mut i32, &mut u32>(ptr)
1343 /// // Now, put together `as` and reborrowing - note the chaining of `as`
1344 /// // `as` is not transitive
1345 /// let val_casts = unsafe { &mut *(ptr as *mut i32 as *mut u32) };
1348 /// Turning an `&str` into a `&[u8]`:
1351 /// // this is not a good way to do this.
1352 /// let slice = unsafe { std::mem::transmute::<&str, &[u8]>("Rust") };
1353 /// assert_eq!(slice, &[82, 117, 115, 116]);
1355 /// // You could use `str::as_bytes`
1356 /// let slice = "Rust".as_bytes();
1357 /// assert_eq!(slice, &[82, 117, 115, 116]);
1359 /// // Or, just use a byte string, if you have control over the string
1361 /// assert_eq!(b"Rust", &[82, 117, 115, 116]);
1364 /// Turning a `Vec<&T>` into a `Vec<Option<&T>>`.
1366 /// To transmute the inner type of the contents of a container, you must make sure to not
1367 /// violate any of the container's invariants. For `Vec`, this means that both the size
1368 /// *and alignment* of the inner types have to match. Other containers might rely on the
1369 /// size of the type, alignment, or even the `TypeId`, in which case transmuting wouldn't
1370 /// be possible at all without violating the container invariants.
1373 /// let store = [0, 1, 2, 3];
1374 /// let v_orig = store.iter().collect::<Vec<&i32>>();
1376 /// // clone the vector as we will reuse them later
1377 /// let v_clone = v_orig.clone();
1379 /// // Using transmute: this relies on the unspecified data layout of `Vec`, which is a
1380 /// // bad idea and could cause Undefined Behavior.
1381 /// // However, it is no-copy.
1382 /// let v_transmuted = unsafe {
1383 /// std::mem::transmute::<Vec<&i32>, Vec<Option<&i32>>>(v_clone)
1386 /// let v_clone = v_orig.clone();
1388 /// // This is the suggested, safe way.
1389 /// // It does copy the entire vector, though, into a new array.
1390 /// let v_collected = v_clone.into_iter()
1392 /// .collect::<Vec<Option<&i32>>>();
1394 /// let v_clone = v_orig.clone();
1396 /// // This is the proper no-copy, unsafe way of "transmuting" a `Vec`, without relying on the
1397 /// // data layout. Instead of literally calling `transmute`, we perform a pointer cast, but
1398 /// // in terms of converting the original inner type (`&i32`) to the new one (`Option<&i32>`),
1399 /// // this has all the same caveats. Besides the information provided above, also consult the
1400 /// // [`from_raw_parts`] documentation.
1401 /// let v_from_raw = unsafe {
1402 // FIXME Update this when vec_into_raw_parts is stabilized
1403 /// // Ensure the original vector is not dropped.
1404 /// let mut v_clone = std::mem::ManuallyDrop::new(v_clone);
1405 /// Vec::from_raw_parts(v_clone.as_mut_ptr() as *mut Option<&i32>,
1407 /// v_clone.capacity())
1411 /// [`from_raw_parts`]: ../../std/vec/struct.Vec.html#method.from_raw_parts
1413 /// Implementing `split_at_mut`:
1416 /// use std::{slice, mem};
1418 /// // There are multiple ways to do this, and there are multiple problems
1419 /// // with the following (transmute) way.
1420 /// fn split_at_mut_transmute<T>(slice: &mut [T], mid: usize)
1421 /// -> (&mut [T], &mut [T]) {
1422 /// let len = slice.len();
1423 /// assert!(mid <= len);
1425 /// let slice2 = mem::transmute::<&mut [T], &mut [T]>(slice);
1426 /// // first: transmute is not type safe; all it checks is that T and
1427 /// // U are of the same size. Second, right here, you have two
1428 /// // mutable references pointing to the same memory.
1429 /// (&mut slice[0..mid], &mut slice2[mid..len])
1433 /// // This gets rid of the type safety problems; `&mut *` will *only* give
1434 /// // you an `&mut T` from an `&mut T` or `*mut T`.
1435 /// fn split_at_mut_casts<T>(slice: &mut [T], mid: usize)
1436 /// -> (&mut [T], &mut [T]) {
1437 /// let len = slice.len();
1438 /// assert!(mid <= len);
1440 /// let slice2 = &mut *(slice as *mut [T]);
1441 /// // however, you still have two mutable references pointing to
1442 /// // the same memory.
1443 /// (&mut slice[0..mid], &mut slice2[mid..len])
1447 /// // This is how the standard library does it. This is the best method, if
1448 /// // you need to do something like this
1449 /// fn split_at_stdlib<T>(slice: &mut [T], mid: usize)
1450 /// -> (&mut [T], &mut [T]) {
1451 /// let len = slice.len();
1452 /// assert!(mid <= len);
1454 /// let ptr = slice.as_mut_ptr();
1455 /// // This now has three mutable references pointing at the same
1456 /// // memory. `slice`, the rvalue ret.0, and the rvalue ret.1.
1457 /// // `slice` is never used after `let ptr = ...`, and so one can
1458 /// // treat it as "dead", and therefore, you only have two real
1459 /// // mutable slices.
1460 /// (slice::from_raw_parts_mut(ptr, mid),
1461 /// slice::from_raw_parts_mut(ptr.add(mid), len - mid))
1465 #[stable(feature = "rust1", since = "1.0.0")]
1466 #[cfg_attr(not(bootstrap), rustc_allowed_through_unstable_modules)]
1467 #[rustc_const_stable(feature = "const_transmute", since = "1.56.0")]
1468 #[rustc_diagnostic_item = "transmute"]
1469 pub fn transmute<T, U>(e: T) -> U;
1471 /// Returns `true` if the actual type given as `T` requires drop
1472 /// glue; returns `false` if the actual type provided for `T`
1473 /// implements `Copy`.
1475 /// If the actual type neither requires drop glue nor implements
1476 /// `Copy`, then the return value of this function is unspecified.
1478 /// Note that, unlike most intrinsics, this is safe to call;
1479 /// it does not require an `unsafe` block.
1480 /// Therefore, implementations must not require the user to uphold
1481 /// any safety invariants.
1483 /// The stabilized version of this intrinsic is [`mem::needs_drop`](crate::mem::needs_drop).
1484 #[rustc_const_stable(feature = "const_needs_drop", since = "1.40.0")]
1485 pub fn needs_drop<T: ?Sized>() -> bool;
1487 /// Calculates the offset from a pointer.
1489 /// This is implemented as an intrinsic to avoid converting to and from an
1490 /// integer, since the conversion would throw away aliasing information.
1494 /// Both the starting and resulting pointer must be either in bounds or one
1495 /// byte past the end of an allocated object. If either pointer is out of
1496 /// bounds or arithmetic overflow occurs then any further use of the
1497 /// returned value will result in undefined behavior.
1499 /// The stabilized version of this intrinsic is [`pointer::offset`].
1500 #[must_use = "returns a new pointer rather than modifying its argument"]
1501 #[rustc_const_stable(feature = "const_ptr_offset", since = "1.61.0")]
1502 pub fn offset<T>(dst: *const T, offset: isize) -> *const T;
1504 /// Calculates the offset from a pointer, potentially wrapping.
1506 /// This is implemented as an intrinsic to avoid converting to and from an
1507 /// integer, since the conversion inhibits certain optimizations.
1511 /// Unlike the `offset` intrinsic, this intrinsic does not restrict the
1512 /// resulting pointer to point into or one byte past the end of an allocated
1513 /// object, and it wraps with two's complement arithmetic. The resulting
1514 /// value is not necessarily valid to be used to actually access memory.
1516 /// The stabilized version of this intrinsic is [`pointer::wrapping_offset`].
1517 #[must_use = "returns a new pointer rather than modifying its argument"]
1518 #[rustc_const_stable(feature = "const_ptr_offset", since = "1.61.0")]
1519 pub fn arith_offset<T>(dst: *const T, offset: isize) -> *const T;
1521 /// Equivalent to the appropriate `llvm.memcpy.p0i8.0i8.*` intrinsic, with
1522 /// a size of `count` * `size_of::<T>()` and an alignment of
1523 /// `min_align_of::<T>()`
1525 /// The volatile parameter is set to `true`, so it will not be optimized out
1526 /// unless size is equal to zero.
1528 /// This intrinsic does not have a stable counterpart.
1529 pub fn volatile_copy_nonoverlapping_memory<T>(dst: *mut T, src: *const T, count: usize);
1530 /// Equivalent to the appropriate `llvm.memmove.p0i8.0i8.*` intrinsic, with
1531 /// a size of `count * size_of::<T>()` and an alignment of
1532 /// `min_align_of::<T>()`
1534 /// The volatile parameter is set to `true`, so it will not be optimized out
1535 /// unless size is equal to zero.
1537 /// This intrinsic does not have a stable counterpart.
1538 pub fn volatile_copy_memory<T>(dst: *mut T, src: *const T, count: usize);
1539 /// Equivalent to the appropriate `llvm.memset.p0i8.*` intrinsic, with a
1540 /// size of `count * size_of::<T>()` and an alignment of
1541 /// `min_align_of::<T>()`.
1543 /// The volatile parameter is set to `true`, so it will not be optimized out
1544 /// unless size is equal to zero.
1546 /// This intrinsic does not have a stable counterpart.
1547 pub fn volatile_set_memory<T>(dst: *mut T, val: u8, count: usize);
1549 /// Performs a volatile load from the `src` pointer.
1551 /// The stabilized version of this intrinsic is [`core::ptr::read_volatile`].
1552 pub fn volatile_load<T>(src: *const T) -> T;
1553 /// Performs a volatile store to the `dst` pointer.
1555 /// The stabilized version of this intrinsic is [`core::ptr::write_volatile`].
1556 pub fn volatile_store<T>(dst: *mut T, val: T);
1558 /// Performs a volatile load from the `src` pointer
1559 /// The pointer is not required to be aligned.
1561 /// This intrinsic does not have a stable counterpart.
1562 pub fn unaligned_volatile_load<T>(src: *const T) -> T;
1563 /// Performs a volatile store to the `dst` pointer.
1564 /// The pointer is not required to be aligned.
1566 /// This intrinsic does not have a stable counterpart.
1567 pub fn unaligned_volatile_store<T>(dst: *mut T, val: T);
1569 /// Returns the square root of an `f32`
1571 /// The stabilized version of this intrinsic is
1572 /// [`f32::sqrt`](../../std/primitive.f32.html#method.sqrt)
1573 pub fn sqrtf32(x: f32) -> f32;
1574 /// Returns the square root of an `f64`
1576 /// The stabilized version of this intrinsic is
1577 /// [`f64::sqrt`](../../std/primitive.f64.html#method.sqrt)
1578 pub fn sqrtf64(x: f64) -> f64;
1580 /// Raises an `f32` to an integer power.
1582 /// The stabilized version of this intrinsic is
1583 /// [`f32::powi`](../../std/primitive.f32.html#method.powi)
1584 pub fn powif32(a: f32, x: i32) -> f32;
1585 /// Raises an `f64` to an integer power.
1587 /// The stabilized version of this intrinsic is
1588 /// [`f64::powi`](../../std/primitive.f64.html#method.powi)
1589 pub fn powif64(a: f64, x: i32) -> f64;
1591 /// Returns the sine of an `f32`.
1593 /// The stabilized version of this intrinsic is
1594 /// [`f32::sin`](../../std/primitive.f32.html#method.sin)
1595 pub fn sinf32(x: f32) -> f32;
1596 /// Returns the sine of an `f64`.
1598 /// The stabilized version of this intrinsic is
1599 /// [`f64::sin`](../../std/primitive.f64.html#method.sin)
1600 pub fn sinf64(x: f64) -> f64;
1602 /// Returns the cosine of an `f32`.
1604 /// The stabilized version of this intrinsic is
1605 /// [`f32::cos`](../../std/primitive.f32.html#method.cos)
1606 pub fn cosf32(x: f32) -> f32;
1607 /// Returns the cosine of an `f64`.
1609 /// The stabilized version of this intrinsic is
1610 /// [`f64::cos`](../../std/primitive.f64.html#method.cos)
1611 pub fn cosf64(x: f64) -> f64;
1613 /// Raises an `f32` to an `f32` power.
1615 /// The stabilized version of this intrinsic is
1616 /// [`f32::powf`](../../std/primitive.f32.html#method.powf)
1617 pub fn powf32(a: f32, x: f32) -> f32;
1618 /// Raises an `f64` to an `f64` power.
1620 /// The stabilized version of this intrinsic is
1621 /// [`f64::powf`](../../std/primitive.f64.html#method.powf)
1622 pub fn powf64(a: f64, x: f64) -> f64;
1624 /// Returns the exponential of an `f32`.
1626 /// The stabilized version of this intrinsic is
1627 /// [`f32::exp`](../../std/primitive.f32.html#method.exp)
1628 pub fn expf32(x: f32) -> f32;
1629 /// Returns the exponential of an `f64`.
1631 /// The stabilized version of this intrinsic is
1632 /// [`f64::exp`](../../std/primitive.f64.html#method.exp)
1633 pub fn expf64(x: f64) -> f64;
1635 /// Returns 2 raised to the power of an `f32`.
1637 /// The stabilized version of this intrinsic is
1638 /// [`f32::exp2`](../../std/primitive.f32.html#method.exp2)
1639 pub fn exp2f32(x: f32) -> f32;
1640 /// Returns 2 raised to the power of an `f64`.
1642 /// The stabilized version of this intrinsic is
1643 /// [`f64::exp2`](../../std/primitive.f64.html#method.exp2)
1644 pub fn exp2f64(x: f64) -> f64;
1646 /// Returns the natural logarithm of an `f32`.
1648 /// The stabilized version of this intrinsic is
1649 /// [`f32::ln`](../../std/primitive.f32.html#method.ln)
1650 pub fn logf32(x: f32) -> f32;
1651 /// Returns the natural logarithm of an `f64`.
1653 /// The stabilized version of this intrinsic is
1654 /// [`f64::ln`](../../std/primitive.f64.html#method.ln)
1655 pub fn logf64(x: f64) -> f64;
1657 /// Returns the base 10 logarithm of an `f32`.
1659 /// The stabilized version of this intrinsic is
1660 /// [`f32::log10`](../../std/primitive.f32.html#method.log10)
1661 pub fn log10f32(x: f32) -> f32;
1662 /// Returns the base 10 logarithm of an `f64`.
1664 /// The stabilized version of this intrinsic is
1665 /// [`f64::log10`](../../std/primitive.f64.html#method.log10)
1666 pub fn log10f64(x: f64) -> f64;
1668 /// Returns the base 2 logarithm of an `f32`.
1670 /// The stabilized version of this intrinsic is
1671 /// [`f32::log2`](../../std/primitive.f32.html#method.log2)
1672 pub fn log2f32(x: f32) -> f32;
1673 /// Returns the base 2 logarithm of an `f64`.
1675 /// The stabilized version of this intrinsic is
1676 /// [`f64::log2`](../../std/primitive.f64.html#method.log2)
1677 pub fn log2f64(x: f64) -> f64;
1679 /// Returns `a * b + c` for `f32` values.
1681 /// The stabilized version of this intrinsic is
1682 /// [`f32::mul_add`](../../std/primitive.f32.html#method.mul_add)
1683 pub fn fmaf32(a: f32, b: f32, c: f32) -> f32;
1684 /// Returns `a * b + c` for `f64` values.
1686 /// The stabilized version of this intrinsic is
1687 /// [`f64::mul_add`](../../std/primitive.f64.html#method.mul_add)
1688 pub fn fmaf64(a: f64, b: f64, c: f64) -> f64;
1690 /// Returns the absolute value of an `f32`.
1692 /// The stabilized version of this intrinsic is
1693 /// [`f32::abs`](../../std/primitive.f32.html#method.abs)
1694 pub fn fabsf32(x: f32) -> f32;
1695 /// Returns the absolute value of an `f64`.
1697 /// The stabilized version of this intrinsic is
1698 /// [`f64::abs`](../../std/primitive.f64.html#method.abs)
1699 pub fn fabsf64(x: f64) -> f64;
1701 /// Returns the minimum of two `f32` values.
1703 /// Note that, unlike most intrinsics, this is safe to call;
1704 /// it does not require an `unsafe` block.
1705 /// Therefore, implementations must not require the user to uphold
1706 /// any safety invariants.
1708 /// The stabilized version of this intrinsic is
1710 pub fn minnumf32(x: f32, y: f32) -> f32;
1711 /// Returns the minimum of two `f64` values.
1713 /// Note that, unlike most intrinsics, this is safe to call;
1714 /// it does not require an `unsafe` block.
1715 /// Therefore, implementations must not require the user to uphold
1716 /// any safety invariants.
1718 /// The stabilized version of this intrinsic is
1720 pub fn minnumf64(x: f64, y: f64) -> f64;
1721 /// Returns the maximum of two `f32` values.
1723 /// Note that, unlike most intrinsics, this is safe to call;
1724 /// it does not require an `unsafe` block.
1725 /// Therefore, implementations must not require the user to uphold
1726 /// any safety invariants.
1728 /// The stabilized version of this intrinsic is
1730 pub fn maxnumf32(x: f32, y: f32) -> f32;
1731 /// Returns the maximum of two `f64` values.
1733 /// Note that, unlike most intrinsics, this is safe to call;
1734 /// it does not require an `unsafe` block.
1735 /// Therefore, implementations must not require the user to uphold
1736 /// any safety invariants.
1738 /// The stabilized version of this intrinsic is
1740 pub fn maxnumf64(x: f64, y: f64) -> f64;
1742 /// Copies the sign from `y` to `x` for `f32` values.
1744 /// The stabilized version of this intrinsic is
1745 /// [`f32::copysign`](../../std/primitive.f32.html#method.copysign)
1746 pub fn copysignf32(x: f32, y: f32) -> f32;
1747 /// Copies the sign from `y` to `x` for `f64` values.
1749 /// The stabilized version of this intrinsic is
1750 /// [`f64::copysign`](../../std/primitive.f64.html#method.copysign)
1751 pub fn copysignf64(x: f64, y: f64) -> f64;
1753 /// Returns the largest integer less than or equal to an `f32`.
1755 /// The stabilized version of this intrinsic is
1756 /// [`f32::floor`](../../std/primitive.f32.html#method.floor)
1757 pub fn floorf32(x: f32) -> f32;
1758 /// Returns the largest integer less than or equal to an `f64`.
1760 /// The stabilized version of this intrinsic is
1761 /// [`f64::floor`](../../std/primitive.f64.html#method.floor)
1762 pub fn floorf64(x: f64) -> f64;
1764 /// Returns the smallest integer greater than or equal to an `f32`.
1766 /// The stabilized version of this intrinsic is
1767 /// [`f32::ceil`](../../std/primitive.f32.html#method.ceil)
1768 pub fn ceilf32(x: f32) -> f32;
1769 /// Returns the smallest integer greater than or equal to an `f64`.
1771 /// The stabilized version of this intrinsic is
1772 /// [`f64::ceil`](../../std/primitive.f64.html#method.ceil)
1773 pub fn ceilf64(x: f64) -> f64;
1775 /// Returns the integer part of an `f32`.
1777 /// The stabilized version of this intrinsic is
1778 /// [`f32::trunc`](../../std/primitive.f32.html#method.trunc)
1779 pub fn truncf32(x: f32) -> f32;
1780 /// Returns the integer part of an `f64`.
1782 /// The stabilized version of this intrinsic is
1783 /// [`f64::trunc`](../../std/primitive.f64.html#method.trunc)
1784 pub fn truncf64(x: f64) -> f64;
1786 /// Returns the nearest integer to an `f32`. May raise an inexact floating-point exception
1787 /// if the argument is not an integer.
1788 pub fn rintf32(x: f32) -> f32;
1789 /// Returns the nearest integer to an `f64`. May raise an inexact floating-point exception
1790 /// if the argument is not an integer.
1791 pub fn rintf64(x: f64) -> f64;
1793 /// Returns the nearest integer to an `f32`.
1795 /// This intrinsic does not have a stable counterpart.
1796 pub fn nearbyintf32(x: f32) -> f32;
1797 /// Returns the nearest integer to an `f64`.
1799 /// This intrinsic does not have a stable counterpart.
1800 pub fn nearbyintf64(x: f64) -> f64;
1802 /// Returns the nearest integer to an `f32`. Rounds half-way cases away from zero.
1804 /// The stabilized version of this intrinsic is
1805 /// [`f32::round`](../../std/primitive.f32.html#method.round)
1806 pub fn roundf32(x: f32) -> f32;
1807 /// Returns the nearest integer to an `f64`. Rounds half-way cases away from zero.
1809 /// The stabilized version of this intrinsic is
1810 /// [`f64::round`](../../std/primitive.f64.html#method.round)
1811 pub fn roundf64(x: f64) -> f64;
1813 /// Float addition that allows optimizations based on algebraic rules.
1814 /// May assume inputs are finite.
1816 /// This intrinsic does not have a stable counterpart.
1817 pub fn fadd_fast<T: Copy>(a: T, b: T) -> T;
1819 /// Float subtraction that allows optimizations based on algebraic rules.
1820 /// May assume inputs are finite.
1822 /// This intrinsic does not have a stable counterpart.
1823 pub fn fsub_fast<T: Copy>(a: T, b: T) -> T;
1825 /// Float multiplication that allows optimizations based on algebraic rules.
1826 /// May assume inputs are finite.
1828 /// This intrinsic does not have a stable counterpart.
1829 pub fn fmul_fast<T: Copy>(a: T, b: T) -> T;
1831 /// Float division that allows optimizations based on algebraic rules.
1832 /// May assume inputs are finite.
1834 /// This intrinsic does not have a stable counterpart.
1835 pub fn fdiv_fast<T: Copy>(a: T, b: T) -> T;
1837 /// Float remainder that allows optimizations based on algebraic rules.
1838 /// May assume inputs are finite.
1840 /// This intrinsic does not have a stable counterpart.
1841 pub fn frem_fast<T: Copy>(a: T, b: T) -> T;
1843 /// Convert with LLVM’s fptoui/fptosi, which may return undef for values out of range
1844 /// (<https://github.com/rust-lang/rust/issues/10184>)
1846 /// Stabilized as [`f32::to_int_unchecked`] and [`f64::to_int_unchecked`].
1847 pub fn float_to_int_unchecked<Float: Copy, Int: Copy>(value: Float) -> Int;
1849 /// Returns the number of bits set in an integer type `T`
1851 /// Note that, unlike most intrinsics, this is safe to call;
1852 /// it does not require an `unsafe` block.
1853 /// Therefore, implementations must not require the user to uphold
1854 /// any safety invariants.
1856 /// The stabilized versions of this intrinsic are available on the integer
1857 /// primitives via the `count_ones` method. For example,
1858 /// [`u32::count_ones`]
1859 #[rustc_const_stable(feature = "const_ctpop", since = "1.40.0")]
1860 pub fn ctpop<T: Copy>(x: T) -> T;
1862 /// Returns the number of leading unset bits (zeroes) in an integer type `T`.
1864 /// Note that, unlike most intrinsics, this is safe to call;
1865 /// it does not require an `unsafe` block.
1866 /// Therefore, implementations must not require the user to uphold
1867 /// any safety invariants.
1869 /// The stabilized versions of this intrinsic are available on the integer
1870 /// primitives via the `leading_zeros` method. For example,
1871 /// [`u32::leading_zeros`]
1876 /// #![feature(core_intrinsics)]
1878 /// use std::intrinsics::ctlz;
1880 /// let x = 0b0001_1100_u8;
1881 /// let num_leading = ctlz(x);
1882 /// assert_eq!(num_leading, 3);
1885 /// An `x` with value `0` will return the bit width of `T`.
1888 /// #![feature(core_intrinsics)]
1890 /// use std::intrinsics::ctlz;
1893 /// let num_leading = ctlz(x);
1894 /// assert_eq!(num_leading, 16);
1896 #[rustc_const_stable(feature = "const_ctlz", since = "1.40.0")]
1897 pub fn ctlz<T: Copy>(x: T) -> T;
1899 /// Like `ctlz`, but extra-unsafe as it returns `undef` when
1900 /// given an `x` with value `0`.
1902 /// This intrinsic does not have a stable counterpart.
1907 /// #![feature(core_intrinsics)]
1909 /// use std::intrinsics::ctlz_nonzero;
1911 /// let x = 0b0001_1100_u8;
1912 /// let num_leading = unsafe { ctlz_nonzero(x) };
1913 /// assert_eq!(num_leading, 3);
1915 #[rustc_const_stable(feature = "constctlz", since = "1.50.0")]
1916 pub fn ctlz_nonzero<T: Copy>(x: T) -> T;
1918 /// Returns the number of trailing unset bits (zeroes) in an integer type `T`.
1920 /// Note that, unlike most intrinsics, this is safe to call;
1921 /// it does not require an `unsafe` block.
1922 /// Therefore, implementations must not require the user to uphold
1923 /// any safety invariants.
1925 /// The stabilized versions of this intrinsic are available on the integer
1926 /// primitives via the `trailing_zeros` method. For example,
1927 /// [`u32::trailing_zeros`]
1932 /// #![feature(core_intrinsics)]
1934 /// use std::intrinsics::cttz;
1936 /// let x = 0b0011_1000_u8;
1937 /// let num_trailing = cttz(x);
1938 /// assert_eq!(num_trailing, 3);
1941 /// An `x` with value `0` will return the bit width of `T`:
1944 /// #![feature(core_intrinsics)]
1946 /// use std::intrinsics::cttz;
1949 /// let num_trailing = cttz(x);
1950 /// assert_eq!(num_trailing, 16);
1952 #[rustc_const_stable(feature = "const_cttz", since = "1.40.0")]
1953 pub fn cttz<T: Copy>(x: T) -> T;
1955 /// Like `cttz`, but extra-unsafe as it returns `undef` when
1956 /// given an `x` with value `0`.
1958 /// This intrinsic does not have a stable counterpart.
1963 /// #![feature(core_intrinsics)]
1965 /// use std::intrinsics::cttz_nonzero;
1967 /// let x = 0b0011_1000_u8;
1968 /// let num_trailing = unsafe { cttz_nonzero(x) };
1969 /// assert_eq!(num_trailing, 3);
1971 #[rustc_const_stable(feature = "const_cttz_nonzero", since = "1.53.0")]
1972 pub fn cttz_nonzero<T: Copy>(x: T) -> T;
1974 /// Reverses the bytes in an integer type `T`.
1976 /// Note that, unlike most intrinsics, this is safe to call;
1977 /// it does not require an `unsafe` block.
1978 /// Therefore, implementations must not require the user to uphold
1979 /// any safety invariants.
1981 /// The stabilized versions of this intrinsic are available on the integer
1982 /// primitives via the `swap_bytes` method. For example,
1983 /// [`u32::swap_bytes`]
1984 #[rustc_const_stable(feature = "const_bswap", since = "1.40.0")]
1985 pub fn bswap<T: Copy>(x: T) -> T;
1987 /// Reverses the bits in an integer type `T`.
1989 /// Note that, unlike most intrinsics, this is safe to call;
1990 /// it does not require an `unsafe` block.
1991 /// Therefore, implementations must not require the user to uphold
1992 /// any safety invariants.
1994 /// The stabilized versions of this intrinsic are available on the integer
1995 /// primitives via the `reverse_bits` method. For example,
1996 /// [`u32::reverse_bits`]
1997 #[rustc_const_stable(feature = "const_bitreverse", since = "1.40.0")]
1998 pub fn bitreverse<T: Copy>(x: T) -> T;
2000 /// Performs checked integer addition.
2002 /// Note that, unlike most intrinsics, this is safe to call;
2003 /// it does not require an `unsafe` block.
2004 /// Therefore, implementations must not require the user to uphold
2005 /// any safety invariants.
2007 /// The stabilized versions of this intrinsic are available on the integer
2008 /// primitives via the `overflowing_add` method. For example,
2009 /// [`u32::overflowing_add`]
2010 #[rustc_const_stable(feature = "const_int_overflow", since = "1.40.0")]
2011 pub fn add_with_overflow<T: Copy>(x: T, y: T) -> (T, bool);
2013 /// Performs checked integer subtraction
2015 /// Note that, unlike most intrinsics, this is safe to call;
2016 /// it does not require an `unsafe` block.
2017 /// Therefore, implementations must not require the user to uphold
2018 /// any safety invariants.
2020 /// The stabilized versions of this intrinsic are available on the integer
2021 /// primitives via the `overflowing_sub` method. For example,
2022 /// [`u32::overflowing_sub`]
2023 #[rustc_const_stable(feature = "const_int_overflow", since = "1.40.0")]
2024 pub fn sub_with_overflow<T: Copy>(x: T, y: T) -> (T, bool);
2026 /// Performs checked integer multiplication
2028 /// Note that, unlike most intrinsics, this is safe to call;
2029 /// it does not require an `unsafe` block.
2030 /// Therefore, implementations must not require the user to uphold
2031 /// any safety invariants.
2033 /// The stabilized versions of this intrinsic are available on the integer
2034 /// primitives via the `overflowing_mul` method. For example,
2035 /// [`u32::overflowing_mul`]
2036 #[rustc_const_stable(feature = "const_int_overflow", since = "1.40.0")]
2037 pub fn mul_with_overflow<T: Copy>(x: T, y: T) -> (T, bool);
2039 /// Performs an exact division, resulting in undefined behavior where
2040 /// `x % y != 0` or `y == 0` or `x == T::MIN && y == -1`
2042 /// This intrinsic does not have a stable counterpart.
2043 pub fn exact_div<T: Copy>(x: T, y: T) -> T;
2045 /// Performs an unchecked division, resulting in undefined behavior
2046 /// where `y == 0` or `x == T::MIN && y == -1`
2048 /// Safe wrappers for this intrinsic are available on the integer
2049 /// primitives via the `checked_div` method. For example,
2050 /// [`u32::checked_div`]
2051 #[rustc_const_stable(feature = "const_int_unchecked_div", since = "1.52.0")]
2052 pub fn unchecked_div<T: Copy>(x: T, y: T) -> T;
2053 /// Returns the remainder of an unchecked division, resulting in
2054 /// undefined behavior when `y == 0` or `x == T::MIN && y == -1`
2056 /// Safe wrappers for this intrinsic are available on the integer
2057 /// primitives via the `checked_rem` method. For example,
2058 /// [`u32::checked_rem`]
2059 #[rustc_const_stable(feature = "const_int_unchecked_rem", since = "1.52.0")]
2060 pub fn unchecked_rem<T: Copy>(x: T, y: T) -> T;
2062 /// Performs an unchecked left shift, resulting in undefined behavior when
2063 /// `y < 0` or `y >= N`, where N is the width of T in bits.
2065 /// Safe wrappers for this intrinsic are available on the integer
2066 /// primitives via the `checked_shl` method. For example,
2067 /// [`u32::checked_shl`]
2068 #[rustc_const_stable(feature = "const_int_unchecked", since = "1.40.0")]
2069 pub fn unchecked_shl<T: Copy>(x: T, y: T) -> T;
2070 /// Performs an unchecked right shift, resulting in undefined behavior when
2071 /// `y < 0` or `y >= N`, where N is the width of T in bits.
2073 /// Safe wrappers for this intrinsic are available on the integer
2074 /// primitives via the `checked_shr` method. For example,
2075 /// [`u32::checked_shr`]
2076 #[rustc_const_stable(feature = "const_int_unchecked", since = "1.40.0")]
2077 pub fn unchecked_shr<T: Copy>(x: T, y: T) -> T;
2079 /// Returns the result of an unchecked addition, resulting in
2080 /// undefined behavior when `x + y > T::MAX` or `x + y < T::MIN`.
2082 /// This intrinsic does not have a stable counterpart.
2083 #[rustc_const_unstable(feature = "const_int_unchecked_arith", issue = "none")]
2084 pub fn unchecked_add<T: Copy>(x: T, y: T) -> T;
2086 /// Returns the result of an unchecked subtraction, resulting in
2087 /// undefined behavior when `x - y > T::MAX` or `x - y < T::MIN`.
2089 /// This intrinsic does not have a stable counterpart.
2090 #[rustc_const_unstable(feature = "const_int_unchecked_arith", issue = "none")]
2091 pub fn unchecked_sub<T: Copy>(x: T, y: T) -> T;
2093 /// Returns the result of an unchecked multiplication, resulting in
2094 /// undefined behavior when `x * y > T::MAX` or `x * y < T::MIN`.
2096 /// This intrinsic does not have a stable counterpart.
2097 #[rustc_const_unstable(feature = "const_int_unchecked_arith", issue = "none")]
2098 pub fn unchecked_mul<T: Copy>(x: T, y: T) -> T;
2100 /// Performs rotate left.
2102 /// Note that, unlike most intrinsics, this is safe to call;
2103 /// it does not require an `unsafe` block.
2104 /// Therefore, implementations must not require the user to uphold
2105 /// any safety invariants.
2107 /// The stabilized versions of this intrinsic are available on the integer
2108 /// primitives via the `rotate_left` method. For example,
2109 /// [`u32::rotate_left`]
2110 #[rustc_const_stable(feature = "const_int_rotate", since = "1.40.0")]
2111 pub fn rotate_left<T: Copy>(x: T, y: T) -> T;
2113 /// Performs rotate right.
2115 /// Note that, unlike most intrinsics, this is safe to call;
2116 /// it does not require an `unsafe` block.
2117 /// Therefore, implementations must not require the user to uphold
2118 /// any safety invariants.
2120 /// The stabilized versions of this intrinsic are available on the integer
2121 /// primitives via the `rotate_right` method. For example,
2122 /// [`u32::rotate_right`]
2123 #[rustc_const_stable(feature = "const_int_rotate", since = "1.40.0")]
2124 pub fn rotate_right<T: Copy>(x: T, y: T) -> T;
2126 /// Returns (a + b) mod 2<sup>N</sup>, where N is the width of T in bits.
2128 /// Note that, unlike most intrinsics, this is safe to call;
2129 /// it does not require an `unsafe` block.
2130 /// Therefore, implementations must not require the user to uphold
2131 /// any safety invariants.
2133 /// The stabilized versions of this intrinsic are available on the integer
2134 /// primitives via the `wrapping_add` method. For example,
2135 /// [`u32::wrapping_add`]
2136 #[rustc_const_stable(feature = "const_int_wrapping", since = "1.40.0")]
2137 pub fn wrapping_add<T: Copy>(a: T, b: T) -> T;
2138 /// Returns (a - b) mod 2<sup>N</sup>, where N is the width of T in bits.
2140 /// Note that, unlike most intrinsics, this is safe to call;
2141 /// it does not require an `unsafe` block.
2142 /// Therefore, implementations must not require the user to uphold
2143 /// any safety invariants.
2145 /// The stabilized versions of this intrinsic are available on the integer
2146 /// primitives via the `wrapping_sub` method. For example,
2147 /// [`u32::wrapping_sub`]
2148 #[rustc_const_stable(feature = "const_int_wrapping", since = "1.40.0")]
2149 pub fn wrapping_sub<T: Copy>(a: T, b: T) -> T;
2150 /// Returns (a * b) mod 2<sup>N</sup>, where N is the width of T in bits.
2152 /// Note that, unlike most intrinsics, this is safe to call;
2153 /// it does not require an `unsafe` block.
2154 /// Therefore, implementations must not require the user to uphold
2155 /// any safety invariants.
2157 /// The stabilized versions of this intrinsic are available on the integer
2158 /// primitives via the `wrapping_mul` method. For example,
2159 /// [`u32::wrapping_mul`]
2160 #[rustc_const_stable(feature = "const_int_wrapping", since = "1.40.0")]
2161 pub fn wrapping_mul<T: Copy>(a: T, b: T) -> T;
2163 /// Computes `a + b`, saturating at numeric bounds.
2165 /// Note that, unlike most intrinsics, this is safe to call;
2166 /// it does not require an `unsafe` block.
2167 /// Therefore, implementations must not require the user to uphold
2168 /// any safety invariants.
2170 /// The stabilized versions of this intrinsic are available on the integer
2171 /// primitives via the `saturating_add` method. For example,
2172 /// [`u32::saturating_add`]
2173 #[rustc_const_stable(feature = "const_int_saturating", since = "1.40.0")]
2174 pub fn saturating_add<T: Copy>(a: T, b: T) -> T;
2175 /// Computes `a - b`, saturating at numeric bounds.
2177 /// Note that, unlike most intrinsics, this is safe to call;
2178 /// it does not require an `unsafe` block.
2179 /// Therefore, implementations must not require the user to uphold
2180 /// any safety invariants.
2182 /// The stabilized versions of this intrinsic are available on the integer
2183 /// primitives via the `saturating_sub` method. For example,
2184 /// [`u32::saturating_sub`]
2185 #[rustc_const_stable(feature = "const_int_saturating", since = "1.40.0")]
2186 pub fn saturating_sub<T: Copy>(a: T, b: T) -> T;
2188 /// Returns the value of the discriminant for the variant in 'v';
2189 /// if `T` has no discriminant, returns `0`.
2191 /// Note that, unlike most intrinsics, this is safe to call;
2192 /// it does not require an `unsafe` block.
2193 /// Therefore, implementations must not require the user to uphold
2194 /// any safety invariants.
2196 /// The stabilized version of this intrinsic is [`core::mem::discriminant`].
2197 #[rustc_const_unstable(feature = "const_discriminant", issue = "69821")]
2198 pub fn discriminant_value<T>(v: &T) -> <T as DiscriminantKind>::Discriminant;
2200 /// Returns the number of variants of the type `T` cast to a `usize`;
2201 /// if `T` has no variants, returns `0`. Uninhabited variants will be counted.
2203 /// Note that, unlike most intrinsics, this is safe to call;
2204 /// it does not require an `unsafe` block.
2205 /// Therefore, implementations must not require the user to uphold
2206 /// any safety invariants.
2208 /// The to-be-stabilized version of this intrinsic is [`mem::variant_count`].
2209 #[rustc_const_unstable(feature = "variant_count", issue = "73662")]
2210 pub fn variant_count<T>() -> usize;
2212 /// Rust's "try catch" construct which invokes the function pointer `try_fn`
2213 /// with the data pointer `data`.
2215 /// The third argument is a function called if a panic occurs. This function
2216 /// takes the data pointer and a pointer to the target-specific exception
2217 /// object that was caught. For more information see the compiler's
2218 /// source as well as std's catch implementation.
2219 pub fn r#try(try_fn: fn(*mut u8), data: *mut u8, catch_fn: fn(*mut u8, *mut u8)) -> i32;
2221 /// Emits a `!nontemporal` store according to LLVM (see their docs).
2222 /// Probably will never become stable.
2223 pub fn nontemporal_store<T>(ptr: *mut T, val: T);
2225 /// See documentation of `<*const T>::offset_from` for details.
2226 #[rustc_const_unstable(feature = "const_ptr_offset_from", issue = "92980")]
2227 pub fn ptr_offset_from<T>(ptr: *const T, base: *const T) -> isize;
2229 /// See documentation of `<*const T>::sub_ptr` for details.
2230 #[rustc_const_unstable(feature = "const_ptr_offset_from", issue = "92980")]
2231 pub fn ptr_offset_from_unsigned<T>(ptr: *const T, base: *const T) -> usize;
2233 /// See documentation of `<*const T>::guaranteed_eq` for details.
2235 /// Note that, unlike most intrinsics, this is safe to call;
2236 /// it does not require an `unsafe` block.
2237 /// Therefore, implementations must not require the user to uphold
2238 /// any safety invariants.
2239 #[rustc_const_unstable(feature = "const_raw_ptr_comparison", issue = "53020")]
2240 pub fn ptr_guaranteed_eq<T>(ptr: *const T, other: *const T) -> bool;
2242 /// See documentation of `<*const T>::guaranteed_ne` for details.
2244 /// Note that, unlike most intrinsics, this is safe to call;
2245 /// it does not require an `unsafe` block.
2246 /// Therefore, implementations must not require the user to uphold
2247 /// any safety invariants.
2248 #[rustc_const_unstable(feature = "const_raw_ptr_comparison", issue = "53020")]
2249 pub fn ptr_guaranteed_ne<T>(ptr: *const T, other: *const T) -> bool;
2251 /// Allocates a block of memory at compile time.
2252 /// At runtime, just returns a null pointer.
2256 /// - The `align` argument must be a power of two.
2257 /// - At compile time, a compile error occurs if this constraint is violated.
2258 /// - At runtime, it is not checked.
2259 #[rustc_const_unstable(feature = "const_heap", issue = "79597")]
2260 pub fn const_allocate(size: usize, align: usize) -> *mut u8;
2262 /// Deallocates a memory which allocated by `intrinsics::const_allocate` at compile time.
2263 /// At runtime, does nothing.
2267 /// - The `align` argument must be a power of two.
2268 /// - At compile time, a compile error occurs if this constraint is violated.
2269 /// - At runtime, it is not checked.
2270 /// - If the `ptr` is created in an another const, this intrinsic doesn't deallocate it.
2271 /// - If the `ptr` is pointing to a local variable, this intrinsic doesn't deallocate it.
2272 #[rustc_const_unstable(feature = "const_heap", issue = "79597")]
2273 pub fn const_deallocate(ptr: *mut u8, size: usize, align: usize);
2275 /// Determines whether the raw bytes of the two values are equal.
2277 /// This is particularly handy for arrays, since it allows things like just
2278 /// comparing `i96`s instead of forcing `alloca`s for `[6 x i16]`.
2280 /// Above some backend-decided threshold this will emit calls to `memcmp`,
2281 /// like slice equality does, instead of causing massive code size.
2285 /// It's UB to call this if any of the *bytes* in `*a` or `*b` are uninitialized or carry a
2287 /// Note that this is a stricter criterion than just the *values* being
2288 /// fully-initialized: if `T` has padding, it's UB to call this intrinsic.
2290 /// (The implementation is allowed to branch on the results of comparisons,
2291 /// which is UB if any of their inputs are `undef`.)
2292 #[rustc_const_unstable(feature = "const_intrinsic_raw_eq", issue = "none")]
2293 pub fn raw_eq<T>(a: &T, b: &T) -> bool;
2295 /// See documentation of [`std::hint::black_box`] for details.
2297 /// [`std::hint::black_box`]: crate::hint::black_box
2298 #[rustc_const_unstable(feature = "const_black_box", issue = "none")]
2299 pub fn black_box<T>(dummy: T) -> T;
2301 /// `ptr` must point to a vtable.
2302 /// The intrinsic will return the size stored in that vtable.
2303 #[cfg(not(bootstrap))]
2304 pub fn vtable_size(ptr: *const ()) -> usize;
2306 /// `ptr` must point to a vtable.
2307 /// The intrinsic will return the alignment stored in that vtable.
2308 #[cfg(not(bootstrap))]
2309 pub fn vtable_align(ptr: *const ()) -> usize;
2312 // Some functions are defined here because they accidentally got made
2313 // available in this module on stable. See <https://github.com/rust-lang/rust/issues/15702>.
2314 // (`transmute` also falls into this category, but it cannot be wrapped due to the
2315 // check that `T` and `U` have the same size.)
2317 /// Check that the preconditions of an unsafe function are followed, if debug_assertions are on,
2318 /// and only at runtime.
2322 /// Invoking this macro is only sound if the following code is already UB when the passed
2323 /// expression evaluates to false.
2325 /// This macro expands to a check at runtime if debug_assertions is set. It has no effect at
2326 /// compile time, but the semantics of the contained `const_eval_select` must be the same at
2327 /// runtime and at compile time. Thus if the expression evaluates to false, this macro produces
2328 /// different behavior at compile time and at runtime, and invoking it is incorrect.
2330 /// So in a sense it is UB if this macro is useful, but we expect callers of `unsafe fn` to make
2331 /// the occasional mistake, and this check should help them figure things out.
2332 #[allow_internal_unstable(const_eval_select)] // permit this to be called in stably-const fn
2333 macro_rules! assert_unsafe_precondition {
2335 if cfg!(debug_assertions) {
2336 // Use a closure so that we can capture arbitrary expressions from the invocation
2339 // abort instead of panicking to reduce impact on code size
2340 ::core::intrinsics::abort();
2343 const fn comptime() {}
2345 ::core::intrinsics::const_eval_select((), comptime, runtime);
2349 pub(crate) use assert_unsafe_precondition;
2351 /// Checks whether `ptr` is properly aligned with respect to
2352 /// `align_of::<T>()`.
2353 pub(crate) fn is_aligned_and_not_null<T>(ptr: *const T) -> bool {
2354 !ptr.is_null() && ptr.addr() % mem::align_of::<T>() == 0
2357 /// Checks whether the regions of memory starting at `src` and `dst` of size
2358 /// `count * size_of::<T>()` do *not* overlap.
2359 pub(crate) fn is_nonoverlapping<T>(src: *const T, dst: *const T, count: usize) -> bool {
2360 let src_usize = src.addr();
2361 let dst_usize = dst.addr();
2362 let size = mem::size_of::<T>().checked_mul(count).unwrap();
2363 let diff = if src_usize > dst_usize { src_usize - dst_usize } else { dst_usize - src_usize };
2364 // If the absolute distance between the ptrs is at least as big as the size of the buffer,
2365 // they do not overlap.
2369 /// Copies `count * size_of::<T>()` bytes from `src` to `dst`. The source
2370 /// and destination must *not* overlap.
2372 /// For regions of memory which might overlap, use [`copy`] instead.
2374 /// `copy_nonoverlapping` is semantically equivalent to C's [`memcpy`], but
2375 /// with the argument order swapped.
2377 /// The copy is "untyped" in the sense that data may be uninitialized or otherwise violate the
2378 /// requirements of `T`. The initialization state is preserved exactly.
2380 /// [`memcpy`]: https://en.cppreference.com/w/c/string/byte/memcpy
2384 /// Behavior is undefined if any of the following conditions are violated:
2386 /// * `src` must be [valid] for reads of `count * size_of::<T>()` bytes.
2388 /// * `dst` must be [valid] for writes of `count * size_of::<T>()` bytes.
2390 /// * Both `src` and `dst` must be properly aligned.
2392 /// * The region of memory beginning at `src` with a size of `count *
2393 /// size_of::<T>()` bytes must *not* overlap with the region of memory
2394 /// beginning at `dst` with the same size.
2396 /// Like [`read`], `copy_nonoverlapping` creates a bitwise copy of `T`, regardless of
2397 /// whether `T` is [`Copy`]. If `T` is not [`Copy`], using *both* the values
2398 /// in the region beginning at `*src` and the region beginning at `*dst` can
2399 /// [violate memory safety][read-ownership].
2401 /// Note that even if the effectively copied size (`count * size_of::<T>()`) is
2402 /// `0`, the pointers must be non-null and properly aligned.
2404 /// [`read`]: crate::ptr::read
2405 /// [read-ownership]: crate::ptr::read#ownership-of-the-returned-value
2406 /// [valid]: crate::ptr#safety
2410 /// Manually implement [`Vec::append`]:
2415 /// /// Moves all the elements of `src` into `dst`, leaving `src` empty.
2416 /// fn append<T>(dst: &mut Vec<T>, src: &mut Vec<T>) {
2417 /// let src_len = src.len();
2418 /// let dst_len = dst.len();
2420 /// // Ensure that `dst` has enough capacity to hold all of `src`.
2421 /// dst.reserve(src_len);
2424 /// // The call to offset is always safe because `Vec` will never
2425 /// // allocate more than `isize::MAX` bytes.
2426 /// let dst_ptr = dst.as_mut_ptr().offset(dst_len as isize);
2427 /// let src_ptr = src.as_ptr();
2429 /// // Truncate `src` without dropping its contents. We do this first,
2430 /// // to avoid problems in case something further down panics.
2433 /// // The two regions cannot overlap because mutable references do
2434 /// // not alias, and two different vectors cannot own the same
2436 /// ptr::copy_nonoverlapping(src_ptr, dst_ptr, src_len);
2438 /// // Notify `dst` that it now holds the contents of `src`.
2439 /// dst.set_len(dst_len + src_len);
2443 /// let mut a = vec!['r'];
2444 /// let mut b = vec!['u', 's', 't'];
2446 /// append(&mut a, &mut b);
2448 /// assert_eq!(a, &['r', 'u', 's', 't']);
2449 /// assert!(b.is_empty());
2452 /// [`Vec::append`]: ../../std/vec/struct.Vec.html#method.append
2453 #[doc(alias = "memcpy")]
2454 #[stable(feature = "rust1", since = "1.0.0")]
2455 #[cfg_attr(not(bootstrap), rustc_allowed_through_unstable_modules)]
2456 #[rustc_const_stable(feature = "const_intrinsic_copy", since = "1.63.0")]
2458 #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
2459 pub const unsafe fn copy_nonoverlapping<T>(src: *const T, dst: *mut T, count: usize) {
2460 extern "rust-intrinsic" {
2461 #[rustc_const_stable(feature = "const_intrinsic_copy", since = "1.63.0")]
2462 pub fn copy_nonoverlapping<T>(src: *const T, dst: *mut T, count: usize);
2465 // SAFETY: the safety contract for `copy_nonoverlapping` must be
2466 // upheld by the caller.
2468 assert_unsafe_precondition!(
2469 is_aligned_and_not_null(src)
2470 && is_aligned_and_not_null(dst)
2471 && is_nonoverlapping(src, dst, count)
2473 copy_nonoverlapping(src, dst, count)
2477 /// Copies `count * size_of::<T>()` bytes from `src` to `dst`. The source
2478 /// and destination may overlap.
2480 /// If the source and destination will *never* overlap,
2481 /// [`copy_nonoverlapping`] can be used instead.
2483 /// `copy` is semantically equivalent to C's [`memmove`], but with the argument
2484 /// order swapped. Copying takes place as if the bytes were copied from `src`
2485 /// to a temporary array and then copied from the array to `dst`.
2487 /// The copy is "untyped" in the sense that data may be uninitialized or otherwise violate the
2488 /// requirements of `T`. The initialization state is preserved exactly.
2490 /// [`memmove`]: https://en.cppreference.com/w/c/string/byte/memmove
2494 /// Behavior is undefined if any of the following conditions are violated:
2496 /// * `src` must be [valid] for reads of `count * size_of::<T>()` bytes.
2498 /// * `dst` must be [valid] for writes of `count * size_of::<T>()` bytes.
2500 /// * Both `src` and `dst` must be properly aligned.
2502 /// Like [`read`], `copy` creates a bitwise copy of `T`, regardless of
2503 /// whether `T` is [`Copy`]. If `T` is not [`Copy`], using both the values
2504 /// in the region beginning at `*src` and the region beginning at `*dst` can
2505 /// [violate memory safety][read-ownership].
2507 /// Note that even if the effectively copied size (`count * size_of::<T>()`) is
2508 /// `0`, the pointers must be non-null and properly aligned.
2510 /// [`read`]: crate::ptr::read
2511 /// [read-ownership]: crate::ptr::read#ownership-of-the-returned-value
2512 /// [valid]: crate::ptr#safety
2516 /// Efficiently create a Rust vector from an unsafe buffer:
2523 /// /// * `ptr` must be correctly aligned for its type and non-zero.
2524 /// /// * `ptr` must be valid for reads of `elts` contiguous elements of type `T`.
2525 /// /// * Those elements must not be used after calling this function unless `T: Copy`.
2526 /// # #[allow(dead_code)]
2527 /// unsafe fn from_buf_raw<T>(ptr: *const T, elts: usize) -> Vec<T> {
2528 /// let mut dst = Vec::with_capacity(elts);
2530 /// // SAFETY: Our precondition ensures the source is aligned and valid,
2531 /// // and `Vec::with_capacity` ensures that we have usable space to write them.
2532 /// ptr::copy(ptr, dst.as_mut_ptr(), elts);
2534 /// // SAFETY: We created it with this much capacity earlier,
2535 /// // and the previous `copy` has initialized these elements.
2536 /// dst.set_len(elts);
2540 #[doc(alias = "memmove")]
2541 #[stable(feature = "rust1", since = "1.0.0")]
2542 #[cfg_attr(not(bootstrap), rustc_allowed_through_unstable_modules)]
2543 #[rustc_const_stable(feature = "const_intrinsic_copy", since = "1.63.0")]
2545 #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
2546 pub const unsafe fn copy<T>(src: *const T, dst: *mut T, count: usize) {
2547 extern "rust-intrinsic" {
2548 #[rustc_const_stable(feature = "const_intrinsic_copy", since = "1.63.0")]
2549 fn copy<T>(src: *const T, dst: *mut T, count: usize);
2552 // SAFETY: the safety contract for `copy` must be upheld by the caller.
2554 assert_unsafe_precondition!(is_aligned_and_not_null(src) && is_aligned_and_not_null(dst));
2555 copy(src, dst, count)
2559 /// Sets `count * size_of::<T>()` bytes of memory starting at `dst` to
2562 /// `write_bytes` is similar to C's [`memset`], but sets `count *
2563 /// size_of::<T>()` bytes to `val`.
2565 /// [`memset`]: https://en.cppreference.com/w/c/string/byte/memset
2569 /// Behavior is undefined if any of the following conditions are violated:
2571 /// * `dst` must be [valid] for writes of `count * size_of::<T>()` bytes.
2573 /// * `dst` must be properly aligned.
2575 /// Note that even if the effectively copied size (`count * size_of::<T>()`) is
2576 /// `0`, the pointer must be non-null and properly aligned.
2578 /// Additionally, note that changing `*dst` in this way can easily lead to undefined behavior (UB)
2579 /// later if the written bytes are not a valid representation of some `T`. For instance, the
2580 /// following is an **incorrect** use of this function:
2584 /// let mut value: u8 = 0;
2585 /// let ptr: *mut bool = &mut value as *mut u8 as *mut bool;
2586 /// let _bool = ptr.read(); // This is fine, `ptr` points to a valid `bool`.
2587 /// ptr.write_bytes(42u8, 1); // This function itself does not cause UB...
2588 /// let _bool = ptr.read(); // ...but it makes this operation UB! ⚠️
2592 /// [valid]: crate::ptr#safety
2601 /// let mut vec = vec![0u32; 4];
2603 /// let vec_ptr = vec.as_mut_ptr();
2604 /// ptr::write_bytes(vec_ptr, 0xfe, 2);
2606 /// assert_eq!(vec, [0xfefefefe, 0xfefefefe, 0, 0]);
2608 #[doc(alias = "memset")]
2609 #[stable(feature = "rust1", since = "1.0.0")]
2610 #[cfg_attr(not(bootstrap), rustc_allowed_through_unstable_modules)]
2611 #[rustc_const_unstable(feature = "const_ptr_write", issue = "86302")]
2613 #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
2614 pub const unsafe fn write_bytes<T>(dst: *mut T, val: u8, count: usize) {
2615 extern "rust-intrinsic" {
2616 #[rustc_const_unstable(feature = "const_ptr_write", issue = "86302")]
2617 fn write_bytes<T>(dst: *mut T, val: u8, count: usize);
2620 // SAFETY: the safety contract for `write_bytes` must be upheld by the caller.
2622 assert_unsafe_precondition!(is_aligned_and_not_null(dst));
2623 write_bytes(dst, val, count)
2627 /// Selects which function to call depending on the context.
2629 /// If this function is evaluated at compile-time, then a call to this
2630 /// intrinsic will be replaced with a call to `called_in_const`. It gets
2631 /// replaced with a call to `called_at_rt` otherwise.
2633 /// # Type Requirements
2635 /// The two functions must be both function items. They cannot be function
2636 /// pointers or closures.
2638 /// `arg` will be the arguments that will be passed to either one of the
2639 /// two functions, therefore, both functions must accept the same type of
2640 /// arguments. Both functions must return RET.
2644 /// The two functions must behave observably equivalent. Safe code in other
2645 /// crates may assume that calling a `const fn` at compile-time and at run-time
2646 /// produces the same result. A function that produces a different result when
2647 /// evaluated at run-time, or has any other observable side-effects, is
2650 /// Here is an example of how this could cause a problem:
2652 /// #![feature(const_eval_select)]
2653 /// #![feature(core_intrinsics)]
2654 /// use std::hint::unreachable_unchecked;
2655 /// use std::intrinsics::const_eval_select;
2658 /// pub const fn inconsistent() -> i32 {
2659 /// fn runtime() -> i32 { 1 }
2660 /// const fn compiletime() -> i32 { 2 }
2663 // // ⚠ This code violates the required equivalence of `compiletime`
2664 /// // and `runtime`.
2665 /// const_eval_select((), compiletime, runtime)
2670 /// const X: i32 = inconsistent();
2671 /// let x = inconsistent();
2672 /// if x != X { unsafe { unreachable_unchecked(); }}
2675 /// This code causes Undefined Behavior when being run, since the
2676 /// `unreachable_unchecked` is actually being reached. The bug is in *crate A*,
2677 /// which violates the principle that a `const fn` must behave the same at
2678 /// compile-time and at run-time. The unsafe code in crate B is fine.
2680 feature = "const_eval_select",
2682 reason = "const_eval_select will never be stable"
2684 #[rustc_const_unstable(feature = "const_eval_select", issue = "none")]
2685 #[lang = "const_eval_select"]
2686 #[rustc_do_not_const_check]
2688 pub const unsafe fn const_eval_select<ARG, F, G, RET>(
2690 _called_in_const: F,
2694 F: ~const FnOnce<ARG, Output = RET>,
2695 G: FnOnce<ARG, Output = RET> + ~const Destruct,
2697 called_at_rt.call_once(arg)
2701 feature = "const_eval_select",
2703 reason = "const_eval_select will never be stable"
2705 #[rustc_const_unstable(feature = "const_eval_select", issue = "none")]
2706 #[lang = "const_eval_select_ct"]
2707 pub const unsafe fn const_eval_select_ct<ARG, F, G, RET>(
2713 F: ~const FnOnce<ARG, Output = RET>,
2714 G: FnOnce<ARG, Output = RET> + ~const Destruct,
2716 called_in_const.call_once(arg)
projects / rust.git / blob