A thread safe pool that works in an alloc-only context.

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 Deref and a DerefMut implementation for easy access to an underlying T.

A Pool impls Sync when T is Send (even if T is not Sync). This is possible because a pool is guaranteed to provide a value to exactly one thread at any time.

Currently, a pool never contracts in size. Its size is proportional to the maximum number of simultaneous uses. This may change in the future.

A Pool 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:

1. Use a thread_local!, which requires the standard library and requires that the regex pattern be statically known.
2. Use a Pool.
3. Make the cache an explicit dependency in your code and pass it around.
4. Put the cache state in a Mutex, but this means only one search can execute at a time.
5. Create a new cache for every search.

A thread_local! 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 Pool or thread through a cache explicitly in your code is a matter of taste and depends on your code architecture.

Warning: may use a spin lock

When this crate is compiled without the std feature, then this type may used a spin lock internally. This can have subtle effects that may be undesirable. See Spinlocks Considered Harmful for a more thorough treatment of this topic.

Example

This example shows how to share a single hybrid regex among multiple threads, while also safely getting exclusive access to a hybrid's Cache without preventing other searches from running while your thread uses the Cache.

use regex_automata::{
    hybrid::regex::{Cache, Regex},
    util::{lazy::Lazy, pool::Pool},
    Match,
};

static RE: Lazy<Regex> =
    Lazy::new(|| Regex::new("foo[0-9]+bar").unwrap());
static CACHE: Lazy<Pool<Cache>> =
    Lazy::new(|| Pool::new(|| RE.create_cache()));

let expected = Some(Match::must(0, 3..14));
assert_eq!(expected, RE.find(&mut CACHE.get(), b"zzzfoo12345barzzz"));