Struct Allocator

pub struct Allocator { /* private fields */ }

A general-purpose memory allocator. It’s recommended to use the Allocator Pool to manage allocator instances. It is important to be aware that *mut u8 return types are type-friendly wrappers on top of libc::c_void, which is just a void* in C.

Implementations

impl Allocator

pub fn new(id: u32, heap: *mut mi_heap_t) -> Self

pub fn id(self) -> u32

pub fn collect(&self, force: bool)

Release outstanding resources in a specific heap.

pub fn malloc(&self, size: usize) -> *mut u8

Allocate size bytes.

Returns pointer to the allocated memory or null if out of memory. Returns a unique pointer if called with size 0.

pub fn free(&self, p: *mut u8)

pub fn zalloc(&self, size: usize) -> *mut u8

Allocate zero-initialized size bytes.

Returns a pointer to newly allocated zero-initialized memory, or null if out of memory.

pub fn calloc(&self, count: usize, size: usize) -> *mut u8

Allocate count items of size length each.

Returns 0 if count * size overflows or on out-of-memory.

All items are initialized to zero.

pub fn mallocn(&self, count: usize, size: usize) -> *mut u8

Allocate count items of size length each.

Returns 0 if count * size overflows or on out-of-memory, otherwise returns the same as malloc(count * size). Equivalent to calloc, but returns uninitialized (and not zeroed) bytes.

pub fn malloc_small(&self, size: usize) -> *mut u8

Allocate an object of no more than SMALL_SIZE_MAX bytes.

Does not check that size is indeed small.

Note: Currently malloc_small checks if size is small and calls this if so at runtime, so its’ only worth using if you know for certain.

pub fn realloc(&self, p: *mut u8, newsize: usize) -> *mut u8

Zero initialized re-allocation.

In general, only valid on memory originally allocated by zero initialization: calloc, zalloc, zalloc_aligned, …

pub fn reallocn(&self, p: *mut u8, count: usize, size: usize) -> *mut u8

Re-allocate memory to count elements of size bytes.

The realloc equivalent of the mallocn interface. Returns null if count * size overflows or on out-of-memory, otherwise returns the same as realloc(p, count * size).

pub fn reallocf(&self, p: *mut u8, newsize: usize) -> *mut u8

Re-allocate memory to newsize bytes.

This differs from realloc in that on failure, p is freed.

pub fn strdup(&self, s: *const c_char) -> *mut c_char

Allocate and duplicate a nul-terminated C string. Because this could be either an i8 or u8, the original type is left unwrapped.

pub fn strndup(&self, s: *const c_char, n: usize) -> *mut c_char

Allocate and duplicate a nul-terminated C string, up to n bytes. Because this could be either an i8 or u8, the original type is left unwrapped.

pub fn realpath( &self, fname: *const c_char, resolved_name: *mut c_char, ) -> *mut c_char

Resolve a file path name, producing a C string which can be passed to free.

resolved_name should be null, but can also point to a buffer of at least PATH_MAX bytes.

If successful, returns a pointer to the resolved absolute file name, or null on failure (with errno set to the error code).

If resolved_name was null, the returned result should be freed with free.

This can rarely be useful in FFI code, but is mostly included for completeness.

pub fn malloc_aligned(&self, size: usize, alignment: usize) -> *mut u8

Allocate size bytes aligned by alignment.

Return pointer to the allocated memory or null if out of memory.

Returns a unique pointer if called with size 0.

pub fn malloc_aligned_at( &self, size: usize, alignment: usize, offset: usize, ) -> *mut u8

Allocate size bytes aligned by alignment at a specified offset.

Note that the resulting pointer itself is not aligned by the alignment, but after offset bytes it will be. This can be useful for allocating data with an inline header, where the data has a specific alignment requirement.

Specifically, if p is the returned pointer p.add(offset) is aligned to alignment.

pub fn zalloc_aligned(&self, size: usize, alignment: usize) -> *mut u8

Allocate size bytes aligned by alignment, initialized to zero.

Return pointer to the allocated memory or null if out of memory.

Returns a unique pointer if called with size 0.

pub fn zalloc_aligned_at( &self, size: usize, alignment: usize, offset: usize, ) -> *mut u8

Allocate size bytes aligned by alignment at a specified offset, zero-initialized.

This is a zalloc equivalent of malloc_aligned_at.

pub fn calloc_aligned( &self, count: usize, size: usize, alignment: usize, ) -> *mut u8

Allocate size * count bytes aligned by alignment.

Return pointer to the allocated memory or null if out of memory or if size * count overflows.

Returns a unique pointer if called with size * count 0.

pub fn calloc_aligned_at( &self, count: usize, size: usize, alignment: usize, offset: usize, ) -> *mut u8

Allocate size * count bytes aligned by alignment at a specified offset, zero-initialized.

This is a calloc equivalent of malloc_aligned_at.

pub fn realloc_aligned( &self, p: *mut u8, new_size: usize, alignment: usize, ) -> *mut u8

Re-allocate memory to newsize bytes, aligned by alignment.

Return pointer to the allocated memory or null if out of memory. If null is returned, the pointer p is not freed. Otherwise the original pointer is either freed or returned as the reallocated result (in case it fits in-place with the new size).

If p is null, it behaves as malloc_aligned. If new_size is larger than the original size allocated for p, the bytes after size are uninitialized.

pub fn realloc_aligned_at( &self, p: *mut u8, newsize: usize, alignment: usize, offset: usize, ) -> *mut u8

Re-allocate memory to newsize bytes aligned by alignment at a specified offset.

This is a realloc equivalent of malloc_aligned_at.

pub fn rezalloc(&self, p: *mut u8, newsize: usize) -> *mut u8

Zero initialized re-allocation.

In general, only valid on memory originally allocated by zero initialization: calloc, zalloc, zalloc_aligned, …

pub fn recalloc(&self, p: *mut u8, newcount: usize, size: usize) -> *mut u8

Zero initialized re-allocation, following calloc paramater conventions.

In general, only valid on memory originally allocated by zero initialization: calloc, zalloc, zalloc_aligned, …

pub fn rezalloc_aligned( &self, p: *mut u8, newsize: usize, alignment: usize, ) -> *mut u8

Aligned version of rezalloc.

pub fn rezalloc_aligned_at( &self, p: *mut u8, newsize: usize, alignment: usize, offset: usize, ) -> *mut u8

Offset-aligned version of rezalloc.

pub fn recalloc_aligned( &self, p: *mut u8, newcount: usize, size: usize, alignment: usize, ) -> *mut u8

Aligned version of recalloc.

pub fn recalloc_aligned_at( &self, p: *mut u8, newcount: usize, size: usize, alignment: usize, offset: usize, ) -> *mut u8

Offset-aligned version of recalloc.

pub fn contains_block(&self, p: *const u8) -> bool

Does a heap contain a pointer to a previously allocated block?

p must be a pointer to a previously allocated block (in any heap) – it cannot be some random pointer!

Returns true if the block pointed to by p is in the heap.

See check_owned.

pub fn check_owned(&self, p: *const u8) -> bool

Check safely if any pointer is part of a heap.

p may be any pointer – not required to be previously allocated by the given heap or any other known heap. Returns true if p points to a block in the given heap, false otherwise.

Note: expensive function, linear in the pages in the heap.

See contains_block, [get_default], and [is_in_region]

pub fn visit_blocks( &self, visit_all_blocks: bool, visitor: mi_block_visit_fun, arg: *mut u8, ) -> bool

Visit all areas and blocks in heap.

If visit_all_blocks is false, the visitor is only called once for every heap area. If it’s true, the visitor is also called for every allocated block inside every area (with !block.is_null()). Return false from the visitor to return early.

arg is an extra argument passed into the visitor.

Returns true if all areas and blocks were visited.

Passing a None visitor is allowed, and is a no-op.

Trait Implementations

impl Default for Allocator

fn default() -> Self

Create an allocator that uses the default heap.

Note: If called multiple times, it will contain the same reference to the same underlying heap. There are not multiple heaps.