once.rs - source
Description: Source of the Rust file `library/core/src/cell/once.rs`.

#
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    #[rustc_should_not_be_called_on_const_items]
    92    pub fn set(&self, value: T) -> Result<(), T> {
    93        match self.try_insert(value) {
    94            Ok(_) => Ok(()),
    95            Err((_, value)) => Err(value),
    96        }
    97    }
    98
    99    /// Initializes the contents of the cell to `value` if the cell was
    100    /// uninitialized, then returns a reference to it.
    101    ///
    102    /// # Errors
    103    ///
    104    /// This method returns `Ok(&value)` if the cell was uninitialized
    105    /// and `Err((&current_value, value))` if it was already initialized.
    106    ///
    107    /// # Examples
    108    ///
    109    /// ```
    110    /// #![feature(once_cell_try_insert)]
    111    ///
    112    /// use std::cell::OnceCell;
    113    ///
    114    /// let cell = OnceCell::new();
    115    /// assert!(cell.get().is_none());
    116    ///
    117    /// assert_eq!(cell.try_insert(92), Ok(&92));
    118    /// assert_eq!(cell.try_insert(62), Err((&92, 62)));
    119    ///
    120    /// assert!(cell.get().is_some());
    121    /// ```
    122    #[inline]
    123    #[unstable(feature = "once_cell_try_insert", issue = "116693")]
    124    #[rustc_should_not_be_called_on_const_items]
    125    pub fn try_insert(&self, value: T) -> Result<&T, (&T, T)> {
    126        if let Some(old) = self.get() {
    127            return Err((old, value));
    128        }
    129
    130        // SAFETY: This is the only place where we set the slot, no races
    131        // due to reentrancy/concurrency are possible, and we've
    132        // checked that slot is currently `None`, so this write
    133        // maintains the `inner`'s invariant.
    134        let slot = unsafe { &mut *self.inner.get() };
    135        Ok(slot.insert(value))
    136    }
    137
    138    /// Gets the contents of the cell, initializing it to `f()`
    139    /// if the cell was uninitialized.
    140    ///
    141    /// # Panics
    142    ///
    143    /// If `f()` panics, the panic is propagated to the caller, and the cell
    144    /// remains uninitialized.
    145    ///
    146    /// It is an error to reentrantly initialize the cell from `f`. Doing
    147    /// so results in a panic.
    148    ///
    149    /// # Examples
    150    ///
    151    /// ```
    152    /// use std::cell::OnceCell;
    153    ///
    154    /// let cell = OnceCell::new();
    155    /// let value = cell.get_or_init(|| 92);
    156    /// assert_eq!(value, &92);
    157    /// let value = cell.get_or_init(|| unreachable!());
    158    /// assert_eq!(value, &92);
    159    /// ```
    160    #[inline]
    161    #[stable(feature = "once_cell", since = "1.70.0")]
    162    #[rustc_should_not_be_called_on_const_items]
    163    pub fn get_or_init<F>(&self, f: F) -> &T
    164    where
    165        F: FnOnce() -> T,
    166    {
    167        match self.get_or_try_init(|| Ok::<T, !>(f())) {
    168            Ok(val) => val,
    169        }
    170    }
    171
    172    /// Gets the mutable reference of the contents of the cell,
    173    /// initializing it to `f()` if the cell was uninitialized.
    174    ///
    175    /// # Panics
    176    ///
    177    /// If `f()` panics, the panic is propagated to the caller, and the cell
    178    /// remains uninitialized.
    179    ///
    180    /// # Examples
    181    ///
    182    /// ```
    183    /// #![feature(once_cell_get_mut)]
    184    ///
    185    /// use std::cell::OnceCell;
    186    ///
    187    /// let mut cell = OnceCell::new();
    188    /// let value = cell.get_mut_or_init(|| 92);
    189    /// assert_eq!(*value, 92);
    190    ///
    191    /// *value += 2;
    192    /// assert_eq!(*value, 94);
    193    ///
    194    /// let value = cell.get_mut_or_init(|| unreachable!());
    195    /// assert_eq!(*value, 94);
    196    /// ```
    197    #[inline]
    198    #[unstable(feature = "once_cell_get_mut", issue = "121641")]
    199    pub fn get_mut_or_init<F>(&mut self, f: F) -> &mut T
    200    where
    201        F: FnOnce() -> T,
    202    {
    203        match self.get_mut_or_try_init(|| Ok::<T, !>(f())) {
    204            Ok(val) => val,
    205        }
    206    }
    207
    208    /// Gets the contents of the cell, initializing it to `f()` if
    209    /// the cell was uninitialized. If the cell was uninitialized
    210    /// and `f()` failed, an error is returned.
    211    ///
    212    /// # Panics
    213    ///
    214    /// If `f()` panics, the panic is propagated to the caller, and the cell
    215    /// remains uninitialized.
    216    ///
    217    /// It is an error to reentrantly initialize the cell from `f`. Doing
    218    /// so results in a panic.
    219    ///
    220    /// # Examples
    221    ///
    222    /// ```
    223    /// #![feature(once_cell_try)]
    224    ///
    225    /// use std::cell::OnceCell;
    226    ///
    227    /// let cell = OnceCell::new();
    228    /// assert_eq!(cell.get_or_try_init(|| Err(())), Err(()));
    229    /// assert!(cell.get().is_none());
    230    /// let value = cell.get_or_try_init(|| -> Result<i32, ()> {
    231    ///     Ok(92)
    232    /// });
    233    /// assert_eq!(value, Ok(&92));
    234    /// assert_eq!(cell.get(), Some(&92))
    235    /// ```
    236    #[unstable(feature = "once_cell_try", issue = "109737")]
    237    #[rustc_should_not_be_called_on_const_items]
    238    pub fn get_or_try_init<F, E>(&self, f: F) -> Result<&T, E>
    239    where
    240        F: FnOnce() -> Result<T, E>,
    241    {
    242        if let Some(val) = self.get() {
    243            return Ok(val);
    244        }
    245        self.try_init(f)
    246    }
    247
    248    /// Gets the mutable reference of the contents of the cell, initializing
    249    /// it to `f()` if the cell was uninitialized. If the cell was uninitialized
    250    /// and `f()` failed, an error is returned.
    251    ///
    252    /// # Panics
    253    ///
    254    /// If `f()` panics, the panic is propagated to the caller, and the cell
    255    /// remains uninitialized.
    256    ///
    257    /// # Examples
    258    ///
    259    /// ```
    260    /// #![feature(once_cell_get_mut)]
    261    ///
    262    /// use std::cell::OnceCell;
    263    ///
    264    /// let mut cell: OnceCell<u32> = OnceCell::new();
    265    ///
    266    /// // Failed attempts to initialize the cell do not change its contents
    267    /// assert!(cell.get_mut_or_try_init(|| "not a number!".parse()).is_err());
    268    /// assert!(cell.get().is_none());
    269    ///
    270    /// let value = cell.get_mut_or_try_init(|| "1234".parse());
    271    /// assert_eq!(value, Ok(&mut 1234));
    272    ///
    273    /// let Ok(value) = value else { return; };
    274    /// *value += 2;
    275    /// assert_eq!(cell.get(), Some(&1236))
    276    /// ```
    277    #[unstable(feature = "once_cell_get_mut", issue = "121641")]
    278    pub fn get_mut_or_try_init<F, E>(&mut self, f: F) -> Result<&mut T, E>
    279    where
    280        F: FnOnce() -> Result<T, E>,
    281    {
    282        if self.get().is_none() {
    283            self.try_init(f)?;
    284        }
    285        Ok(self.get_mut().unwrap())
    286    }
    287
    288    // Avoid inlining the initialization closure into the common path that fetches
    289    // the already initialized value
    290    #[cold]
    291    fn try_init<F, E>(&self, f: F) -> Result<&T, E>
    292    where
    293        F: FnOnce() -> Result<T, E>,
    294    {
    295        let val = f()?;
    296        // Note that *some* forms of reentrant initialization might lead to
    297        // UB (see `reentrant_init` test). I believe that just removing this
    298        // `panic`, while keeping `try_insert` would be sound, but it seems
    299        // better to panic, rather than to silently use an old value.
    300        if let Ok(val) = self.try_insert(val) { Ok(val) } else { panic!("reentrant init") }
    301    }
    302
    303    /// Consumes the cell, returning the wrapped value.
    304    ///
    305    /// Returns `None` if the cell was uninitialized.
    306    ///
    307    /// # Examples
    308    ///
    309    /// ```
    310    /// use std::cell::OnceCell;
    311    ///
    312    /// let cell: OnceCell<String> = OnceCell::new();
    313    /// assert_eq!(cell.into_inner(), None);
    314    ///
    315    /// let cell = OnceCell::new();
    316    /// let _ = cell.set("hello".to_owned());
    317    /// assert_eq!(cell.into_inner(), Some("hello".to_owned()));
    318    /// ```
    319    #[inline]
    320    #[stable(feature = "once_cell", since = "1.70.0")]
    321    #[rustc_const_stable(feature = "const_cell_into_inner", since = "1.83.0")]
    322    #[rustc_allow_const_fn_unstable(const_precise_live_drops)]
    323    pub const fn into_inner(self) -> Option<T> {
    324        // Because `into_inner` takes `self` by value, the compiler statically verifies
    325        // that it is not currently borrowed. So it is safe to move out `Option<T>`.
    326        self.inner.into_inner()
    327    }
    328
    329    /// Takes the value out of this `OnceCell`, moving it back to an uninitialized state.
    330    ///
    331    /// Has no effect and returns `None` if the `OnceCell` is uninitialized.
    332    ///
    333    /// Safety is guaranteed by requiring a mutable reference.
    334    ///
    335    /// # Examples
    336    ///
    337    /// ```
    338    /// use std::cell::OnceCell;
    339    ///
    340    /// let mut cell: OnceCell<String> = OnceCell::new();
    341    /// assert_eq!(cell.take(), None);
    342    ///
    343    /// let mut cell = OnceCell::new();
    344    /// let _ = cell.set("hello".to_owned());
    345    /// assert_eq!(cell.take(), Some("hello".to_owned()));
    346    /// assert_eq!(cell.get(), None);
    347    /// ```
    348    #[inline]
    349    #[stable(feature = "once_cell", since = "1.70.0")]
    350    pub fn take(&mut self) -> Option<T> {
    351        mem::take(self).into_inner()
    352    }
    353}
    354
    355#[stable(feature = "once_cell", since = "1.70.0")]
    356#[rustc_const_unstable(feature = "const_default", issue = "143894")]
    357impl<T> const Default for OnceCell<T> {
    358    #[inline]
    359    fn default() -> Self {
    360        Self::new()
    361    }
    362}
    363
    364#[stable(feature = "once_cell", since = "1.70.0")]
    365impl<T: fmt::Debug> fmt::Debug for OnceCell<T> {
    366    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
    367        let mut d = f.debug_tuple("OnceCell");
    368        match self.get() {
    369            Some(v) => d.field(v),
    370            None => d.field(&format_args!("<uninit>")),
    371        };
    372        d.finish()
    373    }
    374}
    375
    376#[stable(feature = "once_cell", since = "1.70.0")]
    377impl<T: Clone> Clone for OnceCell<T> {
    378    #[inline]
    379    fn clone(&self) -> OnceCell<T> {
    380        match self.get() {
    381            Some(value) => OnceCell::from(value.clone()),
    382            None => OnceCell::new(),
    383        }
    384    }
    385}
    386
    387#[stable(feature = "once_cell", since = "1.70.0")]
    388impl<T: PartialEq> PartialEq for OnceCell<T> {
    389    #[inline]
    390    fn eq(&self, other: &Self) -> bool {
    391        self.get() == other.get()
    392    }
    393}
    394
    395#[stable(feature = "once_cell", since = "1.70.0")]
    396impl<T: Eq> Eq for OnceCell<T> {}
    397
    398#[stable(feature = "once_cell", since = "1.70.0")]
    399#[rustc_const_unstable(feature = "const_convert", issue = "143773")]
    400impl<T> const From<T> for OnceCell<T> {
    401    /// Creates a new `OnceCell<T>` which already contains the given `value`.
    402    #[inline]
    403    fn from(value: T) -> Self {
    404        OnceCell { inner: UnsafeCell::new(Some(value)) }
    405    }
    406}
    407
    408// Just like for `Cell<T>` this isn't needed, but results in nicer error messages.
    409#[stable(feature = "once_cell", since = "1.70.0")]
    410impl<T> !Sync for OnceCell<T> {}