Lib.rs

一个多线程和单线程的 字符串池，允许字符串以最小的内存占用进行缓存，并使用唯一键与之关联，以便在任何时候检索。一个 Rodeo 允许 O(1) 池化和解析，并且可以被转换为一个 RodeoReader 以允许无争用的解析，包括键到字符串和字符串到键的操作。它也可以转换为一个 RodeoResolver，仅提供键到字符串操作，以实现最低的内存占用。

我应该使用哪个池？

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

Cargo特性

默认情况下，lasso有一个依赖项，hashbrown，并且仅公开Rodeo。由于标准库的hashmap中raw_entry api目前不稳定，因此使用了Hashbrown。原始hashmap API用于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 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);

示例：使用ThreadedRodeo

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

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

有时您希望键只存在于（或不存在）一定范围的值中，以便您可以拥有自定义的niche。这允许您将更多数据打包到原本未使用的空间中，这对于内存敏感型应用程序可能至关重要。

use lasso::{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 lasso::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 lasso::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
CPU: Ryzen 9 3900X，主频 3800MHz
RAM: 3200MHz
Rustc: 稳定版 1.44.1

Rodeo

STD 随机状态

AHash

FXHash

ThreadedRodeo

STD 随机状态

AHash

FXHash

RodeoReader

STD 随机状态

AHash

FXHash

RodeoResolver