Lasso String Interner

A RodeoResolver is a read-only view of a Rodeo or ThreadedRodeo that provides contention-free access to interned strings. It is optimized for minimal memory usage and is used specifically for key-to-string resolution.

Once you have converted a Rodeo into a RodeoResolver (using .into_resolver()), you can no longer intern new strings, but you can efficiently resolve existing keys to their string representations. This is ideal for passing a read-only, thread-safe view of your interned data to other parts of your application.

use lasso::Rodeo;

let mut rodeo = Rodeo::default();
let key = rodeo.get_or_intern("example string");

// Convert the interner into a read-only resolver
let resolver = rodeo.into_resolver();

// Resolve the key
assert_eq!("example string", resolver.resolve(&key));

Lasso uses Cargo features to manage dependencies and capabilities. By default, only Rodeo is exposed and hashbrown is used as the underlying hashmap.

Available Features

• multi-threaded: Enables ThreadedRodeo for multi-threaded tasks.
• ahasher: Uses ahash's RandomState as the default hasher.
• no-std: Enables no_std + alloc support for Rodeo and ThreadedRodeo. This automatically enables the ahasher feature.
• serialize: Implements Serialize and Deserialize for all Spur types and all interners.
• inline-more: Annotates external APIs with #[inline] to improve performance.

To optimize for multi-threaded access or to reduce memory overhead, you can convert an Interner into specialized read-only types using the IntoReader and IntoResolver traits.

IntoReader

Use into_reader(self) -> Self::Reader to consume the Interner and convert it into a Reader. This is useful for transitioning from a mutable setup phase to a contention-free, multi-threaded reading phase.

IntoResolver

Use into_resolver(self) -> Self::Resolver to consume a Reader and convert it into a Resolver. This allows for contention-free access from multiple threads with the lowest possible memory consumption, as it focuses strictly on key-to-string resolution.

A ThreadedRodeo is a concurrent string interner designed for high-performance, multi-threaded environments. It allows multiple threads to intern strings and resolve keys to string slices with minimal contention.

Note: This struct is only available when the multi-threaded feature is enabled.

By default, it uses Spur for keys and RandomState as the hasher. You can share a ThreadedRodeo across threads by wrapping it in an Arc.

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));

To allow multiple threads to access the interned strings without contention, you can consume the Rodeo and convert it into specialized read-only types.

• into_reader(): Consumes the Rodeo and returns a RodeoReader. This allows contention-free access to the full interner (including the map for str -> key resolution).
• into_resolver(): Consumes the Rodeo and returns a RodeoResolver. This is the most memory-efficient way to allow multi-threaded access if you only need to resolve key -> str.

use lasso::Rodeo;

let mut rodeo = Rodeo::new();
rodeo.get_or_intern("Thread-safe string");

// Convert to a reader for multi-threaded access
let reader = rodeo.into_reader();
// 'reader' can now be shared across threads

If you only need to resolve keys and do not need to modify the interner (intern new strings), you can convert a Rodeo into a more restricted view:

• into_resolver(): Consumes the Rodeo and returns a type that only supports resolving keys to strings.
• into_reader(): Consumes the Rodeo and returns a type that provides read-only access to the interned data.

The Rodeo interner is designed for single-threaded workloads. It allows you to intern strings to get unique keys and resolve those keys back to strings or find keys for existing strings.

Key methods:

• get_or_intern(s: &str): Returns the key for the string, interning it if it doesn't exist.
• resolve(&key): Returns the string associated with the key.
• get(s: &str): Returns Some(key) if the string is already interned, otherwise None.

use lasso::Rodeo;

let mut rodeo = Rodeo::default();
let key = rodeo.get_or_intern("Hello, world!");

// Easily retrieve the value of a key and find the key for values
assert_eq!("Hello, world!", rodeo.resolve(&key));
assert_eq!(Some(key), rodeo.get("Hello, world!"));

// Interning the same string again will yield the same key
let key2 = rodeo.get_or_intern("Hello, world!");

assert_eq!(key, key2);

For the lowest possible memory usage and contention-free access, you can convert a Rodeo or ThreadedRodeo into a RodeoResolver using .into_resolver().

RodeoResolver is optimized for read-only workloads where you only need to resolve keys to strings. It does not support string-to-key resolution (get).

use lasso::Rodeo;

// Rodeo and ThreadedRodeo are interchangeable here
let mut rodeo = Rodeo::default();

let key = rodeo.get_or_intern("Hello, world!");
assert_eq!("Hello, world!", rodeo.resolve(&key));

let resolver = rodeo.into_resolver();

// Resolver keeps all the strings from the parent
assert_eq!("Hello, world!", resolver.resolve(&key));

// The Resolver can now be shared across threads, no matter what kind of Rodeo created it