Expand description
A safe place for your strings.
asylum is a fast, lightweight, thread-safe string interner.
It stores each unique string once, returns cheap Symbol handles, and
compares symbols by interned identity instead of comparing string bytes.
This is useful for parsers, compilers, protocol implementations, and other
workloads that repeatedly see the same strings.
§Semantics
Symbol equality and hashing are identity-based: two symbols compare
equal when they point to the same interned allocation. Since every live
allocation is canonicalized through intern, symbols created from equal
strings compare equal while they are live. Comparisons with str and
String use string contents instead.
Symbol is intentionally a small handle. Interned bytes are stored in the
global pool and reference counted across all live symbols.
§Cleanup model
Dropping the last Symbol for a string records a pending cleanup on the
affected shard. Once enough final drops accumulate, that shard is swept and
entries with no live Symbol handles are removed. This keeps Drop cheap
for short-lived symbols while bounding stale entries under continuing churn.
Call collect_unused at quiescent points to sweep every shard without
explicitly shrinking capacity. Call shrink_to_fit as a final cleanup
operation before program shutdown when you want to release the pool’s spare
capacity. Both functions remove entries with no live Symbol handles that
are observable while each shard is locked; they are exact when no concurrent
interning or dropping is racing with the sweep. Avoid calling
shrink_to_fit in a running hot path: shrinking shards can make later
intern calls allocate again.
§Concurrency
The global pool is split into independent shards. Interning a string locks
only the shard selected for that string; size, capacity, and
shrink_to_fit inspect all shards.
Structs§
- Symbol
- A lightweight handle to an interned string.
Functions§
- capacity
- Returns the total number of hash-table slots currently allocated by the pool.
- collect_
unused - Collects unused pool entries without explicitly shrinking retained capacity.
- intern
- Interns a string slice and returns its canonical
Symbol. - shrink_
to_ fit - Collects unused pool entries and shrinks the interner’s capacity around the
number of strings still referenced by live
Symbols. - size
- Returns the number of entries currently stored in the interner.