Crate heapless[−][src]

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 push).

All 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
// (because `const-fn` has not been fully stabilized you need to use the helper structs in
// the `i` module, which must be wrapped in a tuple struct)
static mut XS: Vec<u8, U8> = Vec(heapless::i::Vec::new());

let xs = unsafe { &mut XS };

xs.push(42);
assert_eq!(xs.pop(), Some(42));

// 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 while performing operations on them. It’s certainly possible to run out of capacity while growing heapless data 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:

BinaryHeap – priority queue
IndexMap – hash table
IndexSet – hash set
LinearMap
Pool – lock-free memory pool
String
Vec
mpmc::Q* – multiple producer multiple consumer lock-free queue
spsc::Queue – single producer single consumer lock-free queue

Optional Features

The heapless crate provides the following optional Cargo features:

ufmt-impl: Implement ufmt_write::uWrite for String<N> and Vec<u8, N>

Minimum Supported Rust Version (MSRV)

This crate is guaranteed to compile on stable Rust 1.36 and up with its default set of features. It might compile on older versions but that may change in any new patch release.

Re-exports

pub use binary_heap::BinaryHeap;

Modules

binary_heap	A priority queue implemented with a binary heap.
consts	Type aliases for many constants.
i	Unfortunate implementation detail required to construct `heapless` types in const context
mpmc	A fixed capacity Multiple-Producer Multiple-Consumer (MPMC) lock-free queue
pool	A heap-less, interrupt-safe, lock-free memory pool (*)
spsc	Fixed capacity Single Producer Single Consumer (SPSC) queue

Structs

HistoryBuffer	A “history buffer”, similar to a write-only ring buffer of fixed length.
IndexMap	Fixed capacity `IndexMap`
IndexSet	Fixed capacity `IndexSet`.
LinearMap	A fixed capacity map / dictionary that performs lookups via linear search
String	A fixed capacity `String`
Vec	A fixed capacity `Vec`

Traits

ArrayLength	Trait making `GenericArray` work, marking types to be used as length of an array
PowerOfTwo	The marker trait for type-level numbers which are a power of two.

Type Definitions

FnvIndexMap	A `heaples::IndexMap` using the default FNV hasher
FnvIndexSet	A `heapless::IndexSet` using the default FNV hasher. A list of all Methods and Traits available for `FnvIndexSet` can be found in the `heapless::IndexSet` documentation.