<main><divclass="width-limiter"><navclass="sub"><formclass="search-form"><span></span><divid="sidebar-button"tabindex="-1"><ahref="../sharded_slab/all.html"title="show sidebar"></a></div><inputclass="search-input"name="search"aria-label="Run search in the documentation"autocomplete="off"spellcheck="false"placeholder="Click or press ‘S’ to search, ‘?’ for more options…"type="search"><divid="help-button"tabindex="-1"><ahref="../help.html"title="help">?</a></div><divid="settings-menu"tabindex="-1"><ahref="../settings.html"title="settings"><imgwidth="22"height="22"alt="Change settings"src="../static.files/wheel-7b819b6101059cd0.svg"></a></div></form></nav><sectionid="main-content"class="content"><divclass="main-heading"><h1>Crate <aclass="mod"href="#">sharded_slab</a><buttonid="copy-path"title="Copy item path to clipboard"><imgsrc="../static.files/clipboard-7571035ce49a181d.svg"width="19"height="18"alt="Copy item path"></button></h1><spanclass="out-of-band"><aclass="src"href="../src/sharded_slab/lib.rs.html#1-1106">source</a> · <buttonid="toggle-all-docs"title="collapse all docs">[<span>−</span>]</button></span></div><detailsclass="toggle top-doc"open><summaryclass="hideme"><span>Expand description</span></summary><divclass="docblock"><p>A lock-free concurrent slab.</p>
<p>Slabs provide pre-allocated storage for many instances of a single data
type. When a large number of values of a single type are required,
this can be more efficient than allocating each item individually. Since the
allocated items are the same size, memory fragmentation is reduced, and
creating and removing new items can be very cheap.</p>
<p>This crate implements a lock-free concurrent slab, indexed by <code>usize</code>s.</p>
<p>This crate provides two types, <ahref="https://crates.io/crates/loom"><code>Slab</code></a> and <ahref="struct.Pool.html"title="struct sharded_slab::Pool"><code>Pool</code></a>, which provide
slightly different APIs for using a sharded slab.</p>
<p><ahref="https://crates.io/crates/loom"><code>Slab</code></a> implements a slab for <em>storing</em> small types, sharing them between
threads, and accessing them by index. New entries are allocated by
<ahref="struct.Slab.html#method.insert"title="method sharded_slab::Slab::insert">inserting</a> data, moving it in by value. Similarly, entries may be
deallocated by <ahref="struct.Slab.html#method.take"title="method sharded_slab::Slab::take">taking</a> from the slab, moving the value out. This API is
similar to a <code>Vec<Option<T>></code>, but allowing lock-free concurrent insertion
and removal.</p>
<p>In contrast, the <ahref="struct.Pool.html"title="struct sharded_slab::Pool"><code>Pool</code></a> type provides an <ahref="https://en.wikipedia.org/wiki/Object_pool_pattern">object pool</a> style API for
<em>reusing storage</em>. Rather than constructing values and moving them into the
pool, as with <ahref="https://crates.io/crates/loom"><code>Slab</code></a>, <ahref="struct.Pool.html#method.create"title="method sharded_slab::Pool::create">allocating an entry</a> from the pool takes a
closure that’s provided with a mutable reference to initialize the entry in
place. When entries are deallocated, they are <ahref="trait.Clear.html"title="trait sharded_slab::Clear">cleared</a> in place. Types
which own a heap allocation can be cleared by dropping any <em>data</em> they
store, but retaining any previously-allocated capacity. This means that a
<ahref="struct.Pool.html"title="struct sharded_slab::Pool"><code>Pool</code></a> may be used to reuse a set of existing heap allocations, reducing
<p>These graphs were produced by <ahref="https://github.com/hawkw/sharded-slab/blob/master/benches/bench.rs">benchmarks</a> of the sharded slab implementation,
using the <ahref="https://crates.io/crates/criterion"><code>criterion</code></a> crate.</p>
<p>The first shows the results of a benchmark where an increasing number of
items are inserted and then removed into a slab concurrently by five
threads. It compares the performance of the sharded slab implementation
with a <code>RwLock<slab::Slab></code>:</p>
<imgwidth="1124"alt="Screen Shot 2019-10-01 at 5 09 49 PM"src="https://user-images.githubusercontent.com/2796466/66078398-cd6c9f80-e516-11e9-9923-0ed6292e8498.png">
<p>The second graph shows the results of a benchmark where an increasing
number of items are inserted and then removed by a <em>single</em> thread. It
compares the performance of the sharded slab implementation with an
<code>RwLock<slab::Slab></code> and a <code>mut slab::Slab</code>.</p>
<imgwidth="925"alt="Screen Shot 2019-10-01 at 5 13 45 PM"src="https://user-images.githubusercontent.com/2796466/66078469-f0974f00-e516-11e9-95b5-f65f0aa7e494.png">
<p>These benchmarks demonstrate that, while the sharded approach introduces
a small constant-factor overhead, it offers significantly better
</div></details><h2id="modules"class="section-header">Modules<ahref="#modules"class="anchor">§</a></h2><ulclass="item-table"><li><divclass="item-name"><aclass="mod"href="implementation/index.html"title="mod sharded_slab::implementation">implementation</a></div><divclass="desc docblock-short">Notes on <code>sharded-slab</code>’s implementation and design.</div></li><li><divclass="item-name"><aclass="mod"href="pool/index.html"title="mod sharded_slab::pool">pool</a></div><divclass="desc docblock-short">A lock-free concurrent object pool.</div></li></ul><h2id="structs"class="section-header">Structs<ahref="#structs"class="anchor">§</a></h2><ulclass="item-table"><li><divclass="item-name"><aclass="struct"href="struct.DefaultConfig.html"title="struct sharded_slab::DefaultConfig">DefaultConfig</a></div><divclass="desc docblock-short">Default slab configuration values.</div></li><li><divclass="item-name"><aclass="struct"href="struct.Entry.html"title="struct sharded_slab::Entry">Entry</a></div><divclass="desc docblock-short">A handle that allows access to an occupied entry in a <ahref="struct.Slab.html"title="struct sharded_slab::Slab"><code>Slab</code></a>.</div></li><li><divclass="item-name"><aclass="struct"href="struct.OwnedEntry.html"title="struct sharded_slab::OwnedEntry">OwnedEntry</a></div><divclass="desc docblock-short">An owned reference to an occupied entry in a <ahref="struct.Slab.html"title="struct sharded_slab::Slab"><code>Slab</code></a>.</div></li><li><divclass="item-name"><aclass="struct"href="struct.Pool.html"title="struct sharded_slab::Pool">Pool</a></div><divclass="desc docblock-short">A lock-free concurrent object pool.</div></li><li><divclass="item-name"><aclass="struct"href="struct.Slab.html"title="struct sharded_slab::Slab">Slab</a></div><divclass="desc docblock-short">A sharded slab.</div></li><li><divclass="item-name"><aclass="struct"href="struct.UniqueIter.html"title="struct sharded_slab::UniqueIter">UniqueIter</a></div><divclass="desc docblock-short">An exclusive fused iterator over the items in a <ahref="struct.Slab.html"title="struct sharded_slab::Slab"><code>Slab</code></a>.</div></li><li><divclass="item-name"><aclass="struct"href="struct.VacantEntry.html"title="struct sharded_slab::VacantEntry">VacantEntry</a></div><divclass="desc docblock-short">A handle to a vacant entry in a <ahref="struct.Slab.html"title="struct sharded_slab::Slab"><code>Slab</code></a>.</div></li></ul><h2id="traits"class="section-header">Traits<ahref="#traits"class="anchor">§</a></h2><ulclass="item-table"><li><divclass="item-name"><aclass="trait"href="trait.Clear.html"title="trait sharded_slab::Clear">Clear</a></div><divclass="desc docblock-short">Trait implemented by types which can be cleared in place, retaining any
allocated memory.</div></li><li><divclass="item-name"><aclass="trait"href="trait.Config.html"title="trait sharded_slab::Config">Config</a></div><divclass="desc docblock-short">Configuration parameters which can be overridden to tune the behavior of a slab.</div></li></ul></section></div></main></body></html>
