Crate static_id

source ·
Expand description

§StaticId

This Rust library provides a cache-efficient implementation of StaticId for handling interned identifiers with optimal performance.

§Features

  • StaticId: A highly optimized, interned identifier type combining a code and a venue, e.g., for financial products
  • Exceptional cache efficiency: Each StaticId is represented by a single 64-bit pointer
  • Fast comparisons: Equality checks and hashing operations only compare 8 bytes, regardless of the actual string length
  • Lazy evaluation: The actual string data is only accessed during serialization
  • Serialization and deserialization support using Serde

§How this works

  • Compact Representation: Each StaticId is stored as a single 64-bit pointer, regardless of the length of the underlying strings. Duplicate values are not allocated in memory; instead, the actual ID value exists in memory once, and each ID owns only a pointer to that memory location.
  • Fast Comparisons: Equality checks and hash computations only compare the 64-bit pointers, making these operations extremely fast and constant-time. Most operations after creation, such as hashing and comparison, use only 8 bytes and are likely to be cache-efficient.
  • Lazy Evaluation: The actual string data is only accessed when necessary (e.g., during serialization or debugging), minimizing unnecessary memory access. Users should be aware that these operations might be slower as they may require accessing the actual value from memory.
  • Creation Overhead: To ensure uniqueness, there’s a slight overhead during initial creation (approximately 15 ns per object creation). This trade-off allows for significant performance gains in subsequent operations.
  • Input Constraints: For clarity and efficiency, the input values are limited: ‘code’ is restricted to 32 characters, and ‘venue’ to 16 characters.

§Limitations

  • The code component of a StaticId cannot exceed 32 bytes.
  • The venue component of a StaticId cannot exceed 16 bytes.
  • Attempting to create a StaticId with components exceeding these limits will result in truncation.
  • Accessing the data (e.g., during serialization or debugging) may be slow.

§Usage

StaticId combines a Code (up to 32 bytes) and a Venue (up to 16 bytes) into an interned identifier:

use static_id::StaticId;
 
// Create from string slices
let id = StaticId::from_str("AAPL", "NASDAQ");
 
// Create from byte slices
let id_bytes = StaticId::from_bytes(b"AAPL", b"NASDAQ");
 
assert_eq!(id.get_id().code.as_str(), "AAPL");
assert_eq!(id.get_id().venue.as_str(), "NASDAQ");
 
// Get the length of the combined code and venue
println!("Length: {}", id.len());  // Outputs the sum of code and venue lengths
 
// Get the number of unique StaticIds in the cache
println!("Cache size: {}", StaticId::cache_len());
 
// Fast equality check (compares only 8 bytes)
let id2 = StaticId::from_str("AAPL", "NASDAQ");
assert_eq!(id, id2);
 
println!("ID: {}", id); // => APPL@NASDAQ
 
// Memory usage
println!("Size of StaticId: {} bytes", std::mem::size_of::<StaticId>());  // Outputs: 8 bytes

§License

This project is licensed under [LICENSE NAME] - see the LICENSE.md file for details.

§Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Re-exports§

Modules§

Structs§

Type Aliases§