heapless/
lib.rs

Help
1//! `static` friendly data structures that don't require dynamic memory allocation
2//!
3//! The core principle behind `heapless` is that its data structures are backed by a *static* memory
4//! allocation. For example, you can think of `heapless::Vec` as an alternative version of
5//! `std::Vec` with fixed capacity and that can't be re-allocated on the fly (e.g. via `push`).
6//!
7//! All `heapless` data structures store their memory allocation *inline* and specify their capacity
8//! via their type parameter `N`. This means that you can instantiate a `heapless` data structure on
9//! the stack, in a `static` variable, or even in the heap.
10//!
11//! ```
12//! use heapless::Vec; // fixed capacity `std::Vec`
13//!
14//! // on the stack
15//! let mut xs: Vec<u8, 8> = Vec::new(); // can hold up to 8 elements
16//! xs.push(42).unwrap();
17//! assert_eq!(xs.pop(), Some(42));
18//!
19//! // in a `static` variable
20//! static mut XS: Vec<u8, 8> = Vec::new();
21//!
22//! let xs = unsafe { &mut XS };
23//!
24//! xs.push(42);
25//! assert_eq!(xs.pop(), Some(42));
26//!
27//! // in the heap (though kind of pointless because no reallocation)
28//! let mut ys: Box<Vec<u8, 8>> = Box::new(Vec::new());
29//! ys.push(42).unwrap();
30//! assert_eq!(ys.pop(), Some(42));
31//! ```
32//!
33//! Because they have fixed capacity `heapless` data structures don't implicitly reallocate. This
34//! means that operations like `heapless::Vec.push` are *truly* constant time rather than amortized
35//! constant time with potentially unbounded (depends on the allocator) worst case execution time
36//! (which is bad / unacceptable for hard real time applications).
37//!
38//! `heapless` data structures don't use a memory allocator which means no risk of an uncatchable
39//! Out Of Memory (OOM) condition while performing operations on them. It's certainly possible to
40//! run out of capacity while growing `heapless` data structures, but the API lets you handle this
41//! possibility by returning a `Result` on operations that may exhaust the capacity of the data
42//! structure.
43//!
44//! List of currently implemented data structures:
45//!
46//! - [`Arc`](pool/singleton/arc/struct.Arc.html) -- Thread-safe reference-counting pointer backed by a memory pool
47//! - [`BinaryHeap`](binary_heap/struct.BinaryHeap.html) -- priority queue
48//! - [`IndexMap`](struct.IndexMap.html) -- hash table
49//! - [`IndexSet`](struct.IndexSet.html) -- hash set
50//! - [`LinearMap`](struct.LinearMap.html)
51//! - [`Pool`](pool/struct.Pool.html) -- lock-free memory pool
52//! - [`String`](struct.String.html)
53//! - [`Vec`](struct.Vec.html)
54//! - [`mpmc::Q*`](mpmc/index.html) -- multiple producer multiple consumer lock-free queue
55//! - [`spsc::Queue`](spsc/struct.Queue.html) -- single producer single consumer lock-free queue
56//!
57//! # Optional Features
58//!
59//! The `heapless` crate provides the following optional Cargo features:
60//!
61//! - `ufmt-impl`: Implement [`ufmt_write::uWrite`] for `String<N>` and `Vec<u8, N>`
62//!
63//! [`ufmt_write::uWrite`]: https://docs.rs/ufmt-write/
64//!
65//! # Minimum Supported Rust Version (MSRV)
66//!
67//! This crate is guaranteed to compile on stable Rust 1.51 and up with its default set of features.
68//! It *might* compile on older versions but that may change in any new patch release.
69
70#![cfg_attr(not(test), no_std)]
71#![deny(missing_docs)]
72#![deny(rust_2018_compatibility)]
73#![deny(rust_2018_idioms)]
74#![deny(warnings)]
75
76pub use binary_heap::BinaryHeap;
77pub use deque::Deque;
78pub use histbuf::{HistoryBuffer, OldestOrdered};
79pub use indexmap::{Bucket, Entry, FnvIndexMap, IndexMap, OccupiedEntry, Pos, VacantEntry};
80pub use indexset::{FnvIndexSet, IndexSet};
81pub use linear_map::LinearMap;
82#[cfg(all(has_cas, feature = "cas"))]
83pub use pool::singleton::arc::Arc;
84pub use string::String;
85pub use vec::Vec;
86
87#[macro_use]
88#[cfg(test)]
89mod test_helpers;
90
91mod deque;
92mod histbuf;
93mod indexmap;
94mod indexset;
95mod linear_map;
96mod string;
97mod vec;
98
99#[cfg(feature = "serde")]
100mod de;
101#[cfg(feature = "serde")]
102mod ser;
103
104pub mod binary_heap;
105#[cfg(feature = "defmt-impl")]
106mod defmt;
107#[cfg(all(has_cas, feature = "cas"))]
108pub mod mpmc;
109#[cfg(all(has_cas, feature = "cas"))]
110pub mod pool;
111pub mod sorted_linked_list;
112#[cfg(has_atomics)]
113pub mod spsc;
114
115#[cfg(feature = "ufmt-impl")]
116mod ufmt;
117
118mod sealed;
heapless/lib.rs

heapless/
lib.rs
