static_sym!(), documentation

Author: simonask

Cargo.lock

@@ -1,4 +1,4 @@
-# Stringleton String Interner
+# Stringleton
 
 Extremely efficient string interning solution for Rust crates.
 
@@ -9,22 +9,22 @@ Extremely efficient string interning solution for Rust crates.
 - Symbol literals (`sym!(...)`) are "free" at the call-site. Multiple
   invocations with the same string value are eagerly reconciled on program
   startup, using link-time tricks.
+- Symbols are tiny. Just a single pointer - 8 bytes on 64-bit platforms.
 - Debugger friendly: If your debugger is able to display a plain Rust `&str`, it
   is capable of displaying `Symbol`.
 - Dynamic library support: Symbols can be passed across dynamic linking
   boundaries (terms and conditions apply - see the documentation of
   `stringleton-dylib`).
 - `no_std` support: `std` synchronization primitives used in the symbol registry
-  can be replaced with `once_cell` and `spin`. (`alloc` is still needed by the
-  internal hash table used in the registry.)
+  can be replaced with `once_cell` and `spin`. _See below for caveats._
 - `serde` support - symbols are serialized/deserialized as strings.
 - Fast bulk-insertion of symbols at runtime.
 
 ## Good use cases
 
 - You have lots of little strings that you need to frequently copy and compare.
 - Your strings come from trusted sources.
-- You need good debugger support for your symbols.
+- You want good debugger support for your symbols.
 
 ## Bad use cases
 
@@ -36,7 +36,7 @@ Extremely efficient string interning solution for Rust crates.
 
 ## Usage
 
-Add `stringleton` as a dependency of your project.
+Add `stringleton` as a dependency of your project, and then you can do:
 
 ```rust,ignore
 use stringleton::{sym, Symbol};
@@ -56,13 +56,30 @@ assert_eq!(message, message2);
 assert_eq!(message.as_str().as_ptr(), message2.as_str().as_ptr());
 ```
 
+## Crate features
+
+- **std** _(enabled by default)_: Use synchronization primitives from the
+  standard library. Implies `alloc`. When disabled, `critical-section` and
+  `spin` must both be enabled _(see below for caveats)_.
+- **alloc** _(enabled by default)_: Support creating symbols from `String`.
+- **serde**: Implements `serde::Serialize` and `serde::Deserialize` for symbols,
+  which will be serialized/deserialized as plain strings.
+- **debug-assertions**: Enables expensive debugging checks at runtime - mostly
+  useful to diagnose problems in complicated linker scenarios.
+- **critical-section**: When `std` is not enabled, this enables `once_cell` as a
+  dependency with the `critical-section` feature enabled. Only relevant in
+  `no_std` environments. _[See `critical-section` for more
+  details.](https://docs.rs/critical-section/latest/critical_section/)_
+- **spin**: When `std` is not enabled, this enables `spin` as a dependency,
+  which is used to obtain global read/write locks on the symbol registry. Only
+  relevant in `no_std` environments (and is a pessimization in other
+  environments).
+
 ## Efficiency
 
 Stringleton tries to be as efficient as possible, but it may make different
-tradeoffs than other string interning libraries.
-
-In particular, Stringleton is optimized towards making the use of the
-`sym!(...)` macro practically free.
+tradeoffs than other string interning libraries. In particular, Stringleton is
+optimized towards making the use of the `sym!(...)` macro practically free.
 
 Consider this function:
 
@@ -81,6 +98,79 @@ get_symbol:
   8bf7    ret
 ```
 
+This is "as fast as it gets", but the price is that all symbols in the program
+are deduplicated when the program starts. Any theoretically faster solution
+would need fairly deep cooperation from the compiler aimed at this specific use
+case.
+
+Also, symbol literals are _always_ a memory load. The compiler cannot perform
+optimizations based on the contents of symbols, because it doesn't know how they
+will be reconciled until link time. For example, while `sym!(a) != sym!(a)` is
+always false, the compiler cannot eliminate code paths relying on that.
+
+## Dynamic libraries
+
+Stringleton relies on magical linker tricks (supported by `linkme` and `ctor`)
+to minimize the cost of the `sym!(...)` macro at runtime. These tricks are
+broadly compatible with dynamic libraries, but there are a few caveats:
+
+1. When a Rust `dylib` crate appears in the dependency graph, and it has
+   `stringleton` as a dependency, things should "just work", due to Rust's
+   [linkage rules](https://doc.rust-lang.org/reference/linkage.html).
+2. When a Rust `cdylib` crate appears in the dependency graph, Cargo seems to be
+   a little less clever, and the `cdylib` dependency may need to use the
+   `stringleton-dylib` crate instead. Due to Rust's linkage rules, this will
+   cause the "host" crate to also link dynamically with Stringleton, and
+   everything will continue to work.
+3. When a library is loaded dynamically at runtime, and it does not appear in
+   the dependency graph, the "host" crate must be prevented from linking
+   statically to `stringleton`, because it would either cause duplicate symbol
+   definitions, or worse, the host and client binaries would disagree about
+   which `Registry` to use. To avoid this, the _host_ binary can use
+   `stringleton-dylib` explicitly instead of `stringleton`, which forces dynamic
+   linkage of the symbol registry.
+4. Dynamically _unloading_ libraries is extremely risky (`dlclose()` and
+   similar). Unloading a library that has any calls to the `sym!(..)` or
+   `static_sym!(..)` macros is instant UB. Such a library can in principle use
+   `Symbol::new()`, but probably not `Symbol::new_static()`.
+
+To summarize:
+
+1. When no dynamic libraries are present in the project, it is always best to
+   use `stringleton` directly.
+2. When only normal Rust dynamic libraries (`crate-type = ["dylib"]`) are
+   present, it is also fine to use `stringleton` directly - Cargo and rustc will
+   figure out how to link things correctly.
+3. `cdylib` dependencies should use `stringleton-dylib`. The host can use
+   `stringleton`.
+4. When loading dynamic libraries at runtime, both sides should use
+   `stringleton-dylib` instead of `stringleton`.
+5. Do not unload dynamic libraries at runtime unless you are really, really sure
+   what you are doing.
+
+## `no_std` caveats
+
+Stringleton works in `no_std` environments, but it does fundamentally require
+two things:
+
+1. Allocator support, in order to maintain the global symbol registry. This is a
+   `hashbrown` hash map.
+2. Some synchronization primitives to control access to the global symbol
+   registry when new symbols are created.
+
+The latter can be supported by the `spin` and `critical-section` features:
+
+- `spin` replaces `std::sync::RwLock`, and is almost always a worse choice when
+  `std` is available.
+- `critical-section` replaces `std::sync::OnceLock` with
+  [`once_cell::sync::OnceCell`](https://docs.rs/once_cell/latest/once_cell/sync/struct.OnceCell.html),
+  and enables the `critical-secion` feature of `once_cell`. Using
+  `critical-section` requires additional work, because you must manually link in
+  a crate that provides the relevant synchronization primitive for the target
+  platform.
+
+Do not use these features unless you are familiar with the tradeoffs.
+
 ## Name
 
 The name is a portmanteau of "string" and "singleton".

README.md

@@ -24,5 +24,4 @@ alloc = ["stringleton-registry/alloc"]
 debug-assertions = ["stringleton-registry/debug-assertions"]
 serde = ["stringleton-registry/serde"]
 critical-section = ["stringleton-registry/critical-section"]
-race = ["stringleton-registry/race"]
 spin = ["stringleton-registry/spin"]

stringleton-dylib/Cargo.toml

@@ -1,5 +1,7 @@
 //! Dynamic linking support for Stringleton.
 //!
+//! _[See the docs for `stringleton`](../stringleton/index.html)._
+//!
 //! This crate always produces a dynamic library, and it should be used by any
 //! crate that ends up being a `cdylib`. When this appears somewhere in the
 //! dependency graph, it causes the Rust compiler to produce a dynamic version

stringleton-dylib/lib.rs

@@ -18,9 +18,11 @@ workspace = true
 [dependencies]
 hashbrown.workspace = true
 # Using once_cell because `std::sync::OnceLock` is not available in no_std.
-once_cell = { version = "1.21.1", optional = true }
+once_cell = { version = "1.21.1", optional = true, default-features = false }
 serde = { workspace = true, optional = true }
-spin = { version = "0.9.8", optional = true }
+spin = { version = "0.9.8", optional = true, default-features = false, features = [
+    "rwlock",
+] }
 
 [features]
 default = ["std"]
@@ -29,5 +31,4 @@ alloc = []
 debug-assertions = []
 serde = ["dep:serde"]
 critical-section = ["once_cell/critical-section"]
-race = ["once_cell/race"]
 spin = ["dep:spin"]

stringleton-registry/Cargo.toml

@@ -1,6 +1,6 @@
 //! Registry helper crate for `stringleton`
 //!
-//! You probably don't have a use for this crate directly. Use the
+//! You probably don't need to use this crate directly. Use the
 //! [`stringleton`](../stringleton) crate or the
 //! [`stringleton-dylib`](../stringleton-dylib) crate instead.
 //!
@@ -27,13 +27,15 @@
 #[cfg(feature = "std")]
 extern crate std;
 
-#[cfg(feature = "alloc")]
+#[cfg(any(feature = "std", feature = "alloc"))]
 extern crate alloc;
 
 mod registry;
 mod site;
+mod static_symbol;
 mod symbol;
 
 pub use registry::*;
 pub use site::*;
+pub use static_symbol::*;
 pub use symbol::*;

stringleton-registry/lib.rs

@@ -6,18 +6,20 @@ use hashbrown::{HashMap, hash_map};
 #[cfg(feature = "alloc")]
 use alloc::{borrow::ToOwned, boxed::Box};
 
-#[cfg(not(any(feature = "std", feature = "critical-section", feature = "race")))]
-compile_error!("Either the `std` or `critical-section` or `race` feature must be enabled");
+#[cfg(not(any(feature = "std", feature = "critical-section")))]
+compile_error!("Either the `std` or `critical-section` feature must be enabled");
 #[cfg(not(any(feature = "std", feature = "spin")))]
 compile_error!("Either the `std` or `spin` feature must be enabled");
 
-#[cfg(feature = "std")]
-use std::sync::{OnceLock, RwLock, RwLockReadGuard, RwLockWriteGuard};
+#[cfg(feature = "spin")]
+use spin::{RwLock, RwLockReadGuard, RwLockWriteGuard};
+#[cfg(not(feature = "spin"))]
+use std::sync::{RwLock, RwLockReadGuard, RwLockWriteGuard};
 
-#[cfg(not(feature = "std"))]
+#[cfg(feature = "critical-section")]
 use once_cell::sync::OnceCell as OnceLock;
-#[cfg(not(feature = "std"))]
-use spin::{RwLock, RwLockReadGuard, RwLockWriteGuard};
+#[cfg(not(feature = "critical-section"))]
+use std::sync::OnceLock;
 
 /// Helper to control the behavior of symbol strings in the registry's hash map.
 #[derive(Clone, Copy, PartialEq, Eq)]
@@ -54,9 +56,9 @@ impl From<&str> for SymbolStr {
 /// This is available for advanced use cases, such as bulk-insertion of many
 /// symbols.
 pub struct Registry {
-    #[cfg(feature = "std")]
+    #[cfg(not(feature = "spin"))]
     store: std::sync::RwLock<Store>,
-    #[cfg(all(feature = "spin", not(feature = "std")))]
+    #[cfg(feature = "spin")]
     store: spin::RwLock<Store>,
 }
 
@@ -100,12 +102,12 @@ impl Registry {
     #[inline]
     pub fn read(&'static self) -> RegistryReadGuard {
         RegistryReadGuard {
-            #[cfg(feature = "std")]
+            #[cfg(not(feature = "spin"))]
             guard: self
                 .store
                 .read()
                 .unwrap_or_else(std::sync::PoisonError::into_inner),
-            #[cfg(not(feature = "std"))]
+            #[cfg(feature = "spin")]
             guard: self.store.read(),
         }
     }
@@ -117,12 +119,12 @@ impl Registry {
     #[inline]
     pub fn write(&'static self) -> RegistryWriteGuard {
         RegistryWriteGuard {
-            #[cfg(feature = "std")]
+            #[cfg(not(feature = "spin"))]
             guard: self
                 .store
                 .write()
                 .unwrap_or_else(std::sync::PoisonError::into_inner),
-            #[cfg(not(feature = "std"))]
+            #[cfg(feature = "spin")]
             guard: self.store.write(),
         }
     }