1 //! Memory allocation APIs
3 #![stable(feature = "alloc_module", since = "1.28.0")]
8 #[stable(feature = "global_alloc", since = "1.28.0")]
9 pub use self::global
::GlobalAlloc
;
10 #[stable(feature = "alloc_layout", since = "1.28.0")]
11 pub use self::layout
::Layout
;
12 #[stable(feature = "alloc_layout", since = "1.28.0")]
15 note
= "Name does not follow std convention, use LayoutError",
16 suggestion
= "LayoutError"
18 #[allow(deprecated, deprecated_in_future)]
19 pub use self::layout
::LayoutErr
;
21 #[stable(feature = "alloc_layout_error", since = "1.50.0")]
22 pub use self::layout
::LayoutError
;
25 use crate::ptr
::{self, NonNull}
;
27 /// The `AllocError` error indicates an allocation failure
28 /// that may be due to resource exhaustion or to
29 /// something wrong when combining the given input arguments with this
31 #[unstable(feature = "allocator_api", issue = "32838")]
32 #[derive(Copy, Clone, PartialEq, Eq, Debug)]
33 pub struct AllocError
;
35 // (we need this for downstream impl of trait Error)
36 #[unstable(feature = "allocator_api", issue = "32838")]
37 impl fmt
::Display
for AllocError
{
38 fn fmt(&self, f
: &mut fmt
::Formatter
<'_
>) -> fmt
::Result
{
39 f
.write_str("memory allocation failed")
43 /// An implementation of `Allocator` can allocate, grow, shrink, and deallocate arbitrary blocks of
44 /// data described via [`Layout`][].
46 /// `Allocator` is designed to be implemented on ZSTs, references, or smart pointers because having
47 /// an allocator like `MyAlloc([u8; N])` cannot be moved, without updating the pointers to the
50 /// Unlike [`GlobalAlloc`][], zero-sized allocations are allowed in `Allocator`. If an underlying
51 /// allocator does not support this (like jemalloc) or return a null pointer (such as
52 /// `libc::malloc`), this must be caught by the implementation.
54 /// ### Currently allocated memory
56 /// Some of the methods require that a memory block be *currently allocated* via an allocator. This
59 /// * the starting address for that memory block was previously returned by [`allocate`], [`grow`], or
62 /// * the memory block has not been subsequently deallocated, where blocks are either deallocated
63 /// directly by being passed to [`deallocate`] or were changed by being passed to [`grow`] or
64 /// [`shrink`] that returns `Ok`. If `grow` or `shrink` have returned `Err`, the passed pointer
67 /// [`allocate`]: Allocator::allocate
68 /// [`grow`]: Allocator::grow
69 /// [`shrink`]: Allocator::shrink
70 /// [`deallocate`]: Allocator::deallocate
72 /// ### Memory fitting
74 /// Some of the methods require that a layout *fit* a memory block. What it means for a layout to
75 /// "fit" a memory block means (or equivalently, for a memory block to "fit" a layout) is that the
76 /// following conditions must hold:
78 /// * The block must be allocated with the same alignment as [`layout.align()`], and
80 /// * The provided [`layout.size()`] must fall in the range `min ..= max`, where:
81 /// - `min` is the size of the layout most recently used to allocate the block, and
82 /// - `max` is the latest actual size returned from [`allocate`], [`grow`], or [`shrink`].
84 /// [`layout.align()`]: Layout::align
85 /// [`layout.size()`]: Layout::size
89 /// * Memory blocks returned from an allocator must point to valid memory and retain their validity
90 /// until the instance and all of its clones are dropped,
92 /// * cloning or moving the allocator must not invalidate memory blocks returned from this
93 /// allocator. A cloned allocator must behave like the same allocator, and
95 /// * any pointer to a memory block which is [*currently allocated*] may be passed to any other
96 /// method of the allocator.
98 /// [*currently allocated*]: #currently-allocated-memory
99 #[unstable(feature = "allocator_api", issue = "32838")]
100 pub unsafe trait Allocator
{
101 /// Attempts to allocate a block of memory.
103 /// On success, returns a [`NonNull<[u8]>`][NonNull] meeting the size and alignment guarantees of `layout`.
105 /// The returned block may have a larger size than specified by `layout.size()`, and may or may
106 /// not have its contents initialized.
110 /// Returning `Err` indicates that either memory is exhausted or `layout` does not meet
111 /// allocator's size or alignment constraints.
113 /// Implementations are encouraged to return `Err` on memory exhaustion rather than panicking or
114 /// aborting, but this is not a strict requirement. (Specifically: it is *legal* to implement
115 /// this trait atop an underlying native allocation library that aborts on memory exhaustion.)
117 /// Clients wishing to abort computation in response to an allocation error are encouraged to
118 /// call the [`handle_alloc_error`] function, rather than directly invoking `panic!` or similar.
120 /// [`handle_alloc_error`]: ../../alloc/alloc/fn.handle_alloc_error.html
121 fn allocate(&self, layout
: Layout
) -> Result
<NonNull
<[u8]>, AllocError
>;
123 /// Behaves like `allocate`, but also ensures that the returned memory is zero-initialized.
127 /// Returning `Err` indicates that either memory is exhausted or `layout` does not meet
128 /// allocator's size or alignment constraints.
130 /// Implementations are encouraged to return `Err` on memory exhaustion rather than panicking or
131 /// aborting, but this is not a strict requirement. (Specifically: it is *legal* to implement
132 /// this trait atop an underlying native allocation library that aborts on memory exhaustion.)
134 /// Clients wishing to abort computation in response to an allocation error are encouraged to
135 /// call the [`handle_alloc_error`] function, rather than directly invoking `panic!` or similar.
137 /// [`handle_alloc_error`]: ../../alloc/alloc/fn.handle_alloc_error.html
138 fn allocate_zeroed(&self, layout
: Layout
) -> Result
<NonNull
<[u8]>, AllocError
> {
139 let ptr
= self.allocate(layout
)?
;
140 // SAFETY: `alloc` returns a valid memory block
141 unsafe { ptr.as_non_null_ptr().as_ptr().write_bytes(0, ptr.len()) }
145 /// Deallocates the memory referenced by `ptr`.
149 /// * `ptr` must denote a block of memory [*currently allocated*] via this allocator, and
150 /// * `layout` must [*fit*] that block of memory.
152 /// [*currently allocated*]: #currently-allocated-memory
153 /// [*fit*]: #memory-fitting
154 unsafe fn deallocate(&self, ptr
: NonNull
<u8>, layout
: Layout
);
156 /// Attempts to extend the memory block.
158 /// Returns a new [`NonNull<[u8]>`][NonNull] containing a pointer and the actual size of the allocated
159 /// memory. The pointer is suitable for holding data described by `new_layout`. To accomplish
160 /// this, the allocator may extend the allocation referenced by `ptr` to fit the new layout.
162 /// If this returns `Ok`, then ownership of the memory block referenced by `ptr` has been
163 /// transferred to this allocator. The memory may or may not have been freed, and should be
164 /// considered unusable.
166 /// If this method returns `Err`, then ownership of the memory block has not been transferred to
167 /// this allocator, and the contents of the memory block are unaltered.
171 /// * `ptr` must denote a block of memory [*currently allocated*] via this allocator.
172 /// * `old_layout` must [*fit*] that block of memory (The `new_layout` argument need not fit it.).
173 /// * `new_layout.size()` must be greater than or equal to `old_layout.size()`.
175 /// Note that `new_layout.align()` need not be the same as `old_layout.align()`.
177 /// [*currently allocated*]: #currently-allocated-memory
178 /// [*fit*]: #memory-fitting
182 /// Returns `Err` if the new layout does not meet the allocator's size and alignment
183 /// constraints of the allocator, or if growing otherwise fails.
185 /// Implementations are encouraged to return `Err` on memory exhaustion rather than panicking or
186 /// aborting, but this is not a strict requirement. (Specifically: it is *legal* to implement
187 /// this trait atop an underlying native allocation library that aborts on memory exhaustion.)
189 /// Clients wishing to abort computation in response to an allocation error are encouraged to
190 /// call the [`handle_alloc_error`] function, rather than directly invoking `panic!` or similar.
192 /// [`handle_alloc_error`]: ../../alloc/alloc/fn.handle_alloc_error.html
198 ) -> Result
<NonNull
<[u8]>, AllocError
> {
200 new_layout
.size() >= old_layout
.size(),
201 "`new_layout.size()` must be greater than or equal to `old_layout.size()`"
204 let new_ptr
= self.allocate(new_layout
)?
;
206 // SAFETY: because `new_layout.size()` must be greater than or equal to
207 // `old_layout.size()`, both the old and new memory allocation are valid for reads and
208 // writes for `old_layout.size()` bytes. Also, because the old allocation wasn't yet
209 // deallocated, it cannot overlap `new_ptr`. Thus, the call to `copy_nonoverlapping` is
210 // safe. The safety contract for `dealloc` must be upheld by the caller.
212 ptr
::copy_nonoverlapping(ptr
.as_ptr(), new_ptr
.as_mut_ptr(), old_layout
.size());
213 self.deallocate(ptr
, old_layout
);
219 /// Behaves like `grow`, but also ensures that the new contents are set to zero before being
222 /// The memory block will contain the following contents after a successful call to
224 /// * Bytes `0..old_layout.size()` are preserved from the original allocation.
225 /// * Bytes `old_layout.size()..old_size` will either be preserved or zeroed, depending on
226 /// the allocator implementation. `old_size` refers to the size of the memory block prior
227 /// to the `grow_zeroed` call, which may be larger than the size that was originally
228 /// requested when it was allocated.
229 /// * Bytes `old_size..new_size` are zeroed. `new_size` refers to the size of the memory
230 /// block returned by the `grow_zeroed` call.
234 /// * `ptr` must denote a block of memory [*currently allocated*] via this allocator.
235 /// * `old_layout` must [*fit*] that block of memory (The `new_layout` argument need not fit it.).
236 /// * `new_layout.size()` must be greater than or equal to `old_layout.size()`.
238 /// Note that `new_layout.align()` need not be the same as `old_layout.align()`.
240 /// [*currently allocated*]: #currently-allocated-memory
241 /// [*fit*]: #memory-fitting
245 /// Returns `Err` if the new layout does not meet the allocator's size and alignment
246 /// constraints of the allocator, or if growing otherwise fails.
248 /// Implementations are encouraged to return `Err` on memory exhaustion rather than panicking or
249 /// aborting, but this is not a strict requirement. (Specifically: it is *legal* to implement
250 /// this trait atop an underlying native allocation library that aborts on memory exhaustion.)
252 /// Clients wishing to abort computation in response to an allocation error are encouraged to
253 /// call the [`handle_alloc_error`] function, rather than directly invoking `panic!` or similar.
255 /// [`handle_alloc_error`]: ../../alloc/alloc/fn.handle_alloc_error.html
256 unsafe fn grow_zeroed(
261 ) -> Result
<NonNull
<[u8]>, AllocError
> {
263 new_layout
.size() >= old_layout
.size(),
264 "`new_layout.size()` must be greater than or equal to `old_layout.size()`"
267 let new_ptr
= self.allocate_zeroed(new_layout
)?
;
269 // SAFETY: because `new_layout.size()` must be greater than or equal to
270 // `old_layout.size()`, both the old and new memory allocation are valid for reads and
271 // writes for `old_layout.size()` bytes. Also, because the old allocation wasn't yet
272 // deallocated, it cannot overlap `new_ptr`. Thus, the call to `copy_nonoverlapping` is
273 // safe. The safety contract for `dealloc` must be upheld by the caller.
275 ptr
::copy_nonoverlapping(ptr
.as_ptr(), new_ptr
.as_mut_ptr(), old_layout
.size());
276 self.deallocate(ptr
, old_layout
);
282 /// Attempts to shrink the memory block.
284 /// Returns a new [`NonNull<[u8]>`][NonNull] containing a pointer and the actual size of the allocated
285 /// memory. The pointer is suitable for holding data described by `new_layout`. To accomplish
286 /// this, the allocator may shrink the allocation referenced by `ptr` to fit the new layout.
288 /// If this returns `Ok`, then ownership of the memory block referenced by `ptr` has been
289 /// transferred to this allocator. The memory may or may not have been freed, and should be
290 /// considered unusable.
292 /// If this method returns `Err`, then ownership of the memory block has not been transferred to
293 /// this allocator, and the contents of the memory block are unaltered.
297 /// * `ptr` must denote a block of memory [*currently allocated*] via this allocator.
298 /// * `old_layout` must [*fit*] that block of memory (The `new_layout` argument need not fit it.).
299 /// * `new_layout.size()` must be smaller than or equal to `old_layout.size()`.
301 /// Note that `new_layout.align()` need not be the same as `old_layout.align()`.
303 /// [*currently allocated*]: #currently-allocated-memory
304 /// [*fit*]: #memory-fitting
308 /// Returns `Err` if the new layout does not meet the allocator's size and alignment
309 /// constraints of the allocator, or if shrinking otherwise fails.
311 /// Implementations are encouraged to return `Err` on memory exhaustion rather than panicking or
312 /// aborting, but this is not a strict requirement. (Specifically: it is *legal* to implement
313 /// this trait atop an underlying native allocation library that aborts on memory exhaustion.)
315 /// Clients wishing to abort computation in response to an allocation error are encouraged to
316 /// call the [`handle_alloc_error`] function, rather than directly invoking `panic!` or similar.
318 /// [`handle_alloc_error`]: ../../alloc/alloc/fn.handle_alloc_error.html
324 ) -> Result
<NonNull
<[u8]>, AllocError
> {
326 new_layout
.size() <= old_layout
.size(),
327 "`new_layout.size()` must be smaller than or equal to `old_layout.size()`"
330 let new_ptr
= self.allocate(new_layout
)?
;
332 // SAFETY: because `new_layout.size()` must be lower than or equal to
333 // `old_layout.size()`, both the old and new memory allocation are valid for reads and
334 // writes for `new_layout.size()` bytes. Also, because the old allocation wasn't yet
335 // deallocated, it cannot overlap `new_ptr`. Thus, the call to `copy_nonoverlapping` is
336 // safe. The safety contract for `dealloc` must be upheld by the caller.
338 ptr
::copy_nonoverlapping(ptr
.as_ptr(), new_ptr
.as_mut_ptr(), new_layout
.size());
339 self.deallocate(ptr
, old_layout
);
345 /// Creates a "by reference" adapter for this instance of `Allocator`.
347 /// The returned adapter also implements `Allocator` and will simply borrow this.
349 fn by_ref(&self) -> &Self
357 #[unstable(feature = "allocator_api", issue = "32838")]
358 unsafe impl<A
> Allocator
for &A
360 A
: Allocator
+ ?Sized
,
363 fn allocate(&self, layout
: Layout
) -> Result
<NonNull
<[u8]>, AllocError
> {
364 (**self).allocate(layout
)
368 fn allocate_zeroed(&self, layout
: Layout
) -> Result
<NonNull
<[u8]>, AllocError
> {
369 (**self).allocate_zeroed(layout
)
373 unsafe fn deallocate(&self, ptr
: NonNull
<u8>, layout
: Layout
) {
374 // SAFETY: the safety contract must be upheld by the caller
375 unsafe { (**self).deallocate(ptr, layout) }
384 ) -> Result
<NonNull
<[u8]>, AllocError
> {
385 // SAFETY: the safety contract must be upheld by the caller
386 unsafe { (**self).grow(ptr, old_layout, new_layout) }
390 unsafe fn grow_zeroed(
395 ) -> Result
<NonNull
<[u8]>, AllocError
> {
396 // SAFETY: the safety contract must be upheld by the caller
397 unsafe { (**self).grow_zeroed(ptr, old_layout, new_layout) }
406 ) -> Result
<NonNull
<[u8]>, AllocError
> {
407 // SAFETY: the safety contract must be upheld by the caller
408 unsafe { (**self).shrink(ptr, old_layout, new_layout) }