1 // Copyright 2014-2015 The Rust Project Developers. See the COPYRIGHT
2 // file at the top-level directory of this distribution and at
3 // http://rust-lang.org/COPYRIGHT.
5 // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
6 // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
7 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
8 // option. This file may not be copied, modified, or distributed
9 // except according to those terms.
11 //! Thread local storage
13 //! This module provides an implementation of thread local storage for Rust
14 //! programs. Thread local storage is a method of storing data into a global
15 //! variable which each thread in the program will have its own copy of.
16 //! Threads do not share this data, so accesses do not need to be synchronized.
18 //! At a high level, this module provides two variants of storage:
20 //! * Owning thread local storage. This is a type of thread local key which
21 //! owns the value that it contains, and will destroy the value when the
22 //! thread exits. This variant is created with the `thread_local!` macro and
23 //! can contain any value which is `'static` (no borrowed pointers.
25 //! * Scoped thread local storage. This type of key is used to store a reference
26 //! to a value into local storage temporarily for the scope of a function
27 //! call. There are no restrictions on what types of values can be placed
30 //! Both forms of thread local storage provide an accessor function, `with`,
31 //! which will yield a shared reference to the value to the specified
32 //! closure. Thread local keys only allow shared access to values as there is no
33 //! way to guarantee uniqueness if a mutable borrow was allowed. Most values
34 //! will want to make use of some form of **interior mutability** through the
35 //! `Cell` or `RefCell` types.
46 // Sure wish we had macro hygiene, no?
49 pub use super::imp::Key as KeyInner;
50 pub use super::imp::destroy_value;
51 pub use sys_common::thread_local::INIT_INNER as OS_INIT_INNER;
52 pub use sys_common::thread_local::StaticKey as OsStaticKey;
55 /// A thread local storage key which owns its contents.
57 /// This key uses the fastest possible implementation available to it for the
58 /// target platform. It is instantiated with the `thread_local!` macro and the
59 /// primary method is the `with` method.
61 /// The `with` method yields a reference to the contained value which cannot be
62 /// sent across tasks or escape the given closure.
64 /// # Initialization and Destruction
66 /// Initialization is dynamically performed on the first call to `with()`
67 /// within a thread, and values support destructors which will be run when a
73 /// use std::cell::RefCell;
74 /// use std::thread::Thread;
76 /// thread_local!(static FOO: RefCell<uint> = RefCell::new(1));
79 /// assert_eq!(*f.borrow(), 1);
80 /// *f.borrow_mut() = 2;
83 /// // each thread starts out with the initial value of 1
84 /// Thread::spawn(move|| {
86 /// assert_eq!(*f.borrow(), 1);
87 /// *f.borrow_mut() = 3;
91 /// // we retain our original value of 2 despite the child thread
93 /// assert_eq!(*f.borrow(), 2);
98 // The key itself may be tagged with #[thread_local], and this `Key` is
99 // stored as a `static`, and it's not valid for a static to reference the
100 // address of another thread_local static. For this reason we kinda wonkily
101 // work around this by generating a shim function which will give us the
102 // address of the inner TLS key at runtime.
104 // This is trivially devirtualizable by LLVM because we never store anything
105 // to this field and rustc can declare the `static` as constant as well.
107 pub inner: fn() -> &'static __impl::KeyInner<UnsafeCell<Option<T>>>,
109 // initialization routine to invoke to create a value
114 /// Declare a new thread local storage key of type `std::thread_local::Key`.
117 macro_rules! thread_local {
118 (static $name:ident: $t:ty = $init:expr) => (
119 static $name: ::std::thread_local::Key<$t> = {
120 use std::cell::UnsafeCell as __UnsafeCell;
121 use std::thread_local::__impl::KeyInner as __KeyInner;
122 use std::option::Option as __Option;
123 use std::option::Option::None as __None;
125 __thread_local_inner!(static __KEY: __UnsafeCell<__Option<$t>> = {
126 __UnsafeCell { value: __None }
128 fn __init() -> $t { $init }
129 fn __getit() -> &'static __KeyInner<__UnsafeCell<__Option<$t>>> {
132 ::std::thread_local::Key { inner: __getit, init: __init }
135 (pub static $name:ident: $t:ty = $init:expr) => (
136 pub static $name: ::std::thread_local::Key<$t> = {
137 use std::cell::UnsafeCell as __UnsafeCell;
138 use std::thread_local::__impl::KeyInner as __KeyInner;
139 use std::option::Option as __Option;
140 use std::option::Option::None as __None;
142 __thread_local_inner!(static __KEY: __UnsafeCell<__Option<$t>> = {
143 __UnsafeCell { value: __None }
145 fn __init() -> $t { $init }
146 fn __getit() -> &'static __KeyInner<__UnsafeCell<__Option<$t>>> {
149 ::std::thread_local::Key { inner: __getit, init: __init }
156 // When cross compiling, rustc will load plugins and macros from the *host*
157 // platform before search for macros from the target platform. This is primarily
158 // done to detect, for example, plugins. Ideally the macro below would be
159 // defined once per module below, but unfortunately this means we have the
160 // following situation:
162 // 1. We compile libstd for x86_64-unknown-linux-gnu, this thread_local!() macro
163 // will inject #[thread_local] statics.
164 // 2. We then try to compile a program for arm-linux-androideabi
165 // 3. The compiler has a host of linux and a target of android, so it loads
166 // macros from the *linux* libstd.
167 // 4. The macro generates a #[thread_local] field, but the android libstd does
168 // not use #[thread_local]
169 // 5. Compile error about structs with wrong fields.
171 // To get around this, we're forced to inject the #[cfg] logic into the macro
176 macro_rules! __thread_local_inner {
177 (static $name:ident: $t:ty = $init:expr) => (
178 #[cfg_attr(all(any(target_os = "macos", target_os = "linux"),
179 not(target_arch = "aarch64")),
181 static $name: ::std::thread_local::__impl::KeyInner<$t> =
182 __thread_local_inner!($init, $t);
184 (pub static $name:ident: $t:ty = $init:expr) => (
185 #[cfg_attr(all(any(target_os = "macos", target_os = "linux"),
186 not(target_arch = "aarch64")),
188 pub static $name: ::std::thread_local::__impl::KeyInner<$t> =
189 __thread_local_inner!($init, $t);
191 ($init:expr, $t:ty) => ({
192 #[cfg(all(any(target_os = "macos", target_os = "linux"), not(target_arch = "aarch64")))]
193 const _INIT: ::std::thread_local::__impl::KeyInner<$t> = {
194 ::std::thread_local::__impl::KeyInner {
195 inner: ::std::cell::UnsafeCell { value: $init },
196 dtor_registered: ::std::cell::UnsafeCell { value: false },
197 dtor_running: ::std::cell::UnsafeCell { value: false },
201 #[cfg(any(not(any(target_os = "macos", target_os = "linux")), target_arch = "aarch64"))]
202 const _INIT: ::std::thread_local::__impl::KeyInner<$t> = {
203 unsafe extern fn __destroy(ptr: *mut u8) {
204 ::std::thread_local::__impl::destroy_value::<$t>(ptr);
207 ::std::thread_local::__impl::KeyInner {
208 inner: ::std::cell::UnsafeCell { value: $init },
209 os: ::std::thread_local::__impl::OsStaticKey {
210 inner: ::std::thread_local::__impl::OS_INIT_INNER,
211 dtor: ::std::option::Option::Some(__destroy as unsafe extern fn(*mut u8)),
220 /// Indicator of the state of a thread local storage key.
221 #[unstable = "state querying was recently added"]
222 #[derive(Eq, PartialEq, Copy)]
224 /// All keys are in this state whenever a thread starts. Keys will
225 /// transition to the `Valid` state once the first call to `with` happens
226 /// and the initialization expression succeeds.
228 /// Keys in the `Uninitialized` state will yield a reference to the closure
229 /// passed to `with` so long as the initialization routine does not panic.
232 /// Once a key has been accessed successfully, it will enter the `Valid`
233 /// state. Keys in the `Valid` state will remain so until the thread exits,
234 /// at which point the destructor will be run and the key will enter the
235 /// `Destroyed` state.
237 /// Keys in the `Valid` state will be guaranteed to yield a reference to the
238 /// closure passed to `with`.
241 /// When a thread exits, the destructors for keys will be run (if
242 /// necessary). While a destructor is running, and possibly after a
243 /// destructor has run, a key is in the `Destroyed` state.
245 /// Keys in the `Destroyed` states will trigger a panic when accessed via
250 impl<T: 'static> Key<T> {
251 /// Acquire a reference to the value in this TLS key.
253 /// This will lazily initialize the value if this thread has not referenced
258 /// This function will `panic!()` if the key currently has its
259 /// destructor running, and it **may** panic if the destructor has
260 /// previously been run for this thread.
262 pub fn with<F, R>(&'static self, f: F) -> R
263 where F: FnOnce(&T) -> R {
264 let slot = (self.inner)();
266 let slot = slot.get().expect("cannot access a TLS value during or \
267 after it is destroyed");
268 f(match *slot.get() {
269 Some(ref inner) => inner,
270 None => self.init(slot),
275 unsafe fn init(&self, slot: &UnsafeCell<Option<T>>) -> &T {
276 // Execute the initialization up front, *then* move it into our slot,
277 // just in case initialization fails.
278 let value = (self.init)();
279 let ptr = slot.get();
281 (*ptr).as_ref().unwrap()
284 /// Query the current state of this key.
286 /// A key is initially in the `Uninitialized` state whenever a thread
287 /// starts. It will remain in this state up until the first call to `with`
288 /// within a thread has run the initialization expression successfully.
290 /// Once the initialization expression succeeds, the key transitions to the
291 /// `Valid` state which will guarantee that future calls to `with` will
292 /// succeed within the thread.
294 /// When a thread exits, each key will be destroyed in turn, and as keys are
295 /// destroyed they will enter the `Destroyed` state just before the
296 /// destructor starts to run. Keys may remain in the `Destroyed` state after
297 /// destruction has completed. Keys without destructors (e.g. with types
298 /// that are `Copy`), may never enter the `Destroyed` state.
300 /// Keys in the `Uninitialized` can be accessed so long as the
301 /// initialization does not panic. Keys in the `Valid` state are guaranteed
302 /// to be able to be accessed. Keys in the `Destroyed` state will panic on
303 /// any call to `with`.
304 #[unstable = "state querying was recently added"]
305 pub fn state(&'static self) -> State {
307 match (self.inner)().get() {
310 Some(..) => State::Valid,
311 None => State::Uninitialized,
314 None => State::Destroyed,
320 #[deprecated = "function renamed to state() and returns more info"]
321 pub fn destroyed(&'static self) -> bool { self.state() == State::Destroyed }
324 #[cfg(all(any(target_os = "macos", target_os = "linux"), not(target_arch = "aarch64")))]
328 use cell::UnsafeCell;
334 // Place the inner bits in an `UnsafeCell` to currently get around the
335 // "only Sync statics" restriction. This allows any type to be placed in
338 // Note that all access requires `T: 'static` so it can't be a type with
339 // any borrowed pointers still.
340 pub inner: UnsafeCell<T>,
342 // Metadata to keep track of the state of the destructor. Remember that
343 // these variables are thread-local, not global.
344 pub dtor_registered: UnsafeCell<bool>, // should be Cell
345 pub dtor_running: UnsafeCell<bool>, // should be Cell
348 unsafe impl<T> ::kinds::Sync for Key<T> { }
352 pub unsafe fn get(&'static self) -> Option<&'static T> {
353 if intrinsics::needs_drop::<T>() && *self.dtor_running.get() {
356 self.register_dtor();
357 Some(&*self.inner.get())
360 unsafe fn register_dtor(&self) {
361 if !intrinsics::needs_drop::<T>() || *self.dtor_registered.get() {
365 register_dtor(self as *const _ as *mut u8,
367 *self.dtor_registered.get() = true;
371 // Since what appears to be glibc 2.18 this symbol has been shipped which
372 // GCC and clang both use to invoke destructors in thread_local globals, so
373 // let's do the same!
375 // Note, however, that we run on lots older linuxes, as well as cross
376 // compiling from a newer linux to an older linux, so we also have a
377 // fallback implementation to use as well.
379 // Due to rust-lang/rust#18804, make sure this is not generic!
380 #[cfg(target_os = "linux")]
381 unsafe fn register_dtor(t: *mut u8, dtor: unsafe extern fn(*mut u8)) {
384 use sys_common::thread_local as os;
387 static __dso_handle: *mut u8;
388 #[linkage = "extern_weak"]
389 static __cxa_thread_atexit_impl: *const ();
391 if !__cxa_thread_atexit_impl.is_null() {
392 type F = unsafe extern fn(dtor: unsafe extern fn(*mut u8),
394 dso_handle: *mut u8) -> libc::c_int;
395 mem::transmute::<*const (), F>(__cxa_thread_atexit_impl)
396 (dtor, t, __dso_handle);
400 // The fallback implementation uses a vanilla OS-based TLS key to track
401 // the list of destructors that need to be run for this thread. The key
402 // then has its own destructor which runs all the other destructors.
404 // The destructor for DTORS is a little special in that it has a `while`
405 // loop to continuously drain the list of registered destructors. It
406 // *should* be the case that this loop always terminates because we
407 // provide the guarantee that a TLS key cannot be set after it is
408 // flagged for destruction.
409 static DTORS: os::StaticKey = os::StaticKey {
410 inner: os::INIT_INNER,
411 dtor: Some(run_dtors as unsafe extern "C" fn(*mut u8)),
413 type List = Vec<(*mut u8, unsafe extern fn(*mut u8))>;
414 if DTORS.get().is_null() {
415 let v: Box<List> = box Vec::new();
416 DTORS.set(mem::transmute(v));
418 let list: &mut List = &mut *(DTORS.get() as *mut List);
419 list.push((t, dtor));
421 unsafe extern fn run_dtors(mut ptr: *mut u8) {
422 while !ptr.is_null() {
423 let list: Box<List> = mem::transmute(ptr);
424 for &(ptr, dtor) in list.iter() {
428 DTORS.set(0 as *mut _);
433 // OSX's analog of the above linux function is this _tlv_atexit function.
434 // The disassembly of thread_local globals in C++ (at least produced by
435 // clang) will have this show up in the output.
436 #[cfg(target_os = "macos")]
437 unsafe fn register_dtor(t: *mut u8, dtor: unsafe extern fn(*mut u8)) {
439 fn _tlv_atexit(dtor: unsafe extern fn(*mut u8),
442 _tlv_atexit(dtor, t);
446 pub unsafe extern fn destroy_value<T>(ptr: *mut u8) {
447 let ptr = ptr as *mut Key<T>;
448 // Right before we run the user destructor be sure to flag the
449 // destructor as running for this thread so calls to `get` will return
451 *(*ptr).dtor_running.get() = true;
452 ptr::read((*ptr).inner.get() as *const T);
456 #[cfg(any(not(any(target_os = "macos", target_os = "linux")), target_arch = "aarch64"))]
460 use cell::UnsafeCell;
462 use sys_common::thread_local::StaticKey as OsStaticKey;
466 // Statically allocated initialization expression, using an `UnsafeCell`
467 // for the same reasons as above.
468 pub inner: UnsafeCell<T>,
470 // OS-TLS key that we'll use to key off.
474 unsafe impl<T> ::kinds::Sync for Key<T> { }
476 struct Value<T: 'static> {
477 key: &'static Key<T>,
483 pub unsafe fn get(&'static self) -> Option<&'static T> {
484 self.ptr().map(|p| &*p)
487 unsafe fn ptr(&'static self) -> Option<*mut T> {
488 let ptr = self.os.get() as *mut Value<T>;
490 if ptr as uint == 1 {
493 return Some(&mut (*ptr).value as *mut T);
496 // If the lookup returned null, we haven't initialized our own local
497 // copy, so do that now.
499 // Also note that this transmute_copy should be ok because the value
500 // `inner` is already validated to be a valid `static` value, so we
501 // should be able to freely copy the bits.
502 let ptr: Box<Value<T>> = box Value {
504 value: mem::transmute_copy(&self.inner),
506 let ptr: *mut Value<T> = mem::transmute(ptr);
507 self.os.set(ptr as *mut u8);
508 Some(&mut (*ptr).value as *mut T)
513 pub unsafe extern fn destroy_value<T: 'static>(ptr: *mut u8) {
514 // The OS TLS ensures that this key contains a NULL value when this
515 // destructor starts to run. We set it back to a sentinel value of 1 to
516 // ensure that any future calls to `get` for this thread will return
519 // Note that to prevent an infinite loop we reset it back to null right
520 // before we return from the destructor ourselves.
521 let ptr: Box<Value<T>> = mem::transmute(ptr);
523 key.os.set(1 as *mut u8);
525 key.os.set(0 as *mut u8);
533 use sync::mpsc::{channel, Sender};
534 use cell::UnsafeCell;
538 struct Foo(Sender<()>);
542 let Foo(ref s) = *self;
549 thread_local!(static FOO: UnsafeCell<int> = UnsafeCell { value: 1 });
551 FOO.with(|f| unsafe {
552 assert_eq!(*f.get(), 1);
555 let (tx, rx) = channel();
556 let _t = Thread::spawn(move|| {
557 FOO.with(|f| unsafe {
558 assert_eq!(*f.get(), 1);
560 tx.send(()).unwrap();
564 FOO.with(|f| unsafe {
565 assert_eq!(*f.get(), 2);
574 assert!(FOO.state() == State::Destroyed);
578 assert!(FOO.state() == State::Uninitialized);
581 thread_local!(static FOO: Foo = foo());
584 assert!(FOO.state() == State::Uninitialized);
586 assert!(FOO.state() == State::Valid);
588 assert!(FOO.state() == State::Valid);
589 }).join().ok().unwrap();
594 thread_local!(static FOO: UnsafeCell<Option<Foo>> = UnsafeCell {
598 let (tx, rx) = channel();
599 let _t = Thread::spawn(move|| unsafe {
600 let mut tx = Some(tx);
602 *f.get() = Some(Foo(tx.take().unwrap()));
612 thread_local!(static K1: UnsafeCell<Option<S1>> = UnsafeCell {
615 thread_local!(static K2: UnsafeCell<Option<S2>> = UnsafeCell {
618 static mut HITS: uint = 0;
624 if K2.state() == State::Destroyed {
628 K2.with(|s| *s.get() = Some(S2));
640 assert!(K1.state() != State::Destroyed);
642 K1.with(|s| *s.get() = Some(S1));
647 Thread::spawn(move|| {
649 }).join().ok().unwrap();
653 fn self_referential() {
655 thread_local!(static K1: UnsafeCell<Option<S1>> = UnsafeCell {
661 assert!(K1.state() == State::Destroyed);
665 Thread::spawn(move|| unsafe {
666 K1.with(|s| *s.get() = Some(S1));
667 }).join().ok().unwrap();
671 fn dtors_in_dtors_in_dtors() {
672 struct S1(Sender<()>);
673 thread_local!(static K1: UnsafeCell<Option<S1>> = UnsafeCell {
676 thread_local!(static K2: UnsafeCell<Option<Foo>> = UnsafeCell {
682 let S1(ref tx) = *self;
684 if K2.state() != State::Destroyed {
685 K2.with(|s| *s.get() = Some(Foo(tx.clone())));
691 let (tx, rx) = channel();
692 let _t = Thread::spawn(move|| unsafe {
693 let mut tx = Some(tx);
694 K1.with(|s| *s.get() = Some(S1(tx.take().unwrap())));
705 use collections::HashMap;
709 fn square(i: int) -> int { i * i }
710 thread_local!(static FOO: int = square(3));
719 fn map() -> RefCell<HashMap<int, int>> {
720 let mut m = HashMap::new();
724 thread_local!(static FOO: RefCell<HashMap<int, int>> = map());
727 assert_eq!(map.borrow()[1], 2);
733 thread_local!(static FOO: RefCell<Vec<uint>> = RefCell::new(vec![1, 2, 3]));
736 assert_eq!(vec.borrow().len(), 3);
737 vec.borrow_mut().push(4);
738 assert_eq!(vec.borrow()[3], 4);