Ronald Kinard
8 years ago
committed by
GitHub
8 changed files with 1249 additions and 0 deletions
@ -0,0 +1,116 @@ |
|||||||
|
// Copyright 2016 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 <LICENSE-APACHE or
|
||||||
|
// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
|
||||||
|
// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
|
||||||
|
// option. This file may not be copied, modified, or distributed
|
||||||
|
// except according to those terms.
|
||||||
|
|
||||||
|
#![cfg(target_thread_local)] |
||||||
|
#![unstable(feature = "thread_local_internals", issue = "0")] |
||||||
|
|
||||||
|
use cell::{Cell, UnsafeCell}; |
||||||
|
use intrinsics; |
||||||
|
use ptr; |
||||||
|
|
||||||
|
pub struct Key<T> { |
||||||
|
inner: UnsafeCell<Option<T>>, |
||||||
|
|
||||||
|
// Metadata to keep track of the state of the destructor. Remember that
|
||||||
|
// these variables are thread-local, not global.
|
||||||
|
dtor_registered: Cell<bool>, |
||||||
|
dtor_running: Cell<bool>, |
||||||
|
} |
||||||
|
|
||||||
|
unsafe impl<T> ::marker::Sync for Key<T> { } |
||||||
|
|
||||||
|
impl<T> Key<T> { |
||||||
|
pub const fn new() -> Key<T> { |
||||||
|
Key { |
||||||
|
inner: UnsafeCell::new(None), |
||||||
|
dtor_registered: Cell::new(false), |
||||||
|
dtor_running: Cell::new(false) |
||||||
|
} |
||||||
|
} |
||||||
|
|
||||||
|
pub fn get(&'static self) -> Option<&'static UnsafeCell<Option<T>>> { |
||||||
|
unsafe { |
||||||
|
if intrinsics::needs_drop::<T>() && self.dtor_running.get() { |
||||||
|
return None |
||||||
|
} |
||||||
|
self.register_dtor(); |
||||||
|
} |
||||||
|
Some(&self.inner) |
||||||
|
} |
||||||
|
|
||||||
|
unsafe fn register_dtor(&self) { |
||||||
|
if !intrinsics::needs_drop::<T>() || self.dtor_registered.get() { |
||||||
|
return |
||||||
|
} |
||||||
|
|
||||||
|
register_dtor(self as *const _ as *mut u8, |
||||||
|
destroy_value::<T>); |
||||||
|
self.dtor_registered.set(true); |
||||||
|
} |
||||||
|
} |
||||||
|
|
||||||
|
unsafe fn register_dtor(t: *mut u8, dtor: unsafe extern fn(*mut u8)) { |
||||||
|
// The fallback implementation uses a vanilla OS-based TLS key to track
|
||||||
|
// the list of destructors that need to be run for this thread. The key
|
||||||
|
// then has its own destructor which runs all the other destructors.
|
||||||
|
//
|
||||||
|
// The destructor for DTORS is a little special in that it has a `while`
|
||||||
|
// loop to continuously drain the list of registered destructors. It
|
||||||
|
// *should* be the case that this loop always terminates because we
|
||||||
|
// provide the guarantee that a TLS key cannot be set after it is
|
||||||
|
// flagged for destruction.
|
||||||
|
use sys_common::thread_local as os; |
||||||
|
|
||||||
|
static DTORS: os::StaticKey = os::StaticKey::new(Some(run_dtors)); |
||||||
|
type List = Vec<(*mut u8, unsafe extern fn(*mut u8))>; |
||||||
|
if DTORS.get().is_null() { |
||||||
|
let v: Box<List> = box Vec::new(); |
||||||
|
DTORS.set(Box::into_raw(v) as *mut u8); |
||||||
|
} |
||||||
|
let list: &mut List = &mut *(DTORS.get() as *mut List); |
||||||
|
list.push((t, dtor)); |
||||||
|
|
||||||
|
unsafe extern fn run_dtors(mut ptr: *mut u8) { |
||||||
|
while !ptr.is_null() { |
||||||
|
let list: Box<List> = Box::from_raw(ptr as *mut List); |
||||||
|
for &(ptr, dtor) in list.iter() { |
||||||
|
dtor(ptr); |
||||||
|
} |
||||||
|
ptr = DTORS.get(); |
||||||
|
DTORS.set(ptr::null_mut()); |
||||||
|
} |
||||||
|
} |
||||||
|
} |
||||||
|
|
||||||
|
pub unsafe extern fn destroy_value<T>(ptr: *mut u8) { |
||||||
|
let ptr = ptr as *mut Key<T>; |
||||||
|
// Right before we run the user destructor be sure to flag the
|
||||||
|
// destructor as running for this thread so calls to `get` will return
|
||||||
|
// `None`.
|
||||||
|
(*ptr).dtor_running.set(true); |
||||||
|
|
||||||
|
// The OSX implementation of TLS apparently had an odd aspect to it
|
||||||
|
// where the pointer we have may be overwritten while this destructor
|
||||||
|
// is running. Specifically if a TLS destructor re-accesses TLS it may
|
||||||
|
// trigger a re-initialization of all TLS variables, paving over at
|
||||||
|
// least some destroyed ones with initial values.
|
||||||
|
//
|
||||||
|
// This means that if we drop a TLS value in place on OSX that we could
|
||||||
|
// revert the value to its original state halfway through the
|
||||||
|
// destructor, which would be bad!
|
||||||
|
//
|
||||||
|
// Hence, we use `ptr::read` on OSX (to move to a "safe" location)
|
||||||
|
// instead of drop_in_place.
|
||||||
|
if cfg!(target_os = "macos") { |
||||||
|
ptr::read((*ptr).inner.get()); |
||||||
|
} else { |
||||||
|
ptr::drop_in_place((*ptr).inner.get()); |
||||||
|
} |
||||||
|
} |
||||||
@ -0,0 +1,66 @@ |
|||||||
|
// Copyright 2016 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 <LICENSE-APACHE or
|
||||||
|
// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
|
||||||
|
// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
|
||||||
|
// option. This file may not be copied, modified, or distributed
|
||||||
|
// except according to those terms.
|
||||||
|
|
||||||
|
#![allow(dead_code)] // not used on all platforms
|
||||||
|
|
||||||
|
use collections::BTreeMap; |
||||||
|
use ptr; |
||||||
|
use sync::atomic::{AtomicUsize, ATOMIC_USIZE_INIT, Ordering}; |
||||||
|
|
||||||
|
pub type Key = usize; |
||||||
|
|
||||||
|
type Dtor = unsafe extern fn(*mut u8); |
||||||
|
|
||||||
|
static NEXT_KEY: AtomicUsize = ATOMIC_USIZE_INIT; |
||||||
|
|
||||||
|
static mut KEYS: *mut BTreeMap<Key, Option<Dtor>> = ptr::null_mut(); |
||||||
|
|
||||||
|
#[thread_local] |
||||||
|
static mut LOCALS: *mut BTreeMap<Key, *mut u8> = ptr::null_mut(); |
||||||
|
|
||||||
|
unsafe fn keys() -> &'static mut BTreeMap<Key, Option<Dtor>> { |
||||||
|
if KEYS == ptr::null_mut() { |
||||||
|
KEYS = Box::into_raw(Box::new(BTreeMap::new())); |
||||||
|
} |
||||||
|
&mut *KEYS |
||||||
|
} |
||||||
|
|
||||||
|
unsafe fn locals() -> &'static mut BTreeMap<Key, *mut u8> { |
||||||
|
if LOCALS == ptr::null_mut() { |
||||||
|
LOCALS = Box::into_raw(Box::new(BTreeMap::new())); |
||||||
|
} |
||||||
|
&mut *LOCALS |
||||||
|
} |
||||||
|
|
||||||
|
#[inline] |
||||||
|
pub unsafe fn create(dtor: Option<Dtor>) -> Key { |
||||||
|
let key = NEXT_KEY.fetch_add(1, Ordering::SeqCst); |
||||||
|
keys().insert(key, dtor); |
||||||
|
key |
||||||
|
} |
||||||
|
|
||||||
|
#[inline] |
||||||
|
pub unsafe fn get(key: Key) -> *mut u8 { |
||||||
|
if let Some(&entry) = locals().get(&key) { |
||||||
|
entry |
||||||
|
} else { |
||||||
|
ptr::null_mut() |
||||||
|
} |
||||||
|
} |
||||||
|
|
||||||
|
#[inline] |
||||||
|
pub unsafe fn set(key: Key, value: *mut u8) { |
||||||
|
locals().insert(key, value); |
||||||
|
} |
||||||
|
|
||||||
|
#[inline] |
||||||
|
pub unsafe fn destroy(key: Key) { |
||||||
|
keys().remove(&key); |
||||||
|
} |
||||||
@ -0,0 +1,270 @@ |
|||||||
|
// 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 <LICENSE-APACHE or
|
||||||
|
// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
|
||||||
|
// <LICENSE-MIT or http://opensource.org/licenses/MIT>, 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::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`.
|
||||||
|
//!
|
||||||
|
//! ```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)] |
||||||
|
#![unstable(feature = "thread_local_internals", issue = "0")] |
||||||
|
#![allow(dead_code)] // sys isn't exported yet
|
||||||
|
|
||||||
|
use sync::atomic::{self, AtomicUsize, Ordering}; |
||||||
|
|
||||||
|
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.
|
||||||
|
///
|
||||||
|
/// # Examples
|
||||||
|
///
|
||||||
|
/// ```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).
|
||||||
|
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 fn(*mut u8)>, |
||||||
|
} |
||||||
|
|
||||||
|
/// 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`, a raw pointer.
|
||||||
|
///
|
||||||
|
/// # Examples
|
||||||
|
///
|
||||||
|
/// ```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::new(None); |
||||||
|
|
||||||
|
impl StaticKey { |
||||||
|
pub const fn new(dtor: Option<unsafe extern fn(*mut u8)>) -> StaticKey { |
||||||
|
StaticKey { |
||||||
|
key: atomic::AtomicUsize::new(0), |
||||||
|
dtor: 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) } |
||||||
|
|
||||||
|
/// 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.key.swap(0, Ordering::SeqCst) { |
||||||
|
0 => {} |
||||||
|
n => { imp::destroy(n as imp::Key) } |
||||||
|
} |
||||||
|
} |
||||||
|
|
||||||
|
#[inline] |
||||||
|
unsafe fn key(&self) -> imp::Key { |
||||||
|
match self.key.load(Ordering::Relaxed) { |
||||||
|
0 => 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 0, but the compare_and_swap
|
||||||
|
// below relies on using 0 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 0, but with some gyrations to make sure we have a non-0
|
||||||
|
// 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 != 0 { |
||||||
|
key1 |
||||||
|
} else { |
||||||
|
let key2 = imp::create(self.dtor); |
||||||
|
imp::destroy(key1); |
||||||
|
key2 |
||||||
|
}; |
||||||
|
assert!(key != 0); |
||||||
|
match self.key.compare_and_swap(0, key as usize, Ordering::SeqCst) { |
||||||
|
// The CAS succeeded, so we've created the actual key
|
||||||
|
0 => key as usize, |
||||||
|
// If someone beat us to the punch, use their key instead
|
||||||
|
n => { imp::destroy(key); n } |
||||||
|
} |
||||||
|
} |
||||||
|
} |
||||||
|
|
||||||
|
impl Key { |
||||||
|
/// Creates 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<unsafe extern fn(*mut u8)>) -> 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) } |
||||||
|
} |
||||||
|
} |
||||||
|
|
||||||
|
#[cfg(test)] |
||||||
|
mod tests { |
||||||
|
use super::{Key, StaticKey}; |
||||||
|
|
||||||
|
fn assert_sync<T: Sync>() {} |
||||||
|
fn assert_send<T: Send>() {} |
||||||
|
|
||||||
|
#[test] |
||||||
|
fn smoke() { |
||||||
|
assert_sync::<Key>(); |
||||||
|
assert_send::<Key>(); |
||||||
|
|
||||||
|
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 usize, 1); |
||||||
|
assert_eq!(k2.get() as usize, 2); |
||||||
|
} |
||||||
|
|
||||||
|
#[test] |
||||||
|
fn statik() { |
||||||
|
static K1: StaticKey = StaticKey::new(None); |
||||||
|
static K2: StaticKey = StaticKey::new(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 usize, 1); |
||||||
|
assert_eq!(K2.get() as usize, 2); |
||||||
|
} |
||||||
|
} |
||||||
|
} |
||||||
@ -0,0 +1,596 @@ |
|||||||
|
// Copyright 2014-2015 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 <LICENSE-APACHE or
|
||||||
|
// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
|
||||||
|
// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
|
||||||
|
// option. This file may not be copied, modified, or distributed
|
||||||
|
// except according to those terms.
|
||||||
|
|
||||||
|
//! Thread local storage
|
||||||
|
|
||||||
|
#![unstable(feature = "thread_local_internals", issue = "0")] |
||||||
|
|
||||||
|
use cell::UnsafeCell; |
||||||
|
use fmt; |
||||||
|
use mem; |
||||||
|
|
||||||
|
/// A thread local storage key which owns its contents.
|
||||||
|
///
|
||||||
|
/// This key uses the fastest possible implementation available to it for the
|
||||||
|
/// target platform. It is instantiated with the `thread_local!` macro and the
|
||||||
|
/// primary method is the `with` method.
|
||||||
|
///
|
||||||
|
/// The `with` method yields a reference to the contained value which cannot be
|
||||||
|
/// sent across threads or escape the given closure.
|
||||||
|
///
|
||||||
|
/// # Initialization and Destruction
|
||||||
|
///
|
||||||
|
/// Initialization is dynamically performed on the first call to `with()`
|
||||||
|
/// within a thread, and values support destructors which will be run when a
|
||||||
|
/// thread exits.
|
||||||
|
///
|
||||||
|
/// # Examples
|
||||||
|
///
|
||||||
|
/// ```
|
||||||
|
/// use std::cell::RefCell;
|
||||||
|
/// use std::thread;
|
||||||
|
///
|
||||||
|
/// thread_local!(static FOO: RefCell<u32> = RefCell::new(1));
|
||||||
|
///
|
||||||
|
/// FOO.with(|f| {
|
||||||
|
/// assert_eq!(*f.borrow(), 1);
|
||||||
|
/// *f.borrow_mut() = 2;
|
||||||
|
/// });
|
||||||
|
///
|
||||||
|
/// // each thread starts out with the initial value of 1
|
||||||
|
/// thread::spawn(move|| {
|
||||||
|
/// FOO.with(|f| {
|
||||||
|
/// assert_eq!(*f.borrow(), 1);
|
||||||
|
/// *f.borrow_mut() = 3;
|
||||||
|
/// });
|
||||||
|
/// });
|
||||||
|
///
|
||||||
|
/// // we retain our original value of 2 despite the child thread
|
||||||
|
/// FOO.with(|f| {
|
||||||
|
/// assert_eq!(*f.borrow(), 2);
|
||||||
|
/// });
|
||||||
|
/// ```
|
||||||
|
///
|
||||||
|
/// # Platform-specific behavior
|
||||||
|
///
|
||||||
|
/// Note that a "best effort" is made to ensure that destructors for types
|
||||||
|
/// stored in thread local storage are run, but not all platforms can guarantee
|
||||||
|
/// that destructors will be run for all types in thread local storage. For
|
||||||
|
/// example, there are a number of known caveats where destructors are not run:
|
||||||
|
///
|
||||||
|
/// 1. On Unix systems when pthread-based TLS is being used, destructors will
|
||||||
|
/// not be run for TLS values on the main thread when it exits. Note that the
|
||||||
|
/// application will exit immediately after the main thread exits as well.
|
||||||
|
/// 2. On all platforms it's possible for TLS to re-initialize other TLS slots
|
||||||
|
/// during destruction. Some platforms ensure that this cannot happen
|
||||||
|
/// infinitely by preventing re-initialization of any slot that has been
|
||||||
|
/// destroyed, but not all platforms have this guard. Those platforms that do
|
||||||
|
/// not guard typically have a synthetic limit after which point no more
|
||||||
|
/// destructors are run.
|
||||||
|
/// 3. On OSX, initializing TLS during destruction of other TLS slots can
|
||||||
|
/// sometimes cancel *all* destructors for the current thread, whether or not
|
||||||
|
/// the slots have already had their destructors run or not.
|
||||||
|
#[stable(feature = "rust1", since = "1.0.0")] |
||||||
|
pub struct LocalKey<T: 'static> { |
||||||
|
// This outer `LocalKey<T>` type is what's going to be stored in statics,
|
||||||
|
// but actual data inside will sometimes be tagged with #[thread_local].
|
||||||
|
// It's not valid for a true static to reference a #[thread_local] static,
|
||||||
|
// so we get around that by exposing an accessor through a layer of function
|
||||||
|
// indirection (this thunk).
|
||||||
|
//
|
||||||
|
// Note that the thunk is itself unsafe because the returned lifetime of the
|
||||||
|
// slot where data lives, `'static`, is not actually valid. The lifetime
|
||||||
|
// here is actually `'thread`!
|
||||||
|
//
|
||||||
|
// Although this is an extra layer of indirection, it should in theory be
|
||||||
|
// trivially devirtualizable by LLVM because the value of `inner` never
|
||||||
|
// changes and the constant should be readonly within a crate. This mainly
|
||||||
|
// only runs into problems when TLS statics are exported across crates.
|
||||||
|
inner: fn() -> Option<&'static UnsafeCell<Option<T>>>, |
||||||
|
|
||||||
|
// initialization routine to invoke to create a value
|
||||||
|
init: fn() -> T, |
||||||
|
} |
||||||
|
|
||||||
|
#[stable(feature = "std_debug", since = "1.16.0")] |
||||||
|
impl<T: 'static> fmt::Debug for LocalKey<T> { |
||||||
|
fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { |
||||||
|
f.pad("LocalKey { .. }") |
||||||
|
} |
||||||
|
} |
||||||
|
|
||||||
|
/// Declare a new thread local storage key of type `std::thread::LocalKey`.
|
||||||
|
///
|
||||||
|
/// # Syntax
|
||||||
|
///
|
||||||
|
/// The macro wraps any number of static declarations and makes them thread local.
|
||||||
|
/// Each static may be public or private, and attributes are allowed. Example:
|
||||||
|
///
|
||||||
|
/// ```
|
||||||
|
/// use std::cell::RefCell;
|
||||||
|
/// thread_local! {
|
||||||
|
/// pub static FOO: RefCell<u32> = RefCell::new(1);
|
||||||
|
///
|
||||||
|
/// #[allow(unused)]
|
||||||
|
/// static BAR: RefCell<f32> = RefCell::new(1.0);
|
||||||
|
/// }
|
||||||
|
/// # fn main() {}
|
||||||
|
/// ```
|
||||||
|
///
|
||||||
|
/// See [LocalKey documentation](thread/struct.LocalKey.html) for more
|
||||||
|
/// information.
|
||||||
|
#[macro_export] |
||||||
|
#[stable(feature = "rust1", since = "1.0.0")] |
||||||
|
#[allow_internal_unstable] |
||||||
|
macro_rules! thread_local { |
||||||
|
// rule 0: empty (base case for the recursion)
|
||||||
|
() => {}; |
||||||
|
|
||||||
|
// rule 1: process multiple declarations where the first one is private
|
||||||
|
($(#[$attr:meta])* static $name:ident: $t:ty = $init:expr; $($rest:tt)*) => ( |
||||||
|
thread_local!($(#[$attr])* static $name: $t = $init); // go to rule 2
|
||||||
|
thread_local!($($rest)*); |
||||||
|
); |
||||||
|
|
||||||
|
// rule 2: handle a single private declaration
|
||||||
|
($(#[$attr:meta])* static $name:ident: $t:ty = $init:expr) => ( |
||||||
|
$(#[$attr])* static $name: $crate::thread::LocalKey<$t> = |
||||||
|
__thread_local_inner!($t, $init); |
||||||
|
); |
||||||
|
|
||||||
|
// rule 3: handle multiple declarations where the first one is public
|
||||||
|
($(#[$attr:meta])* pub static $name:ident: $t:ty = $init:expr; $($rest:tt)*) => ( |
||||||
|
thread_local!($(#[$attr])* pub static $name: $t = $init); // go to rule 4
|
||||||
|
thread_local!($($rest)*); |
||||||
|
); |
||||||
|
|
||||||
|
// rule 4: handle a single public declaration
|
||||||
|
($(#[$attr:meta])* pub static $name:ident: $t:ty = $init:expr) => ( |
||||||
|
$(#[$attr])* pub static $name: $crate::thread::LocalKey<$t> = |
||||||
|
__thread_local_inner!($t, $init); |
||||||
|
); |
||||||
|
} |
||||||
|
|
||||||
|
#[doc(hidden)] |
||||||
|
#[unstable(feature = "thread_local_internals",
|
||||||
|
reason = "should not be necessary", |
||||||
|
issue = "0")] |
||||||
|
#[macro_export] |
||||||
|
#[allow_internal_unstable] |
||||||
|
macro_rules! __thread_local_inner { |
||||||
|
($t:ty, $init:expr) => {{ |
||||||
|
fn __init() -> $t { $init } |
||||||
|
|
||||||
|
fn __getit() -> $crate::option::Option< |
||||||
|
&'static $crate::cell::UnsafeCell< |
||||||
|
$crate::option::Option<$t>>> |
||||||
|
{ |
||||||
|
#[thread_local] |
||||||
|
#[cfg(target_thread_local)] |
||||||
|
static __KEY: $crate::thread::__FastLocalKeyInner<$t> = |
||||||
|
$crate::thread::__FastLocalKeyInner::new(); |
||||||
|
|
||||||
|
#[cfg(not(target_thread_local))] |
||||||
|
static __KEY: $crate::thread::__OsLocalKeyInner<$t> = |
||||||
|
$crate::thread::__OsLocalKeyInner::new(); |
||||||
|
|
||||||
|
__KEY.get() |
||||||
|
} |
||||||
|
|
||||||
|
$crate::thread::LocalKey::new(__getit, __init) |
||||||
|
}} |
||||||
|
} |
||||||
|
|
||||||
|
/// Indicator of the state of a thread local storage key.
|
||||||
|
#[unstable(feature = "thread_local_state",
|
||||||
|
reason = "state querying was recently added", |
||||||
|
issue = "27716")] |
||||||
|
#[derive(Debug, Eq, PartialEq, Copy, Clone)] |
||||||
|
pub enum LocalKeyState { |
||||||
|
/// All keys are in this state whenever a thread starts. Keys will
|
||||||
|
/// transition to the `Valid` state once the first call to `with` happens
|
||||||
|
/// and the initialization expression succeeds.
|
||||||
|
///
|
||||||
|
/// Keys in the `Uninitialized` state will yield a reference to the closure
|
||||||
|
/// passed to `with` so long as the initialization routine does not panic.
|
||||||
|
Uninitialized, |
||||||
|
|
||||||
|
/// Once a key has been accessed successfully, it will enter the `Valid`
|
||||||
|
/// state. Keys in the `Valid` state will remain so until the thread exits,
|
||||||
|
/// at which point the destructor will be run and the key will enter the
|
||||||
|
/// `Destroyed` state.
|
||||||
|
///
|
||||||
|
/// Keys in the `Valid` state will be guaranteed to yield a reference to the
|
||||||
|
/// closure passed to `with`.
|
||||||
|
Valid, |
||||||
|
|
||||||
|
/// When a thread exits, the destructors for keys will be run (if
|
||||||
|
/// necessary). While a destructor is running, and possibly after a
|
||||||
|
/// destructor has run, a key is in the `Destroyed` state.
|
||||||
|
///
|
||||||
|
/// Keys in the `Destroyed` states will trigger a panic when accessed via
|
||||||
|
/// `with`.
|
||||||
|
Destroyed, |
||||||
|
} |
||||||
|
|
||||||
|
impl<T: 'static> LocalKey<T> { |
||||||
|
#[doc(hidden)] |
||||||
|
#[unstable(feature = "thread_local_internals",
|
||||||
|
reason = "recently added to create a key", |
||||||
|
issue = "0")] |
||||||
|
pub const fn new(inner: fn() -> Option<&'static UnsafeCell<Option<T>>>, |
||||||
|
init: fn() -> T) -> LocalKey<T> { |
||||||
|
LocalKey { |
||||||
|
inner: inner, |
||||||
|
init: init, |
||||||
|
} |
||||||
|
} |
||||||
|
|
||||||
|
/// Acquires a reference to the value in this TLS key.
|
||||||
|
///
|
||||||
|
/// This will lazily initialize the value if this thread has not referenced
|
||||||
|
/// this key yet.
|
||||||
|
///
|
||||||
|
/// # Panics
|
||||||
|
///
|
||||||
|
/// This function will `panic!()` if the key currently has its
|
||||||
|
/// destructor running, and it **may** panic if the destructor has
|
||||||
|
/// previously been run for this thread.
|
||||||
|
#[stable(feature = "rust1", since = "1.0.0")] |
||||||
|
pub fn with<F, R>(&'static self, f: F) -> R |
||||||
|
where F: FnOnce(&T) -> R { |
||||||
|
unsafe { |
||||||
|
let slot = (self.inner)(); |
||||||
|
let slot = slot.expect("cannot access a TLS value during or \ |
||||||
|
after it is destroyed"); |
||||||
|
f(match *slot.get() { |
||||||
|
Some(ref inner) => inner, |
||||||
|
None => self.init(slot), |
||||||
|
}) |
||||||
|
} |
||||||
|
} |
||||||
|
|
||||||
|
unsafe fn init(&self, slot: &UnsafeCell<Option<T>>) -> &T { |
||||||
|
// Execute the initialization up front, *then* move it into our slot,
|
||||||
|
// just in case initialization fails.
|
||||||
|
let value = (self.init)(); |
||||||
|
let ptr = slot.get(); |
||||||
|
|
||||||
|
// note that this can in theory just be `*ptr = Some(value)`, but due to
|
||||||
|
// the compiler will currently codegen that pattern with something like:
|
||||||
|
//
|
||||||
|
// ptr::drop_in_place(ptr)
|
||||||
|
// ptr::write(ptr, Some(value))
|
||||||
|
//
|
||||||
|
// Due to this pattern it's possible for the destructor of the value in
|
||||||
|
// `ptr` (e.g. if this is being recursively initialized) to re-access
|
||||||
|
// TLS, in which case there will be a `&` and `&mut` pointer to the same
|
||||||
|
// value (an aliasing violation). To avoid setting the "I'm running a
|
||||||
|
// destructor" flag we just use `mem::replace` which should sequence the
|
||||||
|
// operations a little differently and make this safe to call.
|
||||||
|
mem::replace(&mut *ptr, Some(value)); |
||||||
|
|
||||||
|
(*ptr).as_ref().unwrap() |
||||||
|
} |
||||||
|
|
||||||
|
/// Query the current state of this key.
|
||||||
|
///
|
||||||
|
/// A key is initially in the `Uninitialized` state whenever a thread
|
||||||
|
/// starts. It will remain in this state up until the first call to `with`
|
||||||
|
/// within a thread has run the initialization expression successfully.
|
||||||
|
///
|
||||||
|
/// Once the initialization expression succeeds, the key transitions to the
|
||||||
|
/// `Valid` state which will guarantee that future calls to `with` will
|
||||||
|
/// succeed within the thread.
|
||||||
|
///
|
||||||
|
/// When a thread exits, each key will be destroyed in turn, and as keys are
|
||||||
|
/// destroyed they will enter the `Destroyed` state just before the
|
||||||
|
/// destructor starts to run. Keys may remain in the `Destroyed` state after
|
||||||
|
/// destruction has completed. Keys without destructors (e.g. with types
|
||||||
|
/// that are `Copy`), may never enter the `Destroyed` state.
|
||||||
|
///
|
||||||
|
/// Keys in the `Uninitialized` state can be accessed so long as the
|
||||||
|
/// initialization does not panic. Keys in the `Valid` state are guaranteed
|
||||||
|
/// to be able to be accessed. Keys in the `Destroyed` state will panic on
|
||||||
|
/// any call to `with`.
|
||||||
|
#[unstable(feature = "thread_local_state",
|
||||||
|
reason = "state querying was recently added", |
||||||
|
issue = "27716")] |
||||||
|
pub fn state(&'static self) -> LocalKeyState { |
||||||
|
unsafe { |
||||||
|
match (self.inner)() { |
||||||
|
Some(cell) => { |
||||||
|
match *cell.get() { |
||||||
|
Some(..) => LocalKeyState::Valid, |
||||||
|
None => LocalKeyState::Uninitialized, |
||||||
|
} |
||||||
|
} |
||||||
|
None => LocalKeyState::Destroyed, |
||||||
|
} |
||||||
|
} |
||||||
|
} |
||||||
|
} |
||||||
|
|
||||||
|
#[doc(hidden)] |
||||||
|
pub mod os { |
||||||
|
use cell::{Cell, UnsafeCell}; |
||||||
|
use fmt; |
||||||
|
use marker; |
||||||
|
use ptr; |
||||||
|
use sys_common::thread_local::StaticKey as OsStaticKey; |
||||||
|
|
||||||
|
pub struct Key<T> { |
||||||
|
// OS-TLS key that we'll use to key off.
|
||||||
|
os: OsStaticKey, |
||||||
|
marker: marker::PhantomData<Cell<T>>, |
||||||
|
} |
||||||
|
|
||||||
|
impl<T> fmt::Debug for Key<T> { |
||||||
|
fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { |
||||||
|
f.pad("Key { .. }") |
||||||
|
} |
||||||
|
} |
||||||
|
|
||||||
|
unsafe impl<T> ::marker::Sync for Key<T> { } |
||||||
|
|
||||||
|
struct Value<T: 'static> { |
||||||
|
key: &'static Key<T>, |
||||||
|
value: UnsafeCell<Option<T>>, |
||||||
|
} |
||||||
|
|
||||||
|
impl<T: 'static> Key<T> { |
||||||
|
pub const fn new() -> Key<T> { |
||||||
|
Key { |
||||||
|
os: OsStaticKey::new(Some(destroy_value::<T>)), |
||||||
|
marker: marker::PhantomData |
||||||
|
} |
||||||
|
} |
||||||
|
|
||||||
|
pub fn get(&'static self) -> Option<&'static UnsafeCell<Option<T>>> { |
||||||
|
unsafe { |
||||||
|
let ptr = self.os.get() as *mut Value<T>; |
||||||
|
if !ptr.is_null() { |
||||||
|
if ptr as usize == 1 { |
||||||
|
return None |
||||||
|
} |
||||||
|
return Some(&(*ptr).value); |
||||||
|
} |
||||||
|
|
||||||
|
// If the lookup returned null, we haven't initialized our own local
|
||||||
|
// copy, so do that now.
|
||||||
|
let ptr: Box<Value<T>> = box Value { |
||||||
|
key: self, |
||||||
|
value: UnsafeCell::new(None), |
||||||
|
}; |
||||||
|
let ptr = Box::into_raw(ptr); |
||||||
|
self.os.set(ptr as *mut u8); |
||||||
|
Some(&(*ptr).value) |
||||||
|
} |
||||||
|
} |
||||||
|
} |
||||||
|
|
||||||
|
pub unsafe extern fn destroy_value<T: 'static>(ptr: *mut u8) { |
||||||
|
// The OS TLS ensures that this key contains a NULL value when this
|
||||||
|
// destructor starts to run. We set it back to a sentinel value of 1 to
|
||||||
|
// ensure that any future calls to `get` for this thread will return
|
||||||
|
// `None`.
|
||||||
|
//
|
||||||
|
// Note that to prevent an infinite loop we reset it back to null right
|
||||||
|
// before we return from the destructor ourselves.
|
||||||
|
let ptr = Box::from_raw(ptr as *mut Value<T>); |
||||||
|
let key = ptr.key; |
||||||
|
key.os.set(1 as *mut u8); |
||||||
|
drop(ptr); |
||||||
|
key.os.set(ptr::null_mut()); |
||||||
|
} |
||||||
|
} |
||||||
|
|
||||||
|
#[cfg(all(test, not(target_os = "emscripten")))] |
||||||
|
mod tests { |
||||||
|
use sync::mpsc::{channel, Sender}; |
||||||
|
use cell::{Cell, UnsafeCell}; |
||||||
|
use super::LocalKeyState; |
||||||
|
use thread; |
||||||
|
|
||||||
|
struct Foo(Sender<()>); |
||||||
|
|
||||||
|
impl Drop for Foo { |
||||||
|
fn drop(&mut self) { |
||||||
|
let Foo(ref s) = *self; |
||||||
|
s.send(()).unwrap(); |
||||||
|
} |
||||||
|
} |
||||||
|
|
||||||
|
#[test] |
||||||
|
fn smoke_no_dtor() { |
||||||
|
thread_local!(static FOO: Cell<i32> = Cell::new(1)); |
||||||
|
|
||||||
|
FOO.with(|f| { |
||||||
|
assert_eq!(f.get(), 1); |
||||||
|
f.set(2); |
||||||
|
}); |
||||||
|
let (tx, rx) = channel(); |
||||||
|
let _t = thread::spawn(move|| { |
||||||
|
FOO.with(|f| { |
||||||
|
assert_eq!(f.get(), 1); |
||||||
|
}); |
||||||
|
tx.send(()).unwrap(); |
||||||
|
}); |
||||||
|
rx.recv().unwrap(); |
||||||
|
|
||||||
|
FOO.with(|f| { |
||||||
|
assert_eq!(f.get(), 2); |
||||||
|
}); |
||||||
|
} |
||||||
|
|
||||||
|
#[test] |
||||||
|
fn states() { |
||||||
|
struct Foo; |
||||||
|
impl Drop for Foo { |
||||||
|
fn drop(&mut self) { |
||||||
|
assert!(FOO.state() == LocalKeyState::Destroyed); |
||||||
|
} |
||||||
|
} |
||||||
|
fn foo() -> Foo { |
||||||
|
assert!(FOO.state() == LocalKeyState::Uninitialized); |
||||||
|
Foo |
||||||
|
} |
||||||
|
thread_local!(static FOO: Foo = foo()); |
||||||
|
|
||||||
|
thread::spawn(|| { |
||||||
|
assert!(FOO.state() == LocalKeyState::Uninitialized); |
||||||
|
FOO.with(|_| { |
||||||
|
assert!(FOO.state() == LocalKeyState::Valid); |
||||||
|
}); |
||||||
|
assert!(FOO.state() == LocalKeyState::Valid); |
||||||
|
}).join().ok().unwrap(); |
||||||
|
} |
||||||
|
|
||||||
|
#[test] |
||||||
|
fn smoke_dtor() { |
||||||
|
thread_local!(static FOO: UnsafeCell<Option<Foo>> = UnsafeCell::new(None)); |
||||||
|
|
||||||
|
let (tx, rx) = channel(); |
||||||
|
let _t = thread::spawn(move|| unsafe { |
||||||
|
let mut tx = Some(tx); |
||||||
|
FOO.with(|f| { |
||||||
|
*f.get() = Some(Foo(tx.take().unwrap())); |
||||||
|
}); |
||||||
|
}); |
||||||
|
rx.recv().unwrap(); |
||||||
|
} |
||||||
|
|
||||||
|
#[test] |
||||||
|
fn circular() { |
||||||
|
struct S1; |
||||||
|
struct S2; |
||||||
|
thread_local!(static K1: UnsafeCell<Option<S1>> = UnsafeCell::new(None)); |
||||||
|
thread_local!(static K2: UnsafeCell<Option<S2>> = UnsafeCell::new(None)); |
||||||
|
static mut HITS: u32 = 0; |
||||||
|
|
||||||
|
impl Drop for S1 { |
||||||
|
fn drop(&mut self) { |
||||||
|
unsafe { |
||||||
|
HITS += 1; |
||||||
|
if K2.state() == LocalKeyState::Destroyed { |
||||||
|
assert_eq!(HITS, 3); |
||||||
|
} else { |
||||||
|
if HITS == 1 { |
||||||
|
K2.with(|s| *s.get() = Some(S2)); |
||||||
|
} else { |
||||||
|
assert_eq!(HITS, 3); |
||||||
|
} |
||||||
|
} |
||||||
|
} |
||||||
|
} |
||||||
|
} |
||||||
|
impl Drop for S2 { |
||||||
|
fn drop(&mut self) { |
||||||
|
unsafe { |
||||||
|
HITS += 1; |
||||||
|
assert!(K1.state() != LocalKeyState::Destroyed); |
||||||
|
assert_eq!(HITS, 2); |
||||||
|
K1.with(|s| *s.get() = Some(S1)); |
||||||
|
} |
||||||
|
} |
||||||
|
} |
||||||
|
|
||||||
|
thread::spawn(move|| { |
||||||
|
drop(S1); |
||||||
|
}).join().ok().unwrap(); |
||||||
|
} |
||||||
|
|
||||||
|
#[test] |
||||||
|
fn self_referential() { |
||||||
|
struct S1; |
||||||
|
thread_local!(static K1: UnsafeCell<Option<S1>> = UnsafeCell::new(None)); |
||||||
|
|
||||||
|
impl Drop for S1 { |
||||||
|
fn drop(&mut self) { |
||||||
|
assert!(K1.state() == LocalKeyState::Destroyed); |
||||||
|
} |
||||||
|
} |
||||||
|
|
||||||
|
thread::spawn(move|| unsafe { |
||||||
|
K1.with(|s| *s.get() = Some(S1)); |
||||||
|
}).join().ok().unwrap(); |
||||||
|
} |
||||||
|
|
||||||
|
// Note that this test will deadlock if TLS destructors aren't run (this
|
||||||
|
// requires the destructor to be run to pass the test). OSX has a known bug
|
||||||
|
// where dtors-in-dtors may cancel other destructors, so we just ignore this
|
||||||
|
// test on OSX.
|
||||||
|
#[test] |
||||||
|
#[cfg_attr(target_os = "macos", ignore)] |
||||||
|
fn dtors_in_dtors_in_dtors() { |
||||||
|
struct S1(Sender<()>); |
||||||
|
thread_local!(static K1: UnsafeCell<Option<S1>> = UnsafeCell::new(None)); |
||||||
|
thread_local!(static K2: UnsafeCell<Option<Foo>> = UnsafeCell::new(None)); |
||||||
|
|
||||||
|
impl Drop for S1 { |
||||||
|
fn drop(&mut self) { |
||||||
|
let S1(ref tx) = *self; |
||||||
|
unsafe { |
||||||
|
if K2.state() != LocalKeyState::Destroyed { |
||||||
|
K2.with(|s| *s.get() = Some(Foo(tx.clone()))); |
||||||
|
} |
||||||
|
} |
||||||
|
} |
||||||
|
} |
||||||
|
|
||||||
|
let (tx, rx) = channel(); |
||||||
|
let _t = thread::spawn(move|| unsafe { |
||||||
|
let mut tx = Some(tx); |
||||||
|
K1.with(|s| *s.get() = Some(S1(tx.take().unwrap()))); |
||||||
|
}); |
||||||
|
rx.recv().unwrap(); |
||||||
|
} |
||||||
|
} |
||||||
|
|
||||||
|
#[cfg(test)] |
||||||
|
mod dynamic_tests { |
||||||
|
use cell::RefCell; |
||||||
|
use collections::HashMap; |
||||||
|
|
||||||
|
#[test] |
||||||
|
fn smoke() { |
||||||
|
fn square(i: i32) -> i32 { i * i } |
||||||
|
thread_local!(static FOO: i32 = square(3)); |
||||||
|
|
||||||
|
FOO.with(|f| { |
||||||
|
assert_eq!(*f, 9); |
||||||
|
}); |
||||||
|
} |
||||||
|
|
||||||
|
#[test] |
||||||
|
fn hashmap() { |
||||||
|
fn map() -> RefCell<HashMap<i32, i32>> { |
||||||
|
let mut m = HashMap::new(); |
||||||
|
m.insert(1, 2); |
||||||
|
RefCell::new(m) |
||||||
|
} |
||||||
|
thread_local!(static FOO: RefCell<HashMap<i32, i32>> = map()); |
||||||
|
|
||||||
|
FOO.with(|map| { |
||||||
|
assert_eq!(map.borrow()[&1], 2); |
||||||
|
}); |
||||||
|
} |
||||||
|
|
||||||
|
#[test] |
||||||
|
fn refcell_vec() { |
||||||
|
thread_local!(static FOO: RefCell<Vec<u32>> = RefCell::new(vec![1, 2, 3])); |
||||||
|
|
||||||
|
FOO.with(|vec| { |
||||||
|
assert_eq!(vec.borrow().len(), 3); |
||||||
|
vec.borrow_mut().push(4); |
||||||
|
assert_eq!(vec.borrow()[3], 4); |
||||||
|
}); |
||||||
|
} |
||||||
|
} |
||||||
@ -0,0 +1,195 @@ |
|||||||
|
// 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 <LICENSE-APACHE or
|
||||||
|
// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
|
||||||
|
// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
|
||||||
|
// option. This file may not be copied, modified, or distributed
|
||||||
|
// except according to those terms.
|
||||||
|
|
||||||
|
//! Native threads.
|
||||||
|
//!
|
||||||
|
//! ## The threading model
|
||||||
|
//!
|
||||||
|
//! An executing Rust program consists of a collection of native OS threads,
|
||||||
|
//! each with their own stack and local state. Threads can be named, and
|
||||||
|
//! provide some built-in support for low-level synchronization.
|
||||||
|
//!
|
||||||
|
//! Communication between threads can be done through
|
||||||
|
//! [channels], Rust's message-passing types, along with [other forms of thread
|
||||||
|
//! synchronization](../../std/sync/index.html) and shared-memory data
|
||||||
|
//! structures. In particular, types that are guaranteed to be
|
||||||
|
//! threadsafe are easily shared between threads using the
|
||||||
|
//! atomically-reference-counted container, [`Arc`].
|
||||||
|
//!
|
||||||
|
//! Fatal logic errors in Rust cause *thread panic*, during which
|
||||||
|
//! a thread will unwind the stack, running destructors and freeing
|
||||||
|
//! owned resources. Thread panic is unrecoverable from within
|
||||||
|
//! the panicking thread (i.e. there is no 'try/catch' in Rust), but
|
||||||
|
//! the panic may optionally be detected from a different thread. If
|
||||||
|
//! the main thread panics, the application will exit with a non-zero
|
||||||
|
//! exit code.
|
||||||
|
//!
|
||||||
|
//! When the main thread of a Rust program terminates, the entire program shuts
|
||||||
|
//! down, even if other threads are still running. However, this module provides
|
||||||
|
//! convenient facilities for automatically waiting for the termination of a
|
||||||
|
//! child thread (i.e., join).
|
||||||
|
//!
|
||||||
|
//! ## Spawning a thread
|
||||||
|
//!
|
||||||
|
//! A new thread can be spawned using the [`thread::spawn`][`spawn`] function:
|
||||||
|
//!
|
||||||
|
//! ```rust
|
||||||
|
//! use std::thread;
|
||||||
|
//!
|
||||||
|
//! thread::spawn(move || {
|
||||||
|
//! // some work here
|
||||||
|
//! });
|
||||||
|
//! ```
|
||||||
|
//!
|
||||||
|
//! In this example, the spawned thread is "detached" from the current
|
||||||
|
//! thread. This means that it can outlive its parent (the thread that spawned
|
||||||
|
//! it), unless this parent is the main thread.
|
||||||
|
//!
|
||||||
|
//! The parent thread can also wait on the completion of the child
|
||||||
|
//! thread; a call to [`spawn`] produces a [`JoinHandle`], which provides
|
||||||
|
//! a `join` method for waiting:
|
||||||
|
//!
|
||||||
|
//! ```rust
|
||||||
|
//! use std::thread;
|
||||||
|
//!
|
||||||
|
//! let child = thread::spawn(move || {
|
||||||
|
//! // some work here
|
||||||
|
//! });
|
||||||
|
//! // some work here
|
||||||
|
//! let res = child.join();
|
||||||
|
//! ```
|
||||||
|
//!
|
||||||
|
//! The [`join`] method returns a [`Result`] containing [`Ok`] of the final
|
||||||
|
//! value produced by the child thread, or [`Err`] of the value given to
|
||||||
|
//! a call to [`panic!`] if the child panicked.
|
||||||
|
//!
|
||||||
|
//! ## Configuring threads
|
||||||
|
//!
|
||||||
|
//! A new thread can be configured before it is spawned via the [`Builder`] type,
|
||||||
|
//! which currently allows you to set the name and stack size for the child thread:
|
||||||
|
//!
|
||||||
|
//! ```rust
|
||||||
|
//! # #![allow(unused_must_use)]
|
||||||
|
//! use std::thread;
|
||||||
|
//!
|
||||||
|
//! thread::Builder::new().name("child1".to_string()).spawn(move || {
|
||||||
|
//! println!("Hello, world!");
|
||||||
|
//! });
|
||||||
|
//! ```
|
||||||
|
//!
|
||||||
|
//! ## The `Thread` type
|
||||||
|
//!
|
||||||
|
//! Threads are represented via the [`Thread`] type, which you can get in one of
|
||||||
|
//! two ways:
|
||||||
|
//!
|
||||||
|
//! * By spawning a new thread, e.g. using the [`thread::spawn`][`spawn`]
|
||||||
|
//! function, and calling [`thread()`] on the [`JoinHandle`].
|
||||||
|
//! * By requesting the current thread, using the [`thread::current()`] function.
|
||||||
|
//!
|
||||||
|
//! The [`thread::current()`] function is available even for threads not spawned
|
||||||
|
//! by the APIs of this module.
|
||||||
|
//!
|
||||||
|
//! ## Blocking support: park and unpark
|
||||||
|
//!
|
||||||
|
//! Every thread is equipped with some basic low-level blocking support, via the
|
||||||
|
//! [`thread::park()`][`park()`] function and [`thread::Thread::unpark()`][`unpark()`]
|
||||||
|
//! method. [`park()`] blocks the current thread, which can then be resumed from
|
||||||
|
//! another thread by calling the [`unpark()`] method on the blocked thread's handle.
|
||||||
|
//!
|
||||||
|
//! Conceptually, each [`Thread`] handle has an associated token, which is
|
||||||
|
//! initially not present:
|
||||||
|
//!
|
||||||
|
//! * The [`thread::park()`][`park()`] function blocks the current thread unless or until
|
||||||
|
//! the token is available for its thread handle, at which point it atomically
|
||||||
|
//! consumes the token. It may also return *spuriously*, without consuming the
|
||||||
|
//! token. [`thread::park_timeout()`] does the same, but allows specifying a
|
||||||
|
//! maximum time to block the thread for.
|
||||||
|
//!
|
||||||
|
//! * The [`unpark()`] method on a [`Thread`] atomically makes the token available
|
||||||
|
//! if it wasn't already.
|
||||||
|
//!
|
||||||
|
//! In other words, each [`Thread`] acts a bit like a semaphore with initial count
|
||||||
|
//! 0, except that the semaphore is *saturating* (the count cannot go above 1),
|
||||||
|
//! and can return spuriously.
|
||||||
|
//!
|
||||||
|
//! The API is typically used by acquiring a handle to the current thread,
|
||||||
|
//! placing that handle in a shared data structure so that other threads can
|
||||||
|
//! find it, and then `park`ing. When some desired condition is met, another
|
||||||
|
//! thread calls [`unpark()`] on the handle.
|
||||||
|
//!
|
||||||
|
//! The motivation for this design is twofold:
|
||||||
|
//!
|
||||||
|
//! * It avoids the need to allocate mutexes and condvars when building new
|
||||||
|
//! synchronization primitives; the threads already provide basic blocking/signaling.
|
||||||
|
//!
|
||||||
|
//! * It can be implemented very efficiently on many platforms.
|
||||||
|
//!
|
||||||
|
//! ## Thread-local storage
|
||||||
|
//!
|
||||||
|
//! This module also provides an implementation of thread-local storage for Rust
|
||||||
|
//! programs. Thread-local storage is a method of storing data into a global
|
||||||
|
//! variable that each thread in the program will have its own copy of.
|
||||||
|
//! Threads do not share this data, so accesses do not need to be synchronized.
|
||||||
|
//!
|
||||||
|
//! A thread-local key owns the value it contains and will destroy the value when the
|
||||||
|
//! thread exits. It is created with the [`thread_local!`] macro and can contain any
|
||||||
|
//! value that is `'static` (no borrowed pointers). It provides an accessor function,
|
||||||
|
//! [`with`], that yields a shared reference to the value to the specified
|
||||||
|
//! closure. Thread-local keys allow only shared access to values, as there would be no
|
||||||
|
//! way to guarantee uniqueness if mutable borrows were allowed. Most values
|
||||||
|
//! will want to make use of some form of **interior mutability** through the
|
||||||
|
//! [`Cell`] or [`RefCell`] types.
|
||||||
|
//!
|
||||||
|
//! [channels]: ../../std/sync/mpsc/index.html
|
||||||
|
//! [`Arc`]: ../../std/sync/struct.Arc.html
|
||||||
|
//! [`spawn`]: ../../std/thread/fn.spawn.html
|
||||||
|
//! [`JoinHandle`]: ../../std/thread/struct.JoinHandle.html
|
||||||
|
//! [`thread()`]: ../../std/thread/struct.JoinHandle.html#method.thread
|
||||||
|
//! [`join`]: ../../std/thread/struct.JoinHandle.html#method.join
|
||||||
|
//! [`Result`]: ../../std/result/enum.Result.html
|
||||||
|
//! [`Ok`]: ../../std/result/enum.Result.html#variant.Ok
|
||||||
|
//! [`Err`]: ../../std/result/enum.Result.html#variant.Err
|
||||||
|
//! [`panic!`]: ../../std/macro.panic.html
|
||||||
|
//! [`Builder`]: ../../std/thread/struct.Builder.html
|
||||||
|
//! [`thread::current()`]: ../../std/thread/fn.spawn.html
|
||||||
|
//! [`Thread`]: ../../std/thread/struct.Thread.html
|
||||||
|
//! [`park()`]: ../../std/thread/fn.park.html
|
||||||
|
//! [`unpark()`]: ../../std/thread/struct.Thread.html#method.unpark
|
||||||
|
//! [`thread::park_timeout()`]: ../../std/thread/fn.park_timeout.html
|
||||||
|
//! [`Cell`]: ../cell/struct.Cell.html
|
||||||
|
//! [`RefCell`]: ../cell/struct.RefCell.html
|
||||||
|
//! [`thread_local!`]: ../macro.thread_local.html
|
||||||
|
//! [`with`]: struct.LocalKey.html#method.with
|
||||||
|
|
||||||
|
#![stable(feature = "rust1", since = "1.0.0")] |
||||||
|
|
||||||
|
////////////////////////////////////////////////////////////////////////////////
|
||||||
|
// Thread-local storage
|
||||||
|
////////////////////////////////////////////////////////////////////////////////
|
||||||
|
|
||||||
|
#[macro_use] mod local; |
||||||
|
|
||||||
|
#[stable(feature = "rust1", since = "1.0.0")] |
||||||
|
pub use self::local::{LocalKey, LocalKeyState}; |
||||||
|
|
||||||
|
// The types used by the thread_local! macro to access TLS keys. Note that there
|
||||||
|
// are two types, the "OS" type and the "fast" type. The OS thread local key
|
||||||
|
// type is accessed via platform-specific API calls and is slow, while the fast
|
||||||
|
// key type is accessed via code generated via LLVM, where TLS keys are set up
|
||||||
|
// by the elf linker. Note that the OS TLS type is always available: on macOS
|
||||||
|
// the standard library is compiled with support for older platform versions
|
||||||
|
// where fast TLS was not available; end-user code is compiled with fast TLS
|
||||||
|
// where available, but both are needed.
|
||||||
|
|
||||||
|
#[unstable(feature = "libstd_thread_internals", issue = "0")] |
||||||
|
#[cfg(target_thread_local)] |
||||||
|
#[doc(hidden)] pub use sys::fast_thread_local::Key as __FastLocalKeyInner; |
||||||
|
#[unstable(feature = "libstd_thread_internals", issue = "0")] |
||||||
|
#[doc(hidden)] pub use self::local::os::Key as __OsLocalKeyInner; |
||||||
Loading…
Reference in new issue