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.
43 #[cfg_attr(stage0, macro_escape)]
44 #[cfg_attr(not(stage0), macro_use)]
47 // Sure wish we had macro hygiene, no?
50 pub use super::imp::Key as KeyInner;
51 pub use super::imp::destroy_value;
52 pub use sys_common::thread_local::INIT_INNER as OS_INIT_INNER;
53 pub use sys_common::thread_local::StaticKey as OsStaticKey;
56 /// A thread local storage key which owns its contents.
58 /// This key uses the fastest possible implementation available to it for the
59 /// target platform. It is instantiated with the `thread_local!` macro and the
60 /// primary method is the `with` method.
62 /// The `with` method yields a reference to the contained value which cannot be
63 /// sent across tasks or escape the given closure.
65 /// # Initialization and Destruction
67 /// Initialization is dynamically performed on the first call to `with()`
68 /// within a thread, and values support destructors which will be run when a
74 /// use std::cell::RefCell;
75 /// use std::thread::Thread;
77 /// thread_local!(static FOO: RefCell<uint> = RefCell::new(1));
80 /// assert_eq!(*f.borrow(), 1);
81 /// *f.borrow_mut() = 2;
84 /// // each thread starts out with the initial value of 1
85 /// Thread::spawn(move|| {
87 /// assert_eq!(*f.borrow(), 1);
88 /// *f.borrow_mut() = 3;
92 /// // we retain our original value of 2 despite the child thread
94 /// assert_eq!(*f.borrow(), 2);
99 // The key itself may be tagged with #[thread_local], and this `Key` is
100 // stored as a `static`, and it's not valid for a static to reference the
101 // address of another thread_local static. For this reason we kinda wonkily
102 // work around this by generating a shim function which will give us the
103 // address of the inner TLS key at runtime.
105 // This is trivially devirtualizable by LLVM because we never store anything
106 // to this field and rustc can declare the `static` as constant as well.
108 pub inner: fn() -> &'static __impl::KeyInner<UnsafeCell<Option<T>>>,
110 // initialization routine to invoke to create a value
115 /// Declare a new thread local storage key of type `std::thread_local::Key`.
118 macro_rules! thread_local {
119 (static $name:ident: $t:ty = $init:expr) => (
120 static $name: ::std::thread_local::Key<$t> = {
121 use std::cell::UnsafeCell as __UnsafeCell;
122 use std::thread_local::__impl::KeyInner as __KeyInner;
123 use std::option::Option as __Option;
124 use std::option::Option::None as __None;
126 __thread_local_inner!(static __KEY: __UnsafeCell<__Option<$t>> = {
127 __UnsafeCell { value: __None }
129 fn __init() -> $t { $init }
130 fn __getit() -> &'static __KeyInner<__UnsafeCell<__Option<$t>>> {
133 ::std::thread_local::Key { inner: __getit, init: __init }
136 (pub static $name:ident: $t:ty = $init:expr) => (
137 pub static $name: ::std::thread_local::Key<$t> = {
138 use std::cell::UnsafeCell as __UnsafeCell;
139 use std::thread_local::__impl::KeyInner as __KeyInner;
140 use std::option::Option as __Option;
141 use std::option::Option::None as __None;
143 __thread_local_inner!(static __KEY: __UnsafeCell<__Option<$t>> = {
144 __UnsafeCell { value: __None }
146 fn __init() -> $t { $init }
147 fn __getit() -> &'static __KeyInner<__UnsafeCell<__Option<$t>>> {
150 ::std::thread_local::Key { inner: __getit, init: __init }
157 // When cross compiling, rustc will load plugins and macros from the *host*
158 // platform before search for macros from the target platform. This is primarily
159 // done to detect, for example, plugins. Ideally the macro below would be
160 // defined once per module below, but unfortunately this means we have the
161 // following situation:
163 // 1. We compile libstd for x86_64-unknown-linux-gnu, this thread_local!() macro
164 // will inject #[thread_local] statics.
165 // 2. We then try to compile a program for arm-linux-androideabi
166 // 3. The compiler has a host of linux and a target of android, so it loads
167 // macros from the *linux* libstd.
168 // 4. The macro generates a #[thread_local] field, but the android libstd does
169 // not use #[thread_local]
170 // 5. Compile error about structs with wrong fields.
172 // To get around this, we're forced to inject the #[cfg] logic into the macro
177 macro_rules! __thread_local_inner {
178 (static $name:ident: $t:ty = $init:expr) => (
179 #[cfg_attr(all(any(target_os = "macos", target_os = "linux"),
180 not(target_arch = "aarch64")),
182 static $name: ::std::thread_local::__impl::KeyInner<$t> =
183 __thread_local_inner!($init, $t);
185 (pub static $name:ident: $t:ty = $init:expr) => (
186 #[cfg_attr(all(any(target_os = "macos", target_os = "linux"),
187 not(target_arch = "aarch64")),
189 pub static $name: ::std::thread_local::__impl::KeyInner<$t> =
190 __thread_local_inner!($init, $t);
192 ($init:expr, $t:ty) => ({
193 #[cfg(all(any(target_os = "macos", target_os = "linux"), not(target_arch = "aarch64")))]
194 const _INIT: ::std::thread_local::__impl::KeyInner<$t> = {
195 ::std::thread_local::__impl::KeyInner {
196 inner: ::std::cell::UnsafeCell { value: $init },
197 dtor_registered: ::std::cell::UnsafeCell { value: false },
198 dtor_running: ::std::cell::UnsafeCell { value: false },
202 #[cfg(any(not(any(target_os = "macos", target_os = "linux")), target_arch = "aarch64"))]
203 const _INIT: ::std::thread_local::__impl::KeyInner<$t> = {
204 unsafe extern fn __destroy(ptr: *mut u8) {
205 ::std::thread_local::__impl::destroy_value::<$t>(ptr);
208 ::std::thread_local::__impl::KeyInner {
209 inner: ::std::cell::UnsafeCell { value: $init },
210 os: ::std::thread_local::__impl::OsStaticKey {
211 inner: ::std::thread_local::__impl::OS_INIT_INNER,
212 dtor: ::std::option::Option::Some(__destroy as unsafe extern fn(*mut u8)),
221 /// Indicator of the state of a thread local storage key.
222 #[unstable = "state querying was recently added"]
223 #[derive(Eq, PartialEq, Copy)]
225 /// All keys are in this state whenever a thread starts. Keys will
226 /// transition to the `Valid` state once the first call to `with` happens
227 /// and the initialization expression succeeds.
229 /// Keys in the `Uninitialized` state will yield a reference to the closure
230 /// passed to `with` so long as the initialization routine does not panic.
233 /// Once a key has been accessed successfully, it will enter the `Valid`
234 /// state. Keys in the `Valid` state will remain so until the thread exits,
235 /// at which point the destructor will be run and the key will enter the
236 /// `Destroyed` state.
238 /// Keys in the `Valid` state will be guaranteed to yield a reference to the
239 /// closure passed to `with`.
242 /// When a thread exits, the destructors for keys will be run (if
243 /// necessary). While a destructor is running, and possibly after a
244 /// destructor has run, a key is in the `Destroyed` state.
246 /// Keys in the `Destroyed` states will trigger a panic when accessed via
251 impl<T: 'static> Key<T> {
252 /// Acquire a reference to the value in this TLS key.
254 /// This will lazily initialize the value if this thread has not referenced
259 /// This function will `panic!()` if the key currently has its
260 /// destructor running, and it **may** panic if the destructor has
261 /// previously been run for this thread.
263 pub fn with<F, R>(&'static self, f: F) -> R
264 where F: FnOnce(&T) -> R {
265 let slot = (self.inner)();
267 let slot = slot.get().expect("cannot access a TLS value during or \
268 after it is destroyed");
269 f(match *slot.get() {
270 Some(ref inner) => inner,
271 None => self.init(slot),
276 unsafe fn init(&self, slot: &UnsafeCell<Option<T>>) -> &T {
277 // Execute the initialization up front, *then* move it into our slot,
278 // just in case initialization fails.
279 let value = (self.init)();
280 let ptr = slot.get();
282 (*ptr).as_ref().unwrap()
285 /// Query the current state of this key.
287 /// A key is initially in the `Uninitialized` state whenever a thread
288 /// starts. It will remain in this state up until the first call to `with`
289 /// within a thread has run the initialization expression successfully.
291 /// Once the initialization expression succeeds, the key transitions to the
292 /// `Valid` state which will guarantee that future calls to `with` will
293 /// succeed within the thread.
295 /// When a thread exits, each key will be destroyed in turn, and as keys are
296 /// destroyed they will enter the `Destroyed` state just before the
297 /// destructor starts to run. Keys may remain in the `Destroyed` state after
298 /// destruction has completed. Keys without destructors (e.g. with types
299 /// that are `Copy`), may never enter the `Destroyed` state.
301 /// Keys in the `Uninitialized` can be accessed so long as the
302 /// initialization does not panic. Keys in the `Valid` state are guaranteed
303 /// to be able to be accessed. Keys in the `Destroyed` state will panic on
304 /// any call to `with`.
305 #[unstable = "state querying was recently added"]
306 pub fn state(&'static self) -> State {
308 match (self.inner)().get() {
311 Some(..) => State::Valid,
312 None => State::Uninitialized,
315 None => State::Destroyed,
321 #[deprecated = "function renamed to state() and returns more info"]
322 pub fn destroyed(&'static self) -> bool { self.state() == State::Destroyed }
325 #[cfg(all(any(target_os = "macos", target_os = "linux"), not(target_arch = "aarch64")))]
329 use cell::UnsafeCell;
335 // Place the inner bits in an `UnsafeCell` to currently get around the
336 // "only Sync statics" restriction. This allows any type to be placed in
339 // Note that all access requires `T: 'static` so it can't be a type with
340 // any borrowed pointers still.
341 pub inner: UnsafeCell<T>,
343 // Metadata to keep track of the state of the destructor. Remember that
344 // these variables are thread-local, not global.
345 pub dtor_registered: UnsafeCell<bool>, // should be Cell
346 pub dtor_running: UnsafeCell<bool>, // should be Cell
349 unsafe impl<T> ::markers::Sync for Key<T> { }
353 pub unsafe fn get(&'static self) -> Option<&'static T> {
354 if intrinsics::needs_drop::<T>() && *self.dtor_running.get() {
357 self.register_dtor();
358 Some(&*self.inner.get())
361 unsafe fn register_dtor(&self) {
362 if !intrinsics::needs_drop::<T>() || *self.dtor_registered.get() {
366 register_dtor(self as *const _ as *mut u8,
368 *self.dtor_registered.get() = true;
372 // Since what appears to be glibc 2.18 this symbol has been shipped which
373 // GCC and clang both use to invoke destructors in thread_local globals, so
374 // let's do the same!
376 // Note, however, that we run on lots older linuxes, as well as cross
377 // compiling from a newer linux to an older linux, so we also have a
378 // fallback implementation to use as well.
380 // Due to rust-lang/rust#18804, make sure this is not generic!
381 #[cfg(target_os = "linux")]
382 unsafe fn register_dtor(t: *mut u8, dtor: unsafe extern fn(*mut u8)) {
385 use sys_common::thread_local as os;
388 static __dso_handle: *mut u8;
389 #[linkage = "extern_weak"]
390 static __cxa_thread_atexit_impl: *const ();
392 if !__cxa_thread_atexit_impl.is_null() {
393 type F = unsafe extern fn(dtor: unsafe extern fn(*mut u8),
395 dso_handle: *mut u8) -> libc::c_int;
396 mem::transmute::<*const (), F>(__cxa_thread_atexit_impl)
397 (dtor, t, __dso_handle);
401 // The fallback implementation uses a vanilla OS-based TLS key to track
402 // the list of destructors that need to be run for this thread. The key
403 // then has its own destructor which runs all the other destructors.
405 // The destructor for DTORS is a little special in that it has a `while`
406 // loop to continuously drain the list of registered destructors. It
407 // *should* be the case that this loop always terminates because we
408 // provide the guarantee that a TLS key cannot be set after it is
409 // flagged for destruction.
410 static DTORS: os::StaticKey = os::StaticKey {
411 inner: os::INIT_INNER,
412 dtor: Some(run_dtors as unsafe extern "C" fn(*mut u8)),
414 type List = Vec<(*mut u8, unsafe extern fn(*mut u8))>;
415 if DTORS.get().is_null() {
416 let v: Box<List> = box Vec::new();
417 DTORS.set(mem::transmute(v));
419 let list: &mut List = &mut *(DTORS.get() as *mut List);
420 list.push((t, dtor));
422 unsafe extern fn run_dtors(mut ptr: *mut u8) {
423 while !ptr.is_null() {
424 let list: Box<List> = mem::transmute(ptr);
425 for &(ptr, dtor) in list.iter() {
429 DTORS.set(0 as *mut _);
434 // OSX's analog of the above linux function is this _tlv_atexit function.
435 // The disassembly of thread_local globals in C++ (at least produced by
436 // clang) will have this show up in the output.
437 #[cfg(target_os = "macos")]
438 unsafe fn register_dtor(t: *mut u8, dtor: unsafe extern fn(*mut u8)) {
440 fn _tlv_atexit(dtor: unsafe extern fn(*mut u8),
443 _tlv_atexit(dtor, t);
447 pub unsafe extern fn destroy_value<T>(ptr: *mut u8) {
448 let ptr = ptr as *mut Key<T>;
449 // Right before we run the user destructor be sure to flag the
450 // destructor as running for this thread so calls to `get` will return
452 *(*ptr).dtor_running.get() = true;
453 ptr::read((*ptr).inner.get() as *const T);
457 #[cfg(any(not(any(target_os = "macos", target_os = "linux")), target_arch = "aarch64"))]
461 use cell::UnsafeCell;
463 use sys_common::thread_local::StaticKey as OsStaticKey;
467 // Statically allocated initialization expression, using an `UnsafeCell`
468 // for the same reasons as above.
469 pub inner: UnsafeCell<T>,
471 // OS-TLS key that we'll use to key off.
475 unsafe impl<T> ::markers::Sync for Key<T> { }
477 struct Value<T: 'static> {
478 key: &'static Key<T>,
484 pub unsafe fn get(&'static self) -> Option<&'static T> {
485 self.ptr().map(|p| &*p)
488 unsafe fn ptr(&'static self) -> Option<*mut T> {
489 let ptr = self.os.get() as *mut Value<T>;
491 if ptr as uint == 1 {
494 return Some(&mut (*ptr).value as *mut T);
497 // If the lookup returned null, we haven't initialized our own local
498 // copy, so do that now.
500 // Also note that this transmute_copy should be ok because the value
501 // `inner` is already validated to be a valid `static` value, so we
502 // should be able to freely copy the bits.
503 let ptr: Box<Value<T>> = box Value {
505 value: mem::transmute_copy(&self.inner),
507 let ptr: *mut Value<T> = mem::transmute(ptr);
508 self.os.set(ptr as *mut u8);
509 Some(&mut (*ptr).value as *mut T)
514 pub unsafe extern fn destroy_value<T: 'static>(ptr: *mut u8) {
515 // The OS TLS ensures that this key contains a NULL value when this
516 // destructor starts to run. We set it back to a sentinel value of 1 to
517 // ensure that any future calls to `get` for this thread will return
520 // Note that to prevent an infinite loop we reset it back to null right
521 // before we return from the destructor ourselves.
522 let ptr: Box<Value<T>> = mem::transmute(ptr);
524 key.os.set(1 as *mut u8);
526 key.os.set(0 as *mut u8);
534 use sync::mpsc::{channel, Sender};
535 use cell::UnsafeCell;
539 struct Foo(Sender<()>);
543 let Foo(ref s) = *self;
550 thread_local!(static FOO: UnsafeCell<int> = UnsafeCell { value: 1 });
552 FOO.with(|f| unsafe {
553 assert_eq!(*f.get(), 1);
556 let (tx, rx) = channel();
557 let _t = Thread::spawn(move|| {
558 FOO.with(|f| unsafe {
559 assert_eq!(*f.get(), 1);
561 tx.send(()).unwrap();
565 FOO.with(|f| unsafe {
566 assert_eq!(*f.get(), 2);
575 assert!(FOO.state() == State::Destroyed);
579 assert!(FOO.state() == State::Uninitialized);
582 thread_local!(static FOO: Foo = foo());
585 assert!(FOO.state() == State::Uninitialized);
587 assert!(FOO.state() == State::Valid);
589 assert!(FOO.state() == State::Valid);
590 }).join().ok().unwrap();
595 thread_local!(static FOO: UnsafeCell<Option<Foo>> = UnsafeCell {
599 let (tx, rx) = channel();
600 let _t = Thread::spawn(move|| unsafe {
601 let mut tx = Some(tx);
603 *f.get() = Some(Foo(tx.take().unwrap()));
613 thread_local!(static K1: UnsafeCell<Option<S1>> = UnsafeCell {
616 thread_local!(static K2: UnsafeCell<Option<S2>> = UnsafeCell {
619 static mut HITS: uint = 0;
625 if K2.state() == State::Destroyed {
629 K2.with(|s| *s.get() = Some(S2));
641 assert!(K1.state() != State::Destroyed);
643 K1.with(|s| *s.get() = Some(S1));
648 Thread::spawn(move|| {
650 }).join().ok().unwrap();
654 fn self_referential() {
656 thread_local!(static K1: UnsafeCell<Option<S1>> = UnsafeCell {
662 assert!(K1.state() == State::Destroyed);
666 Thread::spawn(move|| unsafe {
667 K1.with(|s| *s.get() = Some(S1));
668 }).join().ok().unwrap();
672 fn dtors_in_dtors_in_dtors() {
673 struct S1(Sender<()>);
674 thread_local!(static K1: UnsafeCell<Option<S1>> = UnsafeCell {
677 thread_local!(static K2: UnsafeCell<Option<Foo>> = UnsafeCell {
683 let S1(ref tx) = *self;
685 if K2.state() != State::Destroyed {
686 K2.with(|s| *s.get() = Some(Foo(tx.clone())));
692 let (tx, rx) = channel();
693 let _t = Thread::spawn(move|| unsafe {
694 let mut tx = Some(tx);
695 K1.with(|s| *s.get() = Some(S1(tx.take().unwrap())));
706 use collections::HashMap;
710 fn square(i: int) -> int { i * i }
711 thread_local!(static FOO: int = square(3));
720 fn map() -> RefCell<HashMap<int, int>> {
721 let mut m = HashMap::new();
725 thread_local!(static FOO: RefCell<HashMap<int, int>> = map());
728 assert_eq!(map.borrow()[1], 2);
734 thread_local!(static FOO: RefCell<Vec<uint>> = RefCell::new(vec![1, 2, 3]));
737 assert_eq!(vec.borrow().len(), 3);
738 vec.borrow_mut().push(4);
739 assert_eq!(vec.borrow()[3], 4);