core/cell/
lazy.rs

1use super::UnsafeCell;
2use crate::hint::unreachable_unchecked;
3use crate::ops::{Deref, DerefMut};
4use crate::{fmt, mem};
5
6enum State<T, F> {
7    Uninit(F),
8    Init(T),
9    Poisoned,
10}
11
12/// A value which is initialized on the first access.
13///
14/// For a thread-safe version of this struct, see [`std::sync::LazyLock`].
15///
16/// [`std::sync::LazyLock`]: ../../std/sync/struct.LazyLock.html
17///
18/// # Poisoning
19///
20/// If the initialization closure passed to [`LazyCell::new`] panics, the cell will be poisoned.
21/// Once the cell is poisoned, any threads that attempt to access this cell (via a dereference
22/// or via an explicit call to [`force()`]) will panic.
23///
24/// This concept is similar to that of poisoning in the [`std::sync::poison`] module. A key
25/// difference, however, is that poisoning in `LazyCell` is _unrecoverable_. All future accesses of
26/// the cell from other threads will panic, whereas a type in [`std::sync::poison`] like
27/// [`std::sync::poison::Mutex`] allows recovery via [`PoisonError::into_inner()`].
28///
29/// [`force()`]: LazyCell::force
30/// [`std::sync::poison`]: ../../std/sync/poison/index.html
31/// [`std::sync::poison::Mutex`]: ../../std/sync/poison/struct.Mutex.html
32/// [`PoisonError::into_inner()`]: ../../std/sync/poison/struct.PoisonError.html#method.into_inner
33///
34/// # Examples
35///
36/// ```
37/// use std::cell::LazyCell;
38///
39/// let lazy: LazyCell<i32> = LazyCell::new(|| {
40///     println!("initializing");
41///     92
42/// });
43/// println!("ready");
44/// println!("{}", *lazy);
45/// println!("{}", *lazy);
46///
47/// // Prints:
48/// //   ready
49/// //   initializing
50/// //   92
51/// //   92
52/// ```
53#[stable(feature = "lazy_cell", since = "1.80.0")]
54pub struct LazyCell<T, F = fn() -> T> {
55    state: UnsafeCell<State<T, F>>,
56}
57
58impl<T, F: FnOnce() -> T> LazyCell<T, F> {
59    /// Creates a new lazy value with the given initializing function.
60    ///
61    /// # Examples
62    ///
63    /// ```
64    /// use std::cell::LazyCell;
65    ///
66    /// let hello = "Hello, World!".to_string();
67    ///
68    /// let lazy = LazyCell::new(|| hello.to_uppercase());
69    ///
70    /// assert_eq!(&*lazy, "HELLO, WORLD!");
71    /// ```
72    #[inline]
73    #[stable(feature = "lazy_cell", since = "1.80.0")]
74    #[rustc_const_stable(feature = "lazy_cell", since = "1.80.0")]
75    pub const fn new(f: F) -> LazyCell<T, F> {
76        LazyCell { state: UnsafeCell::new(State::Uninit(f)) }
77    }
78
79    /// Consumes this `LazyCell` returning the stored value.
80    ///
81    /// Returns `Ok(value)` if `Lazy` is initialized and `Err(f)` otherwise.
82    ///
83    /// # Panics
84    ///
85    /// Panics if the cell is poisoned.
86    ///
87    /// # Examples
88    ///
89    /// ```
90    /// #![feature(lazy_cell_into_inner)]
91    ///
92    /// use std::cell::LazyCell;
93    ///
94    /// let hello = "Hello, World!".to_string();
95    ///
96    /// let lazy = LazyCell::new(|| hello.to_uppercase());
97    ///
98    /// assert_eq!(&*lazy, "HELLO, WORLD!");
99    /// assert_eq!(LazyCell::into_inner(lazy).ok(), Some("HELLO, WORLD!".to_string()));
100    /// ```
101    #[unstable(feature = "lazy_cell_into_inner", issue = "125623")]
102    #[rustc_const_unstable(feature = "lazy_cell_into_inner", issue = "125623")]
103    pub const fn into_inner(this: Self) -> Result<T, F> {
104        match this.state.into_inner() {
105            State::Init(data) => Ok(data),
106            State::Uninit(f) => Err(f),
107            State::Poisoned => panic_poisoned(),
108        }
109    }
110
111    /// Forces the evaluation of this lazy value and returns a reference to
112    /// the result.
113    ///
114    /// This is equivalent to the `Deref` impl, but is explicit.
115    ///
116    /// # Panics
117    ///
118    /// If the initialization closure panics (the one that is passed to the [`new()`] method), the
119    /// panic is propagated to the caller, and the cell becomes poisoned. This will cause all future
120    /// accesses of the cell (via [`force()`] or a dereference) to panic.
121    ///
122    /// [`new()`]: LazyCell::new
123    /// [`force()`]: LazyCell::force
124    ///
125    /// # Examples
126    ///
127    /// ```
128    /// use std::cell::LazyCell;
129    ///
130    /// let lazy = LazyCell::new(|| 92);
131    ///
132    /// assert_eq!(LazyCell::force(&lazy), &92);
133    /// assert_eq!(&*lazy, &92);
134    /// ```
135    #[inline]
136    #[stable(feature = "lazy_cell", since = "1.80.0")]
137    #[rustc_should_not_be_called_on_const_items]
138    pub fn force(this: &LazyCell<T, F>) -> &T {
139        // SAFETY:
140        // This invalidates any mutable references to the data. The resulting
141        // reference lives either until the end of the borrow of `this` (in the
142        // initialized case) or is invalidated in `really_init` (in the
143        // uninitialized case; `really_init` will create and return a fresh reference).
144        let state = unsafe { &*this.state.get() };
145        match state {
146            State::Init(data) => data,
147            // SAFETY: The state is uninitialized.
148            State::Uninit(_) => unsafe { LazyCell::really_init(this) },
149            State::Poisoned => panic_poisoned(),
150        }
151    }
152
153    /// Forces the evaluation of this lazy value and returns a mutable reference to
154    /// the result.
155    ///
156    /// # Panics
157    ///
158    /// If the initialization closure panics (the one that is passed to the [`new()`] method), the
159    /// panic is propagated to the caller, and the cell becomes poisoned. This will cause all future
160    /// accesses of the cell (via [`force()`] or a dereference) to panic.
161    ///
162    /// [`new()`]: LazyCell::new
163    /// [`force()`]: LazyCell::force
164    ///
165    /// # Examples
166    ///
167    /// ```
168    /// #![feature(lazy_get)]
169    /// use std::cell::LazyCell;
170    ///
171    /// let mut lazy = LazyCell::new(|| 92);
172    ///
173    /// let p = LazyCell::force_mut(&mut lazy);
174    /// assert_eq!(*p, 92);
175    /// *p = 44;
176    /// assert_eq!(*lazy, 44);
177    /// ```
178    #[inline]
179    #[unstable(feature = "lazy_get", issue = "129333")]
180    pub fn force_mut(this: &mut LazyCell<T, F>) -> &mut T {
181        #[cold]
182        /// # Safety
183        /// May only be called when the state is `Uninit`.
184        unsafe fn really_init_mut<T, F: FnOnce() -> T>(state: &mut State<T, F>) -> &mut T {
185            // INVARIANT: Always valid, but the value may not be dropped.
186            struct PoisonOnPanic<T, F>(*mut State<T, F>);
187            impl<T, F> Drop for PoisonOnPanic<T, F> {
188                #[inline]
189                fn drop(&mut self) {
190                    // SAFETY: Invariant states it is valid, and we don't drop the old value.
191                    unsafe {
192                        self.0.write(State::Poisoned);
193                    }
194                }
195            }
196
197            let State::Uninit(f) = state else {
198                // `unreachable!()` here won't optimize out because the function is cold.
199                // SAFETY: Precondition.
200                unsafe { unreachable_unchecked() };
201            };
202            // SAFETY: We never drop the state after we read `f`, and we write a valid value back
203            // in any case, panic or success. `f` can't access the `LazyCell` because it is mutably
204            // borrowed.
205            let f = unsafe { core::ptr::read(f) };
206            // INVARIANT: Initiated from mutable reference, don't drop because we read it.
207            let guard = PoisonOnPanic(state);
208            let data = f();
209            // SAFETY: `PoisonOnPanic` invariant, and we don't drop the old value.
210            unsafe {
211                core::ptr::write(guard.0, State::Init(data));
212            }
213            core::mem::forget(guard);
214            let State::Init(data) = state else { unreachable!() };
215            data
216        }
217
218        let state = this.state.get_mut();
219        match state {
220            State::Init(data) => data,
221            // SAFETY: `state` is `Uninit`.
222            State::Uninit(_) => unsafe { really_init_mut(state) },
223            State::Poisoned => panic_poisoned(),
224        }
225    }
226
227    /// # Safety
228    /// May only be called when the state is `Uninit`.
229    #[cold]
230    unsafe fn really_init(this: &LazyCell<T, F>) -> &T {
231        // SAFETY:
232        // This function is only called when the state is uninitialized,
233        // so no references to `state` can exist except for the reference
234        // in `force`, which is invalidated here and not accessed again.
235        let state = unsafe { &mut *this.state.get() };
236        // Temporarily mark the state as poisoned. This prevents reentrant
237        // accesses and correctly poisons the cell if the closure panicked.
238        let State::Uninit(f) = mem::replace(state, State::Poisoned) else { unreachable!() };
239
240        let data = f();
241
242        // SAFETY:
243        // If the closure accessed the cell through something like a reentrant
244        // mutex, but caught the panic resulting from the state being poisoned,
245        // the mutable borrow for `state` will be invalidated, so we need to
246        // go through the `UnsafeCell` pointer here. The state can only be
247        // poisoned at this point, so using `write` to skip the destructor
248        // of `State` should help the optimizer.
249        unsafe { this.state.get().write(State::Init(data)) };
250
251        // SAFETY:
252        // The previous references were invalidated by the `write` call above,
253        // so do a new shared borrow of the state instead.
254        let state = unsafe { &*this.state.get() };
255        let State::Init(data) = state else { unreachable!() };
256        data
257    }
258}
259
260impl<T, F> LazyCell<T, F> {
261    /// Returns a mutable reference to the value if initialized. Otherwise (if uninitialized or
262    /// poisoned), returns `None`.
263    ///
264    /// # Examples
265    ///
266    /// ```
267    /// #![feature(lazy_get)]
268    ///
269    /// use std::cell::LazyCell;
270    ///
271    /// let mut lazy = LazyCell::new(|| 92);
272    ///
273    /// assert_eq!(LazyCell::get_mut(&mut lazy), None);
274    /// let _ = LazyCell::force(&lazy);
275    /// *LazyCell::get_mut(&mut lazy).unwrap() = 44;
276    /// assert_eq!(*lazy, 44);
277    /// ```
278    #[inline]
279    #[unstable(feature = "lazy_get", issue = "129333")]
280    pub fn get_mut(this: &mut LazyCell<T, F>) -> Option<&mut T> {
281        let state = this.state.get_mut();
282        match state {
283            State::Init(data) => Some(data),
284            _ => None,
285        }
286    }
287
288    /// Returns a reference to the value if initialized. Otherwise (if uninitialized or poisoned),
289    /// returns `None`.
290    ///
291    /// # Examples
292    ///
293    /// ```
294    /// #![feature(lazy_get)]
295    ///
296    /// use std::cell::LazyCell;
297    ///
298    /// let lazy = LazyCell::new(|| 92);
299    ///
300    /// assert_eq!(LazyCell::get(&lazy), None);
301    /// let _ = LazyCell::force(&lazy);
302    /// assert_eq!(LazyCell::get(&lazy), Some(&92));
303    /// ```
304    #[inline]
305    #[unstable(feature = "lazy_get", issue = "129333")]
306    pub fn get(this: &LazyCell<T, F>) -> Option<&T> {
307        // SAFETY:
308        // This is sound for the same reason as in `force`: once the state is
309        // initialized, it will not be mutably accessed again, so this reference
310        // will stay valid for the duration of the borrow to `self`.
311        let state = unsafe { &*this.state.get() };
312        match state {
313            State::Init(data) => Some(data),
314            _ => None,
315        }
316    }
317}
318
319#[stable(feature = "lazy_cell", since = "1.80.0")]
320impl<T, F: FnOnce() -> T> Deref for LazyCell<T, F> {
321    type Target = T;
322
323    /// # Panics
324    ///
325    /// If the initialization closure panics (the one that is passed to the [`new()`] method), the
326    /// panic is propagated to the caller, and the cell becomes poisoned. This will cause all future
327    /// accesses of the cell (via [`force()`] or a dereference) to panic.
328    ///
329    /// [`new()`]: LazyCell::new
330    /// [`force()`]: LazyCell::force
331    #[inline]
332    fn deref(&self) -> &T {
333        LazyCell::force(self)
334    }
335}
336
337#[stable(feature = "lazy_deref_mut", since = "1.89.0")]
338impl<T, F: FnOnce() -> T> DerefMut for LazyCell<T, F> {
339    /// # Panics
340    ///
341    /// If the initialization closure panics (the one that is passed to the [`new()`] method), the
342    /// panic is propagated to the caller, and the cell becomes poisoned. This will cause all future
343    /// accesses of the cell (via [`force()`] or a dereference) to panic.
344    ///
345    /// [`new()`]: LazyCell::new
346    /// [`force()`]: LazyCell::force
347    #[inline]
348    fn deref_mut(&mut self) -> &mut T {
349        LazyCell::force_mut(self)
350    }
351}
352
353#[stable(feature = "lazy_cell", since = "1.80.0")]
354impl<T: Default> Default for LazyCell<T> {
355    /// Creates a new lazy value using `Default` as the initializing function.
356    #[inline]
357    fn default() -> LazyCell<T> {
358        LazyCell::new(T::default)
359    }
360}
361
362#[stable(feature = "lazy_cell", since = "1.80.0")]
363impl<T: fmt::Debug, F> fmt::Debug for LazyCell<T, F> {
364    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
365        let mut d = f.debug_tuple("LazyCell");
366        match LazyCell::get(self) {
367            Some(data) => d.field(data),
368            None => d.field(&format_args!("<uninit>")),
369        };
370        d.finish()
371    }
372}
373
374#[cold]
375#[inline(never)]
376const fn panic_poisoned() -> ! {
377    panic!("LazyCell instance has previously been poisoned")
378}
core/cell/lazy.rs

core/cell/
lazy.rs
