local.rs - source
Description: Source of the Rust file `library/std/src/thread/local.rs`.

#
std/thread/
local.rs

    1//! Thread local storage
    2
    3#![unstable(feature = "thread_local_internals", issue = "none")]
    4
    5use crate::cell::{Cell, RefCell};
    6use crate::error::Error;
    7use crate::fmt;
    8
    9/// A thread local storage (TLS) key which owns its contents.
    10///
    11/// This key uses the fastest implementation available on the target platform.
    12/// It is instantiated with the [`thread_local!`] macro and the
    13/// primary method is the [`with`] method, though there are helpers to make
    14/// working with [`Cell`] types easier.
    15///
    16/// The [`with`] method yields a reference to the contained value which cannot
    17/// outlive the current thread or escape the given closure.
    18///
    19/// [`thread_local!`]: crate::thread_local
    20///
    21/// # Initialization and Destruction
    22///
    23/// Initialization is dynamically performed on the first call to a setter (e.g.
    24/// [`with`]) within a thread, and values that implement [`Drop`] get
    25/// destructed when a thread exits. Some platform-specific caveats apply, which
    26/// are explained below.
    27/// Note that, should the destructor panic, the whole process will be [aborted].
    28/// On platforms where initialization requires memory allocation, this is
    29/// performed directly through [`System`], allowing the [global allocator]
    30/// to make use of thread local storage.
    31///
    32/// A `LocalKey`'s initializer cannot recursively depend on itself. Using a
    33/// `LocalKey` in this way may cause panics, aborts, or infinite recursion on
    34/// the first call to `with`.
    35///
    36/// [`System`]: crate::alloc::System
    37/// [global allocator]: crate::alloc
    38/// [aborted]: crate::process::abort
    39///
    40/// # Single-thread Synchronization
    41///
    42/// Though there is no potential race with other threads, it is still possible to
    43/// obtain multiple references to the thread-local data in different places on
    44/// the call stack. For this reason, only shared (`&T`) references may be obtained.
    45///
    46/// To allow obtaining an exclusive mutable reference (`&mut T`), typically a
    47/// [`Cell`] or [`RefCell`] is used (see the [`std::cell`] for more information
    48/// on how exactly this works). To make this easier there are specialized
    49/// implementations for [`LocalKey<Cell<T>>`] and [`LocalKey<RefCell<T>>`].
    50///
    51/// [`std::cell`]: `crate::cell`
    52/// [`LocalKey<Cell<T>>`]: struct.LocalKey.html#impl-LocalKey<Cell<T>>
    53/// [`LocalKey<RefCell<T>>`]: struct.LocalKey.html#impl-LocalKey<RefCell<T>>
    54///
    55///
    56/// # Examples
    57///
    58/// ```
    59/// use std::cell::Cell;
    60/// use std::thread;
    61///
    62/// // explicit `const {}` block enables more efficient initialization
    63/// thread_local!(static FOO: Cell<u32> = const { Cell::new(1) });
    64///
    65/// assert_eq!(FOO.get(), 1);
    66/// FOO.set(2);
    67///
    68/// // each thread starts out with the initial value of 1
    69/// let t = thread::spawn(move || {
    70///     assert_eq!(FOO.get(), 1);
    71///     FOO.set(3);
    72/// });
    73///
    74/// // wait for the thread to complete and bail out on panic
    75/// t.join().unwrap();
    76///
    77/// // we retain our original value of 2 despite the child thread
    78/// assert_eq!(FOO.get(), 2);
    79/// ```
    80///
    81/// # Platform-specific behavior
    82///
    83/// Note that a "best effort" is made to ensure that destructors for types
    84/// stored in thread local storage are run, but not all platforms can guarantee
    85/// that destructors will be run for all types in thread local storage. For
    86/// example, there are a number of known caveats where destructors are not run:
    87///
    88/// 1. On Unix systems when pthread-based TLS is being used, destructors will
    89///    not be run for TLS values on the main thread when it exits. Note that the
    90///    application will exit immediately after the main thread exits as well.
    91/// 2. On all platforms it's possible for TLS to re-initialize other TLS slots
    92///    during destruction. Some platforms ensure that this cannot happen
    93///    infinitely by preventing re-initialization of any slot that has been
    94///    destroyed, but not all platforms have this guard. Those platforms that do
    95///    not guard typically have a synthetic limit after which point no more
    96///    destructors are run.
    97/// 3. When the process exits on Windows systems, TLS destructors may only be
    98///    run on the thread that causes the process to exit. This is because the
    99///    other threads may be forcibly terminated.
    100///
    101/// ## Synchronization in thread-local destructors
    102///
    103/// On Windows, synchronization operations (such as [`JoinHandle::join`]) in
    104/// thread local destructors are prone to deadlocks and so should be avoided.
    105/// This is because the [loader lock] is held while a destructor is run. The
    106/// lock is acquired whenever a thread starts or exits or when a DLL is loaded
    107/// or unloaded. Therefore these events are blocked for as long as a thread
    108/// local destructor is running.
    109///
    110/// [loader lock]: https://docs.microsoft.com/en-us/windows/win32/dlls/dynamic-link-library-best-practices
    111/// [`JoinHandle::join`]: crate::thread::JoinHandle::join
    112/// [`with`]: LocalKey::with
    113#[cfg_attr(not(test), rustc_diagnostic_item = "LocalKey")]
    114#[stable(feature = "rust1", since = "1.0.0")]
    115pub struct LocalKey<T: 'static> {
    116    // This outer `LocalKey<T>` type is what's going to be stored in statics,
    117    // but actual data inside will sometimes be tagged with #[thread_local].
    118    // It's not valid for a true static to reference a #[thread_local] static,
    119    // so we get around that by exposing an accessor through a layer of function
    120    // indirection (this thunk).
    121    //
    122    // Note that the thunk is itself unsafe because the returned lifetime of the
    123    // slot where data lives, `'static`, is not actually valid. The lifetime
    124    // here is actually slightly shorter than the currently running thread!
    125    //
    126    // Although this is an extra layer of indirection, it should in theory be
    127    // trivially devirtualizable by LLVM because the value of `inner` never
    128    // changes and the constant should be readonly within a crate. This mainly
    129    // only runs into problems when TLS statics are exported across crates.
    130    inner: fn(Option<&mut Option<T>>) -> *const T,
    131}
    132
    133#[stable(feature = "std_debug", since = "1.16.0")]
    134impl<T: 'static> fmt::Debug for LocalKey<T> {
    135    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
    136        f.debug_struct("LocalKey").finish_non_exhaustive()
    137    }
    138}
    139
    140#[doc(hidden)]
    141#[allow_internal_unstable(thread_local_internals)]
    142#[unstable(feature = "thread_local_internals", issue = "none")]
    143#[rustc_macro_transparency = "semiopaque"]
    144pub macro thread_local_process_attrs {
    145
    146    // Parse `cfg_attr` to figure out whether it's a `rustc_align_static`.
    147    // Each `cfg_attr` can have zero or more attributes on the RHS, and can be nested.
    148
    149    // finished parsing the `cfg_attr`, it had no `rustc_align_static`
    150    (
    151        [] [$(#[$($prev_other_attrs:tt)*])*];
    152        @processing_cfg_attr { pred: ($($predicate:tt)*), rhs: [] };
    153        [$($prev_align_attrs_ret:tt)*] [$($prev_other_attrs_ret:tt)*];
    154        $($rest:tt)*
    155    ) => (
    156        $crate::thread::local_impl::thread_local_process_attrs!(
    157            [$($prev_align_attrs_ret)*] [$($prev_other_attrs_ret)* #[cfg_attr($($predicate)*, $($($prev_other_attrs)*),*)]];
    158            $($rest)*
    159        );
    160    ),
    161
    162    // finished parsing the `cfg_attr`, it had nothing but `rustc_align_static`
    163    (
    164        [$(#[$($prev_align_attrs:tt)*])+] [];
    165        @processing_cfg_attr { pred: ($($predicate:tt)*), rhs: [] };
    166        [$($prev_align_attrs_ret:tt)*] [$($prev_other_attrs_ret:tt)*];
    167        $($rest:tt)*
    168    ) => (
    169        $crate::thread::local_impl::thread_local_process_attrs!(
    170            [$($prev_align_attrs_ret)*  #[cfg_attr($($predicate)*, $($($prev_align_attrs)*),+)]] [$($prev_other_attrs_ret)*];
    171            $($rest)*
    172        );
    173    ),
    174
    175    // finished parsing the `cfg_attr`, it had a mix of `rustc_align_static` and other attrs
    176    (
    177        [$(#[$($prev_align_attrs:tt)*])+] [$(#[$($prev_other_attrs:tt)*])+];
    178        @processing_cfg_attr { pred: ($($predicate:tt)*), rhs: [] };
    179        [$($prev_align_attrs_ret:tt)*] [$($prev_other_attrs_ret:tt)*];
    180        $($rest:tt)*
    181    ) => (
    182        $crate::thread::local_impl::thread_local_process_attrs!(
    183            [$($prev_align_attrs_ret)*  #[cfg_attr($($predicate)*, $($($prev_align_attrs)*),+)]] [$($prev_other_attrs_ret)* #[cfg_attr($($predicate)*, $($($prev_other_attrs)*),+)]];
    184            $($rest)*
    185        );
    186    ),
    187
    188    // it's a `rustc_align_static`
    189    (
    190        [$($prev_align_attrs:tt)*] [$($prev_other_attrs:tt)*];
    191        @processing_cfg_attr { pred: ($($predicate:tt)*), rhs: [rustc_align_static($($align_static_args:tt)*) $(, $($attr_rhs:tt)*)?] };
    192        $($rest:tt)*
    193    ) => (
    194        $crate::thread::local_impl::thread_local_process_attrs!(
    195            [$($prev_align_attrs)* #[rustc_align_static($($align_static_args)*)]] [$($prev_other_attrs)*];
    196            @processing_cfg_attr { pred: ($($predicate)*), rhs: [$($($attr_rhs)*)?] };
    197            $($rest)*
    198        );
    199    ),
    200
    201    // it's a nested `cfg_attr(true, ...)`; recurse into RHS
    202    (
    203        [$($prev_align_attrs:tt)*] [$($prev_other_attrs:tt)*];
    204        @processing_cfg_attr { pred: ($($predicate:tt)*), rhs: [cfg_attr(true, $($cfg_rhs:tt)*) $(, $($attr_rhs:tt)*)?] };
    205        $($rest:tt)*
    206    ) => (
    207        $crate::thread::local_impl::thread_local_process_attrs!(
    208            [] [];
    209            @processing_cfg_attr { pred: (true), rhs: [$($cfg_rhs)*] };
    210            [$($prev_align_attrs)*] [$($prev_other_attrs)*];
    211            @processing_cfg_attr { pred: ($($predicate)*), rhs: [$($($attr_rhs)*)?] };
    212            $($rest)*
    213        );
    214    ),
    215
    216    // it's a nested `cfg_attr(false, ...)`; recurse into RHS
    217    (
    218        [$($prev_align_attrs:tt)*] [$($prev_other_attrs:tt)*];
    219        @processing_cfg_attr { pred: ($($predicate:tt)*), rhs: [cfg_attr(false, $($cfg_rhs:tt)*) $(, $($attr_rhs:tt)*)?] };
    220        $($rest:tt)*
    221    ) => (
    222        $crate::thread::local_impl::thread_local_process_attrs!(
    223            [] [];
    224            @processing_cfg_attr { pred: (false), rhs: [$($cfg_rhs)*] };
    225            [$($prev_align_attrs)*] [$($prev_other_attrs)*];
    226            @processing_cfg_attr { pred: ($($predicate)*), rhs: [$($($attr_rhs)*)?] };
    227            $($rest)*
    228        );
    229    ),
    230
    231
    232    // it's a nested `cfg_attr(..., ...)`; recurse into RHS
    233    (
    234        [$($prev_align_attrs:tt)*] [$($prev_other_attrs:tt)*];
    235        @processing_cfg_attr { pred: ($($predicate:tt)*), rhs: [cfg_attr($cfg_lhs:meta, $($cfg_rhs:tt)*) $(, $($attr_rhs:tt)*)?] };
    236        $($rest:tt)*
    237    ) => (
    238        $crate::thread::local_impl::thread_local_process_attrs!(
    239            [] [];
    240            @processing_cfg_attr { pred: ($cfg_lhs), rhs: [$($cfg_rhs)*] };
    241            [$($prev_align_attrs)*] [$($prev_other_attrs)*];
    242            @processing_cfg_attr { pred: ($($predicate)*), rhs: [$($($attr_rhs)*)?] };
    243            $($rest)*
    244        );
    245    ),
    246
    247    // it's some other attribute
    248    (
    249        [$($prev_align_attrs:tt)*] [$($prev_other_attrs:tt)*];
    250        @processing_cfg_attr { pred: ($($predicate:tt)*), rhs: [$meta:meta $(, $($attr_rhs:tt)*)?] };
    251        $($rest:tt)*
    252    ) => (
    253        $crate::thread::local_impl::thread_local_process_attrs!(
    254            [$($prev_align_attrs)*] [$($prev_other_attrs)* #[$meta]];
    255            @processing_cfg_attr { pred: ($($predicate)*), rhs: [$($($attr_rhs)*)?] };
    256            $($rest)*
    257        );
    258    ),
    259
    260
    261    // Separate attributes into `rustc_align_static` and everything else:
    262
    263    // `rustc_align_static` attribute
    264    ([$($prev_align_attrs:tt)*] [$($prev_other_attrs:tt)*]; #[rustc_align_static $($attr_rest:tt)*] $($rest:tt)*) => (
    265        $crate::thread::local_impl::thread_local_process_attrs!(
    266            [$($prev_align_attrs)* #[rustc_align_static $($attr_rest)*]] [$($prev_other_attrs)*];
    267            $($rest)*
    268        );
    269    ),
    270
    271    // `cfg_attr(true, ...)` attribute; parse it
    272    ([$($prev_align_attrs:tt)*] [$($prev_other_attrs:tt)*]; #[cfg_attr(true, $($cfg_rhs:tt)*)] $($rest:tt)*) => (
    273        $crate::thread::local_impl::thread_local_process_attrs!(
    274            [] [];
    275            @processing_cfg_attr { pred: (true), rhs: [$($cfg_rhs)*] };
    276            [$($prev_align_attrs)*] [$($prev_other_attrs)*];
    277            $($rest)*
    278        );
    279    ),
    280
    281    // `cfg_attr(false, ...)` attribute; parse it
    282    ([$($prev_align_attrs:tt)*] [$($prev_other_attrs:tt)*]; #[cfg_attr(false, $($cfg_rhs:tt)*)] $($rest:tt)*) => (
    283        $crate::thread::local_impl::thread_local_process_attrs!(
    284            [] [];
    285            @processing_cfg_attr { pred: (false), rhs: [$($cfg_rhs)*] };
    286            [$($prev_align_attrs)*] [$($prev_other_attrs)*];
    287            $($rest)*
    288        );
    289    ),
    290
    291    // `cfg_attr(..., ...)` attribute; parse it
    292    ([$($prev_align_attrs:tt)*] [$($prev_other_attrs:tt)*]; #[cfg_attr($cfg_pred:meta, $($cfg_rhs:tt)*)] $($rest:tt)*) => (
    293        $crate::thread::local_impl::thread_local_process_attrs!(
    294            [] [];
    295            @processing_cfg_attr { pred: ($cfg_pred), rhs: [$($cfg_rhs)*] };
    296            [$($prev_align_attrs)*] [$($prev_other_attrs)*];
    297            $($rest)*
    298        );
    299    ),
    300
    301    // doc comment not followed by any other attributes; process it all at once to avoid blowing recursion limit
    302    ([$($prev_align_attrs:tt)*] [$($prev_other_attrs:tt)*]; $(#[doc $($doc_rhs:tt)*])+ $vis:vis static $($rest:tt)*) => (
    303        $crate::thread::local_impl::thread_local_process_attrs!(
    304            [$($prev_align_attrs)*] [$($prev_other_attrs)* $(#[doc $($doc_rhs)*])+];
    305            $vis static $($rest)*
    306        );
    307    ),
    308
    309    // 8 lines of doc comment; process them all at once to avoid blowing recursion limit
    310    ([$($prev_align_attrs:tt)*] [$($prev_other_attrs:tt)*];
    311     #[doc $($doc_rhs_1:tt)*] #[doc $($doc_rhs_2:tt)*] #[doc $($doc_rhs_3:tt)*] #[doc $($doc_rhs_4:tt)*]
    312     #[doc $($doc_rhs_5:tt)*] #[doc $($doc_rhs_6:tt)*] #[doc $($doc_rhs_7:tt)*] #[doc $($doc_rhs_8:tt)*]
    313     $($rest:tt)*) => (
    314        $crate::thread::local_impl::thread_local_process_attrs!(
    315            [$($prev_align_attrs)*] [$($prev_other_attrs)*
    316            #[doc $($doc_rhs_1)*] #[doc $($doc_rhs_2)*] #[doc $($doc_rhs_3)*] #[doc $($doc_rhs_4)*]
    317            #[doc $($doc_rhs_5)*] #[doc $($doc_rhs_6)*] #[doc $($doc_rhs_7)*] #[doc $($doc_rhs_8)*]];
    318            $($rest)*
    319        );
    320    ),
    321
    322    // other attribute
    323    ([$($prev_align_attrs:tt)*] [$($prev_other_attrs:tt)*]; #[$($attr:tt)*] $($rest:tt)*) => (
    324        $crate::thread::local_impl::thread_local_process_attrs!(
    325            [$($prev_align_attrs)*] [$($prev_other_attrs)* #[$($attr)*]];
    326            $($rest)*
    327        );
    328    ),
    329
    330
    331    // Delegate to `thread_local_inner` once attributes are fully categorized:
    332
    333    // process `const` declaration and recurse
    334    ([$($align_attrs:tt)*] [$($other_attrs:tt)*]; $vis:vis static $name:ident: $t:ty = const $init:block $(; $($($rest:tt)+)?)?) => (
    335        $($other_attrs)* $vis const $name: $crate::thread::LocalKey<$t> =
    336            $crate::thread::local_impl::thread_local_inner!(@key $t, $($align_attrs)*, const $init);
    337
    338        $($($crate::thread::local_impl::thread_local_process_attrs!([] []; $($rest)+);)?)?
    339    ),
    340
    341    // process non-`const` declaration and recurse
    342    ([$($align_attrs:tt)*] [$($other_attrs:tt)*]; $vis:vis static $name:ident: $t:ty = $init:expr $(; $($($rest:tt)+)?)?) => (
    343        $($other_attrs)* $vis const $name: $crate::thread::LocalKey<$t> =
    344            $crate::thread::local_impl::thread_local_inner!(@key $t, $($align_attrs)*, $init);
    345
    346        $($($crate::thread::local_impl::thread_local_process_attrs!([] []; $($rest)+);)?)?
    347    ),
    348}
    349
    350/// Declare a new thread local storage key of type [`std::thread::LocalKey`].
    351///
    352/// # Syntax
    353///
    354/// The macro wraps any number of static declarations and makes them thread local.
    355/// Publicity and attributes for each static are allowed. Example:
    356///
    357/// ```
    358/// use std::cell::{Cell, RefCell};
    359///
    360/// thread_local! {
    361///     pub static FOO: Cell<u32> = const { Cell::new(1) };
    362///
    363///     static BAR: RefCell<Vec<f32>> = RefCell::new(vec![1.0, 2.0]);
    364/// }
    365///
    366/// assert_eq!(FOO.get(), 1);
    367/// BAR.with_borrow(|v| assert_eq!(v[1], 2.0));
    368/// ```
    369///
    370/// Note that only shared references (`&T`) to the inner data may be obtained, so a
    371/// type such as [`Cell`] or [`RefCell`] is typically used to allow mutating access.
    372///
    373/// This macro supports a special `const {}` syntax that can be used
    374/// when the initialization expression can be evaluated as a constant.
    375/// This can enable a more efficient thread local implementation that
    376/// can avoid lazy initialization. For types that do not
    377/// [need to be dropped][crate::mem::needs_drop], this can enable an
    378/// even more efficient implementation that does not need to
    379/// track any additional state.
    380///
    381/// ```
    382/// use std::cell::RefCell;
    383///
    384/// thread_local! {
    385///     pub static FOO: RefCell<Vec<u32>> = const { RefCell::new(Vec::new()) };
    386/// }
    387///
    388/// FOO.with_borrow(|v| assert_eq!(v.len(), 0));
    389/// ```
    390///
    391/// See [`LocalKey` documentation][`std::thread::LocalKey`] for more
    392/// information.
    393///
    394/// [`std::thread::LocalKey`]: crate::thread::LocalKey
    395#[macro_export]
    396#[stable(feature = "rust1", since = "1.0.0")]
    397#[cfg_attr(not(test), rustc_diagnostic_item = "thread_local_macro")]
    398#[allow_internal_unstable(thread_local_internals)]
    399macro_rules! thread_local {
    400    () => {};
    401
    402    ($($tt:tt)+) => {
    403        $crate::thread::local_impl::thread_local_process_attrs!([] []; $($tt)+);
    404    };
    405}
    406
    407/// An error returned by [`LocalKey::try_with`](struct.LocalKey.html#method.try_with).
    408#[stable(feature = "thread_local_try_with", since = "1.26.0")]
    409#[non_exhaustive]
    410#[derive(Clone, Copy, Eq, PartialEq)]
    411pub struct AccessError;
    412
    413#[stable(feature = "thread_local_try_with", since = "1.26.0")]
    414impl fmt::Debug for AccessError {
    415    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
    416        f.debug_struct("AccessError").finish()
    417    }
    418}
    419
    420#[stable(feature = "thread_local_try_with", since = "1.26.0")]
    421impl fmt::Display for AccessError {
    422    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
    423        fmt::Display::fmt("already destroyed", f)
    424    }
    425}
    426
    427#[stable(feature = "thread_local_try_with", since = "1.26.0")]
    428impl Error for AccessError {}
    429
    430// This ensures the panicking code is outlined from `with` for `LocalKey`.
    431#[cfg_attr(not(panic = "immediate-abort"), inline(never))]
    432#[track_caller]
    433#[cold]
    434fn panic_access_error(err: AccessError) -> ! {
    435    panic!("cannot access a Thread Local Storage value during or after destruction: {err:?}")
    436}
    437
    438impl<T: 'static> LocalKey<T> {
    439    #[doc(hidden)]
    440    #[unstable(
    441        feature = "thread_local_internals",
    442        reason = "recently added to create a key",
    443        issue = "none"
    444    )]
    445    pub const unsafe fn new(inner: fn(Option<&mut Option<T>>) -> *const T) -> LocalKey<T> {
    446        LocalKey { inner }
    447    }
    448
    449    /// Acquires a reference to the value in this TLS key.
    450    ///
    451    /// This will lazily initialize the value if this thread has not referenced
    452    /// this key yet.
    453    ///
    454    /// # Panics
    455    ///
    456    /// This function will `panic!()` if the key currently has its
    457    /// destructor running, and it **may** panic if the destructor has
    458    /// previously been run for this thread.
    459    ///
    460    /// # Examples
    461    ///
    462    /// ```
    463    /// thread_local! {
    464    ///     pub static STATIC: String = String::from("I am");
    465    /// }
    466    ///
    467    /// assert_eq!(
    468    ///     STATIC.with(|original_value| format!("{original_value} initialized")),
    469    ///     "I am initialized",
    470    /// );
    471    /// ```
    472    #[stable(feature = "rust1", since = "1.0.0")]
    473    pub fn with<F, R>(&'static self, f: F) -> R
    474    where
    475        F: FnOnce(&T) -> R,
    476    {
    477        match self.try_with(f) {
    478            Ok(r) => r,
    479            Err(err) => panic_access_error(err),
    480        }
    481    }
    482
    483    /// Acquires a reference to the value in this TLS key.
    484    ///
    485    /// This will lazily initialize the value if this thread has not referenced
    486    /// this key yet. If the key has been destroyed (which may happen if this is called
    487    /// in a destructor), this function will return an [`AccessError`].
    488    ///
    489    /// # Panics
    490    ///
    491    /// This function will still `panic!()` if the key is uninitialized and the
    492    /// key's initializer panics.
    493    ///
    494    /// # Examples
    495    ///
    496    /// ```
    497    /// thread_local! {
    498    ///     pub static STATIC: String = String::from("I am");
    499    /// }
    500    ///
    501    /// assert_eq!(
    502    ///     STATIC.try_with(|original_value| format!("{original_value} initialized")),
    503    ///     Ok(String::from("I am initialized")),
    504    /// );
    505    /// ```
    506    #[stable(feature = "thread_local_try_with", since = "1.26.0")]
    507    #[inline]
    508    pub fn try_with<F, R>(&'static self, f: F) -> Result<R, AccessError>
    509    where
    510        F: FnOnce(&T) -> R,
    511    {
    512        let thread_local = unsafe { (self.inner)(None).as_ref().ok_or(AccessError)? };
    513        Ok(f(thread_local))
    514    }
    515
    516    /// Acquires a reference to the value in this TLS key, initializing it with
    517    /// `init` if it wasn't already initialized on this thread.
    518    ///
    519    /// If `init` was used to initialize the thread local variable, `None` is
    520    /// passed as the first argument to `f`. If it was already initialized,
    521    /// `Some(init)` is passed to `f`.
    522    ///
    523    /// # Panics
    524    ///
    525    /// This function will panic if the key currently has its destructor
    526    /// running, and it **may** panic if the destructor has previously been run
    527    /// for this thread.
    528    fn initialize_with<F, R>(&'static self, init: T, f: F) -> R
    529    where
    530        F: FnOnce(Option<T>, &T) -> R,
    531    {
    532        let mut init = Some(init);
    533
    534        let reference = unsafe {
    535            match (self.inner)(Some(&mut init)).as_ref() {
    536                Some(r) => r,
    537                None => panic_access_error(AccessError),
    538            }
    539        };
    540
    541        f(init, reference)
    542    }
    543}
    544
    545impl<T: 'static> LocalKey<Cell<T>> {
    546    /// Sets or initializes the contained value.
    547    ///
    548    /// Unlike the other methods, this will *not* run the lazy initializer of
    549    /// the thread local. Instead, it will be directly initialized with the
    550    /// given value if it wasn't initialized yet.
    551    ///
    552    /// # Panics
    553    ///
    554    /// Panics if the key currently has its destructor running,
    555    /// and it **may** panic if the destructor has previously been run for this thread.
    556    ///
    557    /// # Examples
    558    ///
    559    /// ```
    560    /// use std::cell::Cell;
    561    ///
    562    /// thread_local! {
    563    ///     static X: Cell<i32> = panic!("!");
    564    /// }
    565    ///
    566    /// // Calling X.get() here would result in a panic.
    567    ///
    568    /// X.set(123); // But X.set() is fine, as it skips the initializer above.
    569    ///
    570    /// assert_eq!(X.get(), 123);
    571    /// ```
    572    #[stable(feature = "local_key_cell_methods", since = "1.73.0")]
    573    pub fn set(&'static self, value: T) {
    574        self.initialize_with(Cell::new(value), |value, cell| {
    575            if let Some(value) = value {
    576                // The cell was already initialized, so `value` wasn't used to
    577                // initialize it. So we overwrite the current value with the
    578                // new one instead.
    579                cell.set(value.into_inner());
    580            }
    581        });
    582    }
    583
    584    /// Returns a copy of the contained value.
    585    ///
    586    /// This will lazily initialize the value if this thread has not referenced
    587    /// this key yet.
    588    ///
    589    /// # Panics
    590    ///
    591    /// Panics if the key currently has its destructor running,
    592    /// and it **may** panic if the destructor has previously been run for this thread.
    593    ///
    594    /// # Examples
    595    ///
    596    /// ```
    597    /// use std::cell::Cell;
    598    ///
    599    /// thread_local! {
    600    ///     static X: Cell<i32> = const { Cell::new(1) };
    601    /// }
    602    ///
    603    /// assert_eq!(X.get(), 1);
    604    /// ```
    605    #[stable(feature = "local_key_cell_methods", since = "1.73.0")]
    606    pub fn get(&'static self) -> T
    607    where
    608        T: Copy,
    609    {
    610        self.with(Cell::get)
    611    }
    612
    613    /// Takes the contained value, leaving `Default::default()` in its place.
    614    ///
    615    /// This will lazily initialize the value if this thread has not referenced
    616    /// this key yet.
    617    ///
    618    /// # Panics
    619    ///
    620    /// Panics if the key currently has its destructor running,
    621    /// and it **may** panic if the destructor has previously been run for this thread.
    622    ///
    623    /// # Examples
    624    ///
    625    /// ```
    626    /// use std::cell::Cell;
    627    ///
    628    /// thread_local! {
    629    ///     static X: Cell<Option<i32>> = const { Cell::new(Some(1)) };
    630    /// }
    631    ///
    632    /// assert_eq!(X.take(), Some(1));
    633    /// assert_eq!(X.take(), None);
    634    /// ```
    635    #[stable(feature = "local_key_cell_methods", since = "1.73.0")]
    636    pub fn take(&'static self) -> T
    637    where
    638        T: Default,
    639    {
    640        self.with(Cell::take)
    641    }
    642
    643    /// Replaces the contained value, returning the old value.
    644    ///
    645    /// This will lazily initialize the value if this thread has not referenced
    646    /// this key yet.
    647    ///
    648    /// # Panics
    649    ///
    650    /// Panics if the key currently has its destructor running,
    651    /// and it **may** panic if the destructor has previously been run for this thread.
    652    ///
    653    /// # Examples
    654    ///
    655    /// ```
    656    /// use std::cell::Cell;
    657    ///
    658    /// thread_local! {
    659    ///     static X: Cell<i32> = const { Cell::new(1) };
    660    /// }
    661    ///
    662    /// assert_eq!(X.replace(2), 1);
    663    /// assert_eq!(X.replace(3), 2);
    664    /// ```
    665    #[stable(feature = "local_key_cell_methods", since = "1.73.0")]
    666    #[rustc_confusables("swap")]
    667    pub fn replace(&'static self, value: T) -> T {
    668        self.with(|cell| cell.replace(value))
    669    }
    670
    671    /// Updates the contained value using a function.
    672    ///
    673    /// # Examples
    674    ///
    675    /// ```
    676    /// #![feature(local_key_cell_update)]
    677    /// use std::cell::Cell;
    678    ///
    679    /// thread_local! {
    680    ///     static X: Cell<i32> = const { Cell::new(5) };
    681    /// }
    682    ///
    683    /// X.update(|x| x + 1);
    684    /// assert_eq!(X.get(), 6);
    685    /// ```
    686    #[unstable(feature = "local_key_cell_update", issue = "143989")]
    687    pub fn update(&'static self, f: impl FnOnce(T) -> T)
    688    where
    689        T: Copy,
    690    {
    691        self.with(|cell| cell.update(f))
    692    }
    693}
    694
    695impl<T: 'static> LocalKey<RefCell<T>> {
    696    /// Acquires a reference to the contained value.
    697    ///
    698    /// This will lazily initialize the value if this thread has not referenced
    699    /// this key yet.
    700    ///
    701    /// # Panics
    702    ///
    703    /// Panics if the value is currently mutably borrowed.
    704    ///
    705    /// Panics if the key currently has its destructor running,
    706    /// and it **may** panic if the destructor has previously been run for this thread.
    707    ///
    708    /// # Examples
    709    ///
    710    /// ```
    711    /// use std::cell::RefCell;
    712    ///
    713    /// thread_local! {
    714    ///     static X: RefCell<Vec<i32>> = RefCell::new(Vec::new());
    715    /// }
    716    ///
    717    /// X.with_borrow(|v| assert!(v.is_empty()));
    718    /// ```
    719    #[stable(feature = "local_key_cell_methods", since = "1.73.0")]
    720    pub fn with_borrow<F, R>(&'static self, f: F) -> R
    721    where
    722        F: FnOnce(&T) -> R,
    723    {
    724        self.with(|cell| f(&cell.borrow()))
    725    }
    726
    727    /// Acquires a mutable reference to the contained value.
    728    ///
    729    /// This will lazily initialize the value if this thread has not referenced
    730    /// this key yet.
    731    ///
    732    /// # Panics
    733    ///
    734    /// Panics if the value is currently borrowed.
    735    ///
    736    /// Panics if the key currently has its destructor running,
    737    /// and it **may** panic if the destructor has previously been run for this thread.
    738    ///
    739    /// # Examples
    740    ///
    741    /// ```
    742    /// use std::cell::RefCell;
    743    ///
    744    /// thread_local! {
    745    ///     static X: RefCell<Vec<i32>> = RefCell::new(Vec::new());
    746    /// }
    747    ///
    748    /// X.with_borrow_mut(|v| v.push(1));
    749    ///
    750    /// X.with_borrow(|v| assert_eq!(*v, vec![1]));
    751    /// ```
    752    #[stable(feature = "local_key_cell_methods", since = "1.73.0")]
    753    pub fn with_borrow_mut<F, R>(&'static self, f: F) -> R
    754    where
    755        F: FnOnce(&mut T) -> R,
    756    {
    757        self.with(|cell| f(&mut cell.borrow_mut()))
    758    }
    759
    760    /// Sets or initializes the contained value.
    761    ///
    762    /// Unlike the other methods, this will *not* run the lazy initializer of
    763    /// the thread local. Instead, it will be directly initialized with the
    764    /// given value if it wasn't initialized yet.
    765    ///
    766    /// # Panics
    767    ///
    768    /// Panics if the value is currently borrowed.
    769    ///
    770    /// Panics if the key currently has its destructor running,
    771    /// and it **may** panic if the destructor has previously been run for this thread.
    772    ///
    773    /// # Examples
    774    ///
    775    /// ```
    776    /// use std::cell::RefCell;
    777    ///
    778    /// thread_local! {
    779    ///     static X: RefCell<Vec<i32>> = panic!("!");
    780    /// }
    781    ///
    782    /// // Calling X.with() here would result in a panic.
    783    ///
    784    /// X.set(vec![1, 2, 3]); // But X.set() is fine, as it skips the initializer above.
    785    ///
    786    /// X.with_borrow(|v| assert_eq!(*v, vec![1, 2, 3]));
    787    /// ```
    788    #[stable(feature = "local_key_cell_methods", since = "1.73.0")]
    789    pub fn set(&'static self, value: T) {
    790        self.initialize_with(RefCell::new(value), |value, cell| {
    791            if let Some(value) = value {
    792                // The cell was already initialized, so `value` wasn't used to
    793                // initialize it. So we overwrite the current value with the
    794                // new one instead.
    795                *cell.borrow_mut() = value.into_inner();
    796            }
    797        });
    798    }
    799
    800    /// Takes the contained value, leaving `Default::default()` in its place.
    801    ///
    802    /// This will lazily initialize the value if this thread has not referenced
    803    /// this key yet.
    804    ///
    805    /// # Panics
    806    ///
    807    /// Panics if the value is currently borrowed.
    808    ///
    809    /// Panics if the key currently has its destructor running,
    810    /// and it **may** panic if the destructor has previously been run for this thread.
    811    ///
    812    /// # Examples
    813    ///
    814    /// ```
    815    /// use std::cell::RefCell;
    816    ///
    817    /// thread_local! {
    818    ///     static X: RefCell<Vec<i32>> = RefCell::new(Vec::new());
    819    /// }
    820    ///
    821    /// X.with_borrow_mut(|v| v.push(1));
    822    ///
    823    /// let a = X.take();
    824    ///
    825    /// assert_eq!(a, vec![1]);
    826    ///
    827    /// X.with_borrow(|v| assert!(v.is_empty()));
    828    /// ```
    829    #[stable(feature = "local_key_cell_methods", since = "1.73.0")]
    830    pub fn take(&'static self) -> T
    831    where
    832        T: Default,
    833    {
    834        self.with(RefCell::take)
    835    }
    836
    837    /// Replaces the contained value, returning the old value.
    838    ///
    839    /// # Panics
    840    ///
    841    /// Panics if the value is currently borrowed.
    842    ///
    843    /// Panics if the key currently has its destructor running,
    844    /// and it **may** panic if the destructor has previously been run for this thread.
    845    ///
    846    /// # Examples
    847    ///
    848    /// ```
    849    /// use std::cell::RefCell;
    850    ///
    851    /// thread_local! {
    852    ///     static X: RefCell<Vec<i32>> = RefCell::new(Vec::new());
    853    /// }
    854    ///
    855    /// let prev = X.replace(vec![1, 2, 3]);
    856    /// assert!(prev.is_empty());
    857    ///
    858    /// X.with_borrow(|v| assert_eq!(*v, vec![1, 2, 3]));
    859    /// ```
    860    #[stable(feature = "local_key_cell_methods", since = "1.73.0")]
    861    #[rustc_confusables("swap")]
    862    pub fn replace(&'static self, value: T) -> T {
    863        self.with(|cell| cell.replace(value))
    864    }
    865}