// Copyright 2014 The Rust Project Developers. See the COPYRIGHT // file at the top-level directory of this distribution and at // http://rust-lang.org/COPYRIGHT. // // Licensed under the Apache License, Version 2.0 or the MIT license // , at your // option. This file may not be copied, modified, or distributed // except according to those terms. //! 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 pointers, //! //! 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::scoped::Key` are likely much //! more useful in practice than this OS-based version which likely requires //! unsafe code to interoperate with. //! //! # Example //! //! Using a dynamically allocated TLS key. Note that this key can be shared //! among many threads via an `Arc`. //! //! ```rust,ignore //! 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. //! //! ```rust,ignore //! static KEY: StaticKey = INIT; //! //! unsafe { //! assert!(KEY.get().is_null()); //! KEY.set(1 as *mut u8); //! } //! ``` #![allow(non_camel_case_types)] use prelude::*; use kinds::marker; use mem; use rustrt::exclusive::Exclusive; use rustrt; use sync::atomic::{mod, AtomicUint}; use sync::{Once, ONCE_INIT}; use sys::thread_local 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. /// /// # Example /// /// ```ignore /// use tls::os::{StaticKey, INIT}; /// /// static KEY: StaticKey = INIT; /// /// unsafe { /// assert!(KEY.get().is_null()); /// KEY.set(1 as *mut u8); /// } /// ``` pub struct StaticKey { /// Inner static TLS key (internals), created with by `INIT_INNER` in this /// module. pub inner: StaticKeyInner, /// Destructor for the TLS value. /// /// See `Key::new` for information about when the destructor runs and how /// it runs. pub dtor: Option, } /// Inner contents of `StaticKey`, created by the `INIT_INNER` constant. pub struct StaticKeyInner { key: AtomicUint, nc: marker::NoCopy, } /// A type for a safely managed OS-based TLS slot. /// /// This type allocates an OS TLS key when it is initialized and will deallocate /// the key when it falls out of scope. When compared with `StaticKey`, this /// type is entirely safe to use. /// /// Implementations will likely, however, contain unsafe code as this type only /// operates on `*mut u8`, an unsafe pointer. /// /// # Example /// /// ```rust,ignore /// use tls::os::Key; /// /// 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. /// ``` pub struct Key { key: imp::Key, } /// Constant initialization value for static TLS keys. /// /// This value specifies no destructor by default. pub const INIT: StaticKey = StaticKey { inner: INIT_INNER, dtor: None, }; /// Constant initialization value for the inner part of static TLS keys. /// /// This value allows specific configuration of the destructor for a TLS key. pub const INIT_INNER: StaticKeyInner = StaticKeyInner { key: atomic::INIT_ATOMIC_UINT, nc: marker::NoCopy, }; static INIT_KEYS: Once = ONCE_INIT; static mut KEYS: *mut Exclusive> = 0 as *mut _; impl StaticKey { /// 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) } /// Deallocates this OS TLS key. /// /// This function is unsafe as there is no guarantee that the key is not /// currently in use by other threads or will not ever be used again. /// /// Note that this does *not* run the user-provided destructor if one was /// specified at definition time. Doing so must be done manually. pub unsafe fn destroy(&self) { match self.inner.key.swap(0, atomic::SeqCst) { 0 => {} n => { unregister_key(n as imp::Key); imp::destroy(n as imp::Key) } } } #[inline] unsafe fn key(&self) -> imp::Key { match self.inner.key.load(atomic::Relaxed) { 0 => self.lazy_init() as imp::Key, n => n as imp::Key } } unsafe fn lazy_init(&self) -> uint { let key = imp::create(self.dtor); assert!(key != 0); match self.inner.key.compare_and_swap(0, key as uint, atomic::SeqCst) { // The CAS succeeded, so we've created the actual key 0 => { register_key(key); key as uint } // If someone beat us to the punch, use their key instead n => { imp::destroy(key); n } } } } impl Key { /// Create a new managed OS TLS key. /// /// This key will be deallocated when the key falls out of scope. /// /// The argument provided is an optionally-specified destructor for the /// value of this TLS key. When a thread exits and the value for this key /// is non-null the destructor will be invoked. The TLS value will be reset /// to null before the destructor is invoked. /// /// Note that the destructor will not be run when the `Key` goes out of /// scope. #[inline] pub fn new(dtor: Option) -> Key { Key { key: unsafe { imp::create(dtor) } } } /// See StaticKey::get #[inline] pub fn get(&self) -> *mut u8 { unsafe { imp::get(self.key) } } /// See StaticKey::set #[inline] pub fn set(&self, val: *mut u8) { unsafe { imp::set(self.key, val) } } } impl Drop for Key { fn drop(&mut self) { unsafe { imp::destroy(self.key) } } } fn init_keys() { let keys = box Exclusive::new(Vec::::new()); unsafe { KEYS = mem::transmute(keys); } rustrt::at_exit(proc() unsafe { let keys: Box>> = mem::transmute(KEYS); KEYS = 0 as *mut _; let keys = keys.lock(); for key in keys.iter() { imp::destroy(*key); } }); } fn register_key(key: imp::Key) { INIT_KEYS.doit(init_keys); let mut keys = unsafe { (*KEYS).lock() }; keys.push(key); } fn unregister_key(key: imp::Key) { INIT_KEYS.doit(init_keys); let mut keys = unsafe { (*KEYS).lock() }; keys.retain(|k| *k != key); } #[cfg(test)] mod tests { use prelude::*; use super::{Key, StaticKey, INIT_INNER}; fn assert_sync() {} fn assert_send() {} #[test] fn smoke() { assert_sync::(); assert_send::(); let k1 = Key::new(None); let k2 = Key::new(None); assert!(k1.get().is_null()); assert!(k2.get().is_null()); k1.set(1 as *mut _); k2.set(2 as *mut _); assert_eq!(k1.get() as uint, 1); assert_eq!(k2.get() as uint, 2); } #[test] fn statik() { static K1: StaticKey = StaticKey { inner: INIT_INNER, dtor: None }; static K2: StaticKey = StaticKey { inner: INIT_INNER, dtor: None }; unsafe { assert!(K1.get().is_null()); assert!(K2.get().is_null()); K1.set(1 as *mut _); K2.set(2 as *mut _); assert_eq!(K1.get() as uint, 1); assert_eq!(K2.get() as uint, 2); } } }