| //! 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`. |
| //! |
| //! ```ignore (cannot-doctest-private-modules) |
| //! 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. |
| //! ``` |
| //! |
| //! Sometimes a statically allocated key is either required or easier to work |
| //! with, however. |
| //! |
| //! ```ignore (cannot-doctest-private-modules) |
| //! static KEY: StaticKey = INIT; |
| //! |
| //! unsafe { |
| //! assert!(KEY.get().is_null()); |
| //! KEY.set(1 as *mut u8); |
| //! } |
| //! ``` |
| |
| #![allow(non_camel_case_types)] |
| #![unstable(feature = "thread_local_internals", issue = "none")] |
| #![allow(dead_code)] |
| |
| #[cfg(test)] |
| mod tests; |
| |
| use crate::sync::atomic::{self, AtomicUsize, Ordering}; |
| use crate::sys::thread_local_key as imp; |
| |
| /// A type for TLS keys that are statically allocated. |
| /// |
| /// This type is entirely `unsafe` to use as it does not protect against |
| /// use-after-deallocation or use-during-deallocation. |
| /// |
| /// The actual OS-TLS key is lazily allocated when this is used for the first |
| /// time. The key is also deallocated when the Rust runtime exits or `destroy` |
| /// is called, whichever comes first. |
| /// |
| /// # Examples |
| /// |
| /// ```ignore (cannot-doctest-private-modules) |
| /// use tls::os::{StaticKey, INIT}; |
| /// |
| /// // Use a regular global static to store the key. |
| /// static KEY: StaticKey = INIT; |
| /// |
| /// // The state provided via `get` and `set` is thread-local. |
| /// unsafe { |
| /// assert!(KEY.get().is_null()); |
| /// KEY.set(1 as *mut u8); |
| /// } |
| /// ``` |
| pub struct StaticKey { |
| /// Inner static TLS key (internals). |
| key: AtomicUsize, |
| /// Destructor for the TLS value. |
| /// |
| /// See `Key::new` for information about when the destructor runs and how |
| /// it runs. |
| dtor: Option<unsafe extern "C" fn(*mut u8)>, |
| } |
| |
| /// Constant initialization value for static TLS keys. |
| /// |
| /// This value specifies no destructor by default. |
| pub const INIT: StaticKey = StaticKey::new(None); |
| |
| // Define a sentinel value that is likely not to be returned |
| // as a TLS key. |
| #[cfg(not(target_os = "nto"))] |
| const KEY_SENTVAL: usize = 0; |
| // On QNX Neutrino, 0 is always returned when currently not in use. |
| // Using 0 would mean to always create two keys and remote the first |
| // one (with value of 0) immediately afterwards. |
| #[cfg(target_os = "nto")] |
| const KEY_SENTVAL: usize = libc::PTHREAD_KEYS_MAX + 1; |
| |
| impl StaticKey { |
| #[rustc_const_unstable(feature = "thread_local_internals", issue = "none")] |
| pub const fn new(dtor: Option<unsafe extern "C" fn(*mut u8)>) -> StaticKey { |
| StaticKey { key: atomic::AtomicUsize::new(KEY_SENTVAL), dtor } |
| } |
| |
| /// Gets the value associated with this TLS key |
| /// |
| /// This will lazily allocate a TLS key from the OS if one has not already |
| /// been allocated. |
| #[inline] |
| pub unsafe fn get(&self) -> *mut u8 { |
| imp::get(self.key()) |
| } |
| |
| /// Sets this TLS key to a new value. |
| /// |
| /// This will lazily allocate a TLS key from the OS if one has not already |
| /// been allocated. |
| #[inline] |
| pub unsafe fn set(&self, val: *mut u8) { |
| imp::set(self.key(), val) |
| } |
| |
| #[inline] |
| unsafe fn key(&self) -> imp::Key { |
| match self.key.load(Ordering::Relaxed) { |
| KEY_SENTVAL => self.lazy_init() as imp::Key, |
| n => n as imp::Key, |
| } |
| } |
| |
| unsafe fn lazy_init(&self) -> usize { |
| // POSIX allows the key created here to be KEY_SENTVAL, but the compare_exchange |
| // below relies on using KEY_SENTVAL as a sentinel value to check who won the |
| // race to set the shared TLS key. As far as I know, there is no |
| // guaranteed value that cannot be returned as a posix_key_create key, |
| // so there is no value we can initialize the inner key with to |
| // prove that it has not yet been set. As such, we'll continue using a |
| // value of KEY_SENTVAL, but with some gyrations to make sure we have a non-KEY_SENTVAL |
| // value returned from the creation routine. |
| // FIXME: this is clearly a hack, and should be cleaned up. |
| let key1 = imp::create(self.dtor); |
| let key = if key1 as usize != KEY_SENTVAL { |
| key1 |
| } else { |
| let key2 = imp::create(self.dtor); |
| imp::destroy(key1); |
| key2 |
| }; |
| rtassert!(key as usize != KEY_SENTVAL); |
| match self.key.compare_exchange( |
| KEY_SENTVAL, |
| key as usize, |
| Ordering::SeqCst, |
| Ordering::SeqCst, |
| ) { |
| // The CAS succeeded, so we've created the actual key |
| Ok(_) => key as usize, |
| // If someone beat us to the punch, use their key instead |
| Err(n) => { |
| imp::destroy(key); |
| n |
| } |
| } |
| } |
| } |