Trait heresy::alloc::Allocator

source · [−]
pub unsafe trait Allocator {
    fn allocate(&self, layout: Layout) -> Result<NonNull<[u8]>, AllocError>;
    unsafe fn deallocate(&self, ptr: NonNull<u8>, layout: Layout);

    fn allocate_zeroed(
        &self,
        layout: Layout
    ) -> Result<NonNull<[u8]>, AllocError> { ... }
    unsafe fn grow(
        &self,
        ptr: NonNull<u8>,
        old_layout: Layout,
        new_layout: Layout
    ) -> Result<NonNull<[u8]>, AllocError> { ... }
    unsafe fn grow_zeroed(
        &self,
        ptr: NonNull<u8>,
        old_layout: Layout,
        new_layout: Layout
    ) -> Result<NonNull<[u8]>, AllocError> { ... }
    unsafe fn grow_in_place(
        &self,
        ptr: NonNull<u8>,
        old_layout: Layout,
        new_layout: Layout
    ) -> Result<NonNull<[u8]>, AllocError> { ... }
    unsafe fn grow_zeroed_in_place(
        &self,
        ptr: NonNull<u8>,
        old_layout: Layout,
        new_layout: Layout
    ) -> Result<NonNull<[u8]>, AllocError> { ... }
    unsafe fn shrink(
        &self,
        ptr: NonNull<u8>,
        old_layout: Layout,
        new_layout: Layout
    ) -> Result<NonNull<[u8]>, AllocError> { ... }
    unsafe fn shrink_in_place(
        &self,
        ptr: NonNull<u8>,
        old_layout: Layout,
        new_layout: Layout
    ) -> Result<NonNull<[u8]>, AllocError> { ... }
}
Expand description

An implementation of Allocator can allocate, grow, shrink, and deallocate arbitrary blocks of data described via Layout.

Safety

Memory blocks returned from an allocator must point to valid memory and retain their validity until the block is deallocated, or the allocator is dropped or rendered inaccessible, whichever comes first.

Required Methods

Attempts to allocate a block of memory.

On success, returns a NonNull<[u8]> meeting the size and alignment guarantees of layout.

The returned block may have a larger size than specified by layout.size(), and may or may not have its contents initialized.

Errors

Returning Err indicates that either memory is exhausted or layout does not meet an 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 handle_alloc_error function, rather than directly invoking panic! or similar.

Deallocates the memory referenced by ptr.

Safety
  • ptr must denote a block of memory currently allocated via this allocator.
  • layout must fit that block of memory.

Provided Methods

Behaves like allocate, but also ensures that the returned memory is zero-initialized.

Errors

See allocate for errors.

Attempts to extend the memory block.

Returns a new NonNull<[u8]> containing a pointer and the actual size of the allocated memory. The pointer is suitable for holding data described by new_layout. To accomplish this, the allocator may extend the allocation referenced by ptr to fit the 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 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.

Safety
  • ptr must denote a block of memory currently allocated via this allocator.
  • old_layout must fit that block of memory (the new_layout argument need not fit it).
  • new_layout.size() must be greater than or equal to old_layout.size().
Errors

Returns Err if the new layout does not meet the allocator’s size and alignment constraints, or if growing otherwise fails.

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 handle_alloc_error function, rather than directly invoking panic! or similar.

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

The memory block will contain the following contents after a successful call to grow_zeroed:

  • Bytes 0..old_layout.size() are preserved from the original allocation.
  • Bytes old_layout.size()..old_size will either be preserved or zeroed, depending on the allocator implementation. old_size refers to the size of the memory block prior to the grow_zeroed call, which may be larger than the size that was originally requested when it was allocated.
  • Bytes old_size..new_size are zeroed. new_size refers to the size of the memory block returned by the grow_zeroed call.
Safety
  • ptr must denote a block of memory currently allocated via this allocator.
  • old_layout must fit that block of memory (the new_layout argument need not fit it).
  • new_layout.size() must be greater than or equal to old_layout.align().
Errors

Returns Err if the new layout does not meet the allocator’s size and alignment constraints, or if growing otherwise fails.

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 handle_alloc_error function, rather than directly invoking panic! or similar.

Behaves like grow but returns Err if the memory block cannot be grown in-place.

Safety
  • ptr must denote a block of memory currently allocated via this allocator.
  • old_layout must fit that block of memory (the new_layout argument need not fit it).
  • new_layout.size() must be greater than or equal to old_layout.size().
Errors

Returns Err if the new layout does not meet the allocator’s size and alignment constraints, or if growing in place otherwise fails.

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 handle_alloc_error function, rather than directly invoking panic! or similar.

Behaves like grow_zeroed but returns Err if the memory block cannot be grown in-place.

Safety
  • ptr must denote a block of memory currently allocated via this allocator.
  • old_layout must fit that block of memory (the new_layout argument need not fit it).
  • new_layout.size() must be greater than or equal to old_layout.size().
Errors

Returns Err if the new layout does not meet the allocator’s size and alignment constraints, or if growing in place otherwise fails.

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 handle_alloc_error function, rather than directly invoking panic! or similar.

Attempts to shrink the memory block.

Returns a new NonNull<[u8]> containing a pointer and the actual size of the allocated memory. The pointer is suitable for holding data described by new_layout. To accomplish this, the allocator may shrink the allocation referenced by ptr to fit the 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 it was transferred back to the caller again via the return value of this method.

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

Safety
  • ptr must denote a block of memory currently allocated by this allocator.
  • old_layout must fit that block of memory (The new_layout argument need not fit it).
  • new_layout.size() must be less than or equal to old_layout.size().
Errors

Returns Err if the new layout does not meet the allocator’s size and alignment constraints, or if shrinking otherwise fails.

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 handle_alloc_error function, rather than directly invoking panic! or similar.

Behaves like shrink but returns Err if the memory block cannot be shrunk in-place.

Safety
  • ptr must denote a block of memory currently allocated by this allocator.
  • old_layout must fit that block of memory (The new_layout argument need not fit it).
  • new_layout.size() must be less than or equal to old_layout.size().
Errors

Returns Err if the new layout does not meet the allocator’s size and alignment constraints, or if shrinking otherwise fails.

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 handle_alloc_error function, rather than directly invoking panic! or similar.

Implementors