Crate heapless

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`

// on the stack
let mut xs: Vec<u8, 8> = 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, 8> = 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, 8>> = 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
• 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: Implement ufmt_write::uWrite for String<N> and Vec<u8, N>

Minimum Supported Rust Version (MSRV)

This crate does not have a Minimum Supported Rust Version (MSRV) and may make use of language features and API in the standard library available in the latest stable Rust version.

In other words, changes in the Rust version requirement of this crate are not considered semver breaking change and may occur in patch version releases.

Re-exports

• pub use binary_heap::BinaryHeap;
• pub use indexmap::Bucket;
• pub use indexmap::Pos;

Modules

• binary_heap
  A priority queue implemented with a binary heap.
• mpmc
  A fixed capacity Multiple-Producer Multiple-Consumer (MPMC) lock-free queue
• sorted_linked_list
  A fixed sorted priority linked list, similar to BinaryHeap but with different properties on push, pop, etc. For example, the sorting of the list will never memcpy the underlying value, so having large objects in the list will not cause a performance hit.
• spsc
  Fixed capacity Single Producer Single Consumer (SPSC) queue

Structs

• Deque
  A fixed capacity double-ended queue.
• HistoryBuffer
  A “history buffer”, similar to a write-only ring buffer of fixed length.
• IndexMap
  Fixed capacity IndexMap
• IndexMapIter
  An iterator over the items of a IndexMap.
• IndexMapIterMut
  A mutable iterator over the items of a IndexMap.
• IndexMapKeys
  An iterator over the keys of a IndexMap.
• IndexMapValues
  An iterator over the values of a IndexMap.
• IndexMapValuesMut
  A mutable iterator over the values of a IndexMap.
• IndexSet
  Fixed capacity IndexSet.
• IndexSetIter
  An iterator over the items of a IndexSet.
• LinearMap
  A fixed capacity map / dictionary that performs lookups via linear search
• OccupiedEntry
  An occupied entry which can be manipulated
• OldestOrdered
  An iterator on the underlying buffer ordered from oldest data to newest
• String
  A fixed capacity String
• VacantEntry
  A view into an empty slot in the underlying map
• Vec
  A fixed capacity Vec

Enums

• Entry
  A view into an entry in the map

Type Aliases

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