src/liballoc/alloc.rs

   1 //! Memory allocation APIs
   2
   3 #![stable(feature = "alloc_module", since = "1.28.0")]
   4
   5 use core::intrinsics::{min_align_of_val, size_of_val};
   6 use core::ptr::{NonNull, Unique};
   7 use core::usize;
   8
   9 #[stable(feature = "alloc_module", since = "1.28.0")]
  10 #[doc(inline)]
  11 pub use core::alloc::*;
  12
  13 extern "Rust" {
  14     // These are the magic symbols to call the global allocator.  rustc generates
  15     // them from the `#[global_allocator]` attribute if there is one, or uses the
  16     // default implementations in libstd (`__rdl_alloc` etc in `src/libstd/alloc.rs`)
  17     // otherwise.
  18     #[cfg_attr(bootstrap, allocator)]
  19     #[cfg_attr(not(bootstrap), rustc_allocator)]
  20     #[rustc_allocator_nounwind]
  21     fn __rust_alloc(size: usize, align: usize) -> *mut u8;
  22     #[rustc_allocator_nounwind]
  23     fn __rust_dealloc(ptr: *mut u8, size: usize, align: usize);
  24     #[rustc_allocator_nounwind]
  25     fn __rust_realloc(ptr: *mut u8,
  26                       old_size: usize,
  27                       align: usize,
  28                       new_size: usize) -> *mut u8;
  29     #[rustc_allocator_nounwind]
  30     fn __rust_alloc_zeroed(size: usize, align: usize) -> *mut u8;
  31 }
  32
  33 /// The global memory allocator.
  34 ///
  35 /// This type implements the [`Alloc`] trait by forwarding calls
  36 /// to the allocator registered with the `#[global_allocator]` attribute
  37 /// if there is one, or the `std` crate’s default.
  38 ///
  39 /// Note: while this type is unstable, the functionality it provides can be
  40 /// accessed through the [free functions in `alloc`](index.html#functions).
  41 ///
  42 /// [`Alloc`]: trait.Alloc.html
  43 #[unstable(feature = "allocator_api", issue = "32838")]
  44 #[derive(Copy, Clone, Default, Debug)]
  45 pub struct Global;
  46
  47 /// Allocate memory with the global allocator.
  48 ///
  49 /// This function forwards calls to the [`GlobalAlloc::alloc`] method
  50 /// of the allocator registered with the `#[global_allocator]` attribute
  51 /// if there is one, or the `std` crate’s default.
  52 ///
  53 /// This function is expected to be deprecated in favor of the `alloc` method
  54 /// of the [`Global`] type when it and the [`Alloc`] trait become stable.
  55 ///
  56 /// # Safety
  57 ///
  58 /// See [`GlobalAlloc::alloc`].
  59 ///
  60 /// [`Global`]: struct.Global.html
  61 /// [`Alloc`]: trait.Alloc.html
  62 /// [`GlobalAlloc::alloc`]: trait.GlobalAlloc.html#tymethod.alloc
  63 ///
  64 /// # Examples
  65 ///
  66 /// ```
  67 /// use std::alloc::{alloc, dealloc, Layout};
  68 ///
  69 /// unsafe {
  70 ///     let layout = Layout::new::<u16>();
  71 ///     let ptr = alloc(layout);
  72 ///
  73 ///     *(ptr as *mut u16) = 42;
  74 ///     assert_eq!(*(ptr as *mut u16), 42);
  75 ///
  76 ///     dealloc(ptr, layout);
  77 /// }
  78 /// ```
  79 #[stable(feature = "global_alloc", since = "1.28.0")]
  80 #[inline]
  81 pub unsafe fn alloc(layout: Layout) -> *mut u8 {
  82     __rust_alloc(layout.size(), layout.align())
  83 }
  84
  85 /// Deallocate memory with the global allocator.
  86 ///
  87 /// This function forwards calls to the [`GlobalAlloc::dealloc`] method
  88 /// of the allocator registered with the `#[global_allocator]` attribute
  89 /// if there is one, or the `std` crate’s default.
  90 ///
  91 /// This function is expected to be deprecated in favor of the `dealloc` method
  92 /// of the [`Global`] type when it and the [`Alloc`] trait become stable.
  93 ///
  94 /// # Safety
  95 ///
  96 /// See [`GlobalAlloc::dealloc`].
  97 ///
  98 /// [`Global`]: struct.Global.html
  99 /// [`Alloc`]: trait.Alloc.html
 100 /// [`GlobalAlloc::dealloc`]: trait.GlobalAlloc.html#tymethod.dealloc
 101 #[stable(feature = "global_alloc", since = "1.28.0")]
 102 #[inline]
 103 pub unsafe fn dealloc(ptr: *mut u8, layout: Layout) {
 104     __rust_dealloc(ptr, layout.size(), layout.align())
 105 }
 106
 107 /// Reallocate memory with the global allocator.
 108 ///
 109 /// This function forwards calls to the [`GlobalAlloc::realloc`] method
 110 /// of the allocator registered with the `#[global_allocator]` attribute
 111 /// if there is one, or the `std` crate’s default.
 112 ///
 113 /// This function is expected to be deprecated in favor of the `realloc` method
 114 /// of the [`Global`] type when it and the [`Alloc`] trait become stable.
 115 ///
 116 /// # Safety
 117 ///
 118 /// See [`GlobalAlloc::realloc`].
 119 ///
 120 /// [`Global`]: struct.Global.html
 121 /// [`Alloc`]: trait.Alloc.html
 122 /// [`GlobalAlloc::realloc`]: trait.GlobalAlloc.html#method.realloc
 123 #[stable(feature = "global_alloc", since = "1.28.0")]
 124 #[inline]
 125 pub unsafe fn realloc(ptr: *mut u8, layout: Layout, new_size: usize) -> *mut u8 {
 126     __rust_realloc(ptr, layout.size(), layout.align(), new_size)
 127 }
 128
 129 /// Allocate zero-initialized memory with the global allocator.
 130 ///
 131 /// This function forwards calls to the [`GlobalAlloc::alloc_zeroed`] method
 132 /// of the allocator registered with the `#[global_allocator]` attribute
 133 /// if there is one, or the `std` crate’s default.
 134 ///
 135 /// This function is expected to be deprecated in favor of the `alloc_zeroed` method
 136 /// of the [`Global`] type when it and the [`Alloc`] trait become stable.
 137 ///
 138 /// # Safety
 139 ///
 140 /// See [`GlobalAlloc::alloc_zeroed`].
 141 ///
 142 /// [`Global`]: struct.Global.html
 143 /// [`Alloc`]: trait.Alloc.html
 144 /// [`GlobalAlloc::alloc_zeroed`]: trait.GlobalAlloc.html#method.alloc_zeroed
 145 ///
 146 /// # Examples
 147 ///
 148 /// ```
 149 /// use std::alloc::{alloc_zeroed, dealloc, Layout};
 150 ///
 151 /// unsafe {
 152 ///     let layout = Layout::new::<u16>();
 153 ///     let ptr = alloc_zeroed(layout);
 154 ///
 155 ///     assert_eq!(*(ptr as *mut u16), 0);
 156 ///
 157 ///     dealloc(ptr, layout);
 158 /// }
 159 /// ```
 160 #[stable(feature = "global_alloc", since = "1.28.0")]
 161 #[inline]
 162 pub unsafe fn alloc_zeroed(layout: Layout) -> *mut u8 {
 163     __rust_alloc_zeroed(layout.size(), layout.align())
 164 }
 165
 166 #[unstable(feature = "allocator_api", issue = "32838")]
 167 unsafe impl Alloc for Global {
 168     #[inline]
 169     unsafe fn alloc(&mut self, layout: Layout) -> Result<NonNull<u8>, AllocErr> {
 170         NonNull::new(alloc(layout)).ok_or(AllocErr)
 171     }
 172
 173     #[inline]
 174     unsafe fn dealloc(&mut self, ptr: NonNull<u8>, layout: Layout) {
 175         dealloc(ptr.as_ptr(), layout)
 176     }
 177
 178     #[inline]
 179     unsafe fn realloc(&mut self,
 180                       ptr: NonNull<u8>,
 181                       layout: Layout,
 182                       new_size: usize)
 183                       -> Result<NonNull<u8>, AllocErr>
 184     {
 185         NonNull::new(realloc(ptr.as_ptr(), layout, new_size)).ok_or(AllocErr)
 186     }
 187
 188     #[inline]
 189     unsafe fn alloc_zeroed(&mut self, layout: Layout) -> Result<NonNull<u8>, AllocErr> {
 190         NonNull::new(alloc_zeroed(layout)).ok_or(AllocErr)
 191     }
 192 }
 193
 194 /// The allocator for unique pointers.
 195 // This function must not unwind. If it does, MIR codegen will fail.
 196 #[cfg(not(test))]
 197 #[lang = "exchange_malloc"]
 198 #[inline]
 199 unsafe fn exchange_malloc(size: usize, align: usize) -> *mut u8 {
 200     if size == 0 {
 201         align as *mut u8
 202     } else {
 203         let layout = Layout::from_size_align_unchecked(size, align);
 204         let ptr = alloc(layout);
 205         if !ptr.is_null() {
 206             ptr
 207         } else {
 208             handle_alloc_error(layout)
 209         }
 210     }
 211 }
 212
 213 #[cfg_attr(not(test), lang = "box_free")]
 214 #[inline]
 215 pub(crate) unsafe fn box_free<T: ?Sized>(ptr: Unique<T>) {
 216     let ptr = ptr.as_ptr();
 217     let size = size_of_val(&*ptr);
 218     let align = min_align_of_val(&*ptr);
 219     // We do not allocate for Box<T> when T is ZST, so deallocation is also not necessary.
 220     if size != 0 {
 221         let layout = Layout::from_size_align_unchecked(size, align);
 222         dealloc(ptr as *mut u8, layout);
 223     }
 224 }
 225
 226 /// Abort on memory allocation error or failure.
 227 ///
 228 /// Callers of memory allocation APIs wishing to abort computation
 229 /// in response to an allocation error are encouraged to call this function,
 230 /// rather than directly invoking `panic!` or similar.
 231 ///
 232 /// The default behavior of this function is to print a message to standard error
 233 /// and abort the process.
 234 /// It can be replaced with [`set_alloc_error_hook`] and [`take_alloc_error_hook`].
 235 ///
 236 /// [`set_alloc_error_hook`]: ../../std/alloc/fn.set_alloc_error_hook.html
 237 /// [`take_alloc_error_hook`]: ../../std/alloc/fn.take_alloc_error_hook.html
 238 #[stable(feature = "global_alloc", since = "1.28.0")]
 239 #[rustc_allocator_nounwind]
 240 pub fn handle_alloc_error(layout: Layout) -> ! {
 241     #[allow(improper_ctypes)]
 242     extern "Rust" {
 243         #[lang = "oom"]
 244         fn oom_impl(layout: Layout) -> !;
 245     }
 246     unsafe { oom_impl(layout) }
 247 }
 248
 249 #[cfg(test)]
 250 mod tests {
 251     extern crate test;
 252     use test::Bencher;
 253     use crate::boxed::Box;
 254     use crate::alloc::{Global, Alloc, Layout, handle_alloc_error};
 255
 256     #[test]
 257     fn allocate_zeroed() {
 258         unsafe {
 259             let layout = Layout::from_size_align(1024, 1).unwrap();
 260             let ptr = Global.alloc_zeroed(layout.clone())
 261                 .unwrap_or_else(|_| handle_alloc_error(layout));
 262
 263             let mut i = ptr.cast::<u8>().as_ptr();
 264             let end = i.add(layout.size());
 265             while i < end {
 266                 assert_eq!(*i, 0);
 267                 i = i.offset(1);
 268             }
 269             Global.dealloc(ptr, layout);
 270         }
 271     }
 272
 273     #[bench]
 274     #[cfg(not(miri))] // Miri does not support benchmarks
 275     fn alloc_owned_small(b: &mut Bencher) {
 276         b.iter(|| {
 277             let _: Box<_> = box 10;
 278         })
 279     }
 280 }