Dlmalloc

https://docs.rs/dlmalloc
Admin
Dlmalloc is a Rust port of the `dlmalloc` allocator, serving as the default memory allocator for the...
Tokens:39,152
Snippets:308
Trust Score:9.1
Update:4 months ago
Show doc for...
Tokens:
Raw
### dlmalloc Usage Example

Source: https://docs.rs/dlmalloc/latest/src/dlmalloc/dlmalloc.rs.html

Demonstrates basic usage of dlmalloc for memory allocation and deallocation.

```rust
            *p = i as u8;
            *slot = p;
        }
        for (i, &p) in ptrs.iter().enumerate() {
            assert_eq!(*p, i as u8);
            a.free(p);
        }
    }
}
```

--------------------------------

### Get System Allocator Reference

Source: https://docs.rs/dlmalloc/latest/src/dlmalloc/dlmalloc.rs.html

Provides an immutable reference to the underlying system allocator.

```Rust
pub fn allocator(&self) -> &A {
    &self.system_allocator
}
```

--------------------------------

### Get Small Bin Index

Source: https://docs.rs/dlmalloc/latest/src/dlmalloc/dlmalloc.rs.html

Calculates the index for a small bin based on the given size.

```rust
fn small_index(&self, size: usize) -> u32 {
    (size >> SMALLBIN_SHIFT) as u32
}
```

--------------------------------

### Get Mutable System Allocator Reference

Source: https://docs.rs/dlmalloc/latest/src/dlmalloc/dlmalloc.rs.html

Provides a mutable reference to the underlying system allocator.

```Rust
pub fn allocator_mut(&mut self) -> &mut A {
    &mut self.system_allocator
}
```

--------------------------------

### Get Maximum Small Size

Source: https://docs.rs/dlmalloc/latest/src/dlmalloc/dlmalloc.rs.html

Calculates the maximum size for a small memory chunk.

```rust
fn max_small_size(&self) -> usize {
    self.min_large_size() - 1
}
```

--------------------------------

### Get MMapped Foot Padding

Source: https://docs.rs/dlmalloc/latest/src/dlmalloc/dlmalloc.rs.html

Returns the padding size for memory-mapped allocations.

```rust
fn mmap_foot_pad(&self) -> usize {
    4 * mem::size_of::<usize>()
}
```

--------------------------------

### Get Underlying Allocator Reference

Source: https://docs.rs/dlmalloc/latest/src/dlmalloc/lib.rs.html

Provides a reference to the underlying `Allocator` that the `Dlmalloc` instance was constructed with.

```rust
pub fn allocator(&self) -> &A {
        self.0.allocator()
    }
```

--------------------------------

### Get Minimum Chunk Size

Source: https://docs.rs/dlmalloc/latest/src/dlmalloc/dlmalloc.rs.html

Calculates the minimum size of a memory chunk, ensuring it's aligned.

```rust
fn min_chunk_size(&self) -> usize {
    align_up(mem::size_of::<Chunk>(), self.malloc_alignment())
}
```

--------------------------------

### Get Minimum Request Size

Source: https://docs.rs/dlmalloc/latest/src/dlmalloc/dlmalloc.rs.html

Calculates the minimum valid request size for memory allocation, accounting for chunk overhead.

```rust
fn min_request(&self) -> usize {
    self.min_chunk_size() - self.chunk_overhead() - 1
}
```

--------------------------------

### Get Maximum Small Request Size

Source: https://docs.rs/dlmalloc/latest/src/dlmalloc/dlmalloc.rs.html

Calculates the maximum request size that can be handled as a 'small' allocation, considering alignment and chunk overhead.

```rust
fn max_small_request(&self) -> usize {
    self.max_small_size() - (self.malloc_alignment() - 1) - self.chunk_overhead()
}
```

--------------------------------

### Initializing Bins

Source: https://docs.rs/dlmalloc/latest/src/dlmalloc/dlmalloc.rs.html

Initializes the small bins, which are used to store free chunks of small sizes. Each bin is set up as a self-referential linked list initially.

```rust
    unsafe fn init_bins(&mut self) {
        for i in 0..NSMALLBINS_U32 {
            let bin = self.smallbin_at(i);
            (*bin).next = bin;
        }
```

--------------------------------

### Get the size of a chunk

Source: https://docs.rs/dlmalloc/latest/src/dlmalloc/dlmalloc.rs.html

Extracts the size of a chunk from its head by masking out the flag bits.

```rust
unsafe fn size(me: *mut Chunk) -> usize {
        (*me).head & !FLAG_BITS
    }
```

--------------------------------

### Dlmalloc New Constructor

Source: https://docs.rs/dlmalloc/latest/src/dlmalloc/dlmalloc.rs.html

Initializes a new `Dlmalloc` instance with default values and the provided system allocator.

```Rust
pub const fn new(system_allocator: A) -> Dlmalloc<A> {
    Dlmalloc {
        smallmap: 0,
        treemap: 0,
        smallbins: [ptr::null_mut(); (NSMALLBINS + 1) * 2],
        treebins: [ptr::null_mut(); NTREEBINS],
        dvsize: 0,
        topsize: 0,
        dv: ptr::null_mut(),
        top: ptr::null_mut(),
        footprint: 0,
        max_footprint: 0,
        seg: Segment {
            base: ptr::null_mut(),
            size: 0,
            next: ptr::null_mut(),
            flags: 0,
        },
        trim_check: 0,
        least_addr: ptr::null_mut(),
        release_checks: 0,
        granularity: 64 * 1024,
        max_release_check_rate: 4095,
        system_allocator,
    }
}
```

--------------------------------

### Get Chunk Overhead

Source: https://docs.rs/dlmalloc/latest/src/dlmalloc/dlmalloc.rs.html

Returns the memory overhead associated with a standard memory chunk.

```rust
fn chunk_overhead(&self) -> usize {
    mem::size_of::<usize>()
}
```

--------------------------------

### Setting up Allocator with Free Chunks

Source: https://docs.rs/dlmalloc/latest/src/dlmalloc/dlmalloc.rs.html

Primes the allocator with large allocations and then frees them to ensure free chunks are present in the treemap for testing.

```rust
unsafe fn setup_treemap<A: Allocator>(a: &mut Dlmalloc<A>) {
        let large_request_size = NSMALLBINS * (1 << SMALLBIN_SHIFT);
        assert!(!a.is_small(large_request_size));
        let large_request1 = a.malloc(large_request_size);
        assert_ne!(large_request1, ptr::null_mut());
        let large_request2 = a.malloc(large_request_size);
        assert_ne!(large_request2, ptr::null_mut());
        a.free(large_request1);
        assert_ne!(a.treemap, 0);
    }
```

--------------------------------

### Allocate Memory with Alignment (C ABI)

Source: https://docs.rs/dlmalloc/latest/src/dlmalloc/lib.rs.html

Allocates memory with a specified alignment, compatible with the C ABI. Returns a null pointer if allocation fails. Alignment must be a power of two.

```rust
pub unsafe fn c_memalign(&mut self, align: usize, size: usize) -> *mut u8 {
    if align <= self.0.malloc_alignment() {
        self.c_malloc(size)
    } else {
        self.0.memalign(align, size)
    }
}
```

--------------------------------

### Get Malloc Alignment

Source: https://docs.rs/dlmalloc/latest/src/dlmalloc/dlmalloc.rs.html

Calculates and returns the required memory alignment for malloc operations.

```rust
pub fn malloc_alignment(&self) -> usize {
    mem::size_of::<usize>() * 2
}
```

--------------------------------

### Create New Dlmalloc Instance (System Allocator)

Source: https://docs.rs/dlmalloc/latest/dlmalloc/struct.Dlmalloc.html

Creates a new instance of the Dlmalloc allocator using the default System allocator. This is a const function, allowing it to be used in compile-time contexts.

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

--------------------------------

### free

Source: https://docs.rs/dlmalloc/latest/src/dlmalloc/lib.rs.html

Deallocates a memory block pointed to by `ptr`. The `size` and `align` parameters must match the values originally used to allocate the memory.

```APIDOC
## free

### Description
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 and contracts are otherwise largely governed by the `GlobalAlloc::dealloc` method contracts.

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

### Parameters
* `ptr` (*mut u8) - A pointer to the memory block to deallocate.
* `size` (usize) - The size of the memory block.
* `align` (usize) - The alignment of the memory block.

### 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.
```

--------------------------------

### System Allocator Methods

Source: https://docs.rs/dlmalloc/latest/src/dlmalloc/unix.rs.html

Provides methods for memory allocation, remapping, and freeing on Unix-like systems. It interfaces with libc functions like mmap, mremap, and munmap.

```APIDOC
## System Allocator Methods

### Description

This section details the methods available for the `System` allocator, which is designed for Unix-like operating systems. It allows for direct memory management using underlying C library functions.

### Methods

- **`new()`**: Creates a new instance of the `System` allocator.
- **`alloc(size: usize)`**: Allocates a block of memory of the specified size. Returns a pointer to the allocated memory, the size, and flags.
- **`remap(ptr: *mut u8, oldsize: usize, newsize: usize, can_move: bool)`**: Remaps an existing memory block to a new size. The `can_move` flag indicates if the memory block can be moved.
- **`free_part(ptr: *mut u8, oldsize: usize, newsize: usize)`**: Frees a portion of a memory block, reducing its size.
- **`free(ptr: *mut u8, size: usize)`**: Frees an entire memory block.
- **`can_release_part(flags: u32)`**: Checks if a portion of memory can be released.
- **`allocates_zeros()`**: Returns true if the allocator guarantees zeroed memory.
- **`page_size()`**: Returns the system's page size.
```

--------------------------------

### Getting System Flags for a Segment

Source: https://docs.rs/dlmalloc/latest/src/dlmalloc/dlmalloc.rs.html

Extracts the system-related flags from a Segment by right-shifting its flags field.

```rust
unsafe fn sys_flags(seg: *mut Segment) -> u32 {
        (*seg).flags >> 1
    }
```

--------------------------------

### Create New Dlmalloc Instance (Custom Allocator)

Source: https://docs.rs/dlmalloc/latest/dlmalloc/struct.Dlmalloc.html

Creates a new instance of the Dlmalloc allocator with a provided system allocator. This is a const function.

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

--------------------------------

### Getting Chunk Pointer from TreeChunk

Source: https://docs.rs/dlmalloc/latest/src/dlmalloc/dlmalloc.rs.html

Obtains a pointer to the Chunk metadata embedded within a TreeChunk.

```rust
unsafe fn chunk(me: *mut TreeChunk) -> *mut Chunk {
        ptr::addr_of_mut!((*me).chunk)
    }
```

--------------------------------

### Dlmalloc Struct

Source: https://docs.rs/dlmalloc/latest/src/dlmalloc/lib.rs.html

The Dlmalloc struct is the main entry point for using the dlmalloc allocator. It can be instantiated with a specific allocator implementation or use the default system allocator.

```APIDOC
## Dlmalloc Struct

### Description
An allocator instance used to allocate blocks of memory. It wraps a specific `Allocator` implementation.

### Constructors

- **new() -> Dlmalloc<System>**:
  Creates a new instance of the allocator using the default `System` allocator.

- **new_with_allocator(sys_allocator: A) -> Dlmalloc<A>**:
  Creates a new instance of the allocator with a provided `sys_allocator` that implements the `Allocator` trait.

### Methods

- **set_max_frees_between_reclaims(max_frees: usize)**:
  Sets the maximum number of large-chunk frees between periodic `release_unused_segments` passes. A value of `0` disables this pass. The new rate takes effect immediately.
```

--------------------------------

### Test dlmalloc Granularity Settings

Source: https://docs.rs/dlmalloc/latest/src/dlmalloc/dlmalloc.rs.html

Verifies that dlmalloc's granularity can be set to various valid values, including minimum, sub-page, page-sized, and larger powers of two. Asserts that the granularity is updated correctly after each successful setting.

```rust
    #[test]
    fn set_granularity() {
        let mut a = Dlmalloc::new(System::new());

        // exactly malloc_alignment accepted (the smallest legal value)
        assert!(a.set_granularity(MIN_GRANULARITY));
        assert_eq!(a.granularity, MIN_GRANULARITY);

        // sub-page but >= malloc_alignment accepted (the embedded use case)
        let page = a.system_allocator.page_size();
        let sub_page = MIN_GRANULARITY * 2;
        assert!(sub_page < page);
        assert!(a.set_granularity(sub_page));
        assert_eq!(a.granularity, sub_page);

        // page-sized pow2 accepted
        assert!(a.set_granularity(page));
        assert_eq!(a.granularity, page);

        // larger pow2 accepted
        assert!(a.set_granularity(2 * 64 * 1024));
        assert_eq!(a.granularity, 2 * 64 * 1024);
    }

```

--------------------------------

### Dlmalloc::new

Source: https://docs.rs/dlmalloc/latest/dlmalloc/struct.Dlmalloc.html

Creates a new instance of the Dlmalloc allocator. This is the default constructor for creating an allocator with the system's default allocator.

```APIDOC
## Dlmalloc::new

### Description
Creates a new instance of an allocator.

### Method
`new()`

### Returns
A new `Dlmalloc<System>` instance.
```

--------------------------------

### calloc

Source: https://docs.rs/dlmalloc/latest/src/dlmalloc/lib.rs.html

Similar to `malloc`, but guarantees that the allocated memory is zero-initialized if the allocation succeeds. Returns a null pointer if allocation fails.

```APIDOC
## calloc

### Description
Same as `malloc`, except if the allocation succeeds it's guaranteed to point to `size` bytes of zeros. Returns a null pointer if allocation fails.

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

### Parameters
* `size` (usize) - The number of bytes to allocate.
* `align` (usize) - The desired memory alignment.

### Returns
* `*mut u8` - A pointer to the zero-initialized allocated memory, or a null pointer if allocation fails.
```

--------------------------------

### Get Minimum Large Size

Source: https://docs.rs/dlmalloc/latest/src/dlmalloc/dlmalloc.rs.html

Calculates the minimum size for a large memory chunk based on `TREEBIN_SHIFT`.

```rust
fn min_large_size(&self) -> usize {
    1 << TREEBIN_SHIFT
}
```

--------------------------------

### Unix System Allocator Implementation

Source: https://docs.rs/dlmalloc/latest/src/dlmalloc/unix.rs.html

Implements the Allocator trait for a Unix system, using mmap for allocation, mremap for remapping, and munmap for deallocation. Handles platform-specific behaviors for Linux and macOS.

```rust
use crate::Allocator;
use core::ptr;

/// System setting for Linux
pub struct System {
    _priv: (),
}

impl System {
    pub const fn new() -> System {
        System { _priv: () }
    }
}

#[cfg(feature = "global")]
static mut LOCK: libc::pthread_mutex_t = libc::PTHREAD_MUTEX_INITIALIZER;

unsafe impl Allocator for System {
    fn alloc(&self, size: usize) -> (*mut u8, usize, u32) {
        let addr = unsafe {
            libc::mmap(
                ptr::null_mut(),
                size,
                libc::PROT_WRITE | libc::PROT_READ,
                libc::MAP_ANON | libc::MAP_PRIVATE,
                -1,
                0,
            )
        };
        if addr == libc::MAP_FAILED {
            (ptr::null_mut(), 0, 0)
        } else {
            (addr.cast(), size, 0)
        }
    }

    #[cfg(target_os = "linux")]
    fn remap(&self, ptr: *mut u8, oldsize: usize, newsize: usize, can_move: bool) -> *mut u8 {
        let flags = if can_move { libc::MREMAP_MAYMOVE } else { 0 };
        let ptr = unsafe { libc::mremap(ptr.cast(), oldsize, newsize, flags) };
        if ptr == libc::MAP_FAILED {
            ptr::null_mut()
        } else {
            ptr.cast()
        }
    }

    #[cfg(target_os = "macos")]
    fn remap(&self, _ptr: *mut u8, _oldsize: usize, _newsize: usize, _can_move: bool) -> *mut u8 {
        ptr::null_mut()
    }

    #[cfg(target_os = "linux")]
    fn free_part(&self, ptr: *mut u8, oldsize: usize, newsize: usize) -> bool {
        unsafe {
            let rc = libc::mremap(ptr.cast(), oldsize, newsize, 0);
            if rc != libc::MAP_FAILED {
                return true;
            }
            libc::munmap(ptr.add(newsize).cast(), oldsize - newsize) == 0
        }
    }

    #[cfg(target_os = "macos")]
    fn free_part(&self, ptr: *mut u8, oldsize: usize, newsize: usize) -> bool {
        unsafe { libc::munmap(ptr.add(newsize).cast(), oldsize - newsize) == 0 }
    }

    fn free(&self, ptr: *mut u8, size: usize) -> bool {
        unsafe { libc::munmap(ptr.cast(), size) == 0 }
    }

    fn can_release_part(&self, _flags: u32) -> bool {
        true
    }

    fn allocates_zeros(&self) -> bool {
        true
    }

    fn page_size(&self) -> usize {
        4096
    }
}
```

--------------------------------

### Set chunk size and PINUSE flag for a free chunk

Source: https://docs.rs/dlmalloc/latest/src/dlmalloc/dlmalloc.rs.html

Sets the size and PINUSE flag for a free chunk and updates its foot.

```rust
unsafe fn set_size_and_pinuse_of_free_chunk(me: *mut Chunk, size: usize) {
        (*me).head = size | PINUSE;
        Chunk::set_foot(me, size);
    }
```

--------------------------------

### Get MMapped Chunk Overhead

Source: https://docs.rs/dlmalloc/latest/src/dlmalloc/dlmalloc.rs.html

Returns the memory overhead for chunks allocated via memory mapping.

```rust
fn mmap_chunk_overhead(&self) -> usize {
    2 * mem::size_of::<usize>()
}
```

--------------------------------

### Get Mutable Underlying Allocator Reference

Source: https://docs.rs/dlmalloc/latest/src/dlmalloc/lib.rs.html

Provides a mutable reference to the underlying `Allocator` that the `Dlmalloc` instance was constructed with.

```rust
pub fn allocator_mut(&mut self) -> &mut A {
        self.0.allocator_mut()
    }
```

--------------------------------

### Allocate Memory (malloc)

Source: https://docs.rs/dlmalloc/latest/dlmalloc/struct.Dlmalloc.html

Allocates a block of memory of the specified size and alignment. Returns a null pointer if allocation fails. Accepts a size of 0, behaving like c_malloc.

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

--------------------------------

### Getting Previous TreeChunk Pointer

Source: https://docs.rs/dlmalloc/latest/src/dlmalloc/dlmalloc.rs.html

Retrieves the pointer to the previous TreeChunk in sequence, by accessing the 'prev' field of the embedded Chunk.

```rust
unsafe fn prev(me: *mut TreeChunk) -> *mut TreeChunk {
        (*TreeChunk::chunk(me)).prev.cast()
    }
```

--------------------------------

### Set a free chunk with PINUSE flag

Source: https://docs.rs/dlmalloc/latest/src/dlmalloc/dlmalloc.rs.html

Marks a chunk as free, sets its size and PINUSE flag, and clears the PINUSE flag of the next chunk.

```rust
unsafe fn set_free_with_pinuse(p: *mut Chunk, size: usize, n: *mut Chunk) {
        Chunk::clear_pinuse(n);
        Chunk::set_size_and_and_pinuse_of_free_chunk(p, size);
    }
```

--------------------------------

### Getting Next TreeChunk Pointer

Source: https://docs.rs/dlmalloc/latest/src/dlmalloc/dlmalloc.rs.html

Retrieves the pointer to the next TreeChunk in sequence, by accessing the 'next' field of the embedded Chunk.

```rust
unsafe fn next(me: *mut TreeChunk) -> *mut TreeChunk {
        (*TreeChunk::chunk(me)).next.cast()
    }
```

--------------------------------

### Convert Small Bin Index to Size

Source: https://docs.rs/dlmalloc/latest/src/dlmalloc/dlmalloc.rs.html

Converts a small bin index back into its corresponding size.

```rust
fn small_index2size(&self, idx: u32) -> usize {
    usize::try_from(idx).unwrap() << SMALLBIN_SHIFT
}
```

--------------------------------

### Getting Leftmost Child of a TreeChunk

Source: https://docs.rs/dlmalloc/latest/src/dlmalloc/dlmalloc.rs.html

Retrieves the leftmost child of a TreeChunk, prioritizing the first child if available, otherwise returning the second.

```rust
unsafe fn leftmost_child(me: *mut TreeChunk) -> *mut TreeChunk {
        let left = (*me).child[0];
        if left.is_null() {
            (*me).child[1]
        } else {
            left
        }
    }
```

--------------------------------

### page_size Method - Allocator Trait

Source: https://docs.rs/dlmalloc/latest/dlmalloc/trait.Allocator.html

Returns the system's page size, which must be a power of two.

```rust
fn page_size(&self) -> usize;
```

--------------------------------

### Free Memory (C ABI)

Source: https://docs.rs/dlmalloc/latest/src/dlmalloc/lib.rs.html

Frees a memory block, compatible with the C ABI's `free`. A null pointer is a no-op. The pointer must have originated from this allocator instance.

```rust
pub unsafe fn c_free(&mut self, ptr: *mut u8) {
    if ptr.is_null() {
        return;
    }
    self.0.free(ptr)
}
```

--------------------------------

### Get Release Check Target Value

Source: https://docs.rs/dlmalloc/latest/src/dlmalloc/dlmalloc.rs.html

Returns the value to seed `release_checks` with. If the maximum release check rate is zero, it returns `usize::MAX` to disable the periodic release pass.

```rust
const fn release_check_target(&self) -> usize {
    if self.max_release_check_rate == 0 {
        usize::MAX
    } else {
        self.max_release_check_rate
    }
}
```

--------------------------------

### trim

Source: https://docs.rs/dlmalloc/latest/dlmalloc/struct.Dlmalloc.html

Releases unused memory back to the system if possible. It can be called after freeing large blocks to reduce memory requirements, but it's not guaranteed to succeed due to memory fragmentation. The `pad` argument specifies the amount of free trailing space to leave untrimmed.

```APIDOC
## trim

### Description
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.

### Method
`unsafe fn trim(&mut self, pad: usize) -> bool`

### Parameters
#### Path Parameters
- **pad** (usize) - Description: The amount of free trailing space to leave untrimmed.

### Returns
- **bool** - `true` if it actually released any memory, else `false`.

### 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.
```

--------------------------------

### Align Up Utility Function

Source: https://docs.rs/dlmalloc/latest/src/dlmalloc/dlmalloc.rs.html

Calculates the smallest multiple of `alignment` that is greater than or equal to `a`. Ensures alignment is a power of two.

```Rust
fn align_up(a: usize, alignment: usize) -> usize {
    debug_assert!(alignment.is_power_of_two());
    (a + (alignment - 1)) & !(alignment - 1)
}
```

--------------------------------

### Dlmalloc::allocator

Source: https://docs.rs/dlmalloc/latest/src/dlmalloc/dlmalloc.rs.html

Returns a reference to the underlying system allocator.

```APIDOC
## Dlmalloc::allocator

### Description
Returns an immutable reference to the system allocator used by this `Dlmalloc` instance.

### Method
`pub fn allocator(&self) -> &A`

### Returns
A reference to the system allocator (`A`).
```

--------------------------------

### Initializing the Top Chunk

Source: https://docs.rs/dlmalloc/latest/src/dlmalloc/dlmalloc.rs.html

Initializes the 'top' chunk, which represents the end of the memory heap. This function sets up the initial size and properties of the top chunk and adjusts the trim threshold.

```rust
    unsafe fn init_top(&mut self, ptr: *mut Chunk, size: usize) {
        let offset = self.align_offset(Chunk::to_mem(ptr));
        let p = Chunk::plus_offset(ptr, offset);
        let size = size - offset;

        self.top = p;
        self.topsize = size;
        (*p).head = size | PINUSE;
        (*Chunk::plus_offset(p, size)).head = self.top_foot_size();
        self.trim_check = DEFAULT_TRIM_THRESHOLD;
    }
```

--------------------------------

### Configure Allocator Granularity

Source: https://docs.rs/dlmalloc/latest/src/dlmalloc/lib.rs.html

Sets the granularity for system allocations. Returns true if accepted, false otherwise. Granularity must be a power of two and at least twice the size of usize. This is a const fn, allowing configuration in const blocks.

```rust
pub const fn set_granularity(&mut self, granularity: usize) -> bool {
        self.0.set_granularity(granularity)
    }
```

```rust
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
};

```

--------------------------------

### c_free

Source: https://docs.rs/dlmalloc/latest/src/dlmalloc/lib.rs.html

Frees a memory block pointed to by `ptr`. A null `ptr` is a no-op. The `ptr` must have originated from this allocator instance.

```APIDOC
## c_free

### Description
Frees the memory block pointed to by `ptr`. If `ptr` is null, this operation is a no-op. The `ptr` must have been allocated by this allocator instance.

### Safety
- If non-null, `ptr` must originate from this allocator and must not have been freed already.

### Signature
`unsafe fn c_free(&mut self, ptr: *mut u8)`
```

--------------------------------

### GlobalAlloc for GlobalDlmalloc

Source: https://docs.rs/dlmalloc/latest/dlmalloc/struct.GlobalDlmalloc.html

This section details the methods available for the GlobalAlloc trait implemented by the GlobalDlmalloc struct, enabling its use as a global allocator.

```APIDOC
## GlobalAlloc for GlobalDlmalloc

### Description
Provides methods for memory allocation and deallocation when `GlobalDlmalloc` is used as the global allocator.

### Methods

#### `alloc(&self, layout: Layout) -> *mut u8`
Allocates memory as described by the given `layout`.

#### `dealloc(&self, ptr: *mut u8, layout: Layout)`
Deallocates the block of memory at the given `ptr` pointer with the given `layout`.

#### `alloc_zeroed(&self, layout: Layout) -> *mut u8`
Behaves like `alloc`, but also ensures that the contents are set to zero before being returned.

#### `realloc(&self, ptr: *mut u8, layout: Layout, new_size: usize) -> *mut u8`
Shrinks or grows a block of memory to the given `new_size` in bytes. The block is described by the given `ptr` pointer and `layout`.
```

--------------------------------

### c_memalign

Source: https://docs.rs/dlmalloc/latest/dlmalloc/struct.Dlmalloc.html

Allocates a specified number of bytes with a specified alignment. This function is a layout-free counterpart for wrapping C's `memalign` or `posix_memalign` ABIs. It returns a null pointer if allocation fails.

```APIDOC
## c_memalign

### Description
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.

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

### Parameters
#### Path Parameters
- **align** (usize) - The minimum alignment in bytes. Must be a power of two.
- **size** (usize) - The number of bytes to allocate.

### Returns
- ** *mut u8** - A pointer to the allocated memory, or a null pointer if allocation fails.

### Compatibility
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`.
```

--------------------------------

### Prepend Allocation in dlmalloc

Source: https://docs.rs/dlmalloc/latest/src/dlmalloc/dlmalloc.rs.html

Handles prepending a new memory region to the existing allocation. It ensures proper chunk sizing and updates internal pointers like 'top' and 'dv' if necessary. This is used when extending the heap with new memory.

```rust
unsafe fn prepend_alloc(&mut self, newbase: *mut u8, oldbase: *mut u8, size: usize) -> *mut u8 {
        let p = self.align_as_chunk(newbase);
        let mut oldfirst = self.align_as_chunk(oldbase);
        let psize = oldfirst as usize - p as usize;
        let q = Chunk::plus_offset(p, size);
        let mut qsize = psize - size;
        Chunk::set_size_and_pinuse_of_inuse_chunk(p, size);

        debug_assert!(oldfirst > q);
        debug_assert!(Chunk::pinuse(oldfirst));
        debug_assert!(qsize >= self.min_chunk_size());

        // consolidate the remainder with the first chunk of the old base
        if oldfirst == self.top {
            self.topsize += qsize;
            let tsize = self.topsize;
            self.top = q;
            (*q).head = tsize | PINUSE;
            self.check_top_chunk(q);
        } else if oldfirst == self.dv {
            self.dvsize += qsize;
            let dsize = self.dvsize;
            self.dv = q;
            Chunk::set_size_and_pinuse_of_free_chunk(q, dsize);
        } else {
            if !Chunk::inuse(oldfirst) {
                let nsize = Chunk::size(oldfirst);
                self.unlink_chunk(oldfirst, nsize);
                oldfirst = Chunk::plus_offset(oldfirst, nsize);
                qsize += nsize;
            }
            Chunk::set_free_with_pinuse(q, qsize, oldfirst);
            self.insert_chunk(q, qsize);
            self.check_free_chunk(q);
        }

        let ret = Chunk::to_mem(p);
        self.check_malloced_chunk(ret, size);
        self.check_malloc_state();
        return ret;
    }
```

--------------------------------

### Reallocate Memory (C ABI)

Source: https://docs.rs/dlmalloc/latest/src/dlmalloc/lib.rs.html

Reallocates a memory block to a new size, compatible with the C ABI's `realloc`. A null pointer behaves like `c_malloc`. The returned pointer is only guaranteed to be aligned to the natural malloc alignment.

```rust
pub unsafe fn c_realloc(&mut self, ptr: *mut u8, new_size: usize) -> *mut u8 {
    if ptr.is_null() {
        return self.c_malloc(new_size);
    }
    self.0.realloc(ptr, new_size)
}
```

--------------------------------

### Set chunk size and PINUSE flag for an in-use chunk

Source: https://docs.rs/dlmalloc/latest/src/dlmalloc/dlmalloc.rs.html

Sets the size and the PINUSE flag for an in-use chunk. Assumes CINUSE is already set or handled elsewhere.

```rust
unsafe fn set_size_and_pinuse_of_inuse_chunk(me: *mut Chunk, size: usize) {
        (*me).head = size | PINUSE | CINUSE;
    }
```

--------------------------------

### c_malloc

Source: https://docs.rs/dlmalloc/latest/src/dlmalloc/lib.rs.html

Allocates a block of memory of the specified size with the allocator's natural alignment. This function is designed to be compatible with the C `malloc` ABI.

```APIDOC
## c_malloc

### Description
Allocates `size` bytes of memory. The allocation is aligned to the allocator's natural alignment, which is `2 * size_of::<usize>()`. This method is a layout-free counterpart to `malloc` and is suitable for interfacing with C code.

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

### Parameters
#### Path Parameters
- `size` (usize) - The number of bytes to allocate. A size of 0 is accepted.

### Safety
This method is unsafe because the returned pointer, if non-null, points to uninitialized memory that must be managed (freed or reallocated) using the allocator's methods. The caller must ensure `size` is valid and handle the returned pointer appropriately.

### Returns
Returns a pointer to the allocated memory, or a null pointer if allocation fails. The memory is aligned to `2 * size_of::<usize>()`.
```

--------------------------------

### Set chunk as in use with CINUSE and PINUSE flags

Source: https://docs.rs/dlmalloc/latest/src/dlmalloc/dlmalloc.rs.html

Marks a chunk as in use, setting both CINUSE and PINUSE flags, and updates the next chunk's PINUSE flag.

```rust
unsafe fn set_inuse_and_pinuse(me: *mut Chunk, size: usize) {
        (*me).head = PINUSE | size | CINUSE;
        let next = Chunk::plus_offset(me, size);
        (*next).head |= PINUSE;
    }
```

--------------------------------

### Default Constructor Preserves Legacy Defaults

Source: https://docs.rs/dlmalloc/latest/src/dlmalloc/dlmalloc.rs.html

Verifies that the default constructor `Dlmalloc::new` maintains the pre-existing default values for granularity and max release check rate.

```rust
fn default_constructor_preserves_legacy_defaults() {
        let a = Dlmalloc::new(System::new());
        assert_eq!(a.granularity, 64 * 1024);
        assert_eq!(a.max_release_check_rate, 4095);
    }
```

--------------------------------

### c_malloc

Source: https://docs.rs/dlmalloc/latest/dlmalloc/struct.Dlmalloc.html

Allocates a specified number of bytes with the allocator's natural alignment. This is a layout-free function intended for wrapping the C `malloc` ABI. It returns a null pointer if allocation fails.

```APIDOC
## c_malloc

### Description
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.

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

### Parameters
#### Path Parameters
- **size** (usize) - The number of bytes to allocate.

### Returns
- ** *mut u8** - A pointer to the allocated memory, or 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.
```

--------------------------------

### Allocate System Memory (sys_alloc)

Source: https://docs.rs/dlmalloc/latest/src/dlmalloc/dlmalloc.rs.html

Handles the allocation of system memory resources. It calculates the aligned size, interacts with the system allocator, and updates internal state like footprint and segment information. This function is called when the allocator needs to obtain more memory from the operating system.

```rust
unsafe fn sys_alloc(&mut self, size: usize) -> *mut u8 {
        self.check_malloc_state();
        // keep in sync with max_request
        let asize = align_up(
            size + self.top_foot_size() + self.malloc_alignment(),
            self.granularity,
        );

        let (tbase, tsize, flags) = self.system_allocator.alloc(asize);
        if tbase.is_null() {
            return tbase;
        }

        self.footprint += tsize;
        self.max_footprint = cmp::max(self.max_footprint, self.footprint);

        if self.top.is_null() {
            if self.least_addr.is_null() || tbase < self.least_addr {
                self.least_addr = tbase;
            }
            self.seg.base = tbase;
            self.seg.size = tsize;
            self.seg.flags = flags;
            self.release_checks = self.release_check_target();
            self.init_bins();
            let tsize = tsize - self.top_foot_size();
            self.init_top(tbase.cast(), tsize);
        // let mn = Chunk::next(Chunk::from_mem(self as *mut _ as *mut u8));
        // let top_foot_size = self.top_foot_size();
        // self.init_top(mn, tbase as usize + tsize - mn as usize - top_foot_size);
        } else {
            let mut sp: *mut Segment = &mut self.seg;
            while !sp.is_null() && tbase != Segment::top(sp) {
                sp = (*sp).next;
            }
            if !sp.is_null()
                && !Segment::is_extern(sp)
                && Segment::sys_flags(sp) == flags
                && Segment::holds(sp, self.top.cast())
            {
                (*sp).size += tsize;
                let ptr = self.top;
                let size = self.topsize + tsize;
                self.init_top(ptr, size);
            } else {
                self.least_addr = cmp::min(tbase, self.least_addr);
                let mut sp: *mut Segment = &mut self.seg;
                while !sp.is_null() && (*sp).base != tbase.wrapping_add(tsize) {
                    sp = (*sp).next;
                }
                if !sp.is_null() && !Segment::is_extern(sp) && Segment::sys_flags(sp) == flags {
                    let oldbase = (*sp).base;
                    (*sp).base = tbase;
                    (*sp).size += tsize;
                    return self.prepend_alloc(tbase, oldbase, size);
                } else {
                    self.add_segment(tbase, tsize, flags);
                }
            }
        }

        if size < self.topsize {
            self.topsize -= size;
            let rsize = self.topsize;
            let p = self.top;
            self.top = Chunk::plus_offset(p, size);
            let r = self.top;
            (*r).head = rsize | PINUSE;
            Chunk::set_size_and_pinuse_of_inuse_chunk(p, size);
            let ret = Chunk::to_mem(p);
            self.check_top_chunk(self.top);
            self.check_malloced_chunk(ret, size);
            self.check_malloc_state();
            return ret;
        }

        return ptr::null_mut();
    }

```

--------------------------------

### Enable Allocator After Fork

Source: https://docs.rs/dlmalloc/latest/src/dlmalloc/unix.rs.html

Configures `pthread_atfork` handlers to ensure the global allocator remains usable in child processes after a fork. This function must be called before any allocations are made with the global allocator.

```rust
#[cfg(feature = "global")]
/// allows the allocator to remain unsable in the child process,
/// after a call to `fork(2)`
///
/// #Safety
///
/// if used, this function must be called,
/// before any allocations are made with the global allocator.
pub unsafe fn enable_alloc_after_fork() {
    // atfork must only be called once, to avoid a deadlock,
    // where the handler attempts to acquire the global lock twice
    static mut FORK_PROTECTED: bool = false;

    unsafe extern "C" fn _acquire_global_lock() {
        acquire_global_lock()
    }

    unsafe extern "C" fn _release_global_lock() {
        release_global_lock()
    }

    acquire_global_lock();
    // if a process forks,
    // it will acquire the lock before any other thread,
    // protecting it from deadlock,
    // due to the child being created with only the calling thread.
    if !FORK_PROTECTED {
        libc::pthread_atfork(
            Some(_acquire_global_lock),
            Some(_release_global_lock),
            Some(_release_global_lock),
        );
        FORK_PROTECTED = true;
    }
    release_global_lock();
}
```

--------------------------------

### Convert Request to Size

Source: https://docs.rs/dlmalloc/latest/src/dlmalloc/dlmalloc.rs.html

Converts a memory request size into the actual size that will be allocated, ensuring minimum size and alignment.

```rust
fn request2size(&self, req: usize) -> usize {
    if req < self.min_request() {
        self.min_chunk_size()
    } else {
        self.pad_request(req)
    }
}
```

--------------------------------

### Allocate Memory with C-style Malloc

Source: https://docs.rs/dlmalloc/latest/src/dlmalloc/lib.rs.html

Allocates `size` bytes at the allocator's natural alignment of `2 * size_of::<usize>()`. This is the layout-free counterpart of `Dlmalloc::malloc` for wrapping the C `malloc(size_t)` ABI.

```rust
pub unsafe fn c_malloc(&mut self, size: usize) -> *mut u8 {
        self.0.malloc(size)
    }
```

--------------------------------

### alloc Method - Allocator Trait

Source: https://docs.rs/dlmalloc/latest/dlmalloc/trait.Allocator.html

Allocates a system memory region of at least the specified size. Returns the base pointer, actual size, and flags describing the region. Returns null if allocation fails.

```rust
fn alloc(&self, size: usize) -> (*mut u8, usize, u32);
```

--------------------------------

### Dlmalloc::new_with_allocator

Source: https://docs.rs/dlmalloc/latest/dlmalloc/struct.Dlmalloc.html

Creates a new instance of the Dlmalloc allocator with a specified underlying allocator.

```APIDOC
## Dlmalloc::new_with_allocator

### Description
Creates a new instance of an allocator with a provided system allocator.

### Method
`new_with_allocator(sys_allocator: A) -> Dlmalloc<A>`

### Parameters
* `sys_allocator` (A) - The underlying allocator instance to use.
```

--------------------------------

### Allocate Zeroed Memory (calloc)

Source: https://docs.rs/dlmalloc/latest/dlmalloc/struct.Dlmalloc.html

Allocates memory similar to malloc, but guarantees that the allocated block is zeroed if the allocation succeeds. Returns a null pointer on failure.

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

--------------------------------

### c_realloc

Source: https://docs.rs/dlmalloc/latest/dlmalloc/struct.Dlmalloc.html

Reallocates a given pointer to a new size. This is a layout-free function for wrapping the C `realloc` ABI. It returns a null pointer if reallocation fails, in which case the original pointer remains valid.

```APIDOC
## c_realloc

### Description
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.

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

### Parameters
#### Path Parameters
- **ptr** (*mut u8) - A pointer to the memory block to be reallocated. If null, behaves like `c_malloc`.
- **new_size** (usize) - The desired new size in bytes.

### Returns
- ** *mut u8** - A pointer to the reallocated memory, or a null pointer if reallocation fails. If reallocation fails, the original `ptr` remains valid.

### 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`.
```

--------------------------------

### Pad Request Size

Source: https://docs.rs/dlmalloc/latest/src/dlmalloc/dlmalloc.rs.html

Aligns a requested memory amount upwards to meet the allocator's chunk overhead and alignment requirements.

```rust
fn pad_request(&self, amt: usize) -> usize {
    align_up(amt + self.chunk_overhead(), self.malloc_alignment())
}
```

--------------------------------

### enable_alloc_after_fork

Source: https://docs.rs/dlmalloc/latest/dlmalloc/fn.enable_alloc_after_fork.html

Enables the dlmalloc allocator to be used in a child process after a fork. This function must be called before any allocations are made with the global allocator.

```APIDOC
## enable_alloc_after_fork

### Description
Allows the allocator to remain usable in the child process after a call to `fork(2)`.

### Safety
If used, this function must be called before any allocations are made with the global allocator.

### Signature
```
pub unsafe fn enable_alloc_after_fork()
```
```

--------------------------------

### End-to-End Test: Custom Sub-Page Granularity Allocation

Source: https://docs.rs/dlmalloc/latest/src/dlmalloc/dlmalloc.rs.html

Tests dlmalloc's consistency when using a sub-page granularity, which is relevant for embedded systems. It verifies that allocations and deallocations work correctly even when dlmalloc's internal granularity is smaller than the system's page size.

```rust
    // End-to-end: sub-page granularity (the embedded-target use case the
    // configurable granularity was added for). The system allocator may
    // still round individual requests up to its page size, but dlmalloc
    // itself must remain consistent.
    #[test]
    #[cfg(not(miri))]
    fn custom_sub_page_granularity_alloc_free() {
        let sub_page = MIN_GRANULARITY * 2;
        assert!(sub_page < System::new().page_size());
        let mut a = Dlmalloc::new(System::new());
        assert!(a.set_granularity(sub_page));
        assert_eq!(a.granularity, sub_page);
        unsafe {
            let mut ptrs = [ptr::null_mut::<u8>(); 16];
            for (i, slot) in ptrs.iter_mut().enumerate() {
                let p = a.malloc(64 + i * 7);
                assert!(!p.is_null());

```

--------------------------------

### System Trim Function

Source: https://docs.rs/dlmalloc/latest/src/dlmalloc/dlmalloc.rs.html

Attempts to trim unused memory segments from the system. It calculates the amount of memory to release and interacts with the system allocator. Returns true if any memory was released.

```rust
    unsafe fn sys_trim(&mut self, mut pad: usize) -> bool {
        let mut released = 0;
        if pad < self.max_request() && !self.top.is_null() {
            pad += self.top_foot_size();
            if self.topsize > pad {
                let unit = self.granularity;
                let extra = ((self.topsize - pad + unit - 1) / unit - 1) * unit;
                let sp = self.segment_holding(self.top.cast());
                debug_assert!(!sp.is_null());

                if !Segment::is_extern(sp) {
                    if Segment::can_release_part(&self.system_allocator, sp) {
                        if (*sp).size >= extra && !self.has_segment_link(sp) {
                            let newsize = (*sp).size - extra;
                            if self
                                .system_allocator
                                .free_part((*sp).base, (*sp).size, newsize)
                            {
                                released = extra;
                            }
                        }
                    }
                }

                if released != 0 {
                    (*sp).size -= released;
                    self.footprint -= released;
                    let top = self.top;
                    let topsize = self.topsize - released;
                    self.init_top(top, topsize);
                    self.check_top_chunk(self.top);
                }
            }

            released += self.release_unused_segments();

            if released == 0 && self.topsize > self.trim_check {
                self.trim_check = usize::max_value();
            }
        }

        released != 0
    }
```

--------------------------------

### Allocate Memory with Alignment

Source: https://docs.rs/dlmalloc/latest/src/dlmalloc/lib.rs.html

Allocates a specified number of bytes with a given alignment. Returns a null pointer on failure. Handles zero-sized allocations similarly to c_malloc.

```rust
pub unsafe fn malloc(&mut self, size: usize, align: usize) -> *mut u8 {
        self.c_memalign(align, size)
    }
```
Tokens:
Raw