<!DOCTYPE html><htmllang="en"><head><metacharset="utf-8"><metaname="viewport"content="width=device-width, initial-scale=1.0"><metaname="generator"content="rustdoc"><metaname="description"content="A thread safe pool that works in an `alloc`-only context."><title>Pool in regex_automata::util::pool - Rust</title><linkrel="preload"as="font"type="font/woff2"crossoriginhref="../../../static.files/SourceSerif4-Regular-46f98efaafac5295.ttf.woff2"><linkrel="preload"as="font"type="font/woff2"crossoriginhref="../../../static.files/FiraSans-Regular-018c141bf0843ffd.woff2"><linkrel="preload"as="font"type="font/woff2"crossoriginhref="../../../static.files/FiraSans-Medium-8f9a781e4970d388.woff2"><linkrel="preload"as="font"type="font/woff2"crossoriginhref="../../../static.files/SourceCodePro-Regular-562dcc5011b6de7d.ttf.woff2"><linkrel="preload"as="font"type="font/woff2"crossoriginhref="../../../static.files/SourceCodePro-Semibold-d899c5a5c4aeb14a.ttf.woff2"><linkrel="stylesheet"href="../../../static.files/normalize-76eba96aa4d2e634.css"><linkrel="stylesheet"href="../../../static.files/rustdoc-ac92e1bbe349e143.css"><metaname="rustdoc-vars"data-root-path="../../../"data-static-root-path="../../../static.files/"data-current-crate="regex_automata"data-themes=""data-resource-suffix=""data-rustdoc-version="1.76.0 (07dca489a 2024-02-04)"data-channel="1.76.0"data-search-js="search-2b6ce74ff89ae146.js"data-settings-js="settings-4313503d2e1961c2.js"><scriptsrc="../../../static.files/storage-f2adc0d6ca4d09fb.js"></script><scriptdefersrc="sidebar-items.js"></script><scriptdefersrc="../../../static.files/main-305769736d49e732.js"></script><noscript><linkrel="stylesheet"href="../../../static.files/noscript-feafe1bb7466e4bd.css"></noscript><linkrel="alternate icon"type="image/png"href="../../../static.files/favicon-16x16-8b506e7a72182f1c.png"><linkrel="alternate icon"type="image/png"href="../../../static.files/favicon-32x32-422f7d1d52889060.png"><linkrel="icon"type="image/svg+xml"href="../../../static.files/favicon-2c020d218678b618.svg"></head><bodyclass="rustdoc struct"><!--[if lte IE 11]><div class="warning">This old browser is unsupported and will most likely display funky things.</div><![endif]--><navclass="mobile-topbar"><buttonclass="sidebar-menu-toggle">☰</button></nav><navclass="sidebar"><divclass="sidebar-crate"><h2><ahref="../../../regex_automata/index.html">regex_automata</a><spanclass="version">0.4.5</span></h2></div><h2class="location"><ahref="#">Pool</a></h2><divclass="sidebar-elems"><section><h3><ahref="#implementations">Methods</a></h3><ulclass="block method"><li><ahref="#method.get">get</a></li><li><ahref="#method.new">new</a></li></ul><h3><ahref="#trait-implementations">Trait Implementations</a></h3><ulclass="block trait-implementation"><li><ahref="#impl-Debug-for-Pool%3CT,+F%3E">Debug</a></li></ul><h3><ahref="#synthetic-implementations">Auto Trait Implementations</a></h3><ulclass="block synthetic-implementation"><li><ahref="#impl-RefUnwindSafe-for-Pool%3CT,+F%3E">RefUnwindSafe</a></li><li><ahref="#impl-Send-for-Pool%3CT,+F%3E">Send</a></li><li><ahref="#impl-Sync-for-Pool%3CT,+F%3E">Sync</a></li><li><ahref="#impl-Unpin-for-Pool%3CT,+F%3E">Unpin</a></li><li><ahref="#impl-UnwindSafe-for-Pool%3CT,+F%3E">UnwindSafe</a></li></ul><h3><ahref="#blanket-implementations">Blanket Implementations</a></h3><ulclass="block blanket-implementation"><li><ahref="#impl-Any-for-T">Any</a></li><li><ahref="#impl-Borrow%3CT%3E-for-T">Borrow<T></a></li><li><ahref="#impl-BorrowMut%3CT%3E-for-T">BorrowMut<T></a></li><li><ahref="#impl-From%3CT%3E-for-T">From<T></a></li><li><ahref="#impl-Into%3CU%3E-for-T">Into<U></a></li><li><ahref="#impl-TryFrom%3CU%3E-for-T">TryFrom<U></a></li><li><ahref="#impl-TryInto%3CU%3E-for-T">TryInto<U></a></li></ul></section><h2><ahref="index.html">In regex_automata::util::pool</a></h2></div></nav><divclass="sidebar-resizer"></div>
<main><divclass="width-limiter"><navclass="sub"><formclass="search-form"><span></span><divid="sidebar-button"tabindex="-1"><ahref="../../../regex_automata/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>Struct <ahref="../../index.html">regex_automata</a>::<wbr><ahref="../index.html">util</a>::<wbr><ahref="index.html">pool</a>::<wbr><aclass="struct"href="#">Pool</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/regex_automata/util/pool.rs.html#154">source</a> · <buttonid="toggle-all-docs"title="collapse all docs">[<span>−</span>]</button></span></div><preclass="rust item-decl"><code>pub struct Pool<T, F = <aclass="primitive"href="https://doc.rust-lang.org/1.76.0/std/primitive.fn.html">fn</a>() -> T>(<spanclass="comment">/* private fields */</span>);</code></pre><detailsclass="toggle top-doc"open><summaryclass="hideme"><span>Expand description</span></summary><divclass="docblock"><p>A thread safe pool that works in an <code>alloc</code>-only context.</p>
<p>Getting a value out comes with a guard. When that guard is dropped, the
value is automatically put back in the pool. The guard provides both a
<code>Deref</code> and a <code>DerefMut</code> implementation for easy access to an underlying
<code>T</code>.</p>
<p>A <code>Pool</code> impls <code>Sync</code> when <code>T</code> is <code>Send</code> (even if <code>T</code> is not <code>Sync</code>). This
is possible because a pool is guaranteed to provide a value to exactly one
thread at any time.</p>
<p>Currently, a pool never contracts in size. Its size is proportional to the
maximum number of simultaneous uses. This may change in the future.</p>
<p>A <code>Pool</code> is a particularly useful data structure for this crate because
many of the regex engines require a mutable “cache” in order to execute
a search. Since regexes themselves tend to be global, the problem is then:
how do you get a mutable cache to execute a search? You could:</p>
<ol>
<li>Use a <code>thread_local!</code>, which requires the standard library and requires
that the regex pattern be statically known.</li>
<li>Use a <code>Pool</code>.</li>
<li>Make the cache an explicit dependency in your code and pass it around.</li>
<li>Put the cache state in a <code>Mutex</code>, but this means only one search can
execute at a time.</li>
<li>Create a new cache for every search.</li>
</ol>
<p>A <code>thread_local!</code> is perhaps the best choice if it works for your use case.
Putting the cache in a mutex or creating a new cache for every search are
perhaps the worst choices. Of the remaining two choices, whether you use
this <code>Pool</code> or thread through a cache explicitly in your code is a matter
of taste and depends on your code architecture.</p>
<h2id="warning-may-use-a-spin-lock"><ahref="#warning-may-use-a-spin-lock">Warning: may use a spin lock</a></h2>
<p>When this crate is compiled <em>without</em> the <code>std</code> feature, then this type
may used a spin lock internally. This can have subtle effects that may
be undesirable. See <ahref="https://matklad.github.io/2020/01/02/spinlocks-considered-harmful.html">Spinlocks Considered Harmful</a> for a more
<ahref="../../hybrid/regex/struct.Cache.html"title="struct regex_automata::hybrid::regex::Cache"><code>Cache</code></a> without preventing other searches
</div></details><h2id="implementations"class="section-header">Implementations<ahref="#implementations"class="anchor">§</a></h2><divid="implementations-list"><detailsclass="toggle implementors-toggle"open><summary><sectionid="impl-Pool%3CT,+F%3E"class="impl"><aclass="src rightside"href="../../../src/regex_automata/util/pool.rs.html#156-162">source</a><ahref="#impl-Pool%3CT,+F%3E"class="anchor">§</a><h3class="code-header">impl<T, F><aclass="struct"href="struct.Pool.html"title="struct regex_automata::util::pool::Pool">Pool</a><T, F></h3></section></summary><divclass="impl-items"><detailsclass="toggle method-toggle"open><summary><sectionid="method.new"class="method"><aclass="src rightside"href="../../../src/regex_automata/util/pool.rs.html#159-161">source</a><h4class="code-header">pub fn <ahref="#method.new"class="fn">new</a>(create: F) -><aclass="struct"href="struct.Pool.html"title="struct regex_automata::util::pool::Pool">Pool</a><T, F></h4></section></summary><divclass="docblock"><p>Create a new pool. The given closure is used to create values in
the pool when necessary.</p>
</div></details></div></details><detailsclass="toggle implementors-toggle"open><summary><sectionid="impl-Pool%3CT,+F%3E-1"class="impl"><aclass="src rightside"href="../../../src/regex_automata/util/pool.rs.html#164-184">source</a><ahref="#impl-Pool%3CT,+F%3E-1"class="anchor">§</a><h3class="code-header">impl<T: <aclass="trait"href="https://doc.rust-lang.org/1.76.0/core/marker/trait.Send.html"title="trait core::marker::Send">Send</a>, F: <aclass="trait"href="https://doc.rust-lang.org/1.76.0/core/ops/function/trait.Fn.html"title="trait core::ops::function::Fn">Fn</a>() -> T><aclass="struct"href="struct.Pool.html"title="struct regex_automata::util::pool::Pool">Pool</a><T, F></h3></section></summary><divclass="impl-items"><detailsclass="toggle method-toggle"open><summary><sectionid="method.get"class="method"><aclass="src rightside"href="../../../src/regex_automata/util/pool.rs.html#181-183">source</a><h4class="code-header">pub fn <ahref="#method.get"class="fn">get</a>(&self) -><aclass="struct"href="struct.PoolGuard.html"title="struct regex_automata::util::pool::PoolGuard">PoolGuard</a><'_, T, F></h4></section></summary><divclass="docblock"><p>Get a value from the pool. The caller is guaranteed to have
exclusive access to the given value. Namely, it is guaranteed that
this will never return a value that was returned by another call to
<code>get</code> but was not put back into the pool.</p>
<p>When the guard goes out of scope and its destructor is called, then
it will automatically be put back into the pool. Alternatively,
<ahref="struct.PoolGuard.html#method.put"title="associated function regex_automata::util::pool::PoolGuard::put"><code>PoolGuard::put</code></a> may be used to explicitly put it back in the pool
without relying on its destructor.</p>
<p>Note that there is no guarantee provided about which value in the
pool is returned. That is, calling get, dropping the guard (causing
the value to go back into the pool) and then calling get again is
<em>not</em> guaranteed to return the same value received in the first <code>get</code>
call.</p>
</div></details></div></details></div><h2id="trait-implementations"class="section-header">Trait Implementations<ahref="#trait-implementations"class="anchor">§</a></h2><divid="trait-implementations-list"><detailsclass="toggle implementors-toggle"open><summary><sectionid="impl-Debug-for-Pool%3CT,+F%3E"class="impl"><aclass="src rightside"href="../../../src/regex_automata/util/pool.rs.html#186-190">source</a><ahref="#impl-Debug-for-Pool%3CT,+F%3E"class="anchor">§</a><h3class="code-header">impl<T: <aclass="trait"href="https://doc.rust-lang.org/1.76.0/core/fmt/trait.Debug.html"title="trait core::fmt::Debug">Debug</a>, F><aclass="trait"href="https://doc.rust-lang.org/1.76.0/core/fmt/trait.Debug.html"title="trait core::fmt::Debug">Debug</a> for <aclass="struct"href="struct.Pool.html"title="struct regex_automata::util::pool::Pool">Pool</a><T, F></h3></section></summary><divclass="impl-items"><detailsclass="toggle method-toggle"open><summary><sectionid="method.fmt"class="method trait-impl"><aclass="src rightside"href="../../../src/regex_automata/util/pool.rs.html#187-189">source</a><ahref="#method.fmt"class="anchor">§</a><h4class="code-header">fn <ahref="https://doc.rust-lang.org/1.76.0/core/fmt/trait.Debug.html#tymethod.fmt"class="fn">fmt</a>(&self, f: &mut <aclass="struct"href="https://doc.rust-lang.org/1.76.0/core/fmt/struct.Formatter.html"title="struct core::fmt::Formatter">Formatter</a><'_>) -><aclass="type"href="https://doc.rust-lang.org/1.76.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.76.0/core/fmt/trait.Debug.html#tymethod.fmt">Read more</a></div></details></div></details></div><h2id="synthetic-implementations"class="section-header">Auto Trait Implementations<ahref="#synthetic-implementations"class="anchor">§</a></h2><divid="synthetic-implementations-list"><sectionid="impl-RefUnwindSafe-for-Pool%3CT,+F%3E"class="impl"><ahref="#impl-RefUnwindSafe-for-Pool%3CT,+F%3E"class="anchor">§</a><h3class="code-header">impl<T, F><aclass="trait"href="https://doc.rust-lang.org/1.76.0/core/panic/unwind_safe/trait.RefUnwindSafe.html"title="trait core::panic::unwind_safe::RefUnwindSafe">RefUnwindSafe</a> for <aclass="struct"href="struct.Pool.html"title="struct regex_automata::util::pool::Pool">Pool</a><T, F><divclass="where">where
<p>That is, this conversion is whatever the implementation of
<code><ahref="https://doc.rust-lang.org/1.76.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.76.0/src/core/convert/mod.rs.html#803-805">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.76.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.76.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.76.0/core/convert/trait.TryFrom.html#associatedtype.Error"class="associatedtype">Error</a> = <aclass="enum"href="https://doc.rust-lang.org/1.76.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.76.0/src/core/convert/mod.rs.html#810">source</a><ahref="#method.try_from"class="anchor">§</a><h4class="code-header">fn <ahref="https://doc.rust-lang.org/1.76.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.76.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.76.0/core/convert/trait.TryFrom.html"title="trait core::convert::TryFrom">TryFrom</a><U>>::<aclass="associatedtype"href="https://doc.rust-lang.org/1.76.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.76.0/src/core/convert/mod.rs.html#788-790">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.76.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.76.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.76.0/core/convert/trait.TryInto.html#associatedtype.Error"class="associatedtype">Error</a> = <U as <aclass="trait"href="https://doc.rust-lang.org/1.76.0/core/convert/trait.TryFrom.html"title="trait core::convert::TryFrom">TryFrom</a><T>>::<aclass="associatedtype"href="https://doc.rust-lang.org/1.76.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.76.0/src/core/convert/mod.rs.html#795">source</a><ahref="#method.try_into"class="anchor">§</a><h4class="code-header">fn <ahref="https://doc.rust-lang.org/1.76.0/core/convert/trait.TryInto.html#tymethod.try_into"class="fn">try_into</a>(self) -><aclass="enum"href="https://doc.rust-lang.org/1.76.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.76.0/core/convert/trait.TryFrom.html"title="trait core::convert::TryFrom">TryFrom</a><T>>::<aclass="associatedtype"href="https://doc.rust-lang.org/1.76.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>
