Struct Registry

pub struct Registry { /* private fields */ }

The global symbol registry.

This is available for advanced use cases, such as bulk-insertion of many symbols.

Implementations

impl Registry

pub fn global() -> &'static Registry

Get the global registry.

pub fn read(&'static self) -> RegistryReadGuard

Acquire a global read lock of the registry’s data.

New symbols cannot be created while the read lock is held, but acquiring the lock does not prevent other threads from accessing the string representation of a Symbol.

pub fn write(&'static self) -> RegistryWriteGuard

Acquire a global write lock of the registry’s data.

Note that acquiring this lock does not prevent other threads from reading the string representation of a Symbol.

pub unsafe fn register_sites(table: &[Site])

Resolve and register symbols from a table.

You should never need to call this function manually.

Using the stringleton::enable!() causes this to be called with the symbols from the current crate in a static initializer function.

Safety

table must not be accessed from any other thread. This is ensured when this function is called as part of a static initializer function.

pub fn get(&'static self, string: &str) -> Option<Symbol>

Check if the registry contains a symbol matching string and return it if so.

pub fn get_or_insert(&'static self, string: &str) -> Symbol

Get the existing symbol for string, or insert a new one.

This opportunistically takes a read lock to check if the symbol exists, and only takes a write lock if it doesn’t.

If you are inserting many new symbols, prefer acquiring the write lock by calling write() and then repeatedly call RegistryWriteGuard::get_or_insert().

pub fn get_or_insert_static( &'static self, string: &'static &'static str, ) -> Symbol

Get the existing symbol for string, or insert a new one.

This variant is slightly more efficient than get_or_insert(), because it can reuse the storage of string directly for this symbol. In other words, if this call inserted the symbol, the returned Symbol will be backed by string, and no additional allocations will have happened.

This opportunistically takes a read lock to check if the symbol exists, and only takes a write lock if it doesn’t.

If you are inserting many new symbols, prefer acquiring the write lock by calling write() and then repeatedly call RegistryWriteGuard::get_or_insert_static().

pub fn get_by_address(&'static self, address: u64) -> Option<Symbol>

Check if a symbol has been registered at address (i.e., it has been produced by Symbol::to_ffi()), and return the symbol if so.

This can be used to verify symbols that have made a round-trip over an FFI boundary.