1 //! Thread local storage
3 #![unstable(feature = "thread_local_internals", issue = "none")]
5 #[cfg(all(test, not(target_os = "emscripten")))]
11 use crate::error::Error;
14 /// A thread local storage key which owns its contents.
16 /// This key uses the fastest possible implementation available to it for the
17 /// target platform. It is instantiated with the [`thread_local!`] macro and the
18 /// primary method is the [`with`] method.
20 /// The [`with`] method yields a reference to the contained value which cannot be
21 /// sent across threads or escape the given closure.
23 /// # Initialization and Destruction
25 /// Initialization is dynamically performed on the first call to [`with`]
26 /// within a thread, and values that implement [`Drop`] get destructed when a
27 /// thread exits. Some caveats apply, which are explained below.
29 /// A `LocalKey`'s initializer cannot recursively depend on itself, and using
30 /// a `LocalKey` in this way will cause the initializer to infinitely recurse
31 /// on the first call to `with`.
36 /// use std::cell::RefCell;
39 /// thread_local!(static FOO: RefCell<u32> = RefCell::new(1));
42 /// assert_eq!(*f.borrow(), 1);
43 /// *f.borrow_mut() = 2;
46 /// // each thread starts out with the initial value of 1
47 /// let t = thread::spawn(move|| {
49 /// assert_eq!(*f.borrow(), 1);
50 /// *f.borrow_mut() = 3;
54 /// // wait for the thread to complete and bail out on panic
55 /// t.join().unwrap();
57 /// // we retain our original value of 2 despite the child thread
59 /// assert_eq!(*f.borrow(), 2);
63 /// # Platform-specific behavior
65 /// Note that a "best effort" is made to ensure that destructors for types
66 /// stored in thread local storage are run, but not all platforms can guarantee
67 /// that destructors will be run for all types in thread local storage. For
68 /// example, there are a number of known caveats where destructors are not run:
70 /// 1. On Unix systems when pthread-based TLS is being used, destructors will
71 /// not be run for TLS values on the main thread when it exits. Note that the
72 /// application will exit immediately after the main thread exits as well.
73 /// 2. On all platforms it's possible for TLS to re-initialize other TLS slots
74 /// during destruction. Some platforms ensure that this cannot happen
75 /// infinitely by preventing re-initialization of any slot that has been
76 /// destroyed, but not all platforms have this guard. Those platforms that do
77 /// not guard typically have a synthetic limit after which point no more
78 /// destructors are run.
80 /// [`with`]: LocalKey::with
81 #[stable(feature = "rust1", since = "1.0.0")]
82 pub struct LocalKey<T: 'static> {
83 // This outer `LocalKey<T>` type is what's going to be stored in statics,
84 // but actual data inside will sometimes be tagged with #[thread_local].
85 // It's not valid for a true static to reference a #[thread_local] static,
86 // so we get around that by exposing an accessor through a layer of function
87 // indirection (this thunk).
89 // Note that the thunk is itself unsafe because the returned lifetime of the
90 // slot where data lives, `'static`, is not actually valid. The lifetime
91 // here is actually slightly shorter than the currently running thread!
93 // Although this is an extra layer of indirection, it should in theory be
94 // trivially devirtualizable by LLVM because the value of `inner` never
95 // changes and the constant should be readonly within a crate. This mainly
96 // only runs into problems when TLS statics are exported across crates.
97 inner: unsafe fn() -> Option<&'static T>,
100 #[stable(feature = "std_debug", since = "1.16.0")]
101 impl<T: 'static> fmt::Debug for LocalKey<T> {
102 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
103 f.pad("LocalKey { .. }")
107 /// Declare a new thread local storage key of type [`std::thread::LocalKey`].
111 /// The macro wraps any number of static declarations and makes them thread local.
112 /// Publicity and attributes for each static are allowed. Example:
115 /// use std::cell::RefCell;
117 /// pub static FOO: RefCell<u32> = RefCell::new(1);
120 /// static BAR: RefCell<f32> = RefCell::new(1.0);
125 /// See [`LocalKey` documentation][`std::thread::LocalKey`] for more
128 /// [`std::thread::LocalKey`]: crate::thread::LocalKey
130 #[stable(feature = "rust1", since = "1.0.0")]
131 #[allow_internal_unstable(thread_local_internals)]
132 macro_rules! thread_local {
133 // empty (base case for the recursion)
136 // process multiple declarations
137 ($(#[$attr:meta])* $vis:vis static $name:ident: $t:ty = $init:expr; $($rest:tt)*) => (
138 $crate::__thread_local_inner!($(#[$attr])* $vis $name, $t, $init);
139 $crate::thread_local!($($rest)*);
142 // handle a single declaration
143 ($(#[$attr:meta])* $vis:vis static $name:ident: $t:ty = $init:expr) => (
144 $crate::__thread_local_inner!($(#[$attr])* $vis $name, $t, $init);
149 #[unstable(feature = "thread_local_internals", reason = "should not be necessary", issue = "none")]
151 #[allow_internal_unstable(thread_local_internals, cfg_target_thread_local, thread_local)]
152 #[allow_internal_unsafe]
153 macro_rules! __thread_local_inner {
154 (@key $t:ty, $init:expr) => {
157 fn __init() -> $t { $init }
159 unsafe fn __getit() -> $crate::option::Option<&'static $t> {
160 #[cfg(all(target_arch = "wasm32", not(target_feature = "atomics")))]
161 static __KEY: $crate::thread::__StaticLocalKeyInner<$t> =
162 $crate::thread::__StaticLocalKeyInner::new();
167 not(all(target_arch = "wasm32", not(target_feature = "atomics"))),
169 static __KEY: $crate::thread::__FastLocalKeyInner<$t> =
170 $crate::thread::__FastLocalKeyInner::new();
173 not(target_thread_local),
174 not(all(target_arch = "wasm32", not(target_feature = "atomics"))),
176 static __KEY: $crate::thread::__OsLocalKeyInner<$t> =
177 $crate::thread::__OsLocalKeyInner::new();
179 // FIXME: remove the #[allow(...)] marker when macros don't
180 // raise warning for missing/extraneous unsafe blocks anymore.
181 // See https://github.com/rust-lang/rust/issues/74838.
182 #[allow(unused_unsafe)]
183 unsafe { __KEY.get(__init) }
187 $crate::thread::LocalKey::new(__getit)
191 ($(#[$attr:meta])* $vis:vis $name:ident, $t:ty, $init:expr) => {
192 $(#[$attr])* $vis const $name: $crate::thread::LocalKey<$t> =
193 $crate::__thread_local_inner!(@key $t, $init);
197 /// An error returned by [`LocalKey::try_with`](struct.LocalKey.html#method.try_with).
198 #[stable(feature = "thread_local_try_with", since = "1.26.0")]
199 #[derive(Clone, Copy, Eq, PartialEq)]
200 pub struct AccessError {
204 #[stable(feature = "thread_local_try_with", since = "1.26.0")]
205 impl fmt::Debug for AccessError {
206 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
207 f.debug_struct("AccessError").finish()
211 #[stable(feature = "thread_local_try_with", since = "1.26.0")]
212 impl fmt::Display for AccessError {
213 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
214 fmt::Display::fmt("already destroyed", f)
218 #[stable(feature = "thread_local_try_with", since = "1.26.0")]
219 impl Error for AccessError {}
221 impl<T: 'static> LocalKey<T> {
224 feature = "thread_local_internals",
225 reason = "recently added to create a key",
228 #[rustc_const_unstable(feature = "thread_local_internals", issue = "none")]
229 pub const unsafe fn new(inner: unsafe fn() -> Option<&'static T>) -> LocalKey<T> {
233 /// Acquires a reference to the value in this TLS key.
235 /// This will lazily initialize the value if this thread has not referenced
240 /// This function will `panic!()` if the key currently has its
241 /// destructor running, and it **may** panic if the destructor has
242 /// previously been run for this thread.
243 #[stable(feature = "rust1", since = "1.0.0")]
244 pub fn with<F, R>(&'static self, f: F) -> R
248 self.try_with(f).expect(
249 "cannot access a Thread Local Storage value \
250 during or after destruction",
254 /// Acquires a reference to the value in this TLS key.
256 /// This will lazily initialize the value if this thread has not referenced
257 /// this key yet. If the key has been destroyed (which may happen if this is called
258 /// in a destructor), this function will return an [`AccessError`](struct.AccessError.html).
262 /// This function will still `panic!()` if the key is uninitialized and the
263 /// key's initializer panics.
264 #[stable(feature = "thread_local_try_with", since = "1.26.0")]
266 pub fn try_with<F, R>(&'static self, f: F) -> Result<R, AccessError>
271 let thread_local = (self.inner)().ok_or(AccessError { _private: () })?;
278 use crate::cell::UnsafeCell;
282 pub struct LazyKeyInner<T> {
283 inner: UnsafeCell<Option<T>>,
286 impl<T> LazyKeyInner<T> {
287 pub const fn new() -> LazyKeyInner<T> {
288 LazyKeyInner { inner: UnsafeCell::new(None) }
291 pub unsafe fn get(&self) -> Option<&'static T> {
292 (*self.inner.get()).as_ref()
295 pub unsafe fn initialize<F: FnOnce() -> T>(&self, init: F) -> &'static T {
296 // Execute the initialization up front, *then* move it into our slot,
297 // just in case initialization fails.
299 let ptr = self.inner.get();
301 // note that this can in theory just be `*ptr = Some(value)`, but due to
302 // the compiler will currently codegen that pattern with something like:
304 // ptr::drop_in_place(ptr)
305 // ptr::write(ptr, Some(value))
307 // Due to this pattern it's possible for the destructor of the value in
308 // `ptr` (e.g., if this is being recursively initialized) to re-access
309 // TLS, in which case there will be a `&` and `&mut` pointer to the same
310 // value (an aliasing violation). To avoid setting the "I'm running a
311 // destructor" flag we just use `mem::replace` which should sequence the
312 // operations a little differently and make this safe to call.
313 let _ = mem::replace(&mut *ptr, Some(value));
315 // After storing `Some` we want to get a reference to the contents of
316 // what we just stored. While we could use `unwrap` here and it should
317 // always work it empirically doesn't seem to always get optimized away,
318 // which means that using something like `try_with` can pull in
319 // panicking code and cause a large size bloat.
322 None => hint::unreachable_unchecked(),
327 pub unsafe fn take(&mut self) -> Option<T> {
328 (*self.inner.get()).take()
333 /// On some platforms like wasm32 there's no threads, so no need to generate
334 /// thread locals and we can instead just use plain statics!
336 #[cfg(all(target_arch = "wasm32", not(target_feature = "atomics")))]
338 use super::lazy::LazyKeyInner;
342 inner: LazyKeyInner<T>,
345 unsafe impl<T> Sync for Key<T> {}
347 impl<T> fmt::Debug for Key<T> {
348 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
354 pub const fn new() -> Key<T> {
355 Key { inner: LazyKeyInner::new() }
358 pub unsafe fn get(&self, init: fn() -> T) -> Option<&'static T> {
359 let value = match self.inner.get() {
360 Some(ref value) => value,
361 None => self.inner.initialize(init),
369 #[cfg(target_thread_local)]
371 use super::lazy::LazyKeyInner;
372 use crate::cell::Cell;
375 use crate::sys::thread_local_dtor::register_dtor;
377 #[derive(Copy, Clone)]
384 // This data structure has been carefully constructed so that the fast path
385 // only contains one branch on x86. That optimization is necessary to avoid
386 // duplicated tls lookups on OSX.
388 // LLVM issue: https://bugs.llvm.org/show_bug.cgi?id=41722
390 // If `LazyKeyInner::get` returns `None`, that indicates either:
391 // * The value has never been initialized
392 // * The value is being recursively initialized
393 // * The value has already been destroyed or is being destroyed
394 // To determine which kind of `None`, check `dtor_state`.
396 // This is very optimizer friendly for the fast path - initialized but
398 inner: LazyKeyInner<T>,
400 // Metadata to keep track of the state of the destructor. Remember that
401 // this variable is thread-local, not global.
402 dtor_state: Cell<DtorState>,
405 impl<T> fmt::Debug for Key<T> {
406 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
412 pub const fn new() -> Key<T> {
413 Key { inner: LazyKeyInner::new(), dtor_state: Cell::new(DtorState::Unregistered) }
416 pub unsafe fn get<F: FnOnce() -> T>(&self, init: F) -> Option<&'static T> {
417 match self.inner.get() {
418 Some(val) => Some(val),
419 None => self.try_initialize(init),
423 // `try_initialize` is only called once per fast thread local variable,
424 // except in corner cases where thread_local dtors reference other
425 // thread_local's, or it is being recursively initialized.
427 // Macos: Inlining this function can cause two `tlv_get_addr` calls to
428 // be performed for every call to `Key::get`.
429 // LLVM issue: https://bugs.llvm.org/show_bug.cgi?id=41722
431 unsafe fn try_initialize<F: FnOnce() -> T>(&self, init: F) -> Option<&'static T> {
432 if !mem::needs_drop::<T>() || self.try_register_dtor() {
433 Some(self.inner.initialize(init))
439 // `try_register_dtor` is only called once per fast thread local
440 // variable, except in corner cases where thread_local dtors reference
441 // other thread_local's, or it is being recursively initialized.
442 unsafe fn try_register_dtor(&self) -> bool {
443 match self.dtor_state.get() {
444 DtorState::Unregistered => {
445 // dtor registration happens before initialization.
446 register_dtor(self as *const _ as *mut u8, destroy_value::<T>);
447 self.dtor_state.set(DtorState::Registered);
450 DtorState::Registered => {
451 // recursively initialized
454 DtorState::RunningOrHasRun => false,
459 unsafe extern "C" fn destroy_value<T>(ptr: *mut u8) {
460 let ptr = ptr as *mut Key<T>;
462 // Right before we run the user destructor be sure to set the
463 // `Option<T>` to `None`, and `dtor_state` to `RunningOrHasRun`. This
464 // causes future calls to `get` to run `try_initialize_drop` again,
465 // which will now fail, and return `None`.
466 let value = (*ptr).inner.take();
467 (*ptr).dtor_state.set(DtorState::RunningOrHasRun);
474 use super::lazy::LazyKeyInner;
475 use crate::cell::Cell;
479 use crate::sys_common::thread_local_key::StaticKey as OsStaticKey;
482 // OS-TLS key that we'll use to key off.
484 marker: marker::PhantomData<Cell<T>>,
487 impl<T> fmt::Debug for Key<T> {
488 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
493 unsafe impl<T> Sync for Key<T> {}
495 struct Value<T: 'static> {
496 inner: LazyKeyInner<T>,
497 key: &'static Key<T>,
500 impl<T: 'static> Key<T> {
501 #[rustc_const_unstable(feature = "thread_local_internals", issue = "none")]
502 pub const fn new() -> Key<T> {
503 Key { os: OsStaticKey::new(Some(destroy_value::<T>)), marker: marker::PhantomData }
506 pub unsafe fn get(&'static self, init: fn() -> T) -> Option<&'static T> {
507 let ptr = self.os.get() as *mut Value<T>;
508 if ptr as usize > 1 {
509 if let Some(ref value) = (*ptr).inner.get() {
513 self.try_initialize(init)
516 // `try_initialize` is only called once per os thread local variable,
517 // except in corner cases where thread_local dtors reference other
518 // thread_local's, or it is being recursively initialized.
519 unsafe fn try_initialize(&'static self, init: fn() -> T) -> Option<&'static T> {
520 let ptr = self.os.get() as *mut Value<T>;
521 if ptr as usize == 1 {
522 // destructor is running
526 let ptr = if ptr.is_null() {
527 // If the lookup returned null, we haven't initialized our own
528 // local copy, so do that now.
529 let ptr: Box<Value<T>> = box Value { inner: LazyKeyInner::new(), key: self };
530 let ptr = Box::into_raw(ptr);
531 self.os.set(ptr as *mut u8);
534 // recursive initialization
538 Some((*ptr).inner.initialize(init))
542 unsafe extern "C" fn destroy_value<T: 'static>(ptr: *mut u8) {
543 // The OS TLS ensures that this key contains a NULL value when this
544 // destructor starts to run. We set it back to a sentinel value of 1 to
545 // ensure that any future calls to `get` for this thread will return
548 // Note that to prevent an infinite loop we reset it back to null right
549 // before we return from the destructor ourselves.
550 let ptr = Box::from_raw(ptr as *mut Value<T>);
552 key.os.set(1 as *mut u8);
554 key.os.set(ptr::null_mut());