<p>Slabs provide pre-allocated storage for many instances of a single type. But, when working with
heap allocated objects, the advantages of a slab are lost, as the memory allocated for the
object is freed when the object is removed from the slab. With a pool, we can instead reuse
this memory for objects being added to the pool in the future, therefore reducing memory
fragmentation and avoiding additional allocations.</p>
<p>This type implements a lock-free concurrent pool, indexed by <code>usize</code>s. The items stored in this
type need to implement <ahref="trait.Clear.html"title="trait sharded_slab::Clear"><code>Clear</code></a> and <code>Default</code>.</p>
<p>The <code>Pool</code> type shares similar semantics to <ahref="struct.Slab.html"title="struct sharded_slab::Slab"><code>Slab</code></a> when it comes to sharing across threads
and storing mutable shared data. The biggest difference is there are no <ahref="struct.Slab.html#method.insert"title="method sharded_slab::Slab::insert"><code>Slab::insert</code></a> and
<ahref="struct.Slab.html#method.take"title="method sharded_slab::Slab::take"><code>Slab::take</code></a> analouges for the <code>Pool</code> type. Instead new items are added to the pool by using
the <ahref="struct.Pool.html#method.create"title="method sharded_slab::Pool::create"><code>Pool::create</code></a> method, and marked for clearing by the <ahref="struct.Pool.html#method.clear"title="method sharded_slab::Pool::clear"><code>Pool::clear</code></a> method.</p>
<p>Pool entries can be cleared by calling <ahref="struct.Pool.html#method.clear"title="method sharded_slab::Pool::clear"><code>Pool::clear</code></a>. This marks the entry to
be cleared when the guards referencing to it are dropped.</p>
<p>Both <code>Pool</code> and <ahref="struct.Slab.html"title="struct sharded_slab::Slab"><code>Slab</code></a> share the same configuration mechanism. See <ahref="index.html#configuration"title="mod sharded_slab">crate level documentation</a>
T: <aclass="trait"href="trait.Clear.html"title="trait sharded_slab::Clear">Clear</a> + <aclass="trait"href="https://doc.rust-lang.org/1.80.0/core/default/trait.Default.html"title="trait core::default::Default">Default</a>,</div></h3></section></summary><divclass="impl-items"><detailsclass="toggle method-toggle"open><summary><sectionid="method.new"class="method"><aclass="src rightside"href="../src/sharded_slab/pool.rs.html#386-388">source</a><h4class="code-header">pub fn <ahref="#method.new"class="fn">new</a>() -> Self</h4></section></summary><divclass="docblock"><p>Returns a new <code>Pool</code> with the default configuration parameters.</p>
</div></details><detailsclass="toggle method-toggle"open><summary><sectionid="method.new_with_config"class="method"><aclass="src rightside"href="../src/sharded_slab/pool.rs.html#391-397">source</a><h4class="code-header">pub fn <ahref="#method.new_with_config"class="fn">new_with_config</a><C: <aclass="trait"href="trait.Config.html"title="trait sharded_slab::Config">Config</a>>() -><aclass="struct"href="struct.Pool.html"title="struct sharded_slab::Pool">Pool</a><T, C></h4></section></summary><divclass="docblock"><p>Returns a new <code>Pool</code> with the provided configuration parameters.</p>
C: <aclass="trait"href="trait.Config.html"title="trait sharded_slab::Config">Config</a>,</div></h3></section></summary><divclass="impl-items"><detailsclass="toggle"open><summary><sectionid="associatedconstant.USED_BITS"class="associatedconstant"><aclass="src rightside"href="../src/sharded_slab/pool.rs.html#418">source</a><h4class="code-header">pub const <ahref="#associatedconstant.USED_BITS"class="constant">USED_BITS</a>: <aclass="primitive"href="https://doc.rust-lang.org/1.80.0/std/primitive.usize.html">usize</a> = C::USED_BITS</h4></section></summary><divclass="docblock"><p>The number of bits in each index which are used by the pool.</p>
<p>If other data is packed into the <code>usize</code> indices returned by
<ahref="struct.Pool.html#method.create"title="method sharded_slab::Pool::create"><code>Pool::create</code></a>, user code is free to use any bits higher than the
<code>USED_BITS</code>-th bit freely.</p>
<p>This is determined by the <ahref="trait.Config.html"><code>Config</code></a> type that configures the pool’s
parameters. By default, all bits are used; this can be changed by
overriding the <ahref="trait.Config.html#associatedconstant.RESERVED_BITS"><code>Config::RESERVED_BITS</code></a> constant.</p>
</div></details><detailsclass="toggle method-toggle"open><summary><sectionid="method.create"class="method"><aclass="src rightside"href="../src/sharded_slab/pool.rs.html#451-464">source</a><h4class="code-header">pub fn <ahref="#method.create"class="fn">create</a>(&self) -><aclass="enum"href="https://doc.rust-lang.org/1.80.0/core/option/enum.Option.html"title="enum core::option::Option">Option</a><<aclass="struct"href="pool/struct.RefMut.html"title="struct sharded_slab::pool::RefMut">RefMut</a><'_, T, C>></h4></section></summary><divclass="docblock"><p>Creates a new object in the pool, returning an <ahref="pool/struct.RefMut.html"title="struct sharded_slab::pool::RefMut"><code>RefMut</code></a> guard that
</div></details><detailsclass="toggle method-toggle"open><summary><sectionid="method.create_owned"class="method"><aclass="src rightside"href="../src/sharded_slab/pool.rs.html#619-632">source</a><h4class="code-header">pub fn <ahref="#method.create_owned"class="fn">create_owned</a>(self: <aclass="struct"href="https://doc.rust-lang.org/1.80.0/alloc/sync/struct.Arc.html"title="struct alloc::sync::Arc">Arc</a><Self>) -><aclass="enum"href="https://doc.rust-lang.org/1.80.0/core/option/enum.Option.html"title="enum core::option::Option">Option</a><<aclass="struct"href="pool/struct.OwnedRefMut.html"title="struct sharded_slab::pool::OwnedRefMut">OwnedRefMut</a><T, C>></h4></section></summary><divclass="docblock"><p>Creates a new object in the pool, returning an <ahref="pool/struct.OwnedRefMut.html"title="struct sharded_slab::pool::OwnedRefMut"><code>OwnedRefMut</code></a> guard that
<p>If this function returns <code>None</code>, then the shard for the current thread
is full and no items can be added until some are removed, or the maximum
number of shards has been reached.</p>
<p>Unlike <ahref="struct.Pool.html#method.create"title="method sharded_slab::Pool::create"><code>create</code></a>, which borrows the pool, this method <em>clones</em> the <code>Arc</code>
around the pool if a value exists for the given key. This means that the
returned <ahref="pool/struct.OwnedRefMut.html"title="struct sharded_slab::pool::OwnedRefMut"><code>OwnedRefMut</code></a> can be held for an arbitrary lifetime. However,
this method requires that the pool itself be wrapped in an <code>Arc</code>.</p>
<p>An <code>OwnedRefMut<T></code> functions more or less identically to an owned
<code>Box<T></code>: it can be passed to functions, stored in structure fields, and
borrowed mutably or immutably, and can be owned for arbitrary lifetimes.
The difference is that, unlike a <code>Box<T></code>, the memory allocation for the
<code>T</code> lives in the <code>Pool</code>; when an <code>OwnedRefMut</code> is created, it may reuse
memory that was allocated for a previous pooled object that has been
cleared. Additionally, the <code>OwnedRefMut</code> may be <ahref="pool/struct.OwnedRefMut.html#method.downgrade"title="method sharded_slab::pool::OwnedRefMut::downgrade">downgraded</a> to an
<ahref="pool/struct.OwnedRef.html"title="struct sharded_slab::pool::OwnedRef"><code>OwnedRef</code></a> which may be shared freely, essentially turning the <code>Box</code>
<p>Unlike <ahref="pool/struct.RefMut.html"title="struct sharded_slab::pool::RefMut"><code>RefMut</code></a>, an <code>OwnedRefMut</code> may be stored in a struct which must live
</div></details><detailsclass="toggle method-toggle"open><summary><sectionid="method.create_with"class="method"><aclass="src rightside"href="../src/sharded_slab/pool.rs.html#654-659">source</a><h4class="code-header">pub fn <ahref="#method.create_with"class="fn">create_with</a>(&self, init: impl <aclass="trait"href="https://doc.rust-lang.org/1.80.0/core/ops/function/trait.FnOnce.html"title="trait core::ops::function::FnOnce">FnOnce</a>(<aclass="primitive"href="https://doc.rust-lang.org/1.80.0/std/primitive.reference.html">&mut T</a>)) -><aclass="enum"href="https://doc.rust-lang.org/1.80.0/core/option/enum.Option.html"title="enum core::option::Option">Option</a><<aclass="primitive"href="https://doc.rust-lang.org/1.80.0/std/primitive.usize.html">usize</a>></h4></section></summary><divclass="docblock"><p>Creates a new object in the pool with the provided initializer,
</div></details><detailsclass="toggle method-toggle"open><summary><sectionid="method.get"class="method"><aclass="src rightside"href="../src/sharded_slab/pool.rs.html#675-682">source</a><h4class="code-header">pub fn <ahref="#method.get"class="fn">get</a>(&self, key: <aclass="primitive"href="https://doc.rust-lang.org/1.80.0/std/primitive.usize.html">usize</a>) -><aclass="enum"href="https://doc.rust-lang.org/1.80.0/core/option/enum.Option.html"title="enum core::option::Option">Option</a><<aclass="struct"href="pool/struct.Ref.html"title="struct sharded_slab::pool::Ref">Ref</a><'_, T, C>></h4></section></summary><divclass="docblock"><p>Return a borrowed reference to the value associated with the given key.</p>
</div></details><detailsclass="toggle method-toggle"open><summary><sectionid="method.get_owned"class="method"><aclass="src rightside"href="../src/sharded_slab/pool.rs.html#766-777">source</a><h4class="code-header">pub fn <ahref="#method.get_owned"class="fn">get_owned</a>(self: <aclass="struct"href="https://doc.rust-lang.org/1.80.0/alloc/sync/struct.Arc.html"title="struct alloc::sync::Arc">Arc</a><Self>, key: <aclass="primitive"href="https://doc.rust-lang.org/1.80.0/std/primitive.usize.html">usize</a>) -><aclass="enum"href="https://doc.rust-lang.org/1.80.0/core/option/enum.Option.html"title="enum core::option::Option">Option</a><<aclass="struct"href="pool/struct.OwnedRef.html"title="struct sharded_slab::pool::OwnedRef">OwnedRef</a><T, C>></h4></section></summary><divclass="docblock"><p>Return an owned reference to the value associated with the given key.</p>
<p>If the pool does not contain a value for the given key, <code>None</code> is
returned instead.</p>
<p>Unlike <ahref="struct.Pool.html#method.get"title="method sharded_slab::Pool::get"><code>get</code></a>, which borrows the pool, this method <em>clones</em> the <code>Arc</code>
around the pool if a value exists for the given key. This means that the
returned <ahref="pool/struct.OwnedRef.html"title="struct sharded_slab::pool::OwnedRef"><code>OwnedRef</code></a> can be held for an arbitrary lifetime. However,
this method requires that the pool itself be wrapped in an <code>Arc</code>.</p>
<p>Unlike <ahref="pool/struct.Ref.html"title="struct sharded_slab::pool::Ref"><code>Ref</code></a>, an <code>OwnedRef</code> may be stored in a struct which must live
</div></details><detailsclass="toggle method-toggle"open><summary><sectionid="method.clear"class="method"><aclass="src rightside"href="../src/sharded_slab/pool.rs.html#820-833">source</a><h4class="code-header">pub fn <ahref="#method.clear"class="fn">clear</a>(&self, key: <aclass="primitive"href="https://doc.rust-lang.org/1.80.0/std/primitive.usize.html">usize</a>) -><aclass="primitive"href="https://doc.rust-lang.org/1.80.0/std/primitive.bool.html">bool</a></h4></section></summary><divclass="docblock"><p>Remove the value using the storage associated with the given key from the pool, returning
C: <aclass="trait"href="trait.Config.html"title="trait sharded_slab::Config">Config</a>,</div></h3></section></summary><divclass="impl-items"><detailsclass="toggle method-toggle"open><summary><sectionid="method.fmt"class="method trait-impl"><aclass="src rightside"href="../src/sharded_slab/pool.rs.html#863-868">source</a><ahref="#method.fmt"class="anchor">§</a><h4class="code-header">fn <ahref="https://doc.rust-lang.org/1.80.0/core/fmt/trait.Debug.html#tymethod.fmt"class="fn">fmt</a>(&self, f: &mut <aclass="struct"href="https://doc.rust-lang.org/1.80.0/core/fmt/struct.Formatter.html"title="struct core::fmt::Formatter">Formatter</a><'_>) -><aclass="type"href="https://doc.rust-lang.org/1.80.0/core/fmt/type.Result.html"title="type core::fmt::Result">Result</a></h4></section></summary><divclass='docblock'>Formats the value using the given formatter. <ahref="https://doc.rust-lang.org/1.80.0/core/fmt/trait.Debug.html#tymethod.fmt">Read more</a></div></details></div></details><detailsclass="toggle implementors-toggle"open><summary><sectionid="impl-Default-for-Pool%3CT%3E"class="impl"><aclass="src rightside"href="../src/sharded_slab/pool.rs.html#849-856">source</a><ahref="#impl-Default-for-Pool%3CT%3E"class="anchor">§</a><h3class="code-header">impl<T><aclass="trait"href="https://doc.rust-lang.org/1.80.0/core/default/trait.Default.html"title="trait core::default::Default">Default</a> for <aclass="struct"href="struct.Pool.html"title="struct sharded_slab::Pool">Pool</a><T><divclass="where">where
T: <aclass="trait"href="trait.Clear.html"title="trait sharded_slab::Clear">Clear</a> + <aclass="trait"href="https://doc.rust-lang.org/1.80.0/core/default/trait.Default.html"title="trait core::default::Default">Default</a>,</div></h3></section></summary><divclass="impl-items"><detailsclass="toggle method-toggle"open><summary><sectionid="method.default"class="method trait-impl"><aclass="src rightside"href="../src/sharded_slab/pool.rs.html#853-855">source</a><ahref="#method.default"class="anchor">§</a><h4class="code-header">fn <ahref="https://doc.rust-lang.org/1.80.0/core/default/trait.Default.html#tymethod.default"class="fn">default</a>() -> Self</h4></section></summary><divclass='docblock'>Returns the “default value” for a type. <ahref="https://doc.rust-lang.org/1.80.0/core/default/trait.Default.html#tymethod.default">Read more</a></div></details></div></details><sectionid="impl-Send-for-Pool%3CT,+C%3E"class="impl"><aclass="src rightside"href="../src/sharded_slab/pool.rs.html#836-841">source</a><ahref="#impl-Send-for-Pool%3CT,+C%3E"class="anchor">§</a><h3class="code-header">impl<T, C><aclass="trait"href="https://doc.rust-lang.org/1.80.0/core/marker/trait.Send.html"title="trait core::marker::Send">Send</a> for <aclass="struct"href="struct.Pool.html"title="struct sharded_slab::Pool">Pool</a><T, C><divclass="where">where
<code><ahref="https://doc.rust-lang.org/1.80.0/core/convert/trait.From.html"title="trait core::convert::From">From</a><T> for U</code> chooses to do.</p>
</div></details></div></details><detailsclass="toggle implementors-toggle"><summary><sectionid="impl-TryFrom%3CU%3E-for-T"class="impl"><aclass="src rightside"href="https://doc.rust-lang.org/1.80.0/src/core/convert/mod.rs.html#805-807">source</a><ahref="#impl-TryFrom%3CU%3E-for-T"class="anchor">§</a><h3class="code-header">impl<T, U><aclass="trait"href="https://doc.rust-lang.org/1.80.0/core/convert/trait.TryFrom.html"title="trait core::convert::TryFrom">TryFrom</a><U> for T<divclass="where">where
U: <aclass="trait"href="https://doc.rust-lang.org/1.80.0/core/convert/trait.Into.html"title="trait core::convert::Into">Into</a><T>,</div></h3></section></summary><divclass="impl-items"><detailsclass="toggle"open><summary><sectionid="associatedtype.Error"class="associatedtype trait-impl"><ahref="#associatedtype.Error"class="anchor">§</a><h4class="code-header">type <ahref="https://doc.rust-lang.org/1.80.0/core/convert/trait.TryFrom.html#associatedtype.Error"class="associatedtype">Error</a> = <aclass="enum"href="https://doc.rust-lang.org/1.80.0/core/convert/enum.Infallible.html"title="enum core::convert::Infallible">Infallible</a></h4></section></summary><divclass='docblock'>The type returned in the event of a conversion error.</div></details><detailsclass="toggle method-toggle"open><summary><sectionid="method.try_from"class="method trait-impl"><aclass="src rightside"href="https://doc.rust-lang.org/1.80.0/src/core/convert/mod.rs.html#812">source</a><ahref="#method.try_from"class="anchor">§</a><h4class="code-header">fn <ahref="https://doc.rust-lang.org/1.80.0/core/convert/trait.TryFrom.html#tymethod.try_from"class="fn">try_from</a>(value: U) -><aclass="enum"href="https://doc.rust-lang.org/1.80.0/core/result/enum.Result.html"title="enum core::result::Result">Result</a><T, <T as <aclass="trait"href="https://doc.rust-lang.org/1.80.0/core/convert/trait.TryFrom.html"title="trait core::convert::TryFrom">TryFrom</a><U>>::<aclass="associatedtype"href="https://doc.rust-lang.org/1.80.0/core/convert/trait.TryFrom.html#associatedtype.Error"title="type core::convert::TryFrom::Error">Error</a>></h4></section></summary><divclass='docblock'>Performs the conversion.</div></details></div></details><detailsclass="toggle implementors-toggle"><summary><sectionid="impl-TryInto%3CU%3E-for-T"class="impl"><aclass="src rightside"href="https://doc.rust-lang.org/1.80.0/src/core/convert/mod.rs.html#790-792">source</a><ahref="#impl-TryInto%3CU%3E-for-T"class="anchor">§</a><h3class="code-header">impl<T, U><aclass="trait"href="https://doc.rust-lang.org/1.80.0/core/convert/trait.TryInto.html"title="trait core::convert::TryInto">TryInto</a><U> for T<divclass="where">where
U: <aclass="trait"href="https://doc.rust-lang.org/1.80.0/core/convert/trait.TryFrom.html"title="trait core::convert::TryFrom">TryFrom</a><T>,</div></h3></section></summary><divclass="impl-items"><detailsclass="toggle"open><summary><sectionid="associatedtype.Error-1"class="associatedtype trait-impl"><ahref="#associatedtype.Error-1"class="anchor">§</a><h4class="code-header">type <ahref="https://doc.rust-lang.org/1.80.0/core/convert/trait.TryInto.html#associatedtype.Error"class="associatedtype">Error</a> = <U as <aclass="trait"href="https://doc.rust-lang.org/1.80.0/core/convert/trait.TryFrom.html"title="trait core::convert::TryFrom">TryFrom</a><T>>::<aclass="associatedtype"href="https://doc.rust-lang.org/1.80.0/core/convert/trait.TryFrom.html#associatedtype.Error"title="type core::convert::TryFrom::Error">Error</a></h4></section></summary><divclass='docblock'>The type returned in the event of a conversion error.</div></details><detailsclass="toggle method-toggle"open><summary><sectionid="method.try_into"class="method trait-impl"><aclass="src rightside"href="https://doc.rust-lang.org/1.80.0/src/core/convert/mod.rs.html#797">source</a><ahref="#method.try_into"class="anchor">§</a><h4class="code-header">fn <ahref="https://doc.rust-lang.org/1.80.0/core/convert/trait.TryInto.html#tymethod.try_into"class="fn">try_into</a>(self) -><aclass="enum"href="https://doc.rust-lang.org/1.80.0/core/result/enum.Result.html"title="enum core::result::Result">Result</a><U, <U as <aclass="trait"href="https://doc.rust-lang.org/1.80.0/core/convert/trait.TryFrom.html"title="trait core::convert::TryFrom">TryFrom</a><T>>::<aclass="associatedtype"href="https://doc.rust-lang.org/1.80.0/core/convert/trait.TryFrom.html#associatedtype.Error"title="type core::convert::TryFrom::Error">Error</a>></h4></section></summary><divclass='docblock'>Performs the conversion.</div></details></div></details></div></section></div></main></body></html>
