Module drone_core::heap

Dynamic memory allocation.

Dynamic memory is crucial for Drone operation. Objectives like real-time characteristics, high concurrency, small code size, fast execution have led to Memory Pools design of the heap. All operations are lock-free and have O(1) time complexity, which means they are deterministic.

The continuous memory region for the heap is split into pools. A pool is further split into fixed-sized blocks that hold actual allocations. A pool is defined by its block-size and the number of blocks. The pools configuration should be defined in the compile-time. A drawback of this approach is that memory pools may need to be tuned for the application.

Usage

Add the heap configuration to the Drone.toml:

[heap]
size = "10K"
pools = [
    { block = "4", capacity = 896 },
    { block = "32", capacity = 80 },
    { block = "256", capacity = 16 },
]

The size field should match the resulting size of the pools.

Then in the application code:

use drone_core::heap;

// Define a concrete heap type with the layout defined in the Drone.toml
heap! {
    // Heap configuration key in `Drone.toml`.
    config => main;
    /// The main heap allocator generated from the `Drone.toml`.
    metadata => pub Heap;
    // Use this heap as the global allocator.
    global => true;
    // Uncomment the following line to enable heap tracing feature:
    // trace_port => 31;
}

// Create a static instance of the heap type and declare it as the global
// allocator.
/// The global allocator.
#[global_allocator]
pub static HEAP: Heap = Heap::new();

Tuning

Using empiric values for the memory pools layout may lead to undesired memory fragmentation. Eventually the layout will need to be tuned for the application. Drone can capture allocation statistics from the real target device at the run-time and generate an optimized memory layout for this specific application. Ideally this will result in zero fragmentation.

The actual steps are platform-specific. Refer to the platform crate documentation for instructions.

Structs

Pool	The set of free memory blocks.

Constants

HEAPTRACE_KEY

XOR pattern for heap trace output.

Traits

Allocator

Allocator for a generic memory pools layout.

Functions

binary_search

Does a binary search for the pool with the smallest block size to fit value.