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 pub const unsafe fn new(inner: unsafe fn() -> Option<&'static T>) -> LocalKey<T> {
232 /// Acquires a reference to the value in this TLS key.
234 /// This will lazily initialize the value if this thread has not referenced
239 /// This function will `panic!()` if the key currently has its
240 /// destructor running, and it **may** panic if the destructor has
241 /// previously been run for this thread.
242 #[stable(feature = "rust1", since = "1.0.0")]
243 pub fn with<F, R>(&'static self, f: F) -> R
247 self.try_with(f).expect(
248 "cannot access a Thread Local Storage value \
249 during or after destruction",
253 /// Acquires a reference to the value in this TLS key.
255 /// This will lazily initialize the value if this thread has not referenced
256 /// this key yet. If the key has been destroyed (which may happen if this is called
257 /// in a destructor), this function will return an [`AccessError`](struct.AccessError.html).
261 /// This function will still `panic!()` if the key is uninitialized and the
262 /// key's initializer panics.
263 #[stable(feature = "thread_local_try_with", since = "1.26.0")]
265 pub fn try_with<F, R>(&'static self, f: F) -> Result<R, AccessError>
270 let thread_local = (self.inner)().ok_or(AccessError { _private: () })?;
277 use crate::cell::UnsafeCell;
281 pub struct LazyKeyInner<T> {
282 inner: UnsafeCell<Option<T>>,
285 impl<T> LazyKeyInner<T> {
286 pub const fn new() -> LazyKeyInner<T> {
287 LazyKeyInner { inner: UnsafeCell::new(None) }
290 pub unsafe fn get(&self) -> Option<&'static T> {
291 // SAFETY: The caller must ensure no reference is ever handed out to
292 // the inner cell nor mutable reference to the Option<T> inside said
293 // cell. This make it safe to hand a reference, though the lifetime
294 // of 'static is itself unsafe, making the get method unsafe.
295 unsafe { (*self.inner.get()).as_ref() }
298 /// The caller must ensure that no reference is active: this method
299 /// needs unique access.
300 pub unsafe fn initialize<F: FnOnce() -> T>(&self, init: F) -> &'static T {
301 // Execute the initialization up front, *then* move it into our slot,
302 // just in case initialization fails.
304 let ptr = self.inner.get();
308 // note that this can in theory just be `*ptr = Some(value)`, but due to
309 // the compiler will currently codegen that pattern with something like:
311 // ptr::drop_in_place(ptr)
312 // ptr::write(ptr, Some(value))
314 // Due to this pattern it's possible for the destructor of the value in
315 // `ptr` (e.g., if this is being recursively initialized) to re-access
316 // TLS, in which case there will be a `&` and `&mut` pointer to the same
317 // value (an aliasing violation). To avoid setting the "I'm running a
318 // destructor" flag we just use `mem::replace` which should sequence the
319 // operations a little differently and make this safe to call.
321 // The precondition also ensures that we are the only one accessing
322 // `self` at the moment so replacing is fine.
324 let _ = mem::replace(&mut *ptr, Some(value));
327 // SAFETY: With the call to `mem::replace` it is guaranteed there is
328 // a `Some` behind `ptr`, not a `None` so `unreachable_unchecked`
329 // will never be reached.
331 // After storing `Some` we want to get a reference to the contents of
332 // what we just stored. While we could use `unwrap` here and it should
333 // always work it empirically doesn't seem to always get optimized away,
334 // which means that using something like `try_with` can pull in
335 // panicking code and cause a large size bloat.
338 None => hint::unreachable_unchecked(),
343 /// The other methods hand out references while taking &self.
344 /// As such, callers of this method must ensure no `&` and `&mut` are
345 /// available and used at the same time.
347 pub unsafe fn take(&mut self) -> Option<T> {
348 // SAFETY: See doc comment for this method.
349 unsafe { (*self.inner.get()).take() }
354 /// On some platforms like wasm32 there's no threads, so no need to generate
355 /// thread locals and we can instead just use plain statics!
357 #[cfg(all(target_arch = "wasm32", not(target_feature = "atomics")))]
359 use super::lazy::LazyKeyInner;
363 inner: LazyKeyInner<T>,
366 unsafe impl<T> Sync for Key<T> {}
368 impl<T> fmt::Debug for Key<T> {
369 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
375 pub const fn new() -> Key<T> {
376 Key { inner: LazyKeyInner::new() }
379 pub unsafe fn get(&self, init: fn() -> T) -> Option<&'static T> {
380 let value = match self.inner.get() {
381 Some(ref value) => value,
382 None => self.inner.initialize(init),
390 #[cfg(target_thread_local)]
392 use super::lazy::LazyKeyInner;
393 use crate::cell::Cell;
396 use crate::sys::thread_local_dtor::register_dtor;
398 #[derive(Copy, Clone)]
405 // This data structure has been carefully constructed so that the fast path
406 // only contains one branch on x86. That optimization is necessary to avoid
407 // duplicated tls lookups on OSX.
409 // LLVM issue: https://bugs.llvm.org/show_bug.cgi?id=41722
411 // If `LazyKeyInner::get` returns `None`, that indicates either:
412 // * The value has never been initialized
413 // * The value is being recursively initialized
414 // * The value has already been destroyed or is being destroyed
415 // To determine which kind of `None`, check `dtor_state`.
417 // This is very optimizer friendly for the fast path - initialized but
419 inner: LazyKeyInner<T>,
421 // Metadata to keep track of the state of the destructor. Remember that
422 // this variable is thread-local, not global.
423 dtor_state: Cell<DtorState>,
426 impl<T> fmt::Debug for Key<T> {
427 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
433 pub const fn new() -> Key<T> {
434 Key { inner: LazyKeyInner::new(), dtor_state: Cell::new(DtorState::Unregistered) }
437 pub unsafe fn get<F: FnOnce() -> T>(&self, init: F) -> Option<&'static T> {
438 // SAFETY: See the definitions of `LazyKeyInner::get` and
439 // `try_initialize` for more informations.
441 // The caller must ensure no mutable references are ever active to
442 // the inner cell or the inner T when this is called.
443 // The `try_initialize` is dependant on the passed `init` function
446 match self.inner.get() {
447 Some(val) => Some(val),
448 None => self.try_initialize(init),
453 // `try_initialize` is only called once per fast thread local variable,
454 // except in corner cases where thread_local dtors reference other
455 // thread_local's, or it is being recursively initialized.
457 // Macos: Inlining this function can cause two `tlv_get_addr` calls to
458 // be performed for every call to `Key::get`.
459 // LLVM issue: https://bugs.llvm.org/show_bug.cgi?id=41722
461 unsafe fn try_initialize<F: FnOnce() -> T>(&self, init: F) -> Option<&'static T> {
462 // SAFETY: See comment above (this function doc).
463 if !mem::needs_drop::<T>() || unsafe { self.try_register_dtor() } {
464 // SAFETY: See comment above (his function doc).
465 Some(unsafe { self.inner.initialize(init) })
471 // `try_register_dtor` is only called once per fast thread local
472 // variable, except in corner cases where thread_local dtors reference
473 // other thread_local's, or it is being recursively initialized.
474 unsafe fn try_register_dtor(&self) -> bool {
475 match self.dtor_state.get() {
476 DtorState::Unregistered => {
477 // SAFETY: dtor registration happens before initialization.
478 // Passing `self` as a pointer while using `destroy_value<T>`
479 // is safe because the function will build a pointer to a
480 // Key<T>, which is the type of self and so find the correct
482 unsafe { register_dtor(self as *const _ as *mut u8, destroy_value::<T>) };
483 self.dtor_state.set(DtorState::Registered);
486 DtorState::Registered => {
487 // recursively initialized
490 DtorState::RunningOrHasRun => false,
495 unsafe extern "C" fn destroy_value<T>(ptr: *mut u8) {
496 let ptr = ptr as *mut Key<T>;
500 // The pointer `ptr` has been built just above and comes from
501 // `try_register_dtor` where it is originally a Key<T> coming from `self`,
502 // making it non-NUL and of the correct type.
504 // Right before we run the user destructor be sure to set the
505 // `Option<T>` to `None`, and `dtor_state` to `RunningOrHasRun`. This
506 // causes future calls to `get` to run `try_initialize_drop` again,
507 // which will now fail, and return `None`.
509 let value = (*ptr).inner.take();
510 (*ptr).dtor_state.set(DtorState::RunningOrHasRun);
518 use super::lazy::LazyKeyInner;
519 use crate::cell::Cell;
523 use crate::sys_common::thread_local_key::StaticKey as OsStaticKey;
526 // OS-TLS key that we'll use to key off.
528 marker: marker::PhantomData<Cell<T>>,
531 impl<T> fmt::Debug for Key<T> {
532 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
537 unsafe impl<T> Sync for Key<T> {}
539 struct Value<T: 'static> {
540 inner: LazyKeyInner<T>,
541 key: &'static Key<T>,
544 impl<T: 'static> Key<T> {
545 pub const fn new() -> Key<T> {
546 Key { os: OsStaticKey::new(Some(destroy_value::<T>)), marker: marker::PhantomData }
549 /// It is a requirement for the caller to ensure that no mutable
550 /// reference is active when this method is called.
551 pub unsafe fn get(&'static self, init: fn() -> T) -> Option<&'static T> {
552 // SAFETY: See the documentation for this method.
553 let ptr = unsafe { self.os.get() as *mut Value<T> };
554 if ptr as usize > 1 {
555 // SAFETY: the check ensured the pointer is safe (its destructor
556 // is not running) + it is coming from a trusted source (self).
557 if let Some(ref value) = unsafe { (*ptr).inner.get() } {
561 // SAFETY: At this point we are sure we have no value and so
562 // initializing (or trying to) is safe.
563 unsafe { self.try_initialize(init) }
566 // `try_initialize` is only called once per os thread local variable,
567 // except in corner cases where thread_local dtors reference other
568 // thread_local's, or it is being recursively initialized.
569 unsafe fn try_initialize(&'static self, init: fn() -> T) -> Option<&'static T> {
570 // SAFETY: No mutable references are ever handed out meaning getting
572 let ptr = unsafe { self.os.get() as *mut Value<T> };
573 if ptr as usize == 1 {
574 // destructor is running
578 let ptr = if ptr.is_null() {
579 // If the lookup returned null, we haven't initialized our own
580 // local copy, so do that now.
581 let ptr: Box<Value<T>> = box Value { inner: LazyKeyInner::new(), key: self };
582 let ptr = Box::into_raw(ptr);
583 // SAFETY: At this point we are sure there is no value inside
584 // ptr so setting it will not affect anyone else.
586 self.os.set(ptr as *mut u8);
590 // recursive initialization
594 // SAFETY: ptr has been ensured as non-NUL just above an so can be
595 // dereferenced safely.
596 unsafe { Some((*ptr).inner.initialize(init)) }
600 unsafe extern "C" fn destroy_value<T: 'static>(ptr: *mut u8) {
603 // The OS TLS ensures that this key contains a NULL value when this
604 // destructor starts to run. We set it back to a sentinel value of 1 to
605 // ensure that any future calls to `get` for this thread will return
608 // Note that to prevent an infinite loop we reset it back to null right
609 // before we return from the destructor ourselves.
611 let ptr = Box::from_raw(ptr as *mut Value<T>);
613 key.os.set(1 as *mut u8);
615 key.os.set(ptr::null_mut());