Struct AllocatorVtable 

#[repr(C)]
pub struct AllocatorVtable {
    pub alloc: Option<unsafe extern "C" fn(ctx: *mut c_void, len: usize, alignment: u8, ret_addr: usize) -> *mut c_void>,
    pub resize: Option<unsafe extern "C" fn(ctx: *mut c_void, memory: *mut c_void, memory_len: usize, alignment: u8, new_len: usize, ret_addr: usize) -> bool>,
    pub remap: Option<unsafe extern "C" fn(ctx: *mut c_void, memory: *mut c_void, memory_len: usize, alignment: u8, new_len: usize, ret_addr: usize) -> *mut c_void>,
    pub free: Option<unsafe extern "C" fn(ctx: *mut c_void, memory: *mut c_void, memory_len: usize, alignment: u8, ret_addr: usize)>,
}

Function table for custom memory allocator operations.

This vtable defines the interface for a custom memory allocator. All function pointers must be valid and non-NULL.

If you’re not going to use a custom allocator, you can ignore all of this. All functions that take an allocator pointer allow NULL to use a default allocator.

The interface is based on the Zig allocator interface. I’ll say up front that it is easy to look at this interface and think “wow, this is really overcomplicated”. The reason for this complexity is well thought out by the Zig folks, and it enables a diverse set of allocation strategies as shown by the Zig ecosystem. As a consolation, please note that many of the arguments are only needed for advanced use cases and can be safely ignored in simple implementations. For example, if you look at the Zig implementation of the libc allocator in lib/std/heap.zig (search for CAllocator), you’ll see it is very simple.

We chose to align with the Zig allocator interface because:

1. It is a proven interface that serves a wide variety of use cases in the real world via the Zig ecosystem. It’s shown to work.

2. Our core implementation itself is Zig, and this lets us very cheaply and easily convert between C and Zig allocators.

NOTE(mitchellh): In the future, we can have default implementations of resize/remap and allow those to be null.

Fields

alloc: Option<unsafe extern "C" fn(ctx: *mut c_void, len: usize, alignment: u8, ret_addr: usize) -> *mut c_void>

Return a pointer to len bytes with specified alignment, or return NULL indicating the allocation failed.

be a power of two between 1 and 16 inclusive.

resize: Option<unsafe extern "C" fn(ctx: *mut c_void, memory: *mut c_void, memory_len: usize, alignment: u8, new_len: usize, ret_addr: usize) -> bool>

Attempt to expand or shrink memory in place.

memory_len must equal the length requested from the most recent successful call to alloc, resize, or remap. alignment must equal the same value that was passed as the alignment parameter to the original alloc call.

new_len must be greater than zero.

remap: Option<unsafe extern "C" fn(ctx: *mut c_void, memory: *mut c_void, memory_len: usize, alignment: u8, new_len: usize, ret_addr: usize) -> *mut c_void>

Attempt to expand or shrink memory, allowing relocation.

memory_len must equal the length requested from the most recent successful call to alloc, resize, or remap. alignment must equal the same value that was passed as the alignment parameter to the original alloc call.

A non-NULL return value indicates the resize was successful. The allocation may have same address, or may have been relocated. In either case, the allocation now has size of new_len. A NULL return value indicates that the resize would be equivalent to allocating new memory, copying the bytes from the old memory, and then freeing the old memory. In such case, it is more efficient for the caller to perform the copy.

new_len must be greater than zero.

free: Option<unsafe extern "C" fn(ctx: *mut c_void, memory: *mut c_void, memory_len: usize, alignment: u8, ret_addr: usize)>

Free and invalidate a region of memory.

memory_len must equal the length requested from the most recent successful call to alloc, resize, or remap. alignment must equal the same value that was passed as the alignment parameter to the original alloc call.

Trait Implementations

impl Clone for AllocatorVtable

fn clone(&self) -> AllocatorVtable

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Copy for AllocatorVtable

impl Debug for AllocatorVtable

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for AllocatorVtable

fn default() -> AllocatorVtable

Returns the “default value” for a type.