Struct lasso::ThreadedRodeo

pub struct ThreadedRodeo<K = Spur, S = RandomState> { /* private fields */ }

A concurrent string interner that caches strings quickly with a minimal memory footprint, returning a unique key to re-access it with O(1) internment and resolution.

This struct is only available with the multi-threaded feature! By default ThreadedRodeo uses the Spur type for keys and RandomState as the hasher

Implementations

impl<K> ThreadedRodeo<K, RandomState>where
    K: Key + Hash,

pub fn new() -> Self

Create a new ThreadedRodeo

Example

use lasso::{ThreadedRodeo, Spur};
use std::{thread, sync::Arc};

let lasso: Arc<ThreadedRodeo<Spur>> = Arc::new(ThreadedRodeo::new());
let hello = lasso.get_or_intern("Hello, ");

let l = Arc::clone(&lasso);
let world = thread::spawn(move || {
    l.get_or_intern("World!")
})
.join()
.unwrap();

assert_eq!("Hello, ", lasso.resolve(&hello));
assert_eq!("World!", lasso.resolve(&world));

pub fn with_capacity(capacity: Capacity) -> Self

Create a new ThreadedRodeo with the specified capacity. The interner will be able to hold capacity strings without reallocating. If capacity is 0, the interner will not allocate.

See Capacity for more details

Example

use lasso::{ThreadedRodeo, Capacity, Spur};

let rodeo: ThreadedRodeo<Spur> = ThreadedRodeo::with_capacity(Capacity::for_strings(10));

pub fn with_memory_limits(memory_limits: MemoryLimits) -> Self

Create a new ThreadedRodeo with the specified memory limits. The interner will be able to hold max_memory_usage bytes of interned strings until it will start returning None from try_get_or_intern or panicking from get_or_intern.

Note: If the capacity of the interner is greater than the memory limit, then that will be the effective maximum for allocated memory

See MemoryLimits for more information

Example

use lasso::{ThreadedRodeo, MemoryLimits, Spur};

let rodeo: ThreadedRodeo<Spur> = ThreadedRodeo::with_memory_limits(MemoryLimits::for_memory_usage(4096));

pub fn with_capacity_and_memory_limits(
    capacity: Capacity,
    memory_limits: MemoryLimits
) -> Self

Create a new ThreadedRodeo with the specified capacity and memory limits. The interner will be able to hold max_memory_usage bytes of interned strings until it will start returning None from try_get_or_intern or panicking from get_or_intern.

Note: If the capacity of the interner is greater than the memory limit, then that will be the effective maximum for allocated memory

See Capacity MemoryLimits for more information

Example

use lasso::{ThreadedRodeo, MemoryLimits, Spur};

let rodeo: ThreadedRodeo<Spur> = ThreadedRodeo::with_memory_limits(MemoryLimits::for_memory_usage(4096));

impl<K, S> ThreadedRodeo<K, S>where
    K: Key + Hash,
    S: BuildHasher + Clone,

pub fn with_hasher(hash_builder: S) -> Self

Creates an empty ThreadedRodeo which will use the given hasher for its internal hashmap

Example

use lasso::{Spur, ThreadedRodeo};
use std::collections::hash_map::RandomState;

let rodeo: ThreadedRodeo<Spur, RandomState> = ThreadedRodeo::with_hasher(RandomState::new());

pub fn with_capacity_and_hasher(capacity: Capacity, hash_builder: S) -> Self

Creates a new ThreadedRodeo with the specified capacity that will use the given hasher for its internal hashmap

See Capacity for more details

Example

use lasso::{Spur, Capacity, ThreadedRodeo};
use std::collections::hash_map::RandomState;

let rodeo: ThreadedRodeo<Spur, RandomState> = ThreadedRodeo::with_capacity_and_hasher(Capacity::for_strings(10), RandomState::new());

pub fn with_capacity_memory_limits_and_hasher(
    capacity: Capacity,
    memory_limits: MemoryLimits,
    hash_builder: S
) -> Self

Creates a new ThreadedRodeo with the specified capacity and memory limits that will use the given hasher for its internal hashmap

See Capacity and MemoryLimits for more information

Example

use lasso::{Spur, Capacity, MemoryLimits, ThreadedRodeo};
use std::collections::hash_map::RandomState;

let rodeo: ThreadedRodeo<Spur, RandomState> = ThreadedRodeo::with_capacity_memory_limits_and_hasher(
    Capacity::for_strings(10),
    MemoryLimits::for_memory_usage(4096),
    RandomState::new(),
);

pub fn get_or_intern<T>(&self, val: T) -> Kwhere
    T: AsRef<str>,

Get the key for a string, interning it if it does not yet exist

Panics

Panics if the key’s try_from_usize function fails. With the default keys, this means that you’ve interned more strings than it can handle. (For Spur this means that u32::MAX - 1 unique strings were interned)

Example

use lasso::ThreadedRodeo;

let rodeo = ThreadedRodeo::default();

// Interned the string
let key = rodeo.get_or_intern("Strings of things with wings and dings");
assert_eq!("Strings of things with wings and dings", rodeo.resolve(&key));

// No string was interned, as it was already contained
let key = rodeo.get_or_intern("Strings of things with wings and dings");
assert_eq!("Strings of things with wings and dings", rodeo.resolve(&key));

pub fn try_get_or_intern<T>(&self, val: T) -> LassoResult<K>where
    T: AsRef<str>,

Get the key for a string, interning it if it does not yet exist

Example

use lasso::ThreadedRodeo;

let rodeo = ThreadedRodeo::default();

// Interned the string
let key = rodeo.get_or_intern("Strings of things with wings and dings");
assert_eq!("Strings of things with wings and dings", rodeo.resolve(&key));

// No string was interned, as it was already contained
let key = rodeo.get_or_intern("Strings of things with wings and dings");
assert_eq!("Strings of things with wings and dings", rodeo.resolve(&key));

pub fn get_or_intern_static(&self, string: &'static str) -> K

Get the key for a static string, interning it if it does not yet exist

This will not reallocate or copy the given string but will instead just store it

Panics

Panics if the key’s try_from_usize function fails. With the default keys, this means that you’ve interned more strings than it can handle. (For Spur this means that u32::MAX - 1 unique strings were interned)

Example

use lasso::ThreadedRodeo;

let mut rodeo = ThreadedRodeo::default();

// Interned the string
let key = rodeo.get_or_intern_static("Strings of things with wings and dings");
assert_eq!("Strings of things with wings and dings", rodeo.resolve(&key));

// No string was interned, as it was already contained
let key = rodeo.get_or_intern_static("Strings of things with wings and dings");
assert_eq!("Strings of things with wings and dings", rodeo.resolve(&key));

pub fn try_get_or_intern_static(&self, string: &'static str) -> LassoResult<K>

Get the key for a static string, interning it if it does not yet exist

This will not reallocate and copy the given string but will instead just store it

Example

use lasso::ThreadedRodeo;

let mut rodeo = ThreadedRodeo::default();

// Interned the string
let key = rodeo.try_get_or_intern_static("Strings of things with wings and dings").unwrap();
assert_eq!("Strings of things with wings and dings", rodeo.resolve(&key));

// No string was interned, as it was already contained
let key = rodeo.try_get_or_intern_static("Strings of things with wings and dings").unwrap();
assert_eq!("Strings of things with wings and dings", rodeo.resolve(&key));

pub fn get<T>(&self, val: T) -> Option<K>where
    T: AsRef<str>,

Get the key value of a string, returning None if it doesn’t exist

Example

use lasso::ThreadedRodeo;

let rodeo = ThreadedRodeo::default();

let key = rodeo.get_or_intern("Strings of things with wings and dings");
assert_eq!(Some(key), rodeo.get("Strings of things with wings and dings"));

assert_eq!(None, rodeo.get("This string isn't interned"));

pub fn contains<T>(&self, val: T) -> boolwhere
    T: AsRef<str>,

Returns true if the given string has been interned

Example

use lasso::ThreadedRodeo;

let rodeo = ThreadedRodeo::default();

let key = rodeo.get_or_intern("Strings of things with wings and dings");
assert!(rodeo.contains("Strings of things with wings and dings"));

assert!(!rodeo.contains("This string isn't interned"));

pub fn contains_key(&self, key: &K) -> bool

Returns true if the given key exists in the current interner

Example

use lasso::ThreadedRodeo;

let mut rodeo = ThreadedRodeo::default();

let key = rodeo.get_or_intern("Strings of things with wings and dings");
assert!(rodeo.contains_key(&key));

assert!(!rodeo.contains_key(&key_that_doesnt_exist));

pub fn resolve<'a>(&'a self, key: &K) -> &'a str

Resolves a string by its key. Only keys made by the current ThreadedRodeo may be used

Panics

Panics if the key is out of bounds

Example

use lasso::ThreadedRodeo;

let rodeo = ThreadedRodeo::default();

let key = rodeo.get_or_intern("Strings of things with wings and dings");
assert_eq!("Strings of things with wings and dings", rodeo.resolve(&key));

pub fn try_resolve<'a>(&'a self, key: &K) -> Option<&'a str>

Resolves a string by its key, returning None if it is out of bounds. Only keys made by the current ThreadedRodeo may be used

Example

use lasso::ThreadedRodeo;

let rodeo = ThreadedRodeo::default();

let key = rodeo.get_or_intern("Strings of things with wings and dings");
assert_eq!(Some("Strings of things with wings and dings"), rodeo.try_resolve(&key));

pub fn len(&self) -> usize

Gets the number of interned strings

Example

use lasso::ThreadedRodeo;

let rodeo = ThreadedRodeo::default();
rodeo.get_or_intern("Documentation often has little hidden bits in it");

assert_eq!(rodeo.len(), 1);

pub fn is_empty(&self) -> bool

Returns true if there are no currently interned strings

Example

use lasso::ThreadedRodeo;

let rodeo = ThreadedRodeo::default();
assert!(rodeo.is_empty());

pub fn capacity(&self) -> usize

Returns the number of strings that can be interned without a reallocation

This is an unreliable measurement since the underlying hashmap is unreliable in its capacity measurement

Example

use lasso::{Spur, Capacity, ThreadedRodeo};

let rodeo: ThreadedRodeo<Spur> = ThreadedRodeo::with_capacity(Capacity::for_strings(10));
assert_eq!(rodeo.capacity(), 10);

pub fn iter(&self) -> Iter<'_, K, S>

Returns an iterator over the interned strings and their key values

pub fn strings(&self) -> Strings<'_, K, S>

Returns an iterator over the interned strings

pub fn set_memory_limits(&self, memory_limits: MemoryLimits)

Set the ThreadedRodeo’s maximum memory usage while in-flight

Note that setting the maximum memory usage to below the currently allocated memory will do nothing

pub fn current_memory_usage(&self) -> usize

Get the ThreadedRodeo’s currently allocated memory

pub fn max_memory_usage(&self) -> usize

Get the ThreadedRodeo’s current maximum of allocated memory

pub fn into_reader(self) -> RodeoReader<K, S>

Consumes the current ThreadedRodeo, returning a RodeoReader to allow contention-free access of the interner from multiple threads

Example

use lasso::ThreadedRodeo;

let rodeo = ThreadedRodeo::default();
let key = rodeo.get_or_intern("Appear weak when you are strong, and strong when you are weak.");

let rodeo_reader = rodeo.into_reader();
assert_eq!(
    "Appear weak when you are strong, and strong when you are weak.",
    rodeo_reader.resolve(&key),
);

pub fn into_resolver(self) -> RodeoResolver<K>

Consumes the current ThreadedRodeo, returning a RodeoResolver to allow contention-free access of the interner from multiple threads with the lowest possible memory consumption

Example

use lasso::ThreadedRodeo;

let rodeo = ThreadedRodeo::default();
let key = rodeo.get_or_intern("Appear weak when you are strong, and strong when you are weak.");

let rodeo_resolver = rodeo.into_resolver();
assert_eq!(
    "Appear weak when you are strong, and strong when you are weak.",
    rodeo_resolver.resolve(&key),
);

Trait Implementations

impl<K, S> Debug for ThreadedRodeo<K, S>where
    K: Key + Hash + Debug,
    S: BuildHasher + Clone,

fn fmt(&self, f: &mut Formatter<'_>) -> FmtResult

Formats the value using the given formatter.

impl Default for ThreadedRodeo<Spur, RandomState>

Creates a ThreadedRodeo using Spur as its key and RandomState as its hasher

fn default() -> Self

Returns the “default value” for a type.

impl<K, S, T> Extend<T> for ThreadedRodeo<K, S>where
    K: Key + Hash,
    S: BuildHasher + Clone,
    T: AsRef<str>,

fn extend<I>(&mut self, iter: I)where
    I: IntoIterator<Item = T>,

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: A)

🔬This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl<Str, K, S> FromIterator<Str> for ThreadedRodeo<K, S>where
    Str: AsRef<str>,
    K: Key + Hash,
    S: BuildHasher + Clone + Default,

fn from_iter<T>(iter: T) -> Selfwhere
    T: IntoIterator<Item = Str>,

Creates a value from an iterator.

impl<K, S> Index<K> for ThreadedRodeo<K, S>where
    K: Key + Hash,
    S: BuildHasher + Clone,

type Output = str

The returned type after indexing.

fn index(&self, idx: K) -> &Self::Output

Performs the indexing (container[index]) operation.

impl<K, S> Interner<K> for &ThreadedRodeo<K, S>where
    K: Key + Hash,
    S: BuildHasher + Clone,

fn get_or_intern(&mut self, val: &str) -> K

Get the key for a string, interning it if it does not yet exist

fn try_get_or_intern(&mut self, val: &str) -> LassoResult<K>

Get the key for a string, interning it if it does not yet exist

fn get_or_intern_static(&mut self, val: &'static str) -> K

Get the key for a static string, interning it if it does not yet exist

fn try_get_or_intern_static(&mut self, val: &'static str) -> LassoResult<K>

Get the key for a static string, interning it if it does not yet exist

impl<K, S> Interner<K> for ThreadedRodeo<K, S>where
    K: Key + Hash,
    S: BuildHasher + Clone,

fn get_or_intern(&mut self, val: &str) -> K

Get the key for a string, interning it if it does not yet exist

fn try_get_or_intern(&mut self, val: &str) -> LassoResult<K>

Get the key for a string, interning it if it does not yet exist

fn get_or_intern_static(&mut self, val: &'static str) -> K

Get the key for a static string, interning it if it does not yet exist

fn try_get_or_intern_static(&mut self, val: &'static str) -> LassoResult<K>

Get the key for a static string, interning it if it does not yet exist

impl<K, S> IntoReader<K> for ThreadedRodeo<K, S>where
    K: Key + Hash,
    S: BuildHasher + Clone,

type Reader = RodeoReader<K, S>

The type of Reader the interner will be converted into

fn into_reader(self) -> Self::Readerwhere
    Self: 'static,

Consumes the current Interner and converts it into a Reader to allow contention-free access of the interner from multiple threads

impl<K, S> IntoResolver<K> for ThreadedRodeo<K, S>where
    K: Key + Hash,
    S: BuildHasher + Clone,

type Resolver = RodeoResolver<K>

The type of Resolver the reader will be converted into

fn into_resolver(self) -> Self::Resolverwhere
    Self: 'static,

Consumes the current Reader and makes it into a Resolver, allowing contention-free access from multiple threads with the lowest possible memory consumption

impl<K, S> PartialEq<Rodeo<K, S>> for ThreadedRodeo<K, S>where
    K: Eq + Hash + Key,
    S: Clone + BuildHasher,

fn eq(&self, other: &Rodeo<K, S>) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<K, S> PartialEq<RodeoReader<K, S>> for ThreadedRodeo<K, S>where
    K: Eq + Hash + Key,
    S: Clone + BuildHasher,

fn eq(&self, other: &RodeoReader<K, S>) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<K, S> PartialEq<RodeoResolver<K>> for ThreadedRodeo<K, S>where
    K: Eq + Hash + Key,
    S: Clone + BuildHasher,

fn eq(&self, other: &RodeoResolver<K>) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<K, S> PartialEq<ThreadedRodeo<K, S>> for ThreadedRodeo<K, S>where
    K: Eq + Hash,
    S: Clone + BuildHasher,

fn eq(&self, other: &Self) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<K, S> Reader<K> for &ThreadedRodeo<K, S>where
    K: Key + Hash,
    S: BuildHasher + Clone,

fn get(&self, val: &str) -> Option<K>

Get a key for the given string value if it exists

fn contains(&self, val: &str) -> bool

Returns true if the current interner contains the given string

impl<K, S> Reader<K> for ThreadedRodeo<K, S>where
    K: Key + Hash,
    S: BuildHasher + Clone,

fn get(&self, val: &str) -> Option<K>

Get a key for the given string value if it exists

fn contains(&self, val: &str) -> bool

Returns true if the current interner contains the given string

impl<K, S> Resolver<K> for &ThreadedRodeo<K, S>where
    K: Key + Hash,
    S: BuildHasher + Clone,

fn resolve<'a>(&'a self, key: &K) -> &'a str

Resolves the given key into a string

fn try_resolve<'a>(&'a self, key: &K) -> Option<&'a str>

Attempts to resolve the given key into a string, returning None if it cannot be found

unsafe fn resolve_unchecked<'a>(&'a self, key: &K) -> &'a str

Resolves a string by its key without preforming bounds checks

fn contains_key(&self, key: &K) -> bool

Returns true if the current interner contains the given key

fn len(&self) -> usize

Gets the number of currently interned strings

fn is_empty(&self) -> bool

Returns true if there are no currently interned strings

impl<K, S> Resolver<K> for ThreadedRodeo<K, S>where
    K: Key + Hash,
    S: BuildHasher + Clone,

unsafe fn resolve_unchecked<'a>(&'a self, key: &K) -> &'a str

ThreadedRodeo does not actually have a resolve_unchecked() method, so this just forwards to the normal ThreadedRodeo::resolve() method

fn resolve<'a>(&'a self, key: &K) -> &'a str

Resolves the given key into a string

fn try_resolve<'a>(&'a self, key: &K) -> Option<&'a str>

Attempts to resolve the given key into a string, returning None if it cannot be found

fn contains_key(&self, key: &K) -> bool

Returns true if the current interner contains the given key

fn len(&self) -> usize

Gets the number of currently interned strings

fn is_empty(&self) -> bool

Returns true if there are no currently interned strings

impl<K, S> Eq for ThreadedRodeo<K, S>where
    K: Eq + Hash,
    S: Clone + BuildHasher,

impl<K, S> IntoReaderAndResolver<K> for ThreadedRodeo<K, S>where
    K: Key + Hash,
    S: BuildHasher + Clone,

impl<K: Send, S: Send> Send for ThreadedRodeo<K, S>

impl<K: Sync, S: Sync> Sync for ThreadedRodeo<K, S>