Struct Dlmalloc 

pub struct Dlmalloc<A = System>(/* private fields */);

An allocator instance

Instances of this type are used to allocate blocks of memory. For best results only use one of these. Currently doesn’t implement Drop to release lingering memory back to the OS. That may happen eventually though!

Implementations

impl Dlmalloc<System>

pub const fn new() -> Dlmalloc<System>

Creates a new instance of an allocator

impl<A> Dlmalloc<A>

pub const fn new_with_allocator(sys_allocator: A) -> Dlmalloc<A>

Creates a new instance of an allocator

pub const fn set_max_release_check_rate(&mut self, rate: usize)

Sets the maximum number of large-chunk frees between periodic release-unused-segments passes. A value of 0 disables the pass.

May be called at any time. The new rate takes effect immediately: the active countdown is reseeded from the new value, so a disabled -> enabled transition fires on the next free rather than after usize::MAX decrements.

pub const fn set_granularity(&mut self, granularity: usize) -> bool

Sets the granularity used for system allocations.

Returns true if the value was accepted, false otherwise. To be accepted, granularity must be a power of two and at least 2 * size_of::<usize>() (the malloc alignment); smaller values are rejected because they would break the chunk size/flag-bit invariants during trim.

Unlike C dlmalloc’s mallopt(M_GRANULARITY, ...), which rejects sub-page values, this accepts any pow-of-two >= the malloc alignment. Sub-page granularity is intentionally allowed for embedded targets that need tightly-packed allocations.

For best results call this before the first allocation; existing segments retain their original alignment.

Const context

This is a const fn, so a configured allocator can be built in a const block:

let mut alloc = const {
    let mut a = Dlmalloc::new();
    assert!(a.set_granularity(32 * core::mem::size_of::<usize>()));
    a.set_max_release_check_rate(0);
    a
};

Dlmalloc is Send but not Sync, so it cannot be placed directly in a static; use GlobalDlmalloc (behind the global feature) when a static allocator is needed.

impl<A: Allocator> Dlmalloc<A>

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

Allocates size bytes with align align.

Returns a null pointer if allocation fails. Returns a valid pointer otherwise. A size of 0 is also accepted, behaving as Dlmalloc::c_malloc.

See Dlmalloc::c_malloc / Dlmalloc::c_memalign for the layout-free, C-shaped counterparts; pointers from either API may be freed or reallocated through the other.

Safety and contracts are otherwise largely governed by the GlobalAlloc::alloc method contracts.

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

Same as malloc, except if the allocation succeeds it’s guaranteed to point to size bytes of zeros.

pub unsafe fn free(&mut self, ptr: *mut u8, size: usize, align: usize)

Deallocates a ptr with size and align as the previous request used to allocate it.

See Dlmalloc::c_free for the layout-free, C-shaped counterpart; pointers from either API may be freed by this method.

Safety

size and align must match the values originally supplied when ptr was allocated. For pointers obtained from Dlmalloc::c_malloc or Dlmalloc::c_realloc, use 2 * size_of::<usize>() for align; for Dlmalloc::c_memalign, pass the originally-requested align. Passing the wrong size or align violates this method’s safety contract.

Safety and contracts are otherwise largely governed by the GlobalAlloc::dealloc method contracts.

pub unsafe fn realloc( &mut self, ptr: *mut u8, old_size: usize, old_align: usize, new_size: usize, ) -> *mut u8

Reallocates ptr, a previous allocation with old_size and old_align, to have new_size bytes.

If old_align exceeds the natural malloc alignment (2 * size_of::<usize>()), this preserves the original alignment. Otherwise the returned pointer is only guaranteed to be naturally aligned, matching Dlmalloc::c_realloc.

Returns a null pointer if the memory couldn’t be reallocated, but ptr is still valid. Returns a valid pointer and frees ptr if the request is satisfied.

See Dlmalloc::c_realloc for the layout-free, C-shaped counterpart.

Safety

old_size and old_align must match the values originally supplied when ptr was allocated. For pointers obtained from Dlmalloc::c_malloc or Dlmalloc::c_realloc, use 2 * size_of::<usize>() for old_align; for Dlmalloc::c_memalign, pass the originally-requested align. Passing the wrong old_size or old_align violates this method’s safety contract.

Safety and contracts are otherwise largely governed by the GlobalAlloc::realloc method contracts.

pub unsafe fn trim(&mut self, pad: usize) -> bool

If possible, gives memory back to the system if there is unused memory at the high end of the malloc pool or in unused segments.

You can call this after freeing large blocks of memory to potentially reduce the system-level memory requirements of a program. However, it cannot guarantee to reduce memory. Under some allocation patterns, some large free blocks of memory will be locked between two used chunks, so they cannot be given back to the system.

The pad argument represents the amount of free trailing space to leave untrimmed. If this argument is zero, only the minimum amount of memory to maintain internal data structures will be left. Non-zero arguments can be supplied to maintain enough trailing space to service future expected allocations without having to re-obtain memory from the system.

Returns true if it actually released any memory, else false.

pub unsafe fn destroy(self) -> usize

Releases all allocations in this allocator back to the system, consuming self and preventing further use.

Returns the number of bytes released to the system.

pub fn allocator(&self) -> &A

Get a reference to the underlying Allocator that this Dlmalloc was constructed with.

pub fn allocator_mut(&mut self) -> &mut A

Get a mutable reference to the underlying Allocator that this Dlmalloc was constructed with.

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

Allocates size bytes at the allocator’s natural alignment of 2 * size_of::<usize>().

Layout-free counterpart of Dlmalloc::malloc for wrapping the C malloc(size_t) ABI. Any size is accepted, including 0; the returned pointer (if non-null) may be freed or resized through the deallocation/reallocation methods. Returns a null pointer if allocation fails.

Compatibility

The c_* methods and the layout-carrying methods are two API shapes over the same allocator: a pointer obtained from any allocation method may be freed or reallocated by any deallocation/reallocation method on the same allocator. When crossing from c_* to the layout-carrying API, supply the original size and the alignment the allocation was made with — 2 * size_of::<usize>() for c_malloc, the original align for Dlmalloc::c_memalign. Note that reallocating through Dlmalloc::c_realloc does not preserve over-alignment; see its docs.

Safety

c_malloc has no caller preconditions on size. The returned pointer, if non-null, is uninitialized memory aligned to 2 * size_of::<usize>() and must eventually be released via one of the deallocation methods on the same allocator instance.

pub unsafe fn c_memalign(&mut self, align: usize, size: usize) -> *mut u8

Allocates size bytes aligned to at least align bytes.

Layout-free counterpart for wrapping the C memalign / posix_memalign ABIs. When align does not exceed the natural malloc alignment (2 * size_of::<usize>()) this is equivalent to Dlmalloc::c_malloc. Returns a null pointer if allocation fails.

See Dlmalloc::c_malloc for compatibility with the layout-carrying API.

Safety

align must be a power of two. The caller’s obligations on the returned pointer match those of Dlmalloc::c_malloc.

pub unsafe fn c_realloc(&mut self, ptr: *mut u8, new_size: usize) -> *mut u8

Reallocates ptr to new_size bytes.

Layout-free counterpart for wrapping the C realloc(void *, size_t) ABI. A null ptr behaves like Dlmalloc::c_malloc; otherwise ptr may come from any allocation method on this allocator instance, regardless of the alignment it was allocated with.

The returned pointer is only guaranteed to be aligned to the natural malloc alignment (2 * size_of::<usize>()), even when ptr was originally over-aligned via Dlmalloc::c_memalign or Dlmalloc::malloc. Use Dlmalloc::realloc when the original alignment must be preserved.

Returns a null pointer if the memory couldn’t be reallocated, in which case ptr remains valid. Returns a non-null pointer and frees ptr on success.

Safety

If non-null, ptr must come from this allocator instance and must not have been freed already. The caller’s obligations on the returned pointer match those of Dlmalloc::c_malloc.

pub unsafe fn c_free(&mut self, ptr: *mut u8)

Frees ptr.

Layout-free counterpart for wrapping the C free(void *) ABI. A null ptr is a no-op; otherwise ptr must come from any allocation method on this allocator instance.

Safety

If non-null, ptr must come from this allocator and must not have been freed already.