# Crate arduboy_rust::heapless

source ·
Expand description

`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:

- `Arc` – Thread-safe reference-counting pointer backed by a memory pool
- `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.51 and up with its default set of features. It might compile on older versions but that may change in any new patch release.

## Modules

- binary_heap
  A priority queue implemented with a binary heap.
- 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.

## Structs

- BinaryHeap
  A priority queue implemented with a binary heap.
- 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`
- IndexSet
  Fixed capacity `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 Definitions

- FnvIndexMap
  A `heapless::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.