Trait kernel::alloc::Allocator

source ·

pub unsafe trait Allocator {
    // Required method
    unsafe fn realloc(
        ptr: Option<NonNull<u8>>,
        layout: Layout,
        old_layout: Layout,
        flags: Flags
    ) -> Result<NonNull<[u8]>, AllocError>;

    // Provided methods
    fn alloc(layout: Layout, flags: Flags) -> Result<NonNull<[u8]>, AllocError> { ... }
    unsafe fn free(ptr: NonNull<u8>, layout: Layout) { ... }
}

Expand description

The kernel’s Allocator trait.

An implementation of Allocator can allocate, re-allocate and free memory buffers described via Layout.

Allocator is designed to be implemented as a ZST; Allocator functions do not operate on an object instance.

In order to be able to support #[derive(CoercePointee)] later on, we need to avoid a design that requires an Allocator to be instantiated, hence its functions must not contain any kind of self parameter.

§Safety

A memory allocation returned from an allocator must remain valid until it is explicitly freed.
Any pointer to a valid memory allocation must be valid to be passed to any other Allocator function of the same type.
Implementers must ensure that all trait functions abide by the guarantees documented in the # Guarantees sections.

Required Methods§

source

unsafe fn realloc( ptr: Option<NonNull<u8>>, layout: Layout, old_layout: Layout, flags: Flags ) -> Result<NonNull<[u8]>, AllocError>

Re-allocate an existing memory allocation to satisfy the requested layout.

If the requested size is zero, realloc behaves equivalent to free.

If the requested size is larger than the size of the existing allocation, a successful call to realloc guarantees that the new or grown buffer has at least Layout::size bytes, but may also be larger.

If the requested size is smaller than the size of the existing allocation, realloc may or may not shrink the buffer; this is implementation specific to the allocator.

On allocation failure, the existing buffer, if any, remains valid.

The buffer is represented as NonNull<[u8]>.

§Safety

If ptr == Some(p), then p must point to an existing and valid memory allocation created by this Allocator; if old_layout is zero-sized p does not need to be a pointer returned by this Allocator.
ptr is allowed to be None; in this case a new memory allocation is created and old_layout is ignored.
old_layout must match the Layout the allocation has been created with.

§Guarantees

This function has the same guarantees as Allocator::alloc. When ptr == Some(p), then it additionally guarantees that:

the contents of the memory pointed to by p are preserved up to the lesser of the new and old size, i.e. ret_ptr[0..min(layout.size(), old_layout.size())] == p[0..min(layout.size(), old_layout.size())].
when the return value is Err(AllocError), then ptr is still valid.

Provided Methods§

source

fn alloc(layout: Layout, flags: Flags) -> Result<NonNull<[u8]>, AllocError>

Allocate memory based on layout and flags.

On success, returns a buffer represented as NonNull<[u8]> that satisfies the layout constraints (i.e. minimum size and alignment as specified by layout).

This function is equivalent to realloc when called with None.

§Guarantees

When the return value is Ok(ptr), then ptr is

valid for reads and writes for layout.size() bytes, until it is passed to Allocator::free or Allocator::realloc,
aligned to layout.align(),

Additionally, Flags are honored as documented in https://docs.kernel.org/core-api/mm-api.html#mm-api-gfp-flags.

source

unsafe fn free(ptr: NonNull<u8>, layout: Layout)

Free an existing memory allocation.

§Safety

ptr must point to an existing and valid memory allocation created by this Allocator; if old_layout is zero-sized p does not need to be a pointer returned by this Allocator.
layout must match the Layout the allocation has been created with.
The memory allocation at ptr must never again be read from or written to.