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
Allocatorfunction of the same type. -
Implementers must ensure that all trait functions abide by the guarantees documented in the
# Guaranteessections.
Required Methods§
Sourceunsafe fn realloc(
ptr: Option<NonNull<u8>>,
layout: Layout,
old_layout: Layout,
flags: Flags,
) -> Result<NonNull<[u8]>, AllocError>
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), thenpmust point to an existing and valid memory allocation created by thisAllocator; ifold_layoutis zero-sizedpdoes not need to be a pointer returned by thisAllocator. ptris allowed to beNone; in this case a new memory allocation is created andold_layoutis ignored.old_layoutmust match theLayoutthe 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
pare 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), thenptris still valid.
Provided Methods§
Sourcefn alloc(layout: Layout, flags: Flags) -> Result<NonNull<[u8]>, AllocError>
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 toAllocator::freeorAllocator::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.
Sourceunsafe fn free(ptr: NonNull<u8>, layout: Layout)
unsafe fn free(ptr: NonNull<u8>, layout: Layout)
Free an existing memory allocation.
§Safety
ptrmust point to an existing and valid memory allocation created by thisAllocator; ifold_layoutis zero-sizedpdoes not need to be a pointer returned by thisAllocator.layoutmust match theLayoutthe allocation has been created with.- The memory allocation at
ptrmust never again be read from or written to.
Dyn Compatibility§
This trait is not dyn compatible.
In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.