library/core/src/lazy.rs

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