src/libstd/thread/local.rs

   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.
   4 //
   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.
  10
  11 //! Thread local storage
  12
  13 #![unstable(feature = "thread_local_internals", issue = "0")]
  14
  15 use cell::UnsafeCell;
  16 use mem;
  17
  18 /// A thread local storage key which owns its contents.
  19 ///
  20 /// This key uses the fastest possible implementation available to it for the
  21 /// target platform. It is instantiated with the `thread_local!` macro and the
  22 /// primary method is the `with` method.
  23 ///
  24 /// The `with` method yields a reference to the contained value which cannot be
  25 /// sent across threads or escape the given closure.
  26 ///
  27 /// # Initialization and Destruction
  28 ///
  29 /// Initialization is dynamically performed on the first call to `with()`
  30 /// within a thread, and values support destructors which will be run when a
  31 /// thread exits.
  32 ///
  33 /// # Examples
  34 ///
  35 /// ```
  36 /// use std::cell::RefCell;
  37 /// use std::thread;
  38 ///
  39 /// thread_local!(static FOO: RefCell<u32> = RefCell::new(1));
  40 ///
  41 /// FOO.with(|f| {
  42 ///     assert_eq!(*f.borrow(), 1);
  43 ///     *f.borrow_mut() = 2;
  44 /// });
  45 ///
  46 /// // each thread starts out with the initial value of 1
  47 /// thread::spawn(move|| {
  48 ///     FOO.with(|f| {
  49 ///         assert_eq!(*f.borrow(), 1);
  50 ///         *f.borrow_mut() = 3;
  51 ///     });
  52 /// });
  53 ///
  54 /// // we retain our original value of 2 despite the child thread
  55 /// FOO.with(|f| {
  56 ///     assert_eq!(*f.borrow(), 2);
  57 /// });
  58 /// ```
  59 ///
  60 /// # Platform-specific behavior
  61 ///
  62 /// Note that a "best effort" is made to ensure that destructors for types
  63 /// stored in thread local storage are run, but not all platforms can guarantee
  64 /// that destructors will be run for all types in thread local storage. For
  65 /// example, there are a number of known caveats where destructors are not run:
  66 ///
  67 /// 1. On Unix systems when pthread-based TLS is being used, destructors will
  68 ///    not be run for TLS values on the main thread when it exits. Note that the
  69 ///    application will exit immediately after the main thread exits as well.
  70 /// 2. On all platforms it's possible for TLS to re-initialize other TLS slots
  71 ///    during destruction. Some platforms ensure that this cannot happen
  72 ///    infinitely by preventing re-initialization of any slot that has been
  73 ///    destroyed, but not all platforms have this guard. Those platforms that do
  74 ///    not guard typically have a synthetic limit after which point no more
  75 ///    destructors are run.
  76 /// 3. On OSX, initializing TLS during destruction of other TLS slots can
  77 ///    sometimes cancel *all* destructors for the current thread, whether or not
  78 ///    the slots have already had their destructors run or not.
  79 #[stable(feature = "rust1", since = "1.0.0")]
  80 pub struct LocalKey<T: 'static> {
  81     // This outer `LocalKey<T>` type is what's going to be stored in statics,
  82     // but actual data inside will sometimes be tagged with #[thread_local].
  83     // It's not valid for a true static to reference a #[thread_local] static,
  84     // so we get around that by exposing an accessor through a layer of function
  85     // indirection (this thunk).
  86     //
  87     // Note that the thunk is itself unsafe because the returned lifetime of the
  88     // slot where data lives, `'static`, is not actually valid. The lifetime
  89     // here is actually `'thread`!
  90     //
  91     // Although this is an extra layer of indirection, it should in theory be
  92     // trivially devirtualizable by LLVM because the value of `inner` never
  93     // changes and the constant should be readonly within a crate. This mainly
  94     // only runs into problems when TLS statics are exported across crates.
  95     inner: fn() -> Option<&'static UnsafeCell<Option<T>>>,
  96
  97     // initialization routine to invoke to create a value
  98     init: fn() -> T,
  99 }
 100
 101 /// Declare a new thread local storage key of type `std::thread::LocalKey`.
 102 ///
 103 /// # Syntax
 104 ///
 105 /// The macro wraps any number of static declarations and makes them thread local.
 106 /// Each static may be public or private, and attributes are allowed. Example:
 107 ///
 108 /// ```
 109 /// use std::cell::RefCell;
 110 /// thread_local! {
 111 ///     pub static FOO: RefCell<u32> = RefCell::new(1);
 112 ///
 113 ///     #[allow(unused)]
 114 ///     static BAR: RefCell<f32> = RefCell::new(1.0);
 115 /// }
 116 /// # fn main() {}
 117 /// ```
 118 ///
 119 /// See [LocalKey documentation](thread/struct.LocalKey.html) for more
 120 /// information.
 121 #[macro_export]
 122 #[stable(feature = "rust1", since = "1.0.0")]
 123 #[allow_internal_unstable]
 124 macro_rules! thread_local {
 125     // rule 0: empty (base case for the recursion)
 126     () => {};
 127
 128     // rule 1: process multiple declarations where the first one is private
 129     ($(#[$attr:meta])* static $name:ident: $t:ty = $init:expr; $($rest:tt)*) => (
 130         thread_local!($(#[$attr])* static $name: $t = $init); // go to rule 2
 131         thread_local!($($rest)*);
 132     );
 133
 134     // rule 2: handle a single private declaration
 135     ($(#[$attr:meta])* static $name:ident: $t:ty = $init:expr) => (
 136         $(#[$attr])* static $name: $crate::thread::LocalKey<$t> =
 137             __thread_local_inner!($t, $init);
 138     );
 139
 140     // rule 3: handle multiple declarations where the first one is public
 141     ($(#[$attr:meta])* pub static $name:ident: $t:ty = $init:expr; $($rest:tt)*) => (
 142         thread_local!($(#[$attr])* pub static $name: $t = $init); // go to rule 4
 143         thread_local!($($rest)*);
 144     );
 145
 146     // rule 4: handle a single public declaration
 147     ($(#[$attr:meta])* pub static $name:ident: $t:ty = $init:expr) => (
 148         $(#[$attr])* pub static $name: $crate::thread::LocalKey<$t> =
 149             __thread_local_inner!($t, $init);
 150     );
 151 }
 152
 153 #[doc(hidden)]
 154 #[unstable(feature = "thread_local_internals",
 155            reason = "should not be necessary",
 156            issue = "0")]
 157 #[macro_export]
 158 #[allow_internal_unstable]
 159 macro_rules! __thread_local_inner {
 160     ($t:ty, $init:expr) => {{
 161         fn __init() -> $t { $init }
 162
 163         fn __getit() -> $crate::option::Option<
 164             &'static $crate::cell::UnsafeCell<
 165                 $crate::option::Option<$t>>>
 166         {
 167             #[thread_local]
 168             #[cfg(target_thread_local)]
 169             static __KEY: $crate::thread::__FastLocalKeyInner<$t> =
 170                 $crate::thread::__FastLocalKeyInner::new();
 171
 172             #[cfg(not(target_thread_local))]
 173             static __KEY: $crate::thread::__OsLocalKeyInner<$t> =
 174                 $crate::thread::__OsLocalKeyInner::new();
 175
 176             __KEY.get()
 177         }
 178
 179         $crate::thread::LocalKey::new(__getit, __init)
 180     }}
 181 }
 182
 183 /// Indicator of the state of a thread local storage key.
 184 #[unstable(feature = "thread_local_state",
 185            reason = "state querying was recently added",
 186            issue = "27716")]
 187 #[derive(Eq, PartialEq, Copy, Clone)]
 188 pub enum LocalKeyState {
 189     /// All keys are in this state whenever a thread starts. Keys will
 190     /// transition to the `Valid` state once the first call to `with` happens
 191     /// and the initialization expression succeeds.
 192     ///
 193     /// Keys in the `Uninitialized` state will yield a reference to the closure
 194     /// passed to `with` so long as the initialization routine does not panic.
 195     Uninitialized,
 196
 197     /// Once a key has been accessed successfully, it will enter the `Valid`
 198     /// state. Keys in the `Valid` state will remain so until the thread exits,
 199     /// at which point the destructor will be run and the key will enter the
 200     /// `Destroyed` state.
 201     ///
 202     /// Keys in the `Valid` state will be guaranteed to yield a reference to the
 203     /// closure passed to `with`.
 204     Valid,
 205
 206     /// When a thread exits, the destructors for keys will be run (if
 207     /// necessary). While a destructor is running, and possibly after a
 208     /// destructor has run, a key is in the `Destroyed` state.
 209     ///
 210     /// Keys in the `Destroyed` states will trigger a panic when accessed via
 211     /// `with`.
 212     Destroyed,
 213 }
 214
 215 impl<T: 'static> LocalKey<T> {
 216     #[doc(hidden)]
 217     #[unstable(feature = "thread_local_internals",
 218                reason = "recently added to create a key",
 219                issue = "0")]
 220     pub const fn new(inner: fn() -> Option<&'static UnsafeCell<Option<T>>>,
 221                      init: fn() -> T) -> LocalKey<T> {
 222         LocalKey {
 223             inner: inner,
 224             init: init,
 225         }
 226     }
 227
 228     /// Acquires a reference to the value in this TLS key.
 229     ///
 230     /// This will lazily initialize the value if this thread has not referenced
 231     /// this key yet.
 232     ///
 233     /// # Panics
 234     ///
 235     /// This function will `panic!()` if the key currently has its
 236     /// destructor running, and it **may** panic if the destructor has
 237     /// previously been run for this thread.
 238     #[stable(feature = "rust1", since = "1.0.0")]
 239     pub fn with<F, R>(&'static self, f: F) -> R
 240                       where F: FnOnce(&T) -> R {
 241         unsafe {
 242             let slot = (self.inner)();
 243             let slot = slot.expect("cannot access a TLS value during or \
 244                                     after it is destroyed");
 245             f(match *slot.get() {
 246                 Some(ref inner) => inner,
 247                 None => self.init(slot),
 248             })
 249         }
 250     }
 251
 252     unsafe fn init(&self, slot: &UnsafeCell<Option<T>>) -> &T {
 253         // Execute the initialization up front, *then* move it into our slot,
 254         // just in case initialization fails.
 255         let value = (self.init)();
 256         let ptr = slot.get();
 257
 258         // note that this can in theory just be `*ptr = Some(value)`, but due to
 259         // the compiler will currently codegen that pattern with something like:
 260         //
 261         //      ptr::drop_in_place(ptr)
 262         //      ptr::write(ptr, Some(value))
 263         //
 264         // Due to this pattern it's possible for the destructor of the value in
 265         // `ptr` (e.g. if this is being recursively initialized) to re-access
 266         // TLS, in which case there will be a `&` and `&mut` pointer to the same
 267         // value (an aliasing violation). To avoid setting the "I'm running a
 268         // destructor" flag we just use `mem::replace` which should sequence the
 269         // operations a little differently and make this safe to call.
 270         mem::replace(&mut *ptr, Some(value));
 271
 272         (*ptr).as_ref().unwrap()
 273     }
 274
 275     /// Query the current state of this key.
 276     ///
 277     /// A key is initially in the `Uninitialized` state whenever a thread
 278     /// starts. It will remain in this state up until the first call to `with`
 279     /// within a thread has run the initialization expression successfully.
 280     ///
 281     /// Once the initialization expression succeeds, the key transitions to the
 282     /// `Valid` state which will guarantee that future calls to `with` will
 283     /// succeed within the thread.
 284     ///
 285     /// When a thread exits, each key will be destroyed in turn, and as keys are
 286     /// destroyed they will enter the `Destroyed` state just before the
 287     /// destructor starts to run. Keys may remain in the `Destroyed` state after
 288     /// destruction has completed. Keys without destructors (e.g. with types
 289     /// that are `Copy`), may never enter the `Destroyed` state.
 290     ///
 291     /// Keys in the `Uninitialized` state can be accessed so long as the
 292     /// initialization does not panic. Keys in the `Valid` state are guaranteed
 293     /// to be able to be accessed. Keys in the `Destroyed` state will panic on
 294     /// any call to `with`.
 295     #[unstable(feature = "thread_local_state",
 296                reason = "state querying was recently added",
 297                issue = "27716")]
 298     pub fn state(&'static self) -> LocalKeyState {
 299         unsafe {
 300             match (self.inner)() {
 301                 Some(cell) => {
 302                     match *cell.get() {
 303                         Some(..) => LocalKeyState::Valid,
 304                         None => LocalKeyState::Uninitialized,
 305                     }
 306                 }
 307                 None => LocalKeyState::Destroyed,
 308             }
 309         }
 310     }
 311 }
 312
 313 #[doc(hidden)]
 314 pub mod os {
 315     use cell::{Cell, UnsafeCell};
 316     use marker;
 317     use ptr;
 318     use sys_common::thread_local::StaticKey as OsStaticKey;
 319
 320     pub struct Key<T> {
 321         // OS-TLS key that we'll use to key off.
 322         os: OsStaticKey,
 323         marker: marker::PhantomData<Cell<T>>,
 324     }
 325
 326     unsafe impl<T> ::marker::Sync for Key<T> { }
 327
 328     struct Value<T: 'static> {
 329         key: &'static Key<T>,
 330         value: UnsafeCell<Option<T>>,
 331     }
 332
 333     impl<T: 'static> Key<T> {
 334         pub const fn new() -> Key<T> {
 335             Key {
 336                 os: OsStaticKey::new(Some(destroy_value::<T>)),
 337                 marker: marker::PhantomData
 338             }
 339         }
 340
 341         pub fn get(&'static self) -> Option<&'static UnsafeCell<Option<T>>> {
 342             unsafe {
 343                 let ptr = self.os.get() as *mut Value<T>;
 344                 if !ptr.is_null() {
 345                     if ptr as usize == 1 {
 346                         return None
 347                     }
 348                     return Some(&(*ptr).value);
 349                 }
 350
 351                 // If the lookup returned null, we haven't initialized our own local
 352                 // copy, so do that now.
 353                 let ptr: Box<Value<T>> = box Value {
 354                     key: self,
 355                     value: UnsafeCell::new(None),
 356                 };
 357                 let ptr = Box::into_raw(ptr);
 358                 self.os.set(ptr as *mut u8);
 359                 Some(&(*ptr).value)
 360             }
 361         }
 362     }
 363
 364     pub unsafe extern fn destroy_value<T: 'static>(ptr: *mut u8) {
 365         // The OS TLS ensures that this key contains a NULL value when this
 366         // destructor starts to run. We set it back to a sentinel value of 1 to
 367         // ensure that any future calls to `get` for this thread will return
 368         // `None`.
 369         //
 370         // Note that to prevent an infinite loop we reset it back to null right
 371         // before we return from the destructor ourselves.
 372         let ptr = Box::from_raw(ptr as *mut Value<T>);
 373         let key = ptr.key;
 374         key.os.set(1 as *mut u8);
 375         drop(ptr);
 376         key.os.set(ptr::null_mut());
 377     }
 378 }
 379
 380 #[cfg(all(test, not(target_os = "emscripten")))]
 381 mod tests {
 382     use sync::mpsc::{channel, Sender};
 383     use cell::{Cell, UnsafeCell};
 384     use super::LocalKeyState;
 385     use thread;
 386
 387     struct Foo(Sender<()>);
 388
 389     impl Drop for Foo {
 390         fn drop(&mut self) {
 391             let Foo(ref s) = *self;
 392             s.send(()).unwrap();
 393         }
 394     }
 395
 396     #[test]
 397     fn smoke_no_dtor() {
 398         thread_local!(static FOO: Cell<i32> = Cell::new(1));
 399
 400         FOO.with(|f| {
 401             assert_eq!(f.get(), 1);
 402             f.set(2);
 403         });
 404         let (tx, rx) = channel();
 405         let _t = thread::spawn(move|| {
 406             FOO.with(|f| {
 407                 assert_eq!(f.get(), 1);
 408             });
 409             tx.send(()).unwrap();
 410         });
 411         rx.recv().unwrap();
 412
 413         FOO.with(|f| {
 414             assert_eq!(f.get(), 2);
 415         });
 416     }
 417
 418     #[test]
 419     fn states() {
 420         struct Foo;
 421         impl Drop for Foo {
 422             fn drop(&mut self) {
 423                 assert!(FOO.state() == LocalKeyState::Destroyed);
 424             }
 425         }
 426         fn foo() -> Foo {
 427             assert!(FOO.state() == LocalKeyState::Uninitialized);
 428             Foo
 429         }
 430         thread_local!(static FOO: Foo = foo());
 431
 432         thread::spawn(|| {
 433             assert!(FOO.state() == LocalKeyState::Uninitialized);
 434             FOO.with(|_| {
 435                 assert!(FOO.state() == LocalKeyState::Valid);
 436             });
 437             assert!(FOO.state() == LocalKeyState::Valid);
 438         }).join().ok().unwrap();
 439     }
 440
 441     #[test]
 442     fn smoke_dtor() {
 443         thread_local!(static FOO: UnsafeCell<Option<Foo>> = UnsafeCell::new(None));
 444
 445         let (tx, rx) = channel();
 446         let _t = thread::spawn(move|| unsafe {
 447             let mut tx = Some(tx);
 448             FOO.with(|f| {
 449                 *f.get() = Some(Foo(tx.take().unwrap()));
 450             });
 451         });
 452         rx.recv().unwrap();
 453     }
 454
 455     #[test]
 456     fn circular() {
 457         struct S1;
 458         struct S2;
 459         thread_local!(static K1: UnsafeCell<Option<S1>> = UnsafeCell::new(None));
 460         thread_local!(static K2: UnsafeCell<Option<S2>> = UnsafeCell::new(None));
 461         static mut HITS: u32 = 0;
 462
 463         impl Drop for S1 {
 464             fn drop(&mut self) {
 465                 unsafe {
 466                     HITS += 1;
 467                     if K2.state() == LocalKeyState::Destroyed {
 468                         assert_eq!(HITS, 3);
 469                     } else {
 470                         if HITS == 1 {
 471                             K2.with(|s| *s.get() = Some(S2));
 472                         } else {
 473                             assert_eq!(HITS, 3);
 474                         }
 475                     }
 476                 }
 477             }
 478         }
 479         impl Drop for S2 {
 480             fn drop(&mut self) {
 481                 unsafe {
 482                     HITS += 1;
 483                     assert!(K1.state() != LocalKeyState::Destroyed);
 484                     assert_eq!(HITS, 2);
 485                     K1.with(|s| *s.get() = Some(S1));
 486                 }
 487             }
 488         }
 489
 490         thread::spawn(move|| {
 491             drop(S1);
 492         }).join().ok().unwrap();
 493     }
 494
 495     #[test]
 496     fn self_referential() {
 497         struct S1;
 498         thread_local!(static K1: UnsafeCell<Option<S1>> = UnsafeCell::new(None));
 499
 500         impl Drop for S1 {
 501             fn drop(&mut self) {
 502                 assert!(K1.state() == LocalKeyState::Destroyed);
 503             }
 504         }
 505
 506         thread::spawn(move|| unsafe {
 507             K1.with(|s| *s.get() = Some(S1));
 508         }).join().ok().unwrap();
 509     }
 510
 511     // Note that this test will deadlock if TLS destructors aren't run (this
 512     // requires the destructor to be run to pass the test). OSX has a known bug
 513     // where dtors-in-dtors may cancel other destructors, so we just ignore this
 514     // test on OSX.
 515     #[test]
 516     #[cfg_attr(target_os = "macos", ignore)]
 517     fn dtors_in_dtors_in_dtors() {
 518         struct S1(Sender<()>);
 519         thread_local!(static K1: UnsafeCell<Option<S1>> = UnsafeCell::new(None));
 520         thread_local!(static K2: UnsafeCell<Option<Foo>> = UnsafeCell::new(None));
 521
 522         impl Drop for S1 {
 523             fn drop(&mut self) {
 524                 let S1(ref tx) = *self;
 525                 unsafe {
 526                     if K2.state() != LocalKeyState::Destroyed {
 527                         K2.with(|s| *s.get() = Some(Foo(tx.clone())));
 528                     }
 529                 }
 530             }
 531         }
 532
 533         let (tx, rx) = channel();
 534         let _t = thread::spawn(move|| unsafe {
 535             let mut tx = Some(tx);
 536             K1.with(|s| *s.get() = Some(S1(tx.take().unwrap())));
 537         });
 538         rx.recv().unwrap();
 539     }
 540 }
 541
 542 #[cfg(test)]
 543 mod dynamic_tests {
 544     use cell::RefCell;
 545     use collections::HashMap;
 546
 547     #[test]
 548     fn smoke() {
 549         fn square(i: i32) -> i32 { i * i }
 550         thread_local!(static FOO: i32 = square(3));
 551
 552         FOO.with(|f| {
 553             assert_eq!(*f, 9);
 554         });
 555     }
 556
 557     #[test]
 558     fn hashmap() {
 559         fn map() -> RefCell<HashMap<i32, i32>> {
 560             let mut m = HashMap::new();
 561             m.insert(1, 2);
 562             RefCell::new(m)
 563         }
 564         thread_local!(static FOO: RefCell<HashMap<i32, i32>> = map());
 565
 566         FOO.with(|map| {
 567             assert_eq!(map.borrow()[&1], 2);
 568         });
 569     }
 570
 571     #[test]
 572     fn refcell_vec() {
 573         thread_local!(static FOO: RefCell<Vec<u32>> = RefCell::new(vec![1, 2, 3]));
 574
 575         FOO.with(|vec| {
 576             assert_eq!(vec.borrow().len(), 3);
 577             vec.borrow_mut().push(4);
 578             assert_eq!(vec.borrow()[3], 4);
 579         });
 580     }
 581 }