static friendly data structures that don't require dynamic memory allocation
The core principle behind
heapless is that its data structures are backed by a static memory
allocation. For example, you can think of
heapless::Vec as an alternative version of
std::Vec with fixed capacity and that can't be re-allocated on the fly (e.g. via
heapless data structures store their memory allocation inline and specify their capacity
via their type parameter
N. This means that you can instantiate a
heapless data structure on
the stack, in a
static variable, or even in the heap.
use heapless::Vec; // fixed capacity `std::Vec` use heapless::consts::U8; // type level integer used to specify capacity // on the stack let mut xs: Vec<u8, U8> = Vec::new(); // can hold up to 8 elements xs.push(42).unwrap(); assert_eq!(xs.pop(), Some(42)); // in a `static` variable static mut XS: Vec<u8, U8> = Vec::new(); // in the heap (though kind of pointless because no reallocation) let mut ys: Box<Vec<u8, U8>> = Box::new(Vec::new()); ys.push(42).unwrap(); assert_eq!(ys.pop(), Some(42));
Because they have fixed capacity
heapless data structures don't implicitly reallocate. This
means that operations like
heapless::Vec.push are truly constant time rather than amortized
constant time with potentially unbounded (depends on the allocator) worst case execution time
(which is bad / unacceptable for hard real time applications).
heapless data structures don't use a memory allocator which means no risk of an uncatchable
Out Of Memory (OOM) condition (which defaults to abort) while performing operations
on them. It's certainly possible to run out of capacity while growing
structures, but the API lets you handle this possibility by returning a
Result on operations
that may exhaust the capacity of the data structure.
List of currently implemented data structures:
A priority queue implemented with a binary heap.
Type aliases for many constants.
A fixed capacity map / dictionary that performs lookups via linear search
A fixed capacity
A fixed capacity