Lib.rs

一个多线程和单线程的 字符串池，允许以最小的内存占用将字符串进行缓存，并为其分配一个唯一的 键，可以在任何时间通过该键获取字符串。一个 Rodeo 允许 O(1) 池化和解析，并且可以转换为 RodeoReader 以允许无争用解析，包括键到字符串和字符串到键的操作。它还可以转换为仅具有键到字符串操作的 RodeoResolver，以实现最低的内存使用。

我应该使用哪个字符串池？

对于单线程工作负载，建议使用Rodeo，而对于多线程应用程序应使用ThreadedRodeo。这两种方法都是字符串内嵌的唯一方式，但大多数应用程序都会达到一个不再需要内嵌字符串的阶段，此时将选择RodeoReader和RodeoResolver。如果用户仍然需要获取字符串的键，则必须使用RodeoReader（尽管此时它们仍然可以转换为RodeoResolver）。对于只需要键到字符串解析的用户，RodeoResolver在尽可能小的内存使用下提供无争访问。注意，为了访问ThreadedRodeo，需要启用multi-threaded功能。

Cargo功能

默认情况下，lasso2有一个依赖项，hashbrown，并且只暴露了Rodeo。由于标准库的hashmap中当前的raw_entry api是不稳定的，因此使用了Hashbrown。在hashmap中进行自定义哈希，这有助于显著降低内存使用。为了使用ThreadedRodeo，必须启用multi-threaded功能。

• multi-threaded - 启用多线程任务的内嵌器ThreadedRodeo
• ahasher - 使用ahash的RandomState作为默认哈希函数
• no-std - 启用Rodeo和ThreadedRodeo的no_std + alloc支持
  • 自动启用以下所需功能
    • ahasher - no_std哈希函数
• serialize - 为所有Spur类型和所有内嵌器实现Serialize和Deserialize
• inline-more - 使用#[inline]注释外部api

示例：使用Rodeo

use lasso2::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);

示例：使用ThreadedRodeo

use lasso2::ThreadedRodeo;
use std::{thread, sync::Arc};

let rodeo = Arc::new(ThreadedRodeo::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);

// ThreadedRodeo can be shared across threads
let moved = Arc::clone(&rodeo);
let hello = thread::spawn(move || {
    assert_eq!("Hello, world!", moved.resolve(&key));
    moved.get_or_intern("Hello from the thread!")
})
.join()
.unwrap();

assert_eq!("Hello, world!", rodeo.resolve(&key));
assert_eq!("Hello from the thread!", rodeo.resolve(&hello));

示例：创建RodeoReader

use lasso2::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 reader = rodeo.into_reader();

// Reader keeps all the strings from the parent
assert_eq!("Hello, world!", reader.resolve(&key));
assert_eq!(Some(key), reader.get("Hello, world!"));

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

示例：创建RodeoResolver

use lasso2::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

示例：创建自定义范围的键

有时你希望你的键仅存在于（或不存在于）某个特定的值范围内，以便你可以有定制的niches。这允许你将更多数据打包到原本可能未使用的空间中，这对于内存敏感型应用程序可能是关键的。

use lasso2::{Key, Rodeo};

// First make our key type, this will be what we use as handles into our interner
#[derive(Copy, Clone, PartialEq, Eq)]
struct NicheKey(u32);

// This will reserve the upper 255 values for us to use as niches
const NICHE: usize = 0xFF000000;

// Implementing `Key` is unsafe and requires that anything given to `try_from_usize` must produce the
// same `usize` when `into_usize` is later called
unsafe impl Key for NicheKey {
    fn into_usize(self) -> usize {
        self.0 as usize
    }

    fn try_from_usize(int: usize) -> Option<Self> {
        if int < NICHE {
            // The value isn't in our niche range, so we're good to go
            Some(Self(int as u32))
        } else {
            // The value interferes with our niche, so we return `None`
            None
        }
    }
}

// To make sure we're upholding `Key`'s safety contract, let's make two small tests
#[test]
fn value_in_range() {
    let key = NicheKey::try_from_usize(0).unwrap();
    assert_eq!(key.into_usize(), 0);

    let key = NicheKey::try_from_usize(NICHE - 1).unwrap();
    assert_eq!(key.into_usize(), NICHE - 1);
}

#[test]
fn value_out_of_range() {
    let key = NicheKey::try_from_usize(NICHE);
    assert!(key.is_none());

    let key = NicheKey::try_from_usize(u32::max_value() as usize);
    assert!(key.is_none());
}

// And now we're done and can make `Rodeo`s or `ThreadedRodeo`s that use our custom key!
let mut rodeo: Rodeo<NicheKey> = Rodeo::new();
let key = rodeo.get_or_intern("It works!");
assert_eq!(rodeo.resolve(&key), "It works!");

示例：使用 FromIterator 创建

use lasso2::Rodeo;
use core::iter::FromIterator;

// Works for both `Rodeo` and `ThreadedRodeo`
let rodeo = Rodeo::from_iter(vec![
    "one string",
    "two string",
    "red string",
    "blue string",
]);

assert!(rodeo.contains("one string"));
assert!(rodeo.contains("two string"));
assert!(rodeo.contains("red string"));
assert!(rodeo.contains("blue string"));

use lasso2::Rodeo;
use core::iter::FromIterator;

// Works for both `Rodeo` and `ThreadedRodeo`
let rodeo: Rodeo = vec!["one string", "two string", "red string", "blue string"]
    .into_iter()
    .collect();

assert!(rodeo.contains("one string"));
assert!(rodeo.contains("two string"));
assert!(rodeo.contains("red string"));
assert!(rodeo.contains("blue string"));

基准测试

基准测试数据使用 Criterion.rs 收集
操作系统：Windows 10
处理器：Ryzen 9 3900X，主频 3800MHz
内存：3200MHz
Rustc：稳定版 1.44.1

Rodeo

STD 随机状态

AHash

FXHash

ThreadedRodeo

STD 随机状态

AHash

FXHash

RodeoReader

STD 随机状态

AHash

FXHash

RodeoResolver