src/libcore/intrinsics.rs

   1 // Copyright 2013 The Rust Project Developers. See the COPYRIGHT
   2 // file at the top-level directory of this distribution and at
   3 // http://rust-lang.org/COPYRIGHT.
   4 //
   5 // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
   6 // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
   7 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
   8 // option. This file may not be copied, modified, or distributed
   9 // except according to those terms.
  10
  11 //! rustc compiler intrinsics.
  12 //!
  13 //! The corresponding definitions are in librustc_trans/intrinsic.rs.
  14 //!
  15 //! # Volatiles
  16 //!
  17 //! The volatile intrinsics provide operations intended to act on I/O
  18 //! memory, which are guaranteed to not be reordered by the compiler
  19 //! across other volatile intrinsics. See the LLVM documentation on
  20 //! [[volatile]].
  21 //!
  22 //! [volatile]: http://llvm.org/docs/LangRef.html#volatile-memory-accesses
  23 //!
  24 //! # Atomics
  25 //!
  26 //! The atomic intrinsics provide common atomic operations on machine
  27 //! words, with multiple possible memory orderings. They obey the same
  28 //! semantics as C++11. See the LLVM documentation on [[atomics]].
  29 //!
  30 //! [atomics]: http://llvm.org/docs/Atomics.html
  31 //!
  32 //! A quick refresher on memory ordering:
  33 //!
  34 //! * Acquire - a barrier for acquiring a lock. Subsequent reads and writes
  35 //!   take place after the barrier.
  36 //! * Release - a barrier for releasing a lock. Preceding reads and writes
  37 //!   take place before the barrier.
  38 //! * Sequentially consistent - sequentially consistent operations are
  39 //!   guaranteed to happen in order. This is the standard mode for working
  40 //!   with atomic types and is equivalent to Java's `volatile`.
  41
  42 #![unstable(feature = "core_intrinsics",
  43             reason = "intrinsics are unlikely to ever be stabilized, instead \
  44                       they should be used through stabilized interfaces \
  45                       in the rest of the standard library",
  46             issue = "0")]
  47 #![allow(missing_docs)]
  48
  49 #[cfg(not(stage0))]
  50 #[stable(feature = "drop_in_place", since = "1.8.0")]
  51 #[rustc_deprecated(reason = "no longer an intrinsic - use `ptr::drop_in_place` directly",
  52                    since = "1.18.0")]
  53 pub use ptr::drop_in_place;
  54
  55 extern "rust-intrinsic" {
  56     // NB: These intrinsics take raw pointers because they mutate aliased
  57     // memory, which is not valid for either `&` or `&mut`.
  58
  59     /// Stores a value if the current value is the same as the `old` value.
  60     /// The stabilized version of this intrinsic is available on the
  61     /// `std::sync::atomic` types via the `compare_exchange` method by passing
  62     /// [`Ordering::SeqCst`](../../std/sync/atomic/enum.Ordering.html)
  63     /// as both the `success` and `failure` parameters. For example,
  64     /// [`AtomicBool::compare_exchange`][compare_exchange].
  65     ///
  66     /// [compare_exchange]: ../../std/sync/atomic/struct.AtomicBool.html#method.compare_exchange
  67     pub fn atomic_cxchg<T>(dst: *mut T, old: T, src: T) -> (T, bool);
  68     /// Stores a value if the current value is the same as the `old` value.
  69     /// The stabilized version of this intrinsic is available on the
  70     /// `std::sync::atomic` types via the `compare_exchange` method by passing
  71     /// [`Ordering::Acquire`](../../std/sync/atomic/enum.Ordering.html)
  72     /// as both the `success` and `failure` parameters. For example,
  73     /// [`AtomicBool::compare_exchange`][compare_exchange].
  74     ///
  75     /// [compare_exchange]: ../../std/sync/atomic/struct.AtomicBool.html#method.compare_exchange
  76     pub fn atomic_cxchg_acq<T>(dst: *mut T, old: T, src: T) -> (T, bool);
  77     /// Stores a value if the current value is the same as the `old` value.
  78     /// The stabilized version of this intrinsic is available on the
  79     /// `std::sync::atomic` types via the `compare_exchange` method by passing
  80     /// [`Ordering::Release`](../../std/sync/atomic/enum.Ordering.html)
  81     /// as the `success` and
  82     /// [`Ordering::Relaxed`](../../std/sync/atomic/enum.Ordering.html)
  83     /// as the `failure` parameters. For example,
  84     /// [`AtomicBool::compare_exchange`][compare_exchange].
  85     ///
  86     /// [compare_exchange]: ../../std/sync/atomic/struct.AtomicBool.html#method.compare_exchange
  87     pub fn atomic_cxchg_rel<T>(dst: *mut T, old: T, src: T) -> (T, bool);
  88     /// Stores a value if the current value is the same as the `old` value.
  89     /// The stabilized version of this intrinsic is available on the
  90     /// `std::sync::atomic` types via the `compare_exchange` method by passing
  91     /// [`Ordering::AcqRel`](../../std/sync/atomic/enum.Ordering.html)
  92     /// as the `success` and
  93     /// [`Ordering::Acquire`](../../std/sync/atomic/enum.Ordering.html)
  94     /// as the `failure` parameters. For example,
  95     /// [`AtomicBool::compare_exchange`][compare_exchange].
  96     ///
  97     /// [compare_exchange]: ../../std/sync/atomic/struct.AtomicBool.html#method.compare_exchange
  98     pub fn atomic_cxchg_acqrel<T>(dst: *mut T, old: T, src: T) -> (T, bool);
  99     /// Stores a value if the current value is the same as the `old` value.
 100     /// The stabilized version of this intrinsic is available on the
 101     /// `std::sync::atomic` types via the `compare_exchange` method by passing
 102     /// [`Ordering::Relaxed`](../../std/sync/atomic/enum.Ordering.html)
 103     /// as both the `success` and `failure` parameters. For example,
 104     /// [`AtomicBool::compare_exchange`][compare_exchange].
 105     ///
 106     /// [compare_exchange]: ../../std/sync/atomic/struct.AtomicBool.html#method.compare_exchange
 107     pub fn atomic_cxchg_relaxed<T>(dst: *mut T, old: T, src: T) -> (T, bool);
 108     /// Stores a value if the current value is the same as the `old` value.
 109     /// The stabilized version of this intrinsic is available on the
 110     /// `std::sync::atomic` types via the `compare_exchange` method by passing
 111     /// [`Ordering::SeqCst`](../../std/sync/atomic/enum.Ordering.html)
 112     /// as the `success` and
 113     /// [`Ordering::Relaxed`](../../std/sync/atomic/enum.Ordering.html)
 114     /// as the `failure` parameters. For example,
 115     /// [`AtomicBool::compare_exchange`][compare_exchange].
 116     ///
 117     /// [compare_exchange]: ../../std/sync/atomic/struct.AtomicBool.html#method.compare_exchange
 118     pub fn atomic_cxchg_failrelaxed<T>(dst: *mut T, old: T, src: T) -> (T, bool);
 119     /// Stores a value if the current value is the same as the `old` value.
 120     /// The stabilized version of this intrinsic is available on the
 121     /// `std::sync::atomic` types via the `compare_exchange` method by passing
 122     /// [`Ordering::SeqCst`](../../std/sync/atomic/enum.Ordering.html)
 123     /// as the `success` and
 124     /// [`Ordering::Acquire`](../../std/sync/atomic/enum.Ordering.html)
 125     /// as the `failure` parameters. For example,
 126     /// [`AtomicBool::compare_exchange`][compare_exchange].
 127     ///
 128     /// [compare_exchange]: ../../std/sync/atomic/struct.AtomicBool.html#method.compare_exchange
 129     pub fn atomic_cxchg_failacq<T>(dst: *mut T, old: T, src: T) -> (T, bool);
 130     /// Stores a value if the current value is the same as the `old` value.
 131     /// The stabilized version of this intrinsic is available on the
 132     /// `std::sync::atomic` types via the `compare_exchange` method by passing
 133     /// [`Ordering::Acquire`](../../std/sync/atomic/enum.Ordering.html)
 134     /// as the `success` and
 135     /// [`Ordering::Relaxed`](../../std/sync/atomic/enum.Ordering.html)
 136     /// as the `failure` parameters. For example,
 137     /// [`AtomicBool::compare_exchange`][compare_exchange].
 138     ///
 139     /// [compare_exchange]: ../../std/sync/atomic/struct.AtomicBool.html#method.compare_exchange
 140     pub fn atomic_cxchg_acq_failrelaxed<T>(dst: *mut T, old: T, src: T) -> (T, bool);
 141     /// Stores a value if the current value is the same as the `old` value.
 142     /// The stabilized version of this intrinsic is available on the
 143     /// `std::sync::atomic` types via the `compare_exchange` method by passing
 144     /// [`Ordering::AcqRel`](../../std/sync/atomic/enum.Ordering.html)
 145     /// as the `success` and
 146     /// [`Ordering::Relaxed`](../../std/sync/atomic/enum.Ordering.html)
 147     /// as the `failure` parameters. For example,
 148     /// [`AtomicBool::compare_exchange`][compare_exchange].
 149     ///
 150     /// [compare_exchange]: ../../std/sync/atomic/struct.AtomicBool.html#method.compare_exchange
 151     pub fn atomic_cxchg_acqrel_failrelaxed<T>(dst: *mut T, old: T, src: T) -> (T, bool);
 152
 153     /// Stores a value if the current value is the same as the `old` value.
 154     /// The stabilized version of this intrinsic is available on the
 155     /// `std::sync::atomic` types via the `compare_exchange_weak` method by passing
 156     /// [`Ordering::SeqCst`](../../std/sync/atomic/enum.Ordering.html)
 157     /// as both the `success` and `failure` parameters. For example,
 158     /// [`AtomicBool::compare_exchange_weak`][cew].
 159     ///
 160     /// [cew]: ../../std/sync/atomic/struct.AtomicBool.html#method.compare_exchange_weak
 161     pub fn atomic_cxchgweak<T>(dst: *mut T, old: T, src: T) -> (T, bool);
 162     /// Stores a value if the current value is the same as the `old` value.
 163     /// The stabilized version of this intrinsic is available on the
 164     /// `std::sync::atomic` types via the `compare_exchange_weak` method by passing
 165     /// [`Ordering::Acquire`](../../std/sync/atomic/enum.Ordering.html)
 166     /// as both the `success` and `failure` parameters. For example,
 167     /// [`AtomicBool::compare_exchange_weak`][cew].
 168     ///
 169     /// [cew]: ../../std/sync/atomic/struct.AtomicBool.html#method.compare_exchange_weak
 170     pub fn atomic_cxchgweak_acq<T>(dst: *mut T, old: T, src: T) -> (T, bool);
 171     /// Stores a value if the current value is the same as the `old` value.
 172     /// The stabilized version of this intrinsic is available on the
 173     /// `std::sync::atomic` types via the `compare_exchange_weak` method by passing
 174     /// [`Ordering::Release`](../../std/sync/atomic/enum.Ordering.html)
 175     /// as the `success` and
 176     /// [`Ordering::Relaxed`](../../std/sync/atomic/enum.Ordering.html)
 177     /// as the `failure` parameters. For example,
 178     /// [`AtomicBool::compare_exchange_weak`][cew].
 179     ///
 180     /// [cew]: ../../std/sync/atomic/struct.AtomicBool.html#method.compare_exchange_weak
 181     pub fn atomic_cxchgweak_rel<T>(dst: *mut T, old: T, src: T) -> (T, bool);
 182     /// Stores a value if the current value is the same as the `old` value.
 183     /// The stabilized version of this intrinsic is available on the
 184     /// `std::sync::atomic` types via the `compare_exchange_weak` method by passing
 185     /// [`Ordering::AcqRel`](../../std/sync/atomic/enum.Ordering.html)
 186     /// as the `success` and
 187     /// [`Ordering::Acquire`](../../std/sync/atomic/enum.Ordering.html)
 188     /// as the `failure` parameters. For example,
 189     /// [`AtomicBool::compare_exchange_weak`][cew].
 190     ///
 191     /// [cew]: ../../std/sync/atomic/struct.AtomicBool.html#method.compare_exchange_weak
 192     pub fn atomic_cxchgweak_acqrel<T>(dst: *mut T, old: T, src: T) -> (T, bool);
 193     /// Stores a value if the current value is the same as the `old` value.
 194     /// The stabilized version of this intrinsic is available on the
 195     /// `std::sync::atomic` types via the `compare_exchange_weak` method by passing
 196     /// [`Ordering::Relaxed`](../../std/sync/atomic/enum.Ordering.html)
 197     /// as both the `success` and `failure` parameters. For example,
 198     /// [`AtomicBool::compare_exchange_weak`][cew].
 199     ///
 200     /// [cew]: ../../std/sync/atomic/struct.AtomicBool.html#method.compare_exchange_weak
 201     pub fn atomic_cxchgweak_relaxed<T>(dst: *mut T, old: T, src: T) -> (T, bool);
 202     /// Stores a value if the current value is the same as the `old` value.
 203     /// The stabilized version of this intrinsic is available on the
 204     /// `std::sync::atomic` types via the `compare_exchange_weak` method by passing
 205     /// [`Ordering::SeqCst`](../../std/sync/atomic/enum.Ordering.html)
 206     /// as the `success` and
 207     /// [`Ordering::Relaxed`](../../std/sync/atomic/enum.Ordering.html)
 208     /// as the `failure` parameters. For example,
 209     /// [`AtomicBool::compare_exchange_weak`][cew].
 210     ///
 211     /// [cew]: ../../std/sync/atomic/struct.AtomicBool.html#method.compare_exchange_weak
 212     pub fn atomic_cxchgweak_failrelaxed<T>(dst: *mut T, old: T, src: T) -> (T, bool);
 213     /// Stores a value if the current value is the same as the `old` value.
 214     /// The stabilized version of this intrinsic is available on the
 215     /// `std::sync::atomic` types via the `compare_exchange_weak` method by passing
 216     /// [`Ordering::SeqCst`](../../std/sync/atomic/enum.Ordering.html)
 217     /// as the `success` and
 218     /// [`Ordering::Acquire`](../../std/sync/atomic/enum.Ordering.html)
 219     /// as the `failure` parameters. For example,
 220     /// [`AtomicBool::compare_exchange_weak`][cew].
 221     ///
 222     /// [cew]: ../../std/sync/atomic/struct.AtomicBool.html#method.compare_exchange_weak
 223     pub fn atomic_cxchgweak_failacq<T>(dst: *mut T, old: T, src: T) -> (T, bool);
 224     /// Stores a value if the current value is the same as the `old` value.
 225     /// The stabilized version of this intrinsic is available on the
 226     /// `std::sync::atomic` types via the `compare_exchange_weak` method by passing
 227     /// [`Ordering::Acquire`](../../std/sync/atomic/enum.Ordering.html)
 228     /// as the `success` and
 229     /// [`Ordering::Relaxed`](../../std/sync/atomic/enum.Ordering.html)
 230     /// as the `failure` parameters. For example,
 231     /// [`AtomicBool::compare_exchange_weak`][cew].
 232     ///
 233     /// [cew]: ../../std/sync/atomic/struct.AtomicBool.html#method.compare_exchange_weak
 234     pub fn atomic_cxchgweak_acq_failrelaxed<T>(dst: *mut T, old: T, src: T) -> (T, bool);
 235     /// Stores a value if the current value is the same as the `old` value.
 236     /// The stabilized version of this intrinsic is available on the
 237     /// `std::sync::atomic` types via the `compare_exchange_weak` method by passing
 238     /// [`Ordering::AcqRel`](../../std/sync/atomic/enum.Ordering.html)
 239     /// as the `success` and
 240     /// [`Ordering::Relaxed`](../../std/sync/atomic/enum.Ordering.html)
 241     /// as the `failure` parameters. For example,
 242     /// [`AtomicBool::compare_exchange_weak`][cew].
 243     ///
 244     /// [cew]: ../../std/sync/atomic/struct.AtomicBool.html#method.compare_exchange_weak
 245     pub fn atomic_cxchgweak_acqrel_failrelaxed<T>(dst: *mut T, old: T, src: T) -> (T, bool);
 246
 247     /// Loads the current value of the pointer.
 248     /// The stabilized version of this intrinsic is available on the
 249     /// `std::sync::atomic` types via the `load` method by passing
 250     /// [`Ordering::SeqCst`](../../std/sync/atomic/enum.Ordering.html)
 251     /// as the `order`. For example,
 252     /// [`AtomicBool::load`](../../std/sync/atomic/struct.AtomicBool.html#method.load).
 253     pub fn atomic_load<T>(src: *const T) -> T;
 254     /// Loads the current value of the pointer.
 255     /// The stabilized version of this intrinsic is available on the
 256     /// `std::sync::atomic` types via the `load` method by passing
 257     /// [`Ordering::Acquire`](../../std/sync/atomic/enum.Ordering.html)
 258     /// as the `order`. For example,
 259     /// [`AtomicBool::load`](../../std/sync/atomic/struct.AtomicBool.html#method.load).
 260     pub fn atomic_load_acq<T>(src: *const T) -> T;
 261     /// Loads the current value of the pointer.
 262     /// The stabilized version of this intrinsic is available on the
 263     /// `std::sync::atomic` types via the `load` method by passing
 264     /// [`Ordering::Relaxed`](../../std/sync/atomic/enum.Ordering.html)
 265     /// as the `order`. For example,
 266     /// [`AtomicBool::load`](../../std/sync/atomic/struct.AtomicBool.html#method.load).
 267     pub fn atomic_load_relaxed<T>(src: *const T) -> T;
 268     pub fn atomic_load_unordered<T>(src: *const T) -> T;
 269
 270     /// Stores the value at the specified memory location.
 271     /// The stabilized version of this intrinsic is available on the
 272     /// `std::sync::atomic` types via the `store` method by passing
 273     /// [`Ordering::SeqCst`](../../std/sync/atomic/enum.Ordering.html)
 274     /// as the `order`. For example,
 275     /// [`AtomicBool::store`](../../std/sync/atomic/struct.AtomicBool.html#method.store).
 276     pub fn atomic_store<T>(dst: *mut T, val: T);
 277     /// Stores the value at the specified memory location.
 278     /// The stabilized version of this intrinsic is available on the
 279     /// `std::sync::atomic` types via the `store` method by passing
 280     /// [`Ordering::Release`](../../std/sync/atomic/enum.Ordering.html)
 281     /// as the `order`. For example,
 282     /// [`AtomicBool::store`](../../std/sync/atomic/struct.AtomicBool.html#method.store).
 283     pub fn atomic_store_rel<T>(dst: *mut T, val: T);
 284     /// Stores the value at the specified memory location.
 285     /// The stabilized version of this intrinsic is available on the
 286     /// `std::sync::atomic` types via the `store` method by passing
 287     /// [`Ordering::Relaxed`](../../std/sync/atomic/enum.Ordering.html)
 288     /// as the `order`. For example,
 289     /// [`AtomicBool::store`](../../std/sync/atomic/struct.AtomicBool.html#method.store).
 290     pub fn atomic_store_relaxed<T>(dst: *mut T, val: T);
 291     pub fn atomic_store_unordered<T>(dst: *mut T, val: T);
 292
 293     /// Stores the value at the specified memory location, returning the old value.
 294     /// The stabilized version of this intrinsic is available on the
 295     /// `std::sync::atomic` types via the `swap` method by passing
 296     /// [`Ordering::SeqCst`](../../std/sync/atomic/enum.Ordering.html)
 297     /// as the `order`. For example,
 298     /// [`AtomicBool::swap`](../../std/sync/atomic/struct.AtomicBool.html#method.swap).
 299     pub fn atomic_xchg<T>(dst: *mut T, src: T) -> T;
 300     /// Stores the value at the specified memory location, returning the old value.
 301     /// The stabilized version of this intrinsic is available on the
 302     /// `std::sync::atomic` types via the `swap` method by passing
 303     /// [`Ordering::Acquire`](../../std/sync/atomic/enum.Ordering.html)
 304     /// as the `order`. For example,
 305     /// [`AtomicBool::swap`](../../std/sync/atomic/struct.AtomicBool.html#method.swap).
 306     pub fn atomic_xchg_acq<T>(dst: *mut T, src: T) -> T;
 307     /// Stores the value at the specified memory location, returning the old value.
 308     /// The stabilized version of this intrinsic is available on the
 309     /// `std::sync::atomic` types via the `swap` method by passing
 310     /// [`Ordering::Release`](../../std/sync/atomic/enum.Ordering.html)
 311     /// as the `order`. For example,
 312     /// [`AtomicBool::swap`](../../std/sync/atomic/struct.AtomicBool.html#method.swap).
 313     pub fn atomic_xchg_rel<T>(dst: *mut T, src: T) -> T;
 314     /// Stores the value at the specified memory location, returning the old value.
 315     /// The stabilized version of this intrinsic is available on the
 316     /// `std::sync::atomic` types via the `swap` method by passing
 317     /// [`Ordering::AcqRel`](../../std/sync/atomic/enum.Ordering.html)
 318     /// as the `order`. For example,
 319     /// [`AtomicBool::swap`](../../std/sync/atomic/struct.AtomicBool.html#method.swap).
 320     pub fn atomic_xchg_acqrel<T>(dst: *mut T, src: T) -> T;
 321     /// Stores the value at the specified memory location, returning the old value.
 322     /// The stabilized version of this intrinsic is available on the
 323     /// `std::sync::atomic` types via the `swap` method by passing
 324     /// [`Ordering::Relaxed`](../../std/sync/atomic/enum.Ordering.html)
 325     /// as the `order`. For example,
 326     /// [`AtomicBool::swap`](../../std/sync/atomic/struct.AtomicBool.html#method.swap).
 327     pub fn atomic_xchg_relaxed<T>(dst: *mut T, src: T) -> T;
 328
 329     /// Add to the current value, returning the previous value.
 330     /// The stabilized version of this intrinsic is available on the
 331     /// `std::sync::atomic` types via the `fetch_add` method by passing
 332     /// [`Ordering::SeqCst`](../../std/sync/atomic/enum.Ordering.html)
 333     /// as the `order`. For example,
 334     /// [`AtomicIsize::fetch_add`](../../std/sync/atomic/struct.AtomicIsize.html#method.fetch_add).
 335     pub fn atomic_xadd<T>(dst: *mut T, src: T) -> T;
 336     /// Add to the current value, returning the previous value.
 337     /// The stabilized version of this intrinsic is available on the
 338     /// `std::sync::atomic` types via the `fetch_add` method by passing
 339     /// [`Ordering::Acquire`](../../std/sync/atomic/enum.Ordering.html)
 340     /// as the `order`. For example,
 341     /// [`AtomicIsize::fetch_add`](../../std/sync/atomic/struct.AtomicIsize.html#method.fetch_add).
 342     pub fn atomic_xadd_acq<T>(dst: *mut T, src: T) -> T;
 343     /// Add to the current value, returning the previous value.
 344     /// The stabilized version of this intrinsic is available on the
 345     /// `std::sync::atomic` types via the `fetch_add` method by passing
 346     /// [`Ordering::Release`](../../std/sync/atomic/enum.Ordering.html)
 347     /// as the `order`. For example,
 348     /// [`AtomicIsize::fetch_add`](../../std/sync/atomic/struct.AtomicIsize.html#method.fetch_add).
 349     pub fn atomic_xadd_rel<T>(dst: *mut T, src: T) -> T;
 350     /// Add to the current value, returning the previous value.
 351     /// The stabilized version of this intrinsic is available on the
 352     /// `std::sync::atomic` types via the `fetch_add` method by passing
 353     /// [`Ordering::AcqRel`](../../std/sync/atomic/enum.Ordering.html)
 354     /// as the `order`. For example,
 355     /// [`AtomicIsize::fetch_add`](../../std/sync/atomic/struct.AtomicIsize.html#method.fetch_add).
 356     pub fn atomic_xadd_acqrel<T>(dst: *mut T, src: T) -> T;
 357     /// Add to the current value, returning the previous value.
 358     /// The stabilized version of this intrinsic is available on the
 359     /// `std::sync::atomic` types via the `fetch_add` method by passing
 360     /// [`Ordering::Relaxed`](../../std/sync/atomic/enum.Ordering.html)
 361     /// as the `order`. For example,
 362     /// [`AtomicIsize::fetch_add`](../../std/sync/atomic/struct.AtomicIsize.html#method.fetch_add).
 363     pub fn atomic_xadd_relaxed<T>(dst: *mut T, src: T) -> T;
 364
 365     /// Subtract from the current value, returning the previous value.
 366     /// The stabilized version of this intrinsic is available on the
 367     /// `std::sync::atomic` types via the `fetch_sub` method by passing
 368     /// [`Ordering::SeqCst`](../../std/sync/atomic/enum.Ordering.html)
 369     /// as the `order`. For example,
 370     /// [`AtomicIsize::fetch_sub`](../../std/sync/atomic/struct.AtomicIsize.html#method.fetch_sub).
 371     pub fn atomic_xsub<T>(dst: *mut T, src: T) -> T;
 372     /// Subtract from the current value, returning the previous value.
 373     /// The stabilized version of this intrinsic is available on the
 374     /// `std::sync::atomic` types via the `fetch_sub` method by passing
 375     /// [`Ordering::Acquire`](../../std/sync/atomic/enum.Ordering.html)
 376     /// as the `order`. For example,
 377     /// [`AtomicIsize::fetch_sub`](../../std/sync/atomic/struct.AtomicIsize.html#method.fetch_sub).
 378     pub fn atomic_xsub_acq<T>(dst: *mut T, src: T) -> T;
 379     /// Subtract from the current value, returning the previous value.
 380     /// The stabilized version of this intrinsic is available on the
 381     /// `std::sync::atomic` types via the `fetch_sub` method by passing
 382     /// [`Ordering::Release`](../../std/sync/atomic/enum.Ordering.html)
 383     /// as the `order`. For example,
 384     /// [`AtomicIsize::fetch_sub`](../../std/sync/atomic/struct.AtomicIsize.html#method.fetch_sub).
 385     pub fn atomic_xsub_rel<T>(dst: *mut T, src: T) -> T;
 386     /// Subtract from the current value, returning the previous value.
 387     /// The stabilized version of this intrinsic is available on the
 388     /// `std::sync::atomic` types via the `fetch_sub` method by passing
 389     /// [`Ordering::AcqRel`](../../std/sync/atomic/enum.Ordering.html)
 390     /// as the `order`. For example,
 391     /// [`AtomicIsize::fetch_sub`](../../std/sync/atomic/struct.AtomicIsize.html#method.fetch_sub).
 392     pub fn atomic_xsub_acqrel<T>(dst: *mut T, src: T) -> T;
 393     /// Subtract from the current value, returning the previous value.
 394     /// The stabilized version of this intrinsic is available on the
 395     /// `std::sync::atomic` types via the `fetch_sub` method by passing
 396     /// [`Ordering::Relaxed`](../../std/sync/atomic/enum.Ordering.html)
 397     /// as the `order`. For example,
 398     /// [`AtomicIsize::fetch_sub`](../../std/sync/atomic/struct.AtomicIsize.html#method.fetch_sub).
 399     pub fn atomic_xsub_relaxed<T>(dst: *mut T, src: T) -> T;
 400
 401     /// Bitwise and with the current value, returning the previous value.
 402     /// The stabilized version of this intrinsic is available on the
 403     /// `std::sync::atomic` types via the `fetch_and` method by passing
 404     /// [`Ordering::SeqCst`](../../std/sync/atomic/enum.Ordering.html)
 405     /// as the `order`. For example,
 406     /// [`AtomicBool::fetch_and`](../../std/sync/atomic/struct.AtomicBool.html#method.fetch_and).
 407     pub fn atomic_and<T>(dst: *mut T, src: T) -> T;
 408     /// Bitwise and with the current value, returning the previous value.
 409     /// The stabilized version of this intrinsic is available on the
 410     /// `std::sync::atomic` types via the `fetch_and` method by passing
 411     /// [`Ordering::Acquire`](../../std/sync/atomic/enum.Ordering.html)
 412     /// as the `order`. For example,
 413     /// [`AtomicBool::fetch_and`](../../std/sync/atomic/struct.AtomicBool.html#method.fetch_and).
 414     pub fn atomic_and_acq<T>(dst: *mut T, src: T) -> T;
 415     /// Bitwise and with the current value, returning the previous value.
 416     /// The stabilized version of this intrinsic is available on the
 417     /// `std::sync::atomic` types via the `fetch_and` method by passing
 418     /// [`Ordering::Release`](../../std/sync/atomic/enum.Ordering.html)
 419     /// as the `order`. For example,
 420     /// [`AtomicBool::fetch_and`](../../std/sync/atomic/struct.AtomicBool.html#method.fetch_and).
 421     pub fn atomic_and_rel<T>(dst: *mut T, src: T) -> T;
 422     /// Bitwise and with the current value, returning the previous value.
 423     /// The stabilized version of this intrinsic is available on the
 424     /// `std::sync::atomic` types via the `fetch_and` method by passing
 425     /// [`Ordering::AcqRel`](../../std/sync/atomic/enum.Ordering.html)
 426     /// as the `order`. For example,
 427     /// [`AtomicBool::fetch_and`](../../std/sync/atomic/struct.AtomicBool.html#method.fetch_and).
 428     pub fn atomic_and_acqrel<T>(dst: *mut T, src: T) -> T;
 429     /// Bitwise and with the current value, returning the previous value.
 430     /// The stabilized version of this intrinsic is available on the
 431     /// `std::sync::atomic` types via the `fetch_and` method by passing
 432     /// [`Ordering::Relaxed`](../../std/sync/atomic/enum.Ordering.html)
 433     /// as the `order`. For example,
 434     /// [`AtomicBool::fetch_and`](../../std/sync/atomic/struct.AtomicBool.html#method.fetch_and).
 435     pub fn atomic_and_relaxed<T>(dst: *mut T, src: T) -> T;
 436
 437     /// Bitwise nand with the current value, returning the previous value.
 438     /// The stabilized version of this intrinsic is available on the
 439     /// `std::sync::atomic::AtomicBool` type via the `fetch_nand` method by passing
 440     /// [`Ordering::SeqCst`](../../std/sync/atomic/enum.Ordering.html)
 441     /// as the `order`. For example,
 442     /// [`AtomicBool::fetch_nand`](../../std/sync/atomic/struct.AtomicBool.html#method.fetch_nand).
 443     pub fn atomic_nand<T>(dst: *mut T, src: T) -> T;
 444     /// Bitwise nand with the current value, returning the previous value.
 445     /// The stabilized version of this intrinsic is available on the
 446     /// `std::sync::atomic::AtomicBool` type via the `fetch_nand` method by passing
 447     /// [`Ordering::Acquire`](../../std/sync/atomic/enum.Ordering.html)
 448     /// as the `order`. For example,
 449     /// [`AtomicBool::fetch_nand`](../../std/sync/atomic/struct.AtomicBool.html#method.fetch_nand).
 450     pub fn atomic_nand_acq<T>(dst: *mut T, src: T) -> T;
 451     /// Bitwise nand with the current value, returning the previous value.
 452     /// The stabilized version of this intrinsic is available on the
 453     /// `std::sync::atomic::AtomicBool` type via the `fetch_nand` method by passing
 454     /// [`Ordering::Release`](../../std/sync/atomic/enum.Ordering.html)
 455     /// as the `order`. For example,
 456     /// [`AtomicBool::fetch_nand`](../../std/sync/atomic/struct.AtomicBool.html#method.fetch_nand).
 457     pub fn atomic_nand_rel<T>(dst: *mut T, src: T) -> T;
 458     /// Bitwise nand with the current value, returning the previous value.
 459     /// The stabilized version of this intrinsic is available on the
 460     /// `std::sync::atomic::AtomicBool` type via the `fetch_nand` method by passing
 461     /// [`Ordering::AcqRel`](../../std/sync/atomic/enum.Ordering.html)
 462     /// as the `order`. For example,
 463     /// [`AtomicBool::fetch_nand`](../../std/sync/atomic/struct.AtomicBool.html#method.fetch_nand).
 464     pub fn atomic_nand_acqrel<T>(dst: *mut T, src: T) -> T;
 465     /// Bitwise nand with the current value, returning the previous value.
 466     /// The stabilized version of this intrinsic is available on the
 467     /// `std::sync::atomic::AtomicBool` type via the `fetch_nand` method by passing
 468     /// [`Ordering::Relaxed`](../../std/sync/atomic/enum.Ordering.html)
 469     /// as the `order`. For example,
 470     /// [`AtomicBool::fetch_nand`](../../std/sync/atomic/struct.AtomicBool.html#method.fetch_nand).
 471     pub fn atomic_nand_relaxed<T>(dst: *mut T, src: T) -> T;
 472
 473     /// Bitwise or with the current value, returning the previous value.
 474     /// The stabilized version of this intrinsic is available on the
 475     /// `std::sync::atomic` types via the `fetch_or` method by passing
 476     /// [`Ordering::SeqCst`](../../std/sync/atomic/enum.Ordering.html)
 477     /// as the `order`. For example,
 478     /// [`AtomicBool::fetch_or`](../../std/sync/atomic/struct.AtomicBool.html#method.fetch_or).
 479     pub fn atomic_or<T>(dst: *mut T, src: T) -> T;
 480     /// Bitwise or with the current value, returning the previous value.
 481     /// The stabilized version of this intrinsic is available on the
 482     /// `std::sync::atomic` types via the `fetch_or` method by passing
 483     /// [`Ordering::Acquire`](../../std/sync/atomic/enum.Ordering.html)
 484     /// as the `order`. For example,
 485     /// [`AtomicBool::fetch_or`](../../std/sync/atomic/struct.AtomicBool.html#method.fetch_or).
 486     pub fn atomic_or_acq<T>(dst: *mut T, src: T) -> T;
 487     /// Bitwise or with the current value, returning the previous value.
 488     /// The stabilized version of this intrinsic is available on the
 489     /// `std::sync::atomic` types via the `fetch_or` method by passing
 490     /// [`Ordering::Release`](../../std/sync/atomic/enum.Ordering.html)
 491     /// as the `order`. For example,
 492     /// [`AtomicBool::fetch_or`](../../std/sync/atomic/struct.AtomicBool.html#method.fetch_or).
 493     pub fn atomic_or_rel<T>(dst: *mut T, src: T) -> T;
 494     /// Bitwise or with the current value, returning the previous value.
 495     /// The stabilized version of this intrinsic is available on the
 496     /// `std::sync::atomic` types via the `fetch_or` method by passing
 497     /// [`Ordering::AcqRel`](../../std/sync/atomic/enum.Ordering.html)
 498     /// as the `order`. For example,
 499     /// [`AtomicBool::fetch_or`](../../std/sync/atomic/struct.AtomicBool.html#method.fetch_or).
 500     pub fn atomic_or_acqrel<T>(dst: *mut T, src: T) -> T;
 501     /// Bitwise or with the current value, returning the previous value.
 502     /// The stabilized version of this intrinsic is available on the
 503     /// `std::sync::atomic` types via the `fetch_or` method by passing
 504     /// [`Ordering::Relaxed`](../../std/sync/atomic/enum.Ordering.html)
 505     /// as the `order`. For example,
 506     /// [`AtomicBool::fetch_or`](../../std/sync/atomic/struct.AtomicBool.html#method.fetch_or).
 507     pub fn atomic_or_relaxed<T>(dst: *mut T, src: T) -> T;
 508
 509     /// Bitwise xor with the current value, returning the previous value.
 510     /// The stabilized version of this intrinsic is available on the
 511     /// `std::sync::atomic` types via the `fetch_xor` method by passing
 512     /// [`Ordering::SeqCst`](../../std/sync/atomic/enum.Ordering.html)
 513     /// as the `order`. For example,
 514     /// [`AtomicBool::fetch_xor`](../../std/sync/atomic/struct.AtomicBool.html#method.fetch_xor).
 515     pub fn atomic_xor<T>(dst: *mut T, src: T) -> T;
 516     /// Bitwise xor with the current value, returning the previous value.
 517     /// The stabilized version of this intrinsic is available on the
 518     /// `std::sync::atomic` types via the `fetch_xor` method by passing
 519     /// [`Ordering::Acquire`](../../std/sync/atomic/enum.Ordering.html)
 520     /// as the `order`. For example,
 521     /// [`AtomicBool::fetch_xor`](../../std/sync/atomic/struct.AtomicBool.html#method.fetch_xor).
 522     pub fn atomic_xor_acq<T>(dst: *mut T, src: T) -> T;
 523     /// Bitwise xor with the current value, returning the previous value.
 524     /// The stabilized version of this intrinsic is available on the
 525     /// `std::sync::atomic` types via the `fetch_xor` method by passing
 526     /// [`Ordering::Release`](../../std/sync/atomic/enum.Ordering.html)
 527     /// as the `order`. For example,
 528     /// [`AtomicBool::fetch_xor`](../../std/sync/atomic/struct.AtomicBool.html#method.fetch_xor).
 529     pub fn atomic_xor_rel<T>(dst: *mut T, src: T) -> T;
 530     /// Bitwise xor with the current value, returning the previous value.
 531     /// The stabilized version of this intrinsic is available on the
 532     /// `std::sync::atomic` types via the `fetch_xor` method by passing
 533     /// [`Ordering::AcqRel`](../../std/sync/atomic/enum.Ordering.html)
 534     /// as the `order`. For example,
 535     /// [`AtomicBool::fetch_xor`](../../std/sync/atomic/struct.AtomicBool.html#method.fetch_xor).
 536     pub fn atomic_xor_acqrel<T>(dst: *mut T, src: T) -> T;
 537     /// Bitwise xor with the current value, returning the previous value.
 538     /// The stabilized version of this intrinsic is available on the
 539     /// `std::sync::atomic` types via the `fetch_xor` method by passing
 540     /// [`Ordering::Relaxed`](../../std/sync/atomic/enum.Ordering.html)
 541     /// as the `order`. For example,
 542     /// [`AtomicBool::fetch_xor`](../../std/sync/atomic/struct.AtomicBool.html#method.fetch_xor).
 543     pub fn atomic_xor_relaxed<T>(dst: *mut T, src: T) -> T;
 544
 545     pub fn atomic_max<T>(dst: *mut T, src: T) -> T;
 546     pub fn atomic_max_acq<T>(dst: *mut T, src: T) -> T;
 547     pub fn atomic_max_rel<T>(dst: *mut T, src: T) -> T;
 548     pub fn atomic_max_acqrel<T>(dst: *mut T, src: T) -> T;
 549     pub fn atomic_max_relaxed<T>(dst: *mut T, src: T) -> T;
 550
 551     pub fn atomic_min<T>(dst: *mut T, src: T) -> T;
 552     pub fn atomic_min_acq<T>(dst: *mut T, src: T) -> T;
 553     pub fn atomic_min_rel<T>(dst: *mut T, src: T) -> T;
 554     pub fn atomic_min_acqrel<T>(dst: *mut T, src: T) -> T;
 555     pub fn atomic_min_relaxed<T>(dst: *mut T, src: T) -> T;
 556
 557     pub fn atomic_umin<T>(dst: *mut T, src: T) -> T;
 558     pub fn atomic_umin_acq<T>(dst: *mut T, src: T) -> T;
 559     pub fn atomic_umin_rel<T>(dst: *mut T, src: T) -> T;
 560     pub fn atomic_umin_acqrel<T>(dst: *mut T, src: T) -> T;
 561     pub fn atomic_umin_relaxed<T>(dst: *mut T, src: T) -> T;
 562
 563     pub fn atomic_umax<T>(dst: *mut T, src: T) -> T;
 564     pub fn atomic_umax_acq<T>(dst: *mut T, src: T) -> T;
 565     pub fn atomic_umax_rel<T>(dst: *mut T, src: T) -> T;
 566     pub fn atomic_umax_acqrel<T>(dst: *mut T, src: T) -> T;
 567     pub fn atomic_umax_relaxed<T>(dst: *mut T, src: T) -> T;
 568 }
 569
 570 extern "rust-intrinsic" {
 571
 572     pub fn atomic_fence();
 573     pub fn atomic_fence_acq();
 574     pub fn atomic_fence_rel();
 575     pub fn atomic_fence_acqrel();
 576
 577     /// A compiler-only memory barrier.
 578     ///
 579     /// Memory accesses will never be reordered across this barrier by the
 580     /// compiler, but no instructions will be emitted for it. This is
 581     /// appropriate for operations on the same thread that may be preempted,
 582     /// such as when interacting with signal handlers.
 583     pub fn atomic_singlethreadfence();
 584     pub fn atomic_singlethreadfence_acq();
 585     pub fn atomic_singlethreadfence_rel();
 586     pub fn atomic_singlethreadfence_acqrel();
 587
 588     /// Magic intrinsic that derives its meaning from attributes
 589     /// attached to the function.
 590     ///
 591     /// For example, dataflow uses this to inject static assertions so
 592     /// that `rustc_peek(potentially_uninitialized)` would actually
 593     /// double-check that dataflow did indeed compute that it is
 594     /// uninitialized at that point in the control flow.
 595     pub fn rustc_peek<T>(_: T) -> T;
 596
 597     /// Aborts the execution of the process.
 598     pub fn abort() -> !;
 599
 600     /// Tells LLVM that this point in the code is not reachable,
 601     /// enabling further optimizations.
 602     ///
 603     /// NB: This is very different from the `unreachable!()` macro!
 604     pub fn unreachable() -> !;
 605
 606     /// Informs the optimizer that a condition is always true.
 607     /// If the condition is false, the behavior is undefined.
 608     ///
 609     /// No code is generated for this intrinsic, but the optimizer will try
 610     /// to preserve it (and its condition) between passes, which may interfere
 611     /// with optimization of surrounding code and reduce performance. It should
 612     /// not be used if the invariant can be discovered by the optimizer on its
 613     /// own, or if it does not enable any significant optimizations.
 614     pub fn assume(b: bool);
 615
 616     /// Hints to the compiler that branch condition is likely to be true.
 617     /// Returns the value passed to it.
 618     ///
 619     /// Any use other than with `if` statements will probably not have an effect.
 620     pub fn likely(b: bool) -> bool;
 621
 622     /// Hints to the compiler that branch condition is likely to be false.
 623     /// Returns the value passed to it.
 624     ///
 625     /// Any use other than with `if` statements will probably not have an effect.
 626     pub fn unlikely(b: bool) -> bool;
 627
 628     /// Executes a breakpoint trap, for inspection by a debugger.
 629     pub fn breakpoint();
 630
 631     /// The size of a type in bytes.
 632     ///
 633     /// More specifically, this is the offset in bytes between successive
 634     /// items of the same type, including alignment padding.
 635     pub fn size_of<T>() -> usize;
 636
 637     /// Moves a value to an uninitialized memory location.
 638     ///
 639     /// Drop glue is not run on the destination.
 640     pub fn move_val_init<T>(dst: *mut T, src: T);
 641
 642     pub fn min_align_of<T>() -> usize;
 643     pub fn pref_align_of<T>() -> usize;
 644
 645     pub fn size_of_val<T: ?Sized>(_: &T) -> usize;
 646     pub fn min_align_of_val<T: ?Sized>(_: &T) -> usize;
 647
 648     #[cfg(stage0)]
 649     /// Executes the destructor (if any) of the pointed-to value.
 650     ///
 651     /// This has two use cases:
 652     ///
 653     /// * It is *required* to use `drop_in_place` to drop unsized types like
 654     ///   trait objects, because they can't be read out onto the stack and
 655     ///   dropped normally.
 656     ///
 657     /// * It is friendlier to the optimizer to do this over `ptr::read` when
 658     ///   dropping manually allocated memory (e.g. when writing Box/Rc/Vec),
 659     ///   as the compiler doesn't need to prove that it's sound to elide the
 660     ///   copy.
 661     ///
 662     /// # Undefined Behavior
 663     ///
 664     /// This has all the same safety problems as `ptr::read` with respect to
 665     /// invalid pointers, types, and double drops.
 666     #[stable(feature = "drop_in_place", since = "1.8.0")]
 667     pub fn drop_in_place<T: ?Sized>(to_drop: *mut T);
 668
 669     /// Gets a static string slice containing the name of a type.
 670     pub fn type_name<T: ?Sized>() -> &'static str;
 671
 672     /// Gets an identifier which is globally unique to the specified type. This
 673     /// function will return the same value for a type regardless of whichever
 674     /// crate it is invoked in.
 675     pub fn type_id<T: ?Sized + 'static>() -> u64;
 676
 677     /// Creates a value initialized to zero.
 678     ///
 679     /// `init` is unsafe because it returns a zeroed-out datum,
 680     /// which is unsafe unless T is `Copy`.  Also, even if T is
 681     /// `Copy`, an all-zero value may not correspond to any legitimate
 682     /// state for the type in question.
 683     pub fn init<T>() -> T;
 684
 685     /// Creates an uninitialized value.
 686     ///
 687     /// `uninit` is unsafe because there is no guarantee of what its
 688     /// contents are. In particular its drop-flag may be set to any
 689     /// state, which means it may claim either dropped or
 690     /// undropped. In the general case one must use `ptr::write` to
 691     /// initialize memory previous set to the result of `uninit`.
 692     pub fn uninit<T>() -> T;
 693
 694     /// Moves a value out of scope without running drop glue.
 695     pub fn forget<T>(_: T) -> ();
 696
 697     /// Reinterprets the bits of a value of one type as another type.
 698     ///
 699     /// Both types must have the same size. Neither the original, nor the result,
 700     /// may be an [invalid value](../../nomicon/meet-safe-and-unsafe.html).
 701     ///
 702     /// `transmute` is semantically equivalent to a bitwise move of one type
 703     /// into another. It copies the bits from the source value into the
 704     /// destination value, then forgets the original. It's equivalent to C's
 705     /// `memcpy` under the hood, just like `transmute_copy`.
 706     ///
 707     /// `transmute` is **incredibly** unsafe. There are a vast number of ways to
 708     /// cause [undefined behavior][ub] with this function. `transmute` should be
 709     /// the absolute last resort.
 710     ///
 711     /// The [nomicon](../../nomicon/transmutes.html) has additional
 712     /// documentation.
 713     ///
 714     /// [ub]: ../../reference/behavior-considered-undefined.html
 715     ///
 716     /// # Examples
 717     ///
 718     /// There are a few things that `transmute` is really useful for.
 719     ///
 720     /// Getting the bitpattern of a floating point type (or, more generally,
 721     /// type punning, when `T` and `U` aren't pointers):
 722     ///
 723     /// ```
 724     /// let bitpattern = unsafe {
 725     ///     std::mem::transmute::<f32, u32>(1.0)
 726     /// };
 727     /// assert_eq!(bitpattern, 0x3F800000);
 728     /// ```
 729     ///
 730     /// Turning a pointer into a function pointer. This is *not* portable to
 731     /// machines where function pointers and data pointers have different sizes.
 732     ///
 733     /// ```
 734     /// fn foo() -> i32 {
 735     ///     0
 736     /// }
 737     /// let pointer = foo as *const ();
 738     /// let function = unsafe {
 739     ///     std::mem::transmute::<*const (), fn() -> i32>(pointer)
 740     /// };
 741     /// assert_eq!(function(), 0);
 742     /// ```
 743     ///
 744     /// Extending a lifetime, or shortening an invariant lifetime. This is
 745     /// advanced, very unsafe Rust!
 746     ///
 747     /// ```
 748     /// struct R<'a>(&'a i32);
 749     /// unsafe fn extend_lifetime<'b>(r: R<'b>) -> R<'static> {
 750     ///     std::mem::transmute::<R<'b>, R<'static>>(r)
 751     /// }
 752     ///
 753     /// unsafe fn shorten_invariant_lifetime<'b, 'c>(r: &'b mut R<'static>)
 754     ///                                              -> &'b mut R<'c> {
 755     ///     std::mem::transmute::<&'b mut R<'static>, &'b mut R<'c>>(r)
 756     /// }
 757     /// ```
 758     ///
 759     /// # Alternatives
 760     ///
 761     /// Don't despair: many uses of `transmute` can be achieved through other means.
 762     /// Below are common applications of `transmute` which can be replaced with safer
 763     /// constructs.
 764     ///
 765     /// Turning a pointer into a `usize`:
 766     ///
 767     /// ```
 768     /// let ptr = &0;
 769     /// let ptr_num_transmute = unsafe {
 770     ///     std::mem::transmute::<&i32, usize>(ptr)
 771     /// };
 772     ///
 773     /// // Use an `as` cast instead
 774     /// let ptr_num_cast = ptr as *const i32 as usize;
 775     /// ```
 776     ///
 777     /// Turning a `*mut T` into an `&mut T`:
 778     ///
 779     /// ```
 780     /// let ptr: *mut i32 = &mut 0;
 781     /// let ref_transmuted = unsafe {
 782     ///     std::mem::transmute::<*mut i32, &mut i32>(ptr)
 783     /// };
 784     ///
 785     /// // Use a reborrow instead
 786     /// let ref_casted = unsafe { &mut *ptr };
 787     /// ```
 788     ///
 789     /// Turning an `&mut T` into an `&mut U`:
 790     ///
 791     /// ```
 792     /// let ptr = &mut 0;
 793     /// let val_transmuted = unsafe {
 794     ///     std::mem::transmute::<&mut i32, &mut u32>(ptr)
 795     /// };
 796     ///
 797     /// // Now, put together `as` and reborrowing - note the chaining of `as`
 798     /// // `as` is not transitive
 799     /// let val_casts = unsafe { &mut *(ptr as *mut i32 as *mut u32) };
 800     /// ```
 801     ///
 802     /// Turning an `&str` into an `&[u8]`:
 803     ///
 804     /// ```
 805     /// // this is not a good way to do this.
 806     /// let slice = unsafe { std::mem::transmute::<&str, &[u8]>("Rust") };
 807     /// assert_eq!(slice, &[82, 117, 115, 116]);
 808     ///
 809     /// // You could use `str::as_bytes`
 810     /// let slice = "Rust".as_bytes();
 811     /// assert_eq!(slice, &[82, 117, 115, 116]);
 812     ///
 813     /// // Or, just use a byte string, if you have control over the string
 814     /// // literal
 815     /// assert_eq!(b"Rust", &[82, 117, 115, 116]);
 816     /// ```
 817     ///
 818     /// Turning a `Vec<&T>` into a `Vec<Option<&T>>`:
 819     ///
 820     /// ```
 821     /// let store = [0, 1, 2, 3];
 822     /// let mut v_orig = store.iter().collect::<Vec<&i32>>();
 823     ///
 824     /// // Using transmute: this is Undefined Behavior, and a bad idea.
 825     /// // However, it is no-copy.
 826     /// let v_transmuted = unsafe {
 827     ///     std::mem::transmute::<Vec<&i32>, Vec<Option<&i32>>>(
 828     ///         v_orig.clone())
 829     /// };
 830     ///
 831     /// // This is the suggested, safe way.
 832     /// // It does copy the entire vector, though, into a new array.
 833     /// let v_collected = v_orig.clone()
 834     ///                         .into_iter()
 835     ///                         .map(|r| Some(r))
 836     ///                         .collect::<Vec<Option<&i32>>>();
 837     ///
 838     /// // The no-copy, unsafe way, still using transmute, but not UB.
 839     /// // This is equivalent to the original, but safer, and reuses the
 840     /// // same Vec internals. Therefore the new inner type must have the
 841     /// // exact same size, and the same or lesser alignment, as the old
 842     /// // type. The same caveats exist for this method as transmute, for
 843     /// // the original inner type (`&i32`) to the converted inner type
 844     /// // (`Option<&i32>`), so read the nomicon pages linked above.
 845     /// let v_from_raw = unsafe {
 846     ///     Vec::from_raw_parts(v_orig.as_mut_ptr(),
 847     ///                         v_orig.len(),
 848     ///                         v_orig.capacity())
 849     /// };
 850     /// std::mem::forget(v_orig);
 851     /// ```
 852     ///
 853     /// Implementing `split_at_mut`:
 854     ///
 855     /// ```
 856     /// use std::{slice, mem};
 857     ///
 858     /// // There are multiple ways to do this; and there are multiple problems
 859     /// // with the following, transmute, way.
 860     /// fn split_at_mut_transmute<T>(slice: &mut [T], mid: usize)
 861     ///                              -> (&mut [T], &mut [T]) {
 862     ///     let len = slice.len();
 863     ///     assert!(mid <= len);
 864     ///     unsafe {
 865     ///         let slice2 = mem::transmute::<&mut [T], &mut [T]>(slice);
 866     ///         // first: transmute is not typesafe; all it checks is that T and
 867     ///         // U are of the same size. Second, right here, you have two
 868     ///         // mutable references pointing to the same memory.
 869     ///         (&mut slice[0..mid], &mut slice2[mid..len])
 870     ///     }
 871     /// }
 872     ///
 873     /// // This gets rid of the typesafety problems; `&mut *` will *only* give
 874     /// // you an `&mut T` from an `&mut T` or `*mut T`.
 875     /// fn split_at_mut_casts<T>(slice: &mut [T], mid: usize)
 876     ///                          -> (&mut [T], &mut [T]) {
 877     ///     let len = slice.len();
 878     ///     assert!(mid <= len);
 879     ///     unsafe {
 880     ///         let slice2 = &mut *(slice as *mut [T]);
 881     ///         // however, you still have two mutable references pointing to
 882     ///         // the same memory.
 883     ///         (&mut slice[0..mid], &mut slice2[mid..len])
 884     ///     }
 885     /// }
 886     ///
 887     /// // This is how the standard library does it. This is the best method, if
 888     /// // you need to do something like this
 889     /// fn split_at_stdlib<T>(slice: &mut [T], mid: usize)
 890     ///                       -> (&mut [T], &mut [T]) {
 891     ///     let len = slice.len();
 892     ///     assert!(mid <= len);
 893     ///     unsafe {
 894     ///         let ptr = slice.as_mut_ptr();
 895     ///         // This now has three mutable references pointing at the same
 896     ///         // memory. `slice`, the rvalue ret.0, and the rvalue ret.1.
 897     ///         // `slice` is never used after `let ptr = ...`, and so one can
 898     ///         // treat it as "dead", and therefore, you only have two real
 899     ///         // mutable slices.
 900     ///         (slice::from_raw_parts_mut(ptr, mid),
 901     ///          slice::from_raw_parts_mut(ptr.offset(mid as isize), len - mid))
 902     ///     }
 903     /// }
 904     /// ```
 905     #[stable(feature = "rust1", since = "1.0.0")]
 906     pub fn transmute<T, U>(e: T) -> U;
 907
 908     /// Returns `true` if the actual type given as `T` requires drop
 909     /// glue; returns `false` if the actual type provided for `T`
 910     /// implements `Copy`.
 911     ///
 912     /// If the actual type neither requires drop glue nor implements
 913     /// `Copy`, then may return `true` or `false`.
 914     pub fn needs_drop<T>() -> bool;
 915
 916     /// Calculates the offset from a pointer.
 917     ///
 918     /// This is implemented as an intrinsic to avoid converting to and from an
 919     /// integer, since the conversion would throw away aliasing information.
 920     ///
 921     /// # Safety
 922     ///
 923     /// Both the starting and resulting pointer must be either in bounds or one
 924     /// byte past the end of an allocated object. If either pointer is out of
 925     /// bounds or arithmetic overflow occurs then any further use of the
 926     /// returned value will result in undefined behavior.
 927     pub fn offset<T>(dst: *const T, offset: isize) -> *const T;
 928
 929     /// Calculates the offset from a pointer, potentially wrapping.
 930     ///
 931     /// This is implemented as an intrinsic to avoid converting to and from an
 932     /// integer, since the conversion inhibits certain optimizations.
 933     ///
 934     /// # Safety
 935     ///
 936     /// Unlike the `offset` intrinsic, this intrinsic does not restrict the
 937     /// resulting pointer to point into or one byte past the end of an allocated
 938     /// object, and it wraps with two's complement arithmetic. The resulting
 939     /// value is not necessarily valid to be used to actually access memory.
 940     pub fn arith_offset<T>(dst: *const T, offset: isize) -> *const T;
 941
 942     /// Copies `count * size_of<T>` bytes from `src` to `dst`. The source
 943     /// and destination may *not* overlap.
 944     ///
 945     /// `copy_nonoverlapping` is semantically equivalent to C's `memcpy`.
 946     ///
 947     /// # Safety
 948     ///
 949     /// Beyond requiring that the program must be allowed to access both regions
 950     /// of memory, it is Undefined Behavior for source and destination to
 951     /// overlap. Care must also be taken with the ownership of `src` and
 952     /// `dst`. This method semantically moves the values of `src` into `dst`.
 953     /// However it does not drop the contents of `dst`, or prevent the contents
 954     /// of `src` from being dropped or used.
 955     ///
 956     /// # Examples
 957     ///
 958     /// A safe swap function:
 959     ///
 960     /// ```
 961     /// use std::mem;
 962     /// use std::ptr;
 963     ///
 964     /// # #[allow(dead_code)]
 965     /// fn swap<T>(x: &mut T, y: &mut T) {
 966     ///     unsafe {
 967     ///         // Give ourselves some scratch space to work with
 968     ///         let mut t: T = mem::uninitialized();
 969     ///
 970     ///         // Perform the swap, `&mut` pointers never alias
 971     ///         ptr::copy_nonoverlapping(x, &mut t, 1);
 972     ///         ptr::copy_nonoverlapping(y, x, 1);
 973     ///         ptr::copy_nonoverlapping(&t, y, 1);
 974     ///
 975     ///         // y and t now point to the same thing, but we need to completely forget `tmp`
 976     ///         // because it's no longer relevant.
 977     ///         mem::forget(t);
 978     ///     }
 979     /// }
 980     /// ```
 981     #[stable(feature = "rust1", since = "1.0.0")]
 982     pub fn copy_nonoverlapping<T>(src: *const T, dst: *mut T, count: usize);
 983
 984     /// Copies `count * size_of<T>` bytes from `src` to `dst`. The source
 985     /// and destination may overlap.
 986     ///
 987     /// `copy` is semantically equivalent to C's `memmove`.
 988     ///
 989     /// # Safety
 990     ///
 991     /// Care must be taken with the ownership of `src` and `dst`.
 992     /// This method semantically moves the values of `src` into `dst`.
 993     /// However it does not drop the contents of `dst`, or prevent the contents of `src`
 994     /// from being dropped or used.
 995     ///
 996     /// # Examples
 997     ///
 998     /// Efficiently create a Rust vector from an unsafe buffer:
 999     ///
1000     /// ```
1001     /// use std::ptr;
1002     ///
1003     /// # #[allow(dead_code)]
1004     /// unsafe fn from_buf_raw<T>(ptr: *const T, elts: usize) -> Vec<T> {
1005     ///     let mut dst = Vec::with_capacity(elts);
1006     ///     dst.set_len(elts);
1007     ///     ptr::copy(ptr, dst.as_mut_ptr(), elts);
1008     ///     dst
1009     /// }
1010     /// ```
1011     ///
1012     #[stable(feature = "rust1", since = "1.0.0")]
1013     pub fn copy<T>(src: *const T, dst: *mut T, count: usize);
1014
1015     /// Invokes memset on the specified pointer, setting `count * size_of::<T>()`
1016     /// bytes of memory starting at `dst` to `val`.
1017     ///
1018     /// # Examples
1019     ///
1020     /// ```
1021     /// use std::ptr;
1022     ///
1023     /// let mut vec = vec![0; 4];
1024     /// unsafe {
1025     ///     let vec_ptr = vec.as_mut_ptr();
1026     ///     ptr::write_bytes(vec_ptr, b'a', 2);
1027     /// }
1028     /// assert_eq!(vec, [b'a', b'a', 0, 0]);
1029     /// ```
1030     #[stable(feature = "rust1", since = "1.0.0")]
1031     pub fn write_bytes<T>(dst: *mut T, val: u8, count: usize);
1032
1033     /// Equivalent to the appropriate `llvm.memcpy.p0i8.0i8.*` intrinsic, with
1034     /// a size of `count` * `size_of::<T>()` and an alignment of
1035     /// `min_align_of::<T>()`
1036     ///
1037     /// The volatile parameter is set to `true`, so it will not be optimized out.
1038     pub fn volatile_copy_nonoverlapping_memory<T>(dst: *mut T, src: *const T,
1039                                                   count: usize);
1040     /// Equivalent to the appropriate `llvm.memmove.p0i8.0i8.*` intrinsic, with
1041     /// a size of `count` * `size_of::<T>()` and an alignment of
1042     /// `min_align_of::<T>()`
1043     ///
1044     /// The volatile parameter is set to `true`, so it will not be optimized out.
1045     pub fn volatile_copy_memory<T>(dst: *mut T, src: *const T, count: usize);
1046     /// Equivalent to the appropriate `llvm.memset.p0i8.*` intrinsic, with a
1047     /// size of `count` * `size_of::<T>()` and an alignment of
1048     /// `min_align_of::<T>()`.
1049     ///
1050     /// The volatile parameter is set to `true`, so it will not be optimized out.
1051     pub fn volatile_set_memory<T>(dst: *mut T, val: u8, count: usize);
1052
1053     /// Perform a volatile load from the `src` pointer.
1054     /// The stabilized version of this intrinsic is
1055     /// [`std::ptr::read_volatile`](../../std/ptr/fn.read_volatile.html).
1056     pub fn volatile_load<T>(src: *const T) -> T;
1057     /// Perform a volatile store to the `dst` pointer.
1058     /// The stabilized version of this intrinsic is
1059     /// [`std::ptr::write_volatile`](../../std/ptr/fn.write_volatile.html).
1060     pub fn volatile_store<T>(dst: *mut T, val: T);
1061
1062     /// Returns the square root of an `f32`
1063     pub fn sqrtf32(x: f32) -> f32;
1064     /// Returns the square root of an `f64`
1065     pub fn sqrtf64(x: f64) -> f64;
1066
1067     /// Raises an `f32` to an integer power.
1068     pub fn powif32(a: f32, x: i32) -> f32;
1069     /// Raises an `f64` to an integer power.
1070     pub fn powif64(a: f64, x: i32) -> f64;
1071
1072     /// Returns the sine of an `f32`.
1073     pub fn sinf32(x: f32) -> f32;
1074     /// Returns the sine of an `f64`.
1075     pub fn sinf64(x: f64) -> f64;
1076
1077     /// Returns the cosine of an `f32`.
1078     pub fn cosf32(x: f32) -> f32;
1079     /// Returns the cosine of an `f64`.
1080     pub fn cosf64(x: f64) -> f64;
1081
1082     /// Raises an `f32` to an `f32` power.
1083     pub fn powf32(a: f32, x: f32) -> f32;
1084     /// Raises an `f64` to an `f64` power.
1085     pub fn powf64(a: f64, x: f64) -> f64;
1086
1087     /// Returns the exponential of an `f32`.
1088     pub fn expf32(x: f32) -> f32;
1089     /// Returns the exponential of an `f64`.
1090     pub fn expf64(x: f64) -> f64;
1091
1092     /// Returns 2 raised to the power of an `f32`.
1093     pub fn exp2f32(x: f32) -> f32;
1094     /// Returns 2 raised to the power of an `f64`.
1095     pub fn exp2f64(x: f64) -> f64;
1096
1097     /// Returns the natural logarithm of an `f32`.
1098     pub fn logf32(x: f32) -> f32;
1099     /// Returns the natural logarithm of an `f64`.
1100     pub fn logf64(x: f64) -> f64;
1101
1102     /// Returns the base 10 logarithm of an `f32`.
1103     pub fn log10f32(x: f32) -> f32;
1104     /// Returns the base 10 logarithm of an `f64`.
1105     pub fn log10f64(x: f64) -> f64;
1106
1107     /// Returns the base 2 logarithm of an `f32`.
1108     pub fn log2f32(x: f32) -> f32;
1109     /// Returns the base 2 logarithm of an `f64`.
1110     pub fn log2f64(x: f64) -> f64;
1111
1112     /// Returns `a * b + c` for `f32` values.
1113     pub fn fmaf32(a: f32, b: f32, c: f32) -> f32;
1114     /// Returns `a * b + c` for `f64` values.
1115     pub fn fmaf64(a: f64, b: f64, c: f64) -> f64;
1116
1117     /// Returns the absolute value of an `f32`.
1118     pub fn fabsf32(x: f32) -> f32;
1119     /// Returns the absolute value of an `f64`.
1120     pub fn fabsf64(x: f64) -> f64;
1121
1122     /// Copies the sign from `y` to `x` for `f32` values.
1123     pub fn copysignf32(x: f32, y: f32) -> f32;
1124     /// Copies the sign from `y` to `x` for `f64` values.
1125     pub fn copysignf64(x: f64, y: f64) -> f64;
1126
1127     /// Returns the largest integer less than or equal to an `f32`.
1128     pub fn floorf32(x: f32) -> f32;
1129     /// Returns the largest integer less than or equal to an `f64`.
1130     pub fn floorf64(x: f64) -> f64;
1131
1132     /// Returns the smallest integer greater than or equal to an `f32`.
1133     pub fn ceilf32(x: f32) -> f32;
1134     /// Returns the smallest integer greater than or equal to an `f64`.
1135     pub fn ceilf64(x: f64) -> f64;
1136
1137     /// Returns the integer part of an `f32`.
1138     pub fn truncf32(x: f32) -> f32;
1139     /// Returns the integer part of an `f64`.
1140     pub fn truncf64(x: f64) -> f64;
1141
1142     /// Returns the nearest integer to an `f32`. May raise an inexact floating-point exception
1143     /// if the argument is not an integer.
1144     pub fn rintf32(x: f32) -> f32;
1145     /// Returns the nearest integer to an `f64`. May raise an inexact floating-point exception
1146     /// if the argument is not an integer.
1147     pub fn rintf64(x: f64) -> f64;
1148
1149     /// Returns the nearest integer to an `f32`.
1150     pub fn nearbyintf32(x: f32) -> f32;
1151     /// Returns the nearest integer to an `f64`.
1152     pub fn nearbyintf64(x: f64) -> f64;
1153
1154     /// Returns the nearest integer to an `f32`. Rounds half-way cases away from zero.
1155     pub fn roundf32(x: f32) -> f32;
1156     /// Returns the nearest integer to an `f64`. Rounds half-way cases away from zero.
1157     pub fn roundf64(x: f64) -> f64;
1158
1159     /// Float addition that allows optimizations based on algebraic rules.
1160     /// May assume inputs are finite.
1161     pub fn fadd_fast<T>(a: T, b: T) -> T;
1162
1163     /// Float subtraction that allows optimizations based on algebraic rules.
1164     /// May assume inputs are finite.
1165     pub fn fsub_fast<T>(a: T, b: T) -> T;
1166
1167     /// Float multiplication that allows optimizations based on algebraic rules.
1168     /// May assume inputs are finite.
1169     pub fn fmul_fast<T>(a: T, b: T) -> T;
1170
1171     /// Float division that allows optimizations based on algebraic rules.
1172     /// May assume inputs are finite.
1173     pub fn fdiv_fast<T>(a: T, b: T) -> T;
1174
1175     /// Float remainder that allows optimizations based on algebraic rules.
1176     /// May assume inputs are finite.
1177     pub fn frem_fast<T>(a: T, b: T) -> T;
1178
1179
1180     /// Returns the number of bits set in an integer type `T`
1181     pub fn ctpop<T>(x: T) -> T;
1182
1183     /// Returns the number of leading unset bits (zeroes) in an integer type `T`.
1184     ///
1185     /// # Examples
1186     ///
1187     /// ```
1188     /// #![feature(core_intrinsics)]
1189     ///
1190     /// use std::intrinsics::ctlz;
1191     ///
1192     /// let x = 0b0001_1100_u8;
1193     /// let num_leading = unsafe { ctlz(x) };
1194     /// assert_eq!(num_leading, 3);
1195     /// ```
1196     ///
1197     /// An `x` with value `0` will return the bit width of `T`.
1198     ///
1199     /// ```
1200     /// #![feature(core_intrinsics)]
1201     ///
1202     /// use std::intrinsics::ctlz;
1203     ///
1204     /// let x = 0u16;
1205     /// let num_leading = unsafe { ctlz(x) };
1206     /// assert_eq!(num_leading, 16);
1207     /// ```
1208     pub fn ctlz<T>(x: T) -> T;
1209
1210     /// Returns the number of trailing unset bits (zeroes) in an integer type `T`.
1211     ///
1212     /// # Examples
1213     ///
1214     /// ```
1215     /// #![feature(core_intrinsics)]
1216     ///
1217     /// use std::intrinsics::cttz;
1218     ///
1219     /// let x = 0b0011_1000_u8;
1220     /// let num_trailing = unsafe { cttz(x) };
1221     /// assert_eq!(num_trailing, 3);
1222     /// ```
1223     ///
1224     /// An `x` with value `0` will return the bit width of `T`:
1225     ///
1226     /// ```
1227     /// #![feature(core_intrinsics)]
1228     ///
1229     /// use std::intrinsics::cttz;
1230     ///
1231     /// let x = 0u16;
1232     /// let num_trailing = unsafe { cttz(x) };
1233     /// assert_eq!(num_trailing, 16);
1234     /// ```
1235     pub fn cttz<T>(x: T) -> T;
1236
1237     /// Reverses the bytes in an integer type `T`.
1238     pub fn bswap<T>(x: T) -> T;
1239
1240     /// Performs checked integer addition.
1241     /// The stabilized versions of this intrinsic are available on the integer
1242     /// primitives via the `overflowing_add` method. For example,
1243     /// [`std::u32::overflowing_add`](../../std/primitive.u32.html#method.overflowing_add)
1244     pub fn add_with_overflow<T>(x: T, y: T) -> (T, bool);
1245
1246     /// Performs checked integer subtraction
1247     /// The stabilized versions of this intrinsic are available on the integer
1248     /// primitives via the `overflowing_sub` method. For example,
1249     /// [`std::u32::overflowing_sub`](../../std/primitive.u32.html#method.overflowing_sub)
1250     pub fn sub_with_overflow<T>(x: T, y: T) -> (T, bool);
1251
1252     /// Performs checked integer multiplication
1253     /// The stabilized versions of this intrinsic are available on the integer
1254     /// primitives via the `overflowing_mul` method. For example,
1255     /// [`std::u32::overflowing_mul`](../../std/primitive.u32.html#method.overflowing_mul)
1256     pub fn mul_with_overflow<T>(x: T, y: T) -> (T, bool);
1257
1258     /// Performs an unchecked division, resulting in undefined behavior
1259     /// where y = 0 or x = `T::min_value()` and y = -1
1260     pub fn unchecked_div<T>(x: T, y: T) -> T;
1261     /// Returns the remainder of an unchecked division, resulting in
1262     /// undefined behavior where y = 0 or x = `T::min_value()` and y = -1
1263     pub fn unchecked_rem<T>(x: T, y: T) -> T;
1264
1265     /// Performs an unchecked left shift, resulting in undefined behavior when
1266     /// y < 0 or y >= N, where N is the width of T in bits.
1267     #[cfg(not(stage0))]
1268     pub fn unchecked_shl<T>(x: T, y: T) -> T;
1269     /// Performs an unchecked right shift, resulting in undefined behavior when
1270     /// y < 0 or y >= N, where N is the width of T in bits.
1271     #[cfg(not(stage0))]
1272     pub fn unchecked_shr<T>(x: T, y: T) -> T;
1273
1274     /// Returns (a + b) mod 2<sup>N</sup>, where N is the width of T in bits.
1275     /// The stabilized versions of this intrinsic are available on the integer
1276     /// primitives via the `wrapping_add` method. For example,
1277     /// [`std::u32::wrapping_add`](../../std/primitive.u32.html#method.wrapping_add)
1278     pub fn overflowing_add<T>(a: T, b: T) -> T;
1279     /// Returns (a - b) mod 2<sup>N</sup>, where N is the width of T in bits.
1280     /// The stabilized versions of this intrinsic are available on the integer
1281     /// primitives via the `wrapping_sub` method. For example,
1282     /// [`std::u32::wrapping_sub`](../../std/primitive.u32.html#method.wrapping_sub)
1283     pub fn overflowing_sub<T>(a: T, b: T) -> T;
1284     /// Returns (a * b) mod 2<sup>N</sup>, where N is the width of T in bits.
1285     /// The stabilized versions of this intrinsic are available on the integer
1286     /// primitives via the `wrapping_mul` method. For example,
1287     /// [`std::u32::wrapping_mul`](../../std/primitive.u32.html#method.wrapping_mul)
1288     pub fn overflowing_mul<T>(a: T, b: T) -> T;
1289
1290     /// Returns the value of the discriminant for the variant in 'v',
1291     /// cast to a `u64`; if `T` has no discriminant, returns 0.
1292     pub fn discriminant_value<T>(v: &T) -> u64;
1293
1294     /// Rust's "try catch" construct which invokes the function pointer `f` with
1295     /// the data pointer `data`.
1296     ///
1297     /// The third pointer is a target-specific data pointer which is filled in
1298     /// with the specifics of the exception that occurred. For examples on Unix
1299     /// platforms this is a `*mut *mut T` which is filled in by the compiler and
1300     /// on MSVC it's `*mut [usize; 2]`. For more information see the compiler's
1301     /// source as well as std's catch implementation.
1302     pub fn try(f: fn(*mut u8), data: *mut u8, local_ptr: *mut u8) -> i32;
1303 }