mirror/rtic
1
0
Fork 0
mirror of https://github.com/rtic-rs/rtic.git synced 2024-11-26 05:29:38 +01:00
Code Issues Projects Releases Packages Wiki Activity
rtic/1/api/heapless/index.html
korken89 d78e02850b deploy: d251ba7173
2024-10-24 05:57:30 +00:00

64 lines
No EOL
14 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><meta name="generator" content="rustdoc"><meta name="description" content="`static` friendly data structures that don’t require dynamic memory allocation"><title>heapless - Rust</title><script>if(window.location.protocol!=="file:")document.head.insertAdjacentHTML("beforeend","SourceSerif4-Regular-46f98efaafac5295.ttf.woff2,FiraSans-Regular-018c141bf0843ffd.woff2,FiraSans-Medium-8f9a781e4970d388.woff2,SourceCodePro-Regular-562dcc5011b6de7d.ttf.woff2,SourceCodePro-Semibold-d899c5a5c4aeb14a.ttf.woff2".split(",").map(f=>`<link rel="preload" as="font" type="font/woff2" crossorigin href="../static.files/${f}">`).join(""))</script><link rel="stylesheet" href="../static.files/normalize-76eba96aa4d2e634.css"><link rel="stylesheet" href="../static.files/rustdoc-492a78a4a87dcc01.css"><meta name="rustdoc-vars" data-root-path="../" data-static-root-path="../static.files/" data-current-crate="heapless" data-themes="" data-resource-suffix="" data-rustdoc-version="1.82.0 (f6e511eec 2024-10-15)" data-channel="1.82.0" data-search-js="search-a99f1315e7cc5121.js" data-settings-js="settings-4313503d2e1961c2.js" ><script src="../static.files/storage-118b08c4c78b968e.js"></script><script defer src="../crates.js"></script><script defer src="../static.files/main-921df33f47b8780c.js"></script><noscript><link rel="stylesheet" href="../static.files/noscript-3b12f09e550e0385.css"></noscript><link rel="alternate icon" type="image/png" href="../static.files/favicon-32x32-422f7d1d52889060.png"><link rel="icon" type="image/svg+xml" href="../static.files/favicon-2c020d218678b618.svg"></head><body class="rustdoc mod crate"><!--[if lte IE 11]><div class="warning">This old browser is unsupported and will most likely display funky things.</div><![endif]--><nav class="mobile-topbar"><button class="sidebar-menu-toggle" title="show sidebar"></button></nav><nav class="sidebar"><div class="sidebar-crate"><h2><a href="../heapless/index.html">heapless</a><span class="version">0.7.17</span></h2></div><div class="sidebar-elems"><ul class="block"><li><a id="all-types" href="all.html">All Items</a></li></ul><section><ul class="block"><li><a href="#reexports">Re-exports</a></li><li><a href="#modules">Modules</a></li><li><a href="#structs">Structs</a></li><li><a href="#enums">Enums</a></li><li><a href="#types">Type Aliases</a></li></ul></section></div></nav><div class="sidebar-resizer"></div><main><div class="width-limiter"><rustdoc-search></rustdoc-search><section id="main-content" class="content"><div class="main-heading"><h1>Crate <a class="mod" href="#">heapless</a><button id="copy-path" title="Copy item path to clipboard">Copy item path</button></h1><span class="out-of-band"><a class="src" href="../src/heapless/lib.rs.html#1-118">source</a> · <button id="toggle-all-docs" title="collapse all docs">[<span>&#x2212;</span>]</button></span></div><details class="toggle top-doc" open><summary class="hideme"><span>Expand description</span></summary><div class="docblock"><p><code>static</code> friendly data structures that don’t require dynamic memory allocation</p>
<p>The core principle behind <code>heapless</code> is that its data structures are backed by a <em>static</em> memory
allocation. For example, you can think of <code>heapless::Vec</code> as an alternative version of
<code>std::Vec</code> with fixed capacity and that can’t be re-allocated on the fly (e.g. via <code>push</code>).</p>
<p>All <code>heapless</code> data structures store their memory allocation <em>inline</em> and specify their capacity
via their type parameter <code>N</code>. This means that you can instantiate a <code>heapless</code> data structure on
the stack, in a <code>static</code> variable, or even in the heap.</p>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>heapless::Vec; <span class="comment">// fixed capacity `std::Vec`
// on the stack
</span><span class="kw">let </span><span class="kw-2">mut </span>xs: Vec&lt;u8, <span class="number">8</span>&gt; = Vec::new(); <span class="comment">// can hold up to 8 elements
</span>xs.push(<span class="number">42</span>).unwrap();
<span class="macro">assert_eq!</span>(xs.pop(), <span class="prelude-val">Some</span>(<span class="number">42</span>));
<span class="comment">// in a `static` variable
</span><span class="kw">static </span><span class="kw-2">mut </span>XS: Vec&lt;u8, <span class="number">8</span>&gt; = Vec::new();
<span class="kw">let </span>xs = <span class="kw">unsafe </span>{ <span class="kw-2">&amp;mut </span>XS };
xs.push(<span class="number">42</span>);
<span class="macro">assert_eq!</span>(xs.pop(), <span class="prelude-val">Some</span>(<span class="number">42</span>));
<span class="comment">// in the heap (though kind of pointless because no reallocation)
</span><span class="kw">let </span><span class="kw-2">mut </span>ys: Box&lt;Vec&lt;u8, <span class="number">8</span>&gt;&gt; = Box::new(Vec::new());
ys.push(<span class="number">42</span>).unwrap();
<span class="macro">assert_eq!</span>(ys.pop(), <span class="prelude-val">Some</span>(<span class="number">42</span>));</code></pre></div>
<p>Because they have fixed capacity <code>heapless</code> data structures don’t implicitly reallocate. This
means that operations like <code>heapless::Vec.push</code> are <em>truly</em> 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).</p>
<p><code>heapless</code> 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 <code>heapless</code> data structures, but the API lets you handle this
possibility by returning a <code>Result</code> on operations that may exhaust the capacity of the data
structure.</p>
<p>List of currently implemented data structures:</p>
<ul>
<li><a href="pool/singleton/arc/struct.Arc.html"><code>Arc</code></a> – Thread-safe reference-counting pointer backed by a memory pool</li>
<li><a href="binary_heap/struct.BinaryHeap.html"><code>BinaryHeap</code></a> – priority queue</li>
<li><a href="struct.IndexMap.html"><code>IndexMap</code></a> – hash table</li>
<li><a href="struct.IndexSet.html"><code>IndexSet</code></a> – hash set</li>
<li><a href="struct.LinearMap.html"><code>LinearMap</code></a></li>
<li><a href="pool/struct.Pool.html"><code>Pool</code></a> – lock-free memory pool</li>
<li><a href="struct.String.html"><code>String</code></a></li>
<li><a href="struct.Vec.html"><code>Vec</code></a></li>
<li><a href="mpmc/index.html"><code>mpmc::Q*</code></a> – multiple producer multiple consumer lock-free queue</li>
<li><a href="spsc/struct.Queue.html"><code>spsc::Queue</code></a> – single producer single consumer lock-free queue</li>
</ul>
<h2 id="optional-features"><a class="doc-anchor" href="#optional-features">§</a>Optional Features</h2>
<p>The <code>heapless</code> crate provides the following optional Cargo features:</p>
<ul>
<li><code>ufmt-impl</code>: Implement <a href="https://docs.rs/ufmt-write/"><code>ufmt_write::uWrite</code></a> for <code>String&lt;N&gt;</code> and <code>Vec&lt;u8, N&gt;</code></li>
</ul>
<h2 id="minimum-supported-rust-version-msrv"><a class="doc-anchor" href="#minimum-supported-rust-version-msrv">§</a>Minimum Supported Rust Version (MSRV)</h2>
<p>This crate is guaranteed to compile on stable Rust 1.51 and up with its default set of features.
It <em>might</em> compile on older versions but that may change in any new patch release.</p>
</div></details><h2 id="reexports" class="section-header">Re-exports<a href="#reexports" class="anchor">§</a></h2><ul class="item-table"><li><div class="item-name" id="reexport.BinaryHeap"><code>pub use binary_heap::<a class="struct" href="binary_heap/struct.BinaryHeap.html" title="struct heapless::binary_heap::BinaryHeap">BinaryHeap</a>;</code></div></li><li><div class="item-name" id="reexport.Bucket"><code>pub use indexmap::Bucket;</code></div></li><li><div class="item-name" id="reexport.Pos"><code>pub use indexmap::Pos;</code></div></li><li><div class="item-name" id="reexport.Arc"><code>pub use pool::singleton::arc::<a class="struct" href="pool/singleton/arc/struct.Arc.html" title="struct heapless::pool::singleton::arc::Arc">Arc</a>;</code></div></li></ul><h2 id="modules" class="section-header">Modules<a href="#modules" class="anchor">§</a></h2><ul class="item-table"><li><div class="item-name"><a class="mod" href="binary_heap/index.html" title="mod heapless::binary_heap">binary_<wbr>heap</a></div><div class="desc docblock-short">A priority queue implemented with a binary heap.</div></li><li><div class="item-name"><a class="mod" href="mpmc/index.html" title="mod heapless::mpmc">mpmc</a></div><div class="desc docblock-short">A fixed capacity Multiple-Producer Multiple-Consumer (MPMC) lock-free queue</div></li><li><div class="item-name"><a class="mod" href="pool/index.html" title="mod heapless::pool">pool</a></div><div class="desc docblock-short">A heap-less, interrupt-safe, lock-free memory pool (*)</div></li><li><div class="item-name"><a class="mod" href="sorted_linked_list/index.html" title="mod heapless::sorted_linked_list">sorted_<wbr>linked_<wbr>list</a></div><div class="desc docblock-short">A fixed sorted priority linked list, similar to <a href="binary_heap/struct.BinaryHeap.html" title="struct heapless::binary_heap::BinaryHeap"><code>BinaryHeap</code></a> but with different properties
on <code>push</code>, <code>pop</code>, etc.
For example, the sorting of the list will never <code>memcpy</code> the underlying value, so having large
objects in the list will not cause a performance hit.</div></li><li><div class="item-name"><a class="mod" href="spsc/index.html" title="mod heapless::spsc">spsc</a></div><div class="desc docblock-short">Fixed capacity Single Producer Single Consumer (SPSC) queue</div></li></ul><h2 id="structs" class="section-header">Structs<a href="#structs" class="anchor">§</a></h2><ul class="item-table"><li><div class="item-name"><a class="struct" href="struct.Deque.html" title="struct heapless::Deque">Deque</a></div><div class="desc docblock-short">A fixed capacity double-ended queue.</div></li><li><div class="item-name"><a class="struct" href="struct.HistoryBuffer.html" title="struct heapless::HistoryBuffer">History<wbr>Buffer</a></div><div class="desc docblock-short">A “history buffer”, similar to a write-only ring buffer of fixed length.</div></li><li><div class="item-name"><a class="struct" href="struct.IndexMap.html" title="struct heapless::IndexMap">Index<wbr>Map</a></div><div class="desc docblock-short">Fixed capacity <a href="https://docs.rs/indexmap/1/indexmap/map/struct.IndexMap.html"><code>IndexMap</code></a></div></li><li><div class="item-name"><a class="struct" href="struct.IndexSet.html" title="struct heapless::IndexSet">Index<wbr>Set</a></div><div class="desc docblock-short">Fixed capacity <a href="https://docs.rs/indexmap/1/indexmap/set/struct.IndexSet.html"><code>IndexSet</code></a>.</div></li><li><div class="item-name"><a class="struct" href="struct.LinearMap.html" title="struct heapless::LinearMap">Linear<wbr>Map</a></div><div class="desc docblock-short">A fixed capacity map / dictionary that performs lookups via linear search</div></li><li><div class="item-name"><a class="struct" href="struct.OccupiedEntry.html" title="struct heapless::OccupiedEntry">Occupied<wbr>Entry</a></div><div class="desc docblock-short">An occupied entry which can be manipulated</div></li><li><div class="item-name"><a class="struct" href="struct.OldestOrdered.html" title="struct heapless::OldestOrdered">Oldest<wbr>Ordered</a></div><div class="desc docblock-short">An iterator on the underlying buffer ordered from oldest data to newest</div></li><li><div class="item-name"><a class="struct" href="struct.String.html" title="struct heapless::String">String</a></div><div class="desc docblock-short">A fixed capacity <a href="https://doc.rust-lang.org/std/string/struct.String.html"><code>String</code></a></div></li><li><div class="item-name"><a class="struct" href="struct.VacantEntry.html" title="struct heapless::VacantEntry">Vacant<wbr>Entry</a></div><div class="desc docblock-short">A view into an empty slot in the underlying map</div></li><li><div class="item-name"><a class="struct" href="struct.Vec.html" title="struct heapless::Vec">Vec</a></div><div class="desc docblock-short">A fixed capacity <a href="https://doc.rust-lang.org/std/vec/struct.Vec.html"><code>Vec</code></a></div></li></ul><h2 id="enums" class="section-header">Enums<a href="#enums" class="anchor">§</a></h2><ul class="item-table"><li><div class="item-name"><a class="enum" href="enum.Entry.html" title="enum heapless::Entry">Entry</a></div><div class="desc docblock-short">A view into an entry in the map</div></li></ul><h2 id="types" class="section-header">Type Aliases<a href="#types" class="anchor">§</a></h2><ul class="item-table"><li><div class="item-name"><a class="type" href="type.FnvIndexMap.html" title="type heapless::FnvIndexMap">FnvIndex<wbr>Map</a></div><div class="desc docblock-short">A <a href="./struct.IndexMap.html"><code>heapless::IndexMap</code></a> using the default FNV hasher</div></li><li><div class="item-name"><a class="type" href="type.FnvIndexSet.html" title="type heapless::FnvIndexSet">FnvIndex<wbr>Set</a></div><div class="desc docblock-short">A <a href="./struct.IndexSet.html"><code>heapless::IndexSet</code></a> using the
default FNV hasher.
A list of all Methods and Traits available for <code>FnvIndexSet</code> can be found in
the <a href="./struct.IndexSet.html"><code>heapless::IndexSet</code></a> documentation.</div></li></ul></section></div></main></body></html>
Reference in a new issue View git blame Copy permalink