Trait std::heap::Alloc [−] [src]

pub unsafe trait Alloc {
    unsafe fn alloc(&mut self, layout: Layout) -> Result<*mut u8, AllocErr>;

    unsafe fn dealloc(&mut self, ptr: *mut u8, layout: Layout);

    fn oom(&mut self, AllocErr) -> ! { ... }

    fn usable_size(&self, layout: &Layout) -> (usize, usize) { ... }

    unsafe fn realloc(
        &mut self, 
        ptr: *mut u8, 
        layout: Layout, 
        new_layout: Layout
    ) -> Result<*mut u8, AllocErr> { ... }

    unsafe fn alloc_zeroed(
        &mut self, 
        layout: Layout
    ) -> Result<*mut u8, AllocErr> { ... }

    unsafe fn alloc_excess(
        &mut self, 
        layout: Layout
    ) -> Result<Excess, AllocErr> { ... }

    unsafe fn realloc_excess(
        &mut self, 
        ptr: *mut u8, 
        layout: Layout, 
        new_layout: Layout
    ) -> Result<Excess, AllocErr> { ... }

    unsafe fn grow_in_place(
        &mut self, 
        ptr: *mut u8, 
        layout: Layout, 
        new_layout: Layout
    ) -> Result<(), CannotReallocInPlace> { ... }

    unsafe fn shrink_in_place(
        &mut self, 
        ptr: *mut u8, 
        layout: Layout, 
        new_layout: Layout
    ) -> Result<(), CannotReallocInPlace> { ... }

    fn alloc_one<T>(&mut self) -> Result<NonNull<T>, AllocErr> { ... }

    unsafe fn dealloc_one<T>(&mut self, ptr: NonNull<T>) { ... }

    fn alloc_array<T>(&mut self, n: usize) -> Result<NonNull<T>, AllocErr> { ... }

    unsafe fn realloc_array<T>(
        &mut self, 
        ptr: NonNull<T>, 
        n_old: usize, 
        n_new: usize
    ) -> Result<NonNull<T>, AllocErr> { ... }

    unsafe fn dealloc_array<T>(
        &mut self, 
        ptr: NonNull<T>, 
        n: usize
    ) -> Result<(), AllocErr> { ... }
}
🔬 This is a nightly-only experimental API. (allocator_api #32838)

the precise API and guarantees it provides may be tweaked slightly, especially to possibly take into account the types being stored to make room for a future tracing garbage collector

An implementation of Alloc can allocate, reallocate, and deallocate arbitrary blocks of data described via Layout.

Some of the methods require that a memory block be currently allocated via an allocator. This means that:

A note regarding zero-sized types and zero-sized layouts: many methods in the Alloc trait state that allocation requests must be non-zero size, or else undefined behavior can result.

Some of the methods require that a layout fit a memory block. What it means for a layout to "fit" a memory block means (or equivalently, for a memory block to "fit" a layout) is that the following two conditions must hold:

  1. The block's starting address must be aligned to layout.align().

  2. The block's size must fall in the range [use_min, use_max], where:

    • use_min is self.usable_size(layout).0, and

    • use_max is the capacity that was (or would have been) returned when (if) the block was allocated via a call to alloc_excess or realloc_excess.

Note that:

Unsafety

The Alloc trait is an unsafe trait for a number of reasons, and implementors must ensure that they adhere to these contracts:

Note that this list may get tweaked over time as clarifications are made in the future. Additionally global allocators may gain unique requirements for how to safely implement one in the future as well.

Required Methods

🔬 This is a nightly-only experimental API. (allocator_api #32838)

the precise API and guarantees it provides may be tweaked slightly, especially to possibly take into account the types being stored to make room for a future tracing garbage collector

Returns a pointer meeting the size and alignment guarantees of layout.

If this method returns an Ok(addr), then the addr returned will be non-null address pointing to a block of storage suitable for holding an instance of layout.

The returned block of storage may or may not have its contents initialized. (Extension subtraits might restrict this behavior, e.g. to ensure initialization to particular sets of bit patterns.)

Safety

This function is unsafe because undefined behavior can result if the caller does not ensure that layout has non-zero size.

(Extension subtraits might provide more specific bounds on behavior, e.g. guarantee a sentinel address or a null pointer in response to a zero-size allocation request.)

Errors

Returning Err indicates that either memory is exhausted or layout does not meet allocator's size or alignment constraints.

Implementations are encouraged to return Err on memory exhaustion rather than panicking or aborting, but this is not a strict requirement. (Specifically: it is legal to implement this trait atop an underlying native allocation library that aborts on memory exhaustion.)

Clients wishing to abort computation in response to an allocation error are encouraged to call the allocator's oom method, rather than directly invoking panic! or similar.

🔬 This is a nightly-only experimental API. (allocator_api #32838)

the precise API and guarantees it provides may be tweaked slightly, especially to possibly take into account the types being stored to make room for a future tracing garbage collector

Deallocate the memory referenced by ptr.

Safety

This function is unsafe because undefined behavior can result if the caller does not ensure all of the following:

  • ptr must denote a block of memory currently allocated via this allocator,

  • layout must fit that block of memory,

  • In addition to fitting the block of memory layout, the alignment of the layout must match the alignment used to allocate that block of memory.

Provided Methods

🔬 This is a nightly-only experimental API. (allocator_api #32838)

the precise API and guarantees it provides may be tweaked slightly, especially to possibly take into account the types being stored to make room for a future tracing garbage collector

Allocator-specific method for signaling an out-of-memory condition.

oom aborts the thread or process, optionally performing cleanup or logging diagnostic information before panicking or aborting.

oom is meant to be used by clients unable to cope with an unsatisfied allocation request (signaled by an error such as AllocErr::Exhausted), and wish to abandon computation rather than attempt to recover locally. Such clients should pass the signaling error value back into oom, where the allocator may incorporate that error value into its diagnostic report before aborting.

Implementations of the oom method are discouraged from infinitely regressing in nested calls to oom. In practice this means implementors should eschew allocating, especially from self (directly or indirectly).

Implementations of the allocation and reallocation methods (e.g. alloc, alloc_one, realloc) are discouraged from panicking (or aborting) in the event of memory exhaustion; instead they should return an appropriate error from the invoked method, and let the client decide whether to invoke this oom method in response.

🔬 This is a nightly-only experimental API. (allocator_api #32838)

the precise API and guarantees it provides may be tweaked slightly, especially to possibly take into account the types being stored to make room for a future tracing garbage collector

Returns bounds on the guaranteed usable size of a successful allocation created with the specified layout.

In particular, if one has a memory block allocated via a given allocator a and layout k where a.usable_size(k) returns (l, u), then one can pass that block to a.dealloc() with a layout in the size range [l, u].

(All implementors of usable_size must ensure that l <= k.size() <= u)

Both the lower- and upper-bounds (l and u respectively) are provided, because an allocator based on size classes could misbehave if one attempts to deallocate a block without providing a correct value for its size (i.e., one within the range [l, u]).

Clients who wish to make use of excess capacity are encouraged to use the alloc_excess and realloc_excess instead, as this method is constrained to report conservative values that serve as valid bounds for all possible allocation method calls.

However, for clients that do not wish to track the capacity returned by alloc_excess locally, this method is likely to produce useful results.

🔬 This is a nightly-only experimental API. (allocator_api #32838)

the precise API and guarantees it provides may be tweaked slightly, especially to possibly take into account the types being stored to make room for a future tracing garbage collector

Returns a pointer suitable for holding data described by new_layout, meeting its size and alignment guarantees. To accomplish this, this may extend or shrink the allocation referenced by ptr to fit new_layout.

If this returns Ok, then ownership of the memory block referenced by ptr has been transferred to this allocator. The memory may or may not have been freed, and should be considered unusable (unless of course it was transferred back to the caller again via the return value of this method).

If this method returns Err, then ownership of the memory block has not been transferred to this allocator, and the contents of the memory block are unaltered.

For best results, new_layout should not impose a different alignment constraint than layout. (In other words, new_layout.align() should equal layout.align().) However, behavior is well-defined (though underspecified) when this constraint is violated; further discussion below.

Safety

This function is unsafe because undefined behavior can result if the caller does not ensure all of the following:

  • ptr must be currently allocated via this allocator,

  • layout must fit the ptr (see above). (The new_layout argument need not fit it.)

  • new_layout must have size greater than zero.

  • the alignment of new_layout is non-zero.

(Extension subtraits might provide more specific bounds on behavior, e.g. guarantee a sentinel address or a null pointer in response to a zero-size allocation request.)

Errors

Returns Err only if new_layout does not match the alignment of layout, or does not meet the allocator's size and alignment constraints of the allocator, or if reallocation otherwise fails.

(Note the previous sentence did not say "if and only if" -- in particular, an implementation of this method can return Ok if new_layout.align() != old_layout.align(); or it can return Err in that scenario, depending on whether this allocator can dynamically adjust the alignment constraint for the block.)

Implementations are encouraged to return Err on memory exhaustion rather than panicking or aborting, but this is not a strict requirement. (Specifically: it is legal to implement this trait atop an underlying native allocation library that aborts on memory exhaustion.)

Clients wishing to abort computation in response to an reallocation error are encouraged to call the allocator's oom method, rather than directly invoking panic! or similar.

🔬 This is a nightly-only experimental API. (allocator_api #32838)

the precise API and guarantees it provides may be tweaked slightly, especially to possibly take into account the types being stored to make room for a future tracing garbage collector

Behaves like alloc, but also ensures that the contents are set to zero before being returned.

Safety

This function is unsafe for the same reasons that alloc is.

Errors

Returning Err indicates that either memory is exhausted or layout does not meet allocator's size or alignment constraints, just as in alloc.

Clients wishing to abort computation in response to an allocation error are encouraged to call the allocator's oom method, rather than directly invoking panic! or similar.

🔬 This is a nightly-only experimental API. (allocator_api #32838)

the precise API and guarantees it provides may be tweaked slightly, especially to possibly take into account the types being stored to make room for a future tracing garbage collector

Behaves like alloc, but also returns the whole size of the returned block. For some layout inputs, like arrays, this may include extra storage usable for additional data.

Safety

This function is unsafe for the same reasons that alloc is.

Errors

Returning Err indicates that either memory is exhausted or layout does not meet allocator's size or alignment constraints, just as in alloc.

Clients wishing to abort computation in response to an allocation error are encouraged to call the allocator's oom method, rather than directly invoking panic! or similar.

🔬 This is a nightly-only experimental API. (allocator_api #32838)

the precise API and guarantees it provides may be tweaked slightly, especially to possibly take into account the types being stored to make room for a future tracing garbage collector

Behaves like realloc, but also returns the whole size of the returned block. For some layout inputs, like arrays, this may include extra storage usable for additional data.

Safety

This function is unsafe for the same reasons that realloc is.

Errors

Returning Err indicates that either memory is exhausted or layout does not meet allocator's size or alignment constraints, just as in realloc.

Clients wishing to abort computation in response to an reallocation error are encouraged to call the allocator's oom method, rather than directly invoking panic! or similar.

🔬 This is a nightly-only experimental API. (allocator_api #32838)

the precise API and guarantees it provides may be tweaked slightly, especially to possibly take into account the types being stored to make room for a future tracing garbage collector

Attempts to extend the allocation referenced by ptr to fit new_layout.

If this returns Ok, then the allocator has asserted that the memory block referenced by ptr now fits new_layout, and thus can be used to carry data of that layout. (The allocator is allowed to expend effort to accomplish this, such as extending the memory block to include successor blocks, or virtual memory tricks.)

Regardless of what this method returns, ownership of the memory block referenced by ptr has not been transferred, and the contents of the memory block are unaltered.

Safety

This function is unsafe because undefined behavior can result if the caller does not ensure all of the following:

  • ptr must be currently allocated via this allocator,

  • layout must fit the ptr (see above); note the new_layout argument need not fit it,

  • new_layout.size() must not be less than layout.size(),

  • new_layout.align() must equal layout.align().

Errors

Returns Err(CannotReallocInPlace) when the allocator is unable to assert that the memory block referenced by ptr could fit layout.

Note that one cannot pass CannotReallocInPlace to the oom method; clients are expected either to be able to recover from grow_in_place failures without aborting, or to fall back on another reallocation method before resorting to an abort.

🔬 This is a nightly-only experimental API. (allocator_api #32838)

the precise API and guarantees it provides may be tweaked slightly, especially to possibly take into account the types being stored to make room for a future tracing garbage collector

Attempts to shrink the allocation referenced by ptr to fit new_layout.

If this returns Ok, then the allocator has asserted that the memory block referenced by ptr now fits new_layout, and thus can only be used to carry data of that smaller layout. (The allocator is allowed to take advantage of this, carving off portions of the block for reuse elsewhere.) The truncated contents of the block within the smaller layout are unaltered, and ownership of block has not been transferred.

If this returns Err, then the memory block is considered to still represent the original (larger) layout. None of the block has been carved off for reuse elsewhere, ownership of the memory block has not been transferred, and the contents of the memory block are unaltered.

Safety

This function is unsafe because undefined behavior can result if the caller does not ensure all of the following:

  • ptr must be currently allocated via this allocator,

  • layout must fit the ptr (see above); note the new_layout argument need not fit it,

  • new_layout.size() must not be greater than layout.size() (and must be greater than zero),

  • new_layout.align() must equal layout.align().

Errors

Returns Err(CannotReallocInPlace) when the allocator is unable to assert that the memory block referenced by ptr could fit layout.

Note that one cannot pass CannotReallocInPlace to the oom method; clients are expected either to be able to recover from shrink_in_place failures without aborting, or to fall back on another reallocation method before resorting to an abort.

🔬 This is a nightly-only experimental API. (allocator_api #32838)

the precise API and guarantees it provides may be tweaked slightly, especially to possibly take into account the types being stored to make room for a future tracing garbage collector

Allocates a block suitable for holding an instance of T.

Captures a common usage pattern for allocators.

The returned block is suitable for passing to the alloc/realloc methods of this allocator.

Note to implementors: If this returns Ok(ptr), then ptr must be considered "currently allocated" and must be acceptable input to methods such as realloc or dealloc, even if T is a zero-sized type. In other words, if your Alloc implementation overrides this method in a manner that can return a zero-sized ptr, then all reallocation and deallocation methods need to be similarly overridden to accept such values as input.

Errors

Returning Err indicates that either memory is exhausted or T does not meet allocator's size or alignment constraints.

For zero-sized T, may return either of Ok or Err, but will not yield undefined behavior.

Clients wishing to abort computation in response to an allocation error are encouraged to call the allocator's oom method, rather than directly invoking panic! or similar.

🔬 This is a nightly-only experimental API. (allocator_api #32838)

the precise API and guarantees it provides may be tweaked slightly, especially to possibly take into account the types being stored to make room for a future tracing garbage collector

Deallocates a block suitable for holding an instance of T.

The given block must have been produced by this allocator, and must be suitable for storing a T (in terms of alignment as well as minimum and maximum size); otherwise yields undefined behavior.

Captures a common usage pattern for allocators.

Safety

This function is unsafe because undefined behavior can result if the caller does not ensure both:

  • ptr must denote a block of memory currently allocated via this allocator

  • the layout of T must fit that block of memory.

🔬 This is a nightly-only experimental API. (allocator_api #32838)

the precise API and guarantees it provides may be tweaked slightly, especially to possibly take into account the types being stored to make room for a future tracing garbage collector

Allocates a block suitable for holding n instances of T.

Captures a common usage pattern for allocators.

The returned block is suitable for passing to the alloc/realloc methods of this allocator.

Note to implementors: If this returns Ok(ptr), then ptr must be considered "currently allocated" and must be acceptable input to methods such as realloc or dealloc, even if T is a zero-sized type. In other words, if your Alloc implementation overrides this method in a manner that can return a zero-sized ptr, then all reallocation and deallocation methods need to be similarly overridden to accept such values as input.

Errors

Returning Err indicates that either memory is exhausted or [T; n] does not meet allocator's size or alignment constraints.

For zero-sized T or n == 0, may return either of Ok or Err, but will not yield undefined behavior.

Always returns Err on arithmetic overflow.

Clients wishing to abort computation in response to an allocation error are encouraged to call the allocator's oom method, rather than directly invoking panic! or similar.

🔬 This is a nightly-only experimental API. (allocator_api #32838)

the precise API and guarantees it provides may be tweaked slightly, especially to possibly take into account the types being stored to make room for a future tracing garbage collector

Reallocates a block previously suitable for holding n_old instances of T, returning a block suitable for holding n_new instances of T.

Captures a common usage pattern for allocators.

The returned block is suitable for passing to the alloc/realloc methods of this allocator.

Safety

This function is unsafe because undefined behavior can result if the caller does not ensure all of the following:

  • ptr must be currently allocated via this allocator,

  • the layout of [T; n_old] must fit that block of memory.

Errors

Returning Err indicates that either memory is exhausted or [T; n_new] does not meet allocator's size or alignment constraints.

For zero-sized T or n_new == 0, may return either of Ok or Err, but will not yield undefined behavior.

Always returns Err on arithmetic overflow.

Clients wishing to abort computation in response to an reallocation error are encouraged to call the allocator's oom method, rather than directly invoking panic! or similar.

🔬 This is a nightly-only experimental API. (allocator_api #32838)

the precise API and guarantees it provides may be tweaked slightly, especially to possibly take into account the types being stored to make room for a future tracing garbage collector

Deallocates a block suitable for holding n instances of T.

Captures a common usage pattern for allocators.

Safety

This function is unsafe because undefined behavior can result if the caller does not ensure both:

  • ptr must denote a block of memory currently allocated via this allocator

  • the layout of [T; n] must fit that block of memory.

Errors

Returning Err indicates that either [T; n] or the given memory block does not meet allocator's size or alignment constraints.

Always returns Err on arithmetic overflow.

Implementors