core/cell/
once.rs

1use crate::cell::UnsafeCell;
2use crate::{fmt, mem};
3
4/// A cell which can nominally be written to only once.
5///
6/// This allows obtaining a shared `&T` reference to its inner value without copying or replacing
7/// it (unlike [`Cell`]), and without runtime borrow checks (unlike [`RefCell`]). However,
8/// only immutable references can be obtained unless one has a mutable reference to the cell
9/// itself. In the same vein, the cell can only be re-initialized with such a mutable reference.
10///
11/// A `OnceCell` can be thought of as a safe abstraction over uninitialized data that becomes
12/// initialized once written.
13///
14/// For a thread-safe version of this struct, see [`std::sync::OnceLock`].
15///
16/// [`RefCell`]: crate::cell::RefCell
17/// [`Cell`]: crate::cell::Cell
18/// [`std::sync::OnceLock`]: ../../std/sync/struct.OnceLock.html
19///
20/// # Examples
21///
22/// ```
23/// use std::cell::OnceCell;
24///
25/// let cell = OnceCell::new();
26/// assert!(cell.get().is_none());
27///
28/// let value: &String = cell.get_or_init(|| {
29///     "Hello, World!".to_string()
30/// });
31/// assert_eq!(value, "Hello, World!");
32/// assert!(cell.get().is_some());
33/// ```
34#[stable(feature = "once_cell", since = "1.70.0")]
35pub struct OnceCell<T> {
36    // Invariant: written to at most once.
37    inner: UnsafeCell<Option<T>>,
38}
39
40impl<T> OnceCell<T> {
41    /// Creates a new uninitialized cell.
42    #[inline]
43    #[must_use]
44    #[stable(feature = "once_cell", since = "1.70.0")]
45    #[rustc_const_stable(feature = "once_cell", since = "1.70.0")]
46    pub const fn new() -> OnceCell<T> {
47        OnceCell { inner: UnsafeCell::new(None) }
48    }
49
50    /// Gets the reference to the underlying value.
51    ///
52    /// Returns `None` if the cell is uninitialized.
53    #[inline]
54    #[stable(feature = "once_cell", since = "1.70.0")]
55    pub fn get(&self) -> Option<&T> {
56        // SAFETY: Safe due to `inner`'s invariant
57        unsafe { &*self.inner.get() }.as_ref()
58    }
59
60    /// Gets the mutable reference to the underlying value.
61    ///
62    /// Returns `None` if the cell is uninitialized.
63    #[inline]
64    #[stable(feature = "once_cell", since = "1.70.0")]
65    pub fn get_mut(&mut self) -> Option<&mut T> {
66        self.inner.get_mut().as_mut()
67    }
68
69    /// Initializes the contents of the cell to `value`.
70    ///
71    /// # Errors
72    ///
73    /// This method returns `Ok(())` if the cell was uninitialized
74    /// and `Err(value)` if it was already initialized.
75    ///
76    /// # Examples
77    ///
78    /// ```
79    /// use std::cell::OnceCell;
80    ///
81    /// let cell = OnceCell::new();
82    /// assert!(cell.get().is_none());
83    ///
84    /// assert_eq!(cell.set(92), Ok(()));
85    /// assert_eq!(cell.set(62), Err(62));
86    ///
87    /// assert!(cell.get().is_some());
88    /// ```
89    #[inline]
90    #[stable(feature = "once_cell", since = "1.70.0")]
91    pub fn set(&self, value: T) -> Result<(), T> {
92        match self.try_insert(value) {
93            Ok(_) => Ok(()),
94            Err((_, value)) => Err(value),
95        }
96    }
97
98    /// Initializes the contents of the cell to `value` if the cell was
99    /// uninitialized, then returns a reference to it.
100    ///
101    /// # Errors
102    ///
103    /// This method returns `Ok(&value)` if the cell was uninitialized
104    /// and `Err((&current_value, value))` if it was already initialized.
105    ///
106    /// # Examples
107    ///
108    /// ```
109    /// #![feature(once_cell_try_insert)]
110    ///
111    /// use std::cell::OnceCell;
112    ///
113    /// let cell = OnceCell::new();
114    /// assert!(cell.get().is_none());
115    ///
116    /// assert_eq!(cell.try_insert(92), Ok(&92));
117    /// assert_eq!(cell.try_insert(62), Err((&92, 62)));
118    ///
119    /// assert!(cell.get().is_some());
120    /// ```
121    #[inline]
122    #[unstable(feature = "once_cell_try_insert", issue = "116693")]
123    pub fn try_insert(&self, value: T) -> Result<&T, (&T, T)> {
124        if let Some(old) = self.get() {
125            return Err((old, value));
126        }
127
128        // SAFETY: This is the only place where we set the slot, no races
129        // due to reentrancy/concurrency are possible, and we've
130        // checked that slot is currently `None`, so this write
131        // maintains the `inner`'s invariant.
132        let slot = unsafe { &mut *self.inner.get() };
133        Ok(slot.insert(value))
134    }
135
136    /// Gets the contents of the cell, initializing it to `f()`
137    /// if the cell was uninitialized.
138    ///
139    /// # Panics
140    ///
141    /// If `f()` panics, the panic is propagated to the caller, and the cell
142    /// remains uninitialized.
143    ///
144    /// It is an error to reentrantly initialize the cell from `f`. Doing
145    /// so results in a panic.
146    ///
147    /// # Examples
148    ///
149    /// ```
150    /// use std::cell::OnceCell;
151    ///
152    /// let cell = OnceCell::new();
153    /// let value = cell.get_or_init(|| 92);
154    /// assert_eq!(value, &92);
155    /// let value = cell.get_or_init(|| unreachable!());
156    /// assert_eq!(value, &92);
157    /// ```
158    #[inline]
159    #[stable(feature = "once_cell", since = "1.70.0")]
160    pub fn get_or_init<F>(&self, f: F) -> &T
161    where
162        F: FnOnce() -> T,
163    {
164        match self.get_or_try_init(|| Ok::<T, !>(f())) {
165            Ok(val) => val,
166        }
167    }
168
169    /// Gets the mutable reference of the contents of the cell,
170    /// initializing it to `f()` if the cell was uninitialized.
171    ///
172    /// # Panics
173    ///
174    /// If `f()` panics, the panic is propagated to the caller, and the cell
175    /// remains uninitialized.
176    ///
177    /// # Examples
178    ///
179    /// ```
180    /// #![feature(once_cell_get_mut)]
181    ///
182    /// use std::cell::OnceCell;
183    ///
184    /// let mut cell = OnceCell::new();
185    /// let value = cell.get_mut_or_init(|| 92);
186    /// assert_eq!(*value, 92);
187    ///
188    /// *value += 2;
189    /// assert_eq!(*value, 94);
190    ///
191    /// let value = cell.get_mut_or_init(|| unreachable!());
192    /// assert_eq!(*value, 94);
193    /// ```
194    #[inline]
195    #[unstable(feature = "once_cell_get_mut", issue = "121641")]
196    pub fn get_mut_or_init<F>(&mut self, f: F) -> &mut T
197    where
198        F: FnOnce() -> T,
199    {
200        match self.get_mut_or_try_init(|| Ok::<T, !>(f())) {
201            Ok(val) => val,
202        }
203    }
204
205    /// Gets the contents of the cell, initializing it to `f()` if
206    /// the cell was uninitialized. If the cell was uninitialized
207    /// and `f()` failed, an error is returned.
208    ///
209    /// # Panics
210    ///
211    /// If `f()` panics, the panic is propagated to the caller, and the cell
212    /// remains uninitialized.
213    ///
214    /// It is an error to reentrantly initialize the cell from `f`. Doing
215    /// so results in a panic.
216    ///
217    /// # Examples
218    ///
219    /// ```
220    /// #![feature(once_cell_try)]
221    ///
222    /// use std::cell::OnceCell;
223    ///
224    /// let cell = OnceCell::new();
225    /// assert_eq!(cell.get_or_try_init(|| Err(())), Err(()));
226    /// assert!(cell.get().is_none());
227    /// let value = cell.get_or_try_init(|| -> Result<i32, ()> {
228    ///     Ok(92)
229    /// });
230    /// assert_eq!(value, Ok(&92));
231    /// assert_eq!(cell.get(), Some(&92))
232    /// ```
233    #[unstable(feature = "once_cell_try", issue = "109737")]
234    pub fn get_or_try_init<F, E>(&self, f: F) -> Result<&T, E>
235    where
236        F: FnOnce() -> Result<T, E>,
237    {
238        if let Some(val) = self.get() {
239            return Ok(val);
240        }
241        self.try_init(f)
242    }
243
244    /// Gets the mutable reference of the contents of the cell, initializing
245    /// it to `f()` if the cell was uninitialized. If the cell was uninitialized
246    /// and `f()` failed, an error is returned.
247    ///
248    /// # Panics
249    ///
250    /// If `f()` panics, the panic is propagated to the caller, and the cell
251    /// remains uninitialized.
252    ///
253    /// # Examples
254    ///
255    /// ```
256    /// #![feature(once_cell_get_mut)]
257    ///
258    /// use std::cell::OnceCell;
259    ///
260    /// let mut cell: OnceCell<u32> = OnceCell::new();
261    ///
262    /// // Failed attempts to initialize the cell do not change its contents
263    /// assert!(cell.get_mut_or_try_init(|| "not a number!".parse()).is_err());
264    /// assert!(cell.get().is_none());
265    ///
266    /// let value = cell.get_mut_or_try_init(|| "1234".parse());
267    /// assert_eq!(value, Ok(&mut 1234));
268    ///
269    /// let Ok(value) = value else { return; };
270    /// *value += 2;
271    /// assert_eq!(cell.get(), Some(&1236))
272    /// ```
273    #[unstable(feature = "once_cell_get_mut", issue = "121641")]
274    pub fn get_mut_or_try_init<F, E>(&mut self, f: F) -> Result<&mut T, E>
275    where
276        F: FnOnce() -> Result<T, E>,
277    {
278        if self.get().is_none() {
279            self.try_init(f)?;
280        }
281        Ok(self.get_mut().unwrap())
282    }
283
284    // Avoid inlining the initialization closure into the common path that fetches
285    // the already initialized value
286    #[cold]
287    fn try_init<F, E>(&self, f: F) -> Result<&T, E>
288    where
289        F: FnOnce() -> Result<T, E>,
290    {
291        let val = f()?;
292        // Note that *some* forms of reentrant initialization might lead to
293        // UB (see `reentrant_init` test). I believe that just removing this
294        // `panic`, while keeping `try_insert` would be sound, but it seems
295        // better to panic, rather than to silently use an old value.
296        if let Ok(val) = self.try_insert(val) { Ok(val) } else { panic!("reentrant init") }
297    }
298
299    /// Consumes the cell, returning the wrapped value.
300    ///
301    /// Returns `None` if the cell was uninitialized.
302    ///
303    /// # Examples
304    ///
305    /// ```
306    /// use std::cell::OnceCell;
307    ///
308    /// let cell: OnceCell<String> = OnceCell::new();
309    /// assert_eq!(cell.into_inner(), None);
310    ///
311    /// let cell = OnceCell::new();
312    /// let _ = cell.set("hello".to_owned());
313    /// assert_eq!(cell.into_inner(), Some("hello".to_owned()));
314    /// ```
315    #[inline]
316    #[stable(feature = "once_cell", since = "1.70.0")]
317    #[rustc_const_stable(feature = "const_cell_into_inner", since = "1.83.0")]
318    #[rustc_allow_const_fn_unstable(const_precise_live_drops)]
319    pub const fn into_inner(self) -> Option<T> {
320        // Because `into_inner` takes `self` by value, the compiler statically verifies
321        // that it is not currently borrowed. So it is safe to move out `Option<T>`.
322        self.inner.into_inner()
323    }
324
325    /// Takes the value out of this `OnceCell`, moving it back to an uninitialized state.
326    ///
327    /// Has no effect and returns `None` if the `OnceCell` is uninitialized.
328    ///
329    /// Safety is guaranteed by requiring a mutable reference.
330    ///
331    /// # Examples
332    ///
333    /// ```
334    /// use std::cell::OnceCell;
335    ///
336    /// let mut cell: OnceCell<String> = OnceCell::new();
337    /// assert_eq!(cell.take(), None);
338    ///
339    /// let mut cell = OnceCell::new();
340    /// let _ = cell.set("hello".to_owned());
341    /// assert_eq!(cell.take(), Some("hello".to_owned()));
342    /// assert_eq!(cell.get(), None);
343    /// ```
344    #[inline]
345    #[stable(feature = "once_cell", since = "1.70.0")]
346    pub fn take(&mut self) -> Option<T> {
347        mem::take(self).into_inner()
348    }
349}
350
351#[stable(feature = "once_cell", since = "1.70.0")]
352impl<T> Default for OnceCell<T> {
353    #[inline]
354    fn default() -> Self {
355        Self::new()
356    }
357}
358
359#[stable(feature = "once_cell", since = "1.70.0")]
360impl<T: fmt::Debug> fmt::Debug for OnceCell<T> {
361    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
362        let mut d = f.debug_tuple("OnceCell");
363        match self.get() {
364            Some(v) => d.field(v),
365            None => d.field(&format_args!("<uninit>")),
366        };
367        d.finish()
368    }
369}
370
371#[stable(feature = "once_cell", since = "1.70.0")]
372impl<T: Clone> Clone for OnceCell<T> {
373    #[inline]
374    fn clone(&self) -> OnceCell<T> {
375        let res = OnceCell::new();
376        if let Some(value) = self.get() {
377            match res.set(value.clone()) {
378                Ok(()) => (),
379                Err(_) => unreachable!(),
380            }
381        }
382        res
383    }
384}
385
386#[stable(feature = "once_cell", since = "1.70.0")]
387impl<T: PartialEq> PartialEq for OnceCell<T> {
388    #[inline]
389    fn eq(&self, other: &Self) -> bool {
390        self.get() == other.get()
391    }
392}
393
394#[stable(feature = "once_cell", since = "1.70.0")]
395impl<T: Eq> Eq for OnceCell<T> {}
396
397#[stable(feature = "once_cell", since = "1.70.0")]
398impl<T> From<T> for OnceCell<T> {
399    /// Creates a new `OnceCell<T>` which already contains the given `value`.
400    #[inline]
401    fn from(value: T) -> Self {
402        OnceCell { inner: UnsafeCell::new(Some(value)) }
403    }
404}
405
406// Just like for `Cell<T>` this isn't needed, but results in nicer error messages.
407#[stable(feature = "once_cell", since = "1.70.0")]
408impl<T> !Sync for OnceCell<T> {}
core/cell/once.rs

core/cell/
once.rs
