🔬This is a nightly-only experimental API. (thread_local_internals)
Expand description

OS-based thread local storage

This module provides an implementation of OS-based thread local storage, using the native OS-provided facilities (think TlsAlloc or pthread_setspecific). The interface of this differs from the other types of thread-local-storage provided in this crate in that OS-based TLS can only get/set pointer-sized data, possibly with an associated destructor.

This module also provides two flavors of TLS. One is intended for static initialization, and does not contain a Drop implementation to deallocate the OS-TLS key. The other is a type which does implement Drop and hence has a safe interface.

Usage

This module should likely not be used directly unless other primitives are being built on. Types such as thread_local::spawn::Key are likely much more useful in practice than this OS-based version which likely requires unsafe code to interoperate with.

Examples

Using a dynamically allocated TLS key. Note that this key can be shared among many threads via an Arc.

let key = Key::new(None);
assert!(key.get().is_null());
key.set(1 as *mut u8);
assert!(!key.get().is_null());

drop(key); // deallocate this TLS slot.
Run

Sometimes a statically allocated key is either required or easier to work with, however.

static KEY: StaticKey = INIT;

unsafe {
    assert!(KEY.get().is_null());
    KEY.set(1 as *mut u8);
}
Run

Structs

KeyExperimental
A type for a safely managed OS-based TLS slot.
StaticKeyExperimental
A type for TLS keys that are statically allocated.

Constants

INITExperimental
Constant initialization value for static TLS keys.
KEY_SENTVAL 🔒 Experimental