vendor/once_cell/src/lib.rs

   1 //! # Overview
   2 //!
   3 //! `once_cell` provides two new cell-like types, [`unsync::OnceCell`] and [`sync::OnceCell`]. A `OnceCell`
   4 //! might store arbitrary non-`Copy` types, can be assigned to at most once and provides direct access
   5 //! to the stored contents. The core API looks *roughly* like this (and there's much more inside, read on!):
   6 //!
   7 //! ```rust,ignore
   8 //! impl<T> OnceCell<T> {
   9 //!     const fn new() -> OnceCell<T> { ... }
  10 //!     fn set(&self, value: T) -> Result<(), T> { ... }
  11 //!     fn get(&self) -> Option<&T> { ... }
  12 //! }
  13 //! ```
  14 //!
  15 //! Note that, like with [`RefCell`] and [`Mutex`], the `set` method requires only a shared reference.
  16 //! Because of the single assignment restriction `get` can return a `&T` instead of `Ref<T>`
  17 //! or `MutexGuard<T>`.
  18 //!
  19 //! The `sync` flavor is thread-safe (that is, implements the [`Sync`] trait), while the `unsync` one is not.
  20 //!
  21 //! [`unsync::OnceCell`]: unsync/struct.OnceCell.html
  22 //! [`sync::OnceCell`]: sync/struct.OnceCell.html
  23 //! [`RefCell`]: https://doc.rust-lang.org/std/cell/struct.RefCell.html
  24 //! [`Mutex`]: https://doc.rust-lang.org/std/sync/struct.Mutex.html
  25 //! [`Sync`]: https://doc.rust-lang.org/std/marker/trait.Sync.html
  26 //!
  27 //! # Recipes
  28 //!
  29 //! `OnceCell` might be useful for a variety of patterns.
  30 //!
  31 //! ## Safe Initialization of Global Data
  32 //!
  33 //! ```rust
  34 //! use std::{env, io};
  35 //!
  36 //! use once_cell::sync::OnceCell;
  37 //!
  38 //! #[derive(Debug)]
  39 //! pub struct Logger {
  40 //!     // ...
  41 //! }
  42 //! static INSTANCE: OnceCell<Logger> = OnceCell::new();
  43 //!
  44 //! impl Logger {
  45 //!     pub fn global() -> &'static Logger {
  46 //!         INSTANCE.get().expect("logger is not initialized")
  47 //!     }
  48 //!
  49 //!     fn from_cli(args: env::Args) -> Result<Logger, std::io::Error> {
  50 //!        // ...
  51 //! #      Ok(Logger {})
  52 //!     }
  53 //! }
  54 //!
  55 //! fn main() {
  56 //!     let logger = Logger::from_cli(env::args()).unwrap();
  57 //!     INSTANCE.set(logger).unwrap();
  58 //!     // use `Logger::global()` from now on
  59 //! }
  60 //! ```
  61 //!
  62 //! ## Lazy Initialized Global Data
  63 //!
  64 //! This is essentially the `lazy_static!` macro, but without a macro.
  65 //!
  66 //! ```rust
  67 //! use std::{sync::Mutex, collections::HashMap};
  68 //!
  69 //! use once_cell::sync::OnceCell;
  70 //!
  71 //! fn global_data() -> &'static Mutex<HashMap<i32, String>> {
  72 //!     static INSTANCE: OnceCell<Mutex<HashMap<i32, String>>> = OnceCell::new();
  73 //!     INSTANCE.get_or_init(|| {
  74 //!         let mut m = HashMap::new();
  75 //!         m.insert(13, "Spica".to_string());
  76 //!         m.insert(74, "Hoyten".to_string());
  77 //!         Mutex::new(m)
  78 //!     })
  79 //! }
  80 //! ```
  81 //!
  82 //! There are also the [`sync::Lazy`] and [`unsync::Lazy`] convenience types to streamline this pattern:
  83 //!
  84 //! ```rust
  85 //! use std::{sync::Mutex, collections::HashMap};
  86 //! use once_cell::sync::Lazy;
  87 //!
  88 //! static GLOBAL_DATA: Lazy<Mutex<HashMap<i32, String>>> = Lazy::new(|| {
  89 //!     let mut m = HashMap::new();
  90 //!     m.insert(13, "Spica".to_string());
  91 //!     m.insert(74, "Hoyten".to_string());
  92 //!     Mutex::new(m)
  93 //! });
  94 //!
  95 //! fn main() {
  96 //!     println!("{:?}", GLOBAL_DATA.lock().unwrap());
  97 //! }
  98 //! ```
  99 //!
 100 //! Note that the variable that holds `Lazy` is declared as `static`, *not*
 101 //! `const`. This is important: using `const` instead compiles, but works wrong.
 102 //!
 103 //! [`sync::Lazy`]: sync/struct.Lazy.html
 104 //! [`unsync::Lazy`]: unsync/struct.Lazy.html
 105 //!
 106 //! ## General purpose lazy evaluation
 107 //!
 108 //! Unlike `lazy_static!`, `Lazy` works with local variables.
 109 //!
 110 //! ```rust
 111 //! use once_cell::unsync::Lazy;
 112 //!
 113 //! fn main() {
 114 //!     let ctx = vec![1, 2, 3];
 115 //!     let thunk = Lazy::new(|| {
 116 //!         ctx.iter().sum::<i32>()
 117 //!     });
 118 //!     assert_eq!(*thunk, 6);
 119 //! }
 120 //! ```
 121 //!
 122 //! If you need a lazy field in a struct, you probably should use `OnceCell`
 123 //! directly, because that will allow you to access `self` during initialization.
 124 //!
 125 //! ```rust
 126 //! use std::{fs, path::PathBuf};
 127 //!
 128 //! use once_cell::unsync::OnceCell;
 129 //!
 130 //! struct Ctx {
 131 //!     config_path: PathBuf,
 132 //!     config: OnceCell<String>,
 133 //! }
 134 //!
 135 //! impl Ctx {
 136 //!     pub fn get_config(&self) -> Result<&str, std::io::Error> {
 137 //!         let cfg = self.config.get_or_try_init(|| {
 138 //!             fs::read_to_string(&self.config_path)
 139 //!         })?;
 140 //!         Ok(cfg.as_str())
 141 //!     }
 142 //! }
 143 //! ```
 144 //!
 145 //! ## Lazily Compiled Regex
 146 //!
 147 //! This is a `regex!` macro which takes a string literal and returns an
 148 //! *expression* that evaluates to a `&'static Regex`:
 149 //!
 150 //! ```
 151 //! macro_rules! regex {
 152 //!     ($re:literal $(,)?) => {{
 153 //!         static RE: once_cell::sync::OnceCell<regex::Regex> = once_cell::sync::OnceCell::new();
 154 //!         RE.get_or_init(|| regex::Regex::new($re).unwrap())
 155 //!     }};
 156 //! }
 157 //! ```
 158 //!
 159 //! This macro can be useful to avoid the "compile regex on every loop iteration" problem.
 160 //!
 161 //! ## Runtime `include_bytes!`
 162 //!
 163 //! The `include_bytes` macro is useful to include test resources, but it slows
 164 //! down test compilation a lot. An alternative is to load the resources at
 165 //! runtime:
 166 //!
 167 //! ```
 168 //! use std::path::Path;
 169 //!
 170 //! use once_cell::sync::OnceCell;
 171 //!
 172 //! pub struct TestResource {
 173 //!     path: &'static str,
 174 //!     cell: OnceCell<Vec<u8>>,
 175 //! }
 176 //!
 177 //! impl TestResource {
 178 //!     pub const fn new(path: &'static str) -> TestResource {
 179 //!         TestResource { path, cell: OnceCell::new() }
 180 //!     }
 181 //!     pub fn bytes(&self) -> &[u8] {
 182 //!         self.cell.get_or_init(|| {
 183 //!             let dir = std::env::var("CARGO_MANIFEST_DIR").unwrap();
 184 //!             let path = Path::new(dir.as_str()).join(self.path);
 185 //!             std::fs::read(&path).unwrap_or_else(|_err| {
 186 //!                 panic!("failed to load test resource: {}", path.display())
 187 //!             })
 188 //!         }).as_slice()
 189 //!     }
 190 //! }
 191 //!
 192 //! static TEST_IMAGE: TestResource = TestResource::new("test_data/lena.png");
 193 //!
 194 //! #[test]
 195 //! fn test_sobel_filter() {
 196 //!     let rgb: &[u8] = TEST_IMAGE.bytes();
 197 //!     // ...
 198 //! # drop(rgb);
 199 //! }
 200 //! ```
 201 //!
 202 //! ## `lateinit`
 203 //!
 204 //! `LateInit` type for delayed initialization. It is reminiscent of Kotlin's
 205 //! `lateinit` keyword and allows construction of cyclic data structures:
 206 //!
 207 //!
 208 //! ```
 209 //! use once_cell::sync::OnceCell;
 210 //!
 211 //! #[derive(Debug)]
 212 //! pub struct LateInit<T> { cell: OnceCell<T> }
 213 //!
 214 //! impl<T> LateInit<T> {
 215 //!     pub fn init(&self, value: T) {
 216 //!         assert!(self.cell.set(value).is_ok())
 217 //!     }
 218 //! }
 219 //!
 220 //! impl<T> Default for LateInit<T> {
 221 //!     fn default() -> Self { LateInit { cell: OnceCell::default() } }
 222 //! }
 223 //!
 224 //! impl<T> std::ops::Deref for LateInit<T> {
 225 //!     type Target = T;
 226 //!     fn deref(&self) -> &T {
 227 //!         self.cell.get().unwrap()
 228 //!     }
 229 //! }
 230 //!
 231 //! #[derive(Default, Debug)]
 232 //! struct A<'a> {
 233 //!     b: LateInit<&'a B<'a>>,
 234 //! }
 235 //!
 236 //! #[derive(Default, Debug)]
 237 //! struct B<'a> {
 238 //!     a: LateInit<&'a A<'a>>
 239 //! }
 240 //!
 241 //! fn build_cycle() {
 242 //!     let a = A::default();
 243 //!     let b = B::default();
 244 //!     a.b.init(&b);
 245 //!     b.a.init(&a);
 246 //!     println!("{:?}", a.b.a.b.a);
 247 //! }
 248 //! ```
 249 //!
 250 //! # Comparison with std
 251 //!
 252 //! |`!Sync` types         | Access Mode            | Drawbacks                                     |
 253 //! |----------------------|------------------------|-----------------------------------------------|
 254 //! |`Cell<T>`             | `T`                    | requires `T: Copy` for `get`                  |
 255 //! |`RefCell<T>`          | `RefMut<T>` / `Ref<T>` | may panic at runtime                          |
 256 //! |`unsync::OnceCell<T>` | `&T`                   | assignable only once                          |
 257 //!
 258 //! |`Sync` types          | Access Mode            | Drawbacks                                     |
 259 //! |----------------------|------------------------|-----------------------------------------------|
 260 //! |`AtomicT`             | `T`                    | works only with certain `Copy` types          |
 261 //! |`Mutex<T>`            | `MutexGuard<T>`        | may deadlock at runtime, may block the thread |
 262 //! |`sync::OnceCell<T>`   | `&T`                   | assignable only once, may block the thread    |
 263 //!
 264 //! Technically, calling `get_or_init` will also cause a panic or a deadlock if it recursively calls
 265 //! itself. However, because the assignment can happen only once, such cases should be more rare than
 266 //! equivalents with `RefCell` and `Mutex`.
 267 //!
 268 //! # Minimum Supported `rustc` Version
 269 //!
 270 //! This crate's minimum supported `rustc` version is `1.36.0`.
 271 //!
 272 //! If only the `std` feature is enabled, MSRV will be updated conservatively.
 273 //! When using other features, like `parking_lot`, MSRV might be updated more frequently, up to the latest stable.
 274 //! In both cases, increasing MSRV is *not* considered a semver-breaking change.
 275 //!
 276 //! # Implementation details
 277 //!
 278 //! The implementation is based on the [`lazy_static`](https://github.com/rust-lang-nursery/lazy-static.rs/)
 279 //! and [`lazy_cell`](https://github.com/indiv0/lazycell/) crates and [`std::sync::Once`]. In some sense,
 280 //! `once_cell` just streamlines and unifies those APIs.
 281 //!
 282 //! To implement a sync flavor of `OnceCell`, this crates uses either a custom
 283 //! re-implementation of `std::sync::Once` or `parking_lot::Mutex`. This is
 284 //! controlled by the `parking_lot` feature (disabled by default). Performance
 285 //! is the same for both cases, but the `parking_lot` based `OnceCell<T>` is
 286 //! smaller by up to 16 bytes.
 287 //!
 288 //! This crate uses `unsafe`.
 289 //!
 290 //! [`std::sync::Once`]: https://doc.rust-lang.org/std/sync/struct.Once.html
 291 //!
 292 //! # F.A.Q.
 293 //!
 294 //! **Should I use lazy_static or once_cell?**
 295 //!
 296 //! To the first approximation, `once_cell` is both more flexible and more convenient than `lazy_static`
 297 //! and should be preferred.
 298 //!
 299 //! Unlike `once_cell`, `lazy_static` supports spinlock-based implementation of blocking which works with
 300 //! `#![no_std]`.
 301 //!
 302 //! `lazy_static` has received significantly more real world testing, but `once_cell` is also a widely
 303 //! used crate.
 304 //!
 305 //! **Should I use the sync or unsync flavor?**
 306 //!
 307 //! Because Rust compiler checks thread safety for you, it's impossible to accidentally use `unsync` where
 308 //! `sync` is required. So, use `unsync` in single-threaded code and `sync` in multi-threaded. It's easy
 309 //! to switch between the two if code becomes multi-threaded later.
 310 //!
 311 //! At the moment, `unsync` has an additional benefit that reentrant initialization causes a panic, which
 312 //! might be easier to debug than a deadlock.
 313 //!
 314 //! # Related crates
 315 //!
 316 //! * [double-checked-cell](https://github.com/niklasf/double-checked-cell)
 317 //! * [lazy-init](https://crates.io/crates/lazy-init)
 318 //! * [lazycell](https://crates.io/crates/lazycell)
 319 //! * [mitochondria](https://crates.io/crates/mitochondria)
 320 //! * [lazy_static](https://crates.io/crates/lazy_static)
 321 //!
 322 //! Most of this crate's functionality is available in `std` in nightly Rust.
 323 //! See the [tracking issue](https://github.com/rust-lang/rust/issues/74465).
 324
 325 #![cfg_attr(not(feature = "std"), no_std)]
 326
 327 #[cfg(feature = "alloc")]
 328 extern crate alloc;
 329
 330 #[cfg(feature = "std")]
 331 #[cfg(feature = "parking_lot")]
 332 #[path = "imp_pl.rs"]
 333 mod imp;
 334
 335 #[cfg(feature = "std")]
 336 #[cfg(not(feature = "parking_lot"))]
 337 #[path = "imp_std.rs"]
 338 mod imp;
 339
 340 /// Single-threaded version of `OnceCell`.
 341 pub mod unsync {
 342     use core::{
 343         cell::{Cell, UnsafeCell},
 344         fmt, hint, mem,
 345         ops::{Deref, DerefMut},
 346     };
 347
 348     #[cfg(feature = "std")]
 349     use std::panic::{RefUnwindSafe, UnwindSafe};
 350
 351     /// A cell which can be written to only once. It is not thread safe.
 352     ///
 353     /// Unlike [`std::cell::RefCell`], a `OnceCell` provides simple `&`
 354     /// references to the contents.
 355     ///
 356     /// [`std::cell::RefCell`]: https://doc.rust-lang.org/std/cell/struct.RefCell.html
 357     ///
 358     /// # Example
 359     /// ```
 360     /// use once_cell::unsync::OnceCell;
 361     ///
 362     /// let cell = OnceCell::new();
 363     /// assert!(cell.get().is_none());
 364     ///
 365     /// let value: &String = cell.get_or_init(|| {
 366     ///     "Hello, World!".to_string()
 367     /// });
 368     /// assert_eq!(value, "Hello, World!");
 369     /// assert!(cell.get().is_some());
 370     /// ```
 371     pub struct OnceCell<T> {
 372         // Invariant: written to at most once.
 373         inner: UnsafeCell<Option<T>>,
 374     }
 375
 376     // Similarly to a `Sync` bound on `sync::OnceCell`, we can use
 377     // `&unsync::OnceCell` to sneak a `T` through `catch_unwind`,
 378     // by initializing the cell in closure and extracting the value in the
 379     // `Drop`.
 380     #[cfg(feature = "std")]
 381     impl<T: RefUnwindSafe + UnwindSafe> RefUnwindSafe for OnceCell<T> {}
 382     #[cfg(feature = "std")]
 383     impl<T: UnwindSafe> UnwindSafe for OnceCell<T> {}
 384
 385     impl<T> Default for OnceCell<T> {
 386         fn default() -> Self {
 387             Self::new()
 388         }
 389     }
 390
 391     impl<T: fmt::Debug> fmt::Debug for OnceCell<T> {
 392         fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
 393             match self.get() {
 394                 Some(v) => f.debug_tuple("OnceCell").field(v).finish(),
 395                 None => f.write_str("OnceCell(Uninit)"),
 396             }
 397         }
 398     }
 399
 400     impl<T: Clone> Clone for OnceCell<T> {
 401         fn clone(&self) -> OnceCell<T> {
 402             let res = OnceCell::new();
 403             if let Some(value) = self.get() {
 404                 match res.set(value.clone()) {
 405                     Ok(()) => (),
 406                     Err(_) => unreachable!(),
 407                 }
 408             }
 409             res
 410         }
 411     }
 412
 413     impl<T: PartialEq> PartialEq for OnceCell<T> {
 414         fn eq(&self, other: &Self) -> bool {
 415             self.get() == other.get()
 416         }
 417     }
 418
 419     impl<T: Eq> Eq for OnceCell<T> {}
 420
 421     impl<T> From<T> for OnceCell<T> {
 422         fn from(value: T) -> Self {
 423             OnceCell { inner: UnsafeCell::new(Some(value)) }
 424         }
 425     }
 426
 427     impl<T> OnceCell<T> {
 428         /// Creates a new empty cell.
 429         pub const fn new() -> OnceCell<T> {
 430             OnceCell { inner: UnsafeCell::new(None) }
 431         }
 432
 433         /// Gets a reference to the underlying value.
 434         ///
 435         /// Returns `None` if the cell is empty.
 436         pub fn get(&self) -> Option<&T> {
 437             // Safe due to `inner`'s invariant
 438             unsafe { &*self.inner.get() }.as_ref()
 439         }
 440
 441         /// Gets a mutable reference to the underlying value.
 442         ///
 443         /// Returns `None` if the cell is empty.
 444         pub fn get_mut(&mut self) -> Option<&mut T> {
 445             // Safe because we have unique access
 446             unsafe { &mut *self.inner.get() }.as_mut()
 447         }
 448
 449         /// Sets the contents of this cell to `value`.
 450         ///
 451         /// Returns `Ok(())` if the cell was empty and `Err(value)` if it was
 452         /// full.
 453         ///
 454         /// # Example
 455         /// ```
 456         /// use once_cell::unsync::OnceCell;
 457         ///
 458         /// let cell = OnceCell::new();
 459         /// assert!(cell.get().is_none());
 460         ///
 461         /// assert_eq!(cell.set(92), Ok(()));
 462         /// assert_eq!(cell.set(62), Err(62));
 463         ///
 464         /// assert!(cell.get().is_some());
 465         /// ```
 466         pub fn set(&self, value: T) -> Result<(), T> {
 467             match self.try_insert(value) {
 468                 Ok(_) => Ok(()),
 469                 Err((_, value)) => Err(value),
 470             }
 471         }
 472
 473         /// Like [`set`](Self::set), but also returns a referce to the final cell value.
 474         ///
 475         /// # Example
 476         /// ```
 477         /// use once_cell::unsync::OnceCell;
 478         ///
 479         /// let cell = OnceCell::new();
 480         /// assert!(cell.get().is_none());
 481         ///
 482         /// assert_eq!(cell.try_insert(92), Ok(&92));
 483         /// assert_eq!(cell.try_insert(62), Err((&92, 62)));
 484         ///
 485         /// assert!(cell.get().is_some());
 486         /// ```
 487         pub fn try_insert(&self, value: T) -> Result<&T, (&T, T)> {
 488             if let Some(old) = self.get() {
 489                 return Err((old, value));
 490             }
 491             let slot = unsafe { &mut *self.inner.get() };
 492             // This is the only place where we set the slot, no races
 493             // due to reentrancy/concurrency are possible, and we've
 494             // checked that slot is currently `None`, so this write
 495             // maintains the `inner`'s invariant.
 496             *slot = Some(value);
 497             Ok(match &*slot {
 498                 Some(value) => value,
 499                 None => unsafe { hint::unreachable_unchecked() },
 500             })
 501         }
 502
 503         /// Gets the contents of the cell, initializing it with `f`
 504         /// if the cell was empty.
 505         ///
 506         /// # Panics
 507         ///
 508         /// If `f` panics, the panic is propagated to the caller, and the cell
 509         /// remains uninitialized.
 510         ///
 511         /// It is an error to reentrantly initialize the cell from `f`. Doing
 512         /// so results in a panic.
 513         ///
 514         /// # Example
 515         /// ```
 516         /// use once_cell::unsync::OnceCell;
 517         ///
 518         /// let cell = OnceCell::new();
 519         /// let value = cell.get_or_init(|| 92);
 520         /// assert_eq!(value, &92);
 521         /// let value = cell.get_or_init(|| unreachable!());
 522         /// assert_eq!(value, &92);
 523         /// ```
 524         pub fn get_or_init<F>(&self, f: F) -> &T
 525         where
 526             F: FnOnce() -> T,
 527         {
 528             enum Void {}
 529             match self.get_or_try_init(|| Ok::<T, Void>(f())) {
 530                 Ok(val) => val,
 531                 Err(void) => match void {},
 532             }
 533         }
 534
 535         /// Gets the contents of the cell, initializing it with `f` if
 536         /// the cell was empty. If the cell was empty and `f` failed, an
 537         /// error is returned.
 538         ///
 539         /// # Panics
 540         ///
 541         /// If `f` panics, the panic is propagated to the caller, and the cell
 542         /// remains uninitialized.
 543         ///
 544         /// It is an error to reentrantly initialize the cell from `f`. Doing
 545         /// so results in a panic.
 546         ///
 547         /// # Example
 548         /// ```
 549         /// use once_cell::unsync::OnceCell;
 550         ///
 551         /// let cell = OnceCell::new();
 552         /// assert_eq!(cell.get_or_try_init(|| Err(())), Err(()));
 553         /// assert!(cell.get().is_none());
 554         /// let value = cell.get_or_try_init(|| -> Result<i32, ()> {
 555         ///     Ok(92)
 556         /// });
 557         /// assert_eq!(value, Ok(&92));
 558         /// assert_eq!(cell.get(), Some(&92))
 559         /// ```
 560         pub fn get_or_try_init<F, E>(&self, f: F) -> Result<&T, E>
 561         where
 562             F: FnOnce() -> Result<T, E>,
 563         {
 564             if let Some(val) = self.get() {
 565                 return Ok(val);
 566             }
 567             let val = f()?;
 568             // Note that *some* forms of reentrant initialization might lead to
 569             // UB (see `reentrant_init` test). I believe that just removing this
 570             // `assert`, while keeping `set/get` would be sound, but it seems
 571             // better to panic, rather than to silently use an old value.
 572             assert!(self.set(val).is_ok(), "reentrant init");
 573             Ok(self.get().unwrap())
 574         }
 575
 576         /// Takes the value out of this `OnceCell`, moving it back to an uninitialized state.
 577         ///
 578         /// Has no effect and returns `None` if the `OnceCell` hasn't been initialized.
 579         ///
 580         /// # Examples
 581         ///
 582         /// ```
 583         /// use once_cell::unsync::OnceCell;
 584         ///
 585         /// let mut cell: OnceCell<String> = OnceCell::new();
 586         /// assert_eq!(cell.take(), None);
 587         ///
 588         /// let mut cell = OnceCell::new();
 589         /// cell.set("hello".to_string()).unwrap();
 590         /// assert_eq!(cell.take(), Some("hello".to_string()));
 591         /// assert_eq!(cell.get(), None);
 592         /// ```
 593         pub fn take(&mut self) -> Option<T> {
 594             mem::replace(self, Self::default()).into_inner()
 595         }
 596
 597         /// Consumes the `OnceCell`, returning the wrapped value.
 598         ///
 599         /// Returns `None` if the cell was empty.
 600         ///
 601         /// # Examples
 602         ///
 603         /// ```
 604         /// use once_cell::unsync::OnceCell;
 605         ///
 606         /// let cell: OnceCell<String> = OnceCell::new();
 607         /// assert_eq!(cell.into_inner(), None);
 608         ///
 609         /// let cell = OnceCell::new();
 610         /// cell.set("hello".to_string()).unwrap();
 611         /// assert_eq!(cell.into_inner(), Some("hello".to_string()));
 612         /// ```
 613         pub fn into_inner(self) -> Option<T> {
 614             // Because `into_inner` takes `self` by value, the compiler statically verifies
 615             // that it is not currently borrowed. So it is safe to move out `Option<T>`.
 616             self.inner.into_inner()
 617         }
 618     }
 619
 620     /// A value which is initialized on the first access.
 621     ///
 622     /// # Example
 623     /// ```
 624     /// use once_cell::unsync::Lazy;
 625     ///
 626     /// let lazy: Lazy<i32> = Lazy::new(|| {
 627     ///     println!("initializing");
 628     ///     92
 629     /// });
 630     /// println!("ready");
 631     /// println!("{}", *lazy);
 632     /// println!("{}", *lazy);
 633     ///
 634     /// // Prints:
 635     /// //   ready
 636     /// //   initializing
 637     /// //   92
 638     /// //   92
 639     /// ```
 640     pub struct Lazy<T, F = fn() -> T> {
 641         cell: OnceCell<T>,
 642         init: Cell<Option<F>>,
 643     }
 644
 645     #[cfg(feature = "std")]
 646     impl<T, F: RefUnwindSafe> RefUnwindSafe for Lazy<T, F> where OnceCell<T>: RefUnwindSafe {}
 647
 648     impl<T: fmt::Debug, F> fmt::Debug for Lazy<T, F> {
 649         fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
 650             f.debug_struct("Lazy").field("cell", &self.cell).field("init", &"..").finish()
 651         }
 652     }
 653
 654     impl<T, F> Lazy<T, F> {
 655         /// Creates a new lazy value with the given initializing function.
 656         ///
 657         /// # Example
 658         /// ```
 659         /// # fn main() {
 660         /// use once_cell::unsync::Lazy;
 661         ///
 662         /// let hello = "Hello, World!".to_string();
 663         ///
 664         /// let lazy = Lazy::new(|| hello.to_uppercase());
 665         ///
 666         /// assert_eq!(&*lazy, "HELLO, WORLD!");
 667         /// # }
 668         /// ```
 669         pub const fn new(init: F) -> Lazy<T, F> {
 670             Lazy { cell: OnceCell::new(), init: Cell::new(Some(init)) }
 671         }
 672
 673         /// Consumes this `Lazy` returning the stored value.
 674         ///
 675         /// Returns `Ok(value)` if `Lazy` is initialized and `Err(f)` otherwise.
 676         pub fn into_value(this: Lazy<T, F>) -> Result<T, F> {
 677             let cell = this.cell;
 678             let init = this.init;
 679             cell.into_inner().ok_or_else(|| {
 680                 init.take().unwrap_or_else(|| panic!("Lazy instance has previously been poisoned"))
 681             })
 682         }
 683     }
 684
 685     impl<T, F: FnOnce() -> T> Lazy<T, F> {
 686         /// Forces the evaluation of this lazy value and returns a reference to
 687         /// the result.
 688         ///
 689         /// This is equivalent to the `Deref` impl, but is explicit.
 690         ///
 691         /// # Example
 692         /// ```
 693         /// use once_cell::unsync::Lazy;
 694         ///
 695         /// let lazy = Lazy::new(|| 92);
 696         ///
 697         /// assert_eq!(Lazy::force(&lazy), &92);
 698         /// assert_eq!(&*lazy, &92);
 699         /// ```
 700         pub fn force(this: &Lazy<T, F>) -> &T {
 701             this.cell.get_or_init(|| match this.init.take() {
 702                 Some(f) => f(),
 703                 None => panic!("Lazy instance has previously been poisoned"),
 704             })
 705         }
 706     }
 707
 708     impl<T, F: FnOnce() -> T> Deref for Lazy<T, F> {
 709         type Target = T;
 710         fn deref(&self) -> &T {
 711             Lazy::force(self)
 712         }
 713     }
 714
 715     impl<T, F: FnOnce() -> T> DerefMut for Lazy<T, F> {
 716         fn deref_mut(&mut self) -> &mut T {
 717             Lazy::force(self);
 718             self.cell.get_mut().unwrap_or_else(|| unreachable!())
 719         }
 720     }
 721
 722     impl<T: Default> Default for Lazy<T> {
 723         /// Creates a new lazy value using `Default` as the initializing function.
 724         fn default() -> Lazy<T> {
 725             Lazy::new(T::default)
 726         }
 727     }
 728 }
 729
 730 /// Thread-safe, blocking version of `OnceCell`.
 731 #[cfg(feature = "std")]
 732 pub mod sync {
 733     use std::{
 734         cell::Cell,
 735         fmt, mem,
 736         ops::{Deref, DerefMut},
 737         panic::RefUnwindSafe,
 738     };
 739
 740     use crate::imp::OnceCell as Imp;
 741
 742     /// A thread-safe cell which can be written to only once.
 743     ///
 744     /// `OnceCell` provides `&` references to the contents without RAII guards.
 745     ///
 746     /// Reading a non-`None` value out of `OnceCell` establishes a
 747     /// happens-before relationship with a corresponding write. For example, if
 748     /// thread A initializes the cell with `get_or_init(f)`, and thread B
 749     /// subsequently reads the result of this call, B also observes all the side
 750     /// effects of `f`.
 751     ///
 752     /// # Example
 753     /// ```
 754     /// use once_cell::sync::OnceCell;
 755     ///
 756     /// static CELL: OnceCell<String> = OnceCell::new();
 757     /// assert!(CELL.get().is_none());
 758     ///
 759     /// std::thread::spawn(|| {
 760     ///     let value: &String = CELL.get_or_init(|| {
 761     ///         "Hello, World!".to_string()
 762     ///     });
 763     ///     assert_eq!(value, "Hello, World!");
 764     /// }).join().unwrap();
 765     ///
 766     /// let value: Option<&String> = CELL.get();
 767     /// assert!(value.is_some());
 768     /// assert_eq!(value.unwrap().as_str(), "Hello, World!");
 769     /// ```
 770     pub struct OnceCell<T>(Imp<T>);
 771
 772     impl<T> Default for OnceCell<T> {
 773         fn default() -> OnceCell<T> {
 774             OnceCell::new()
 775         }
 776     }
 777
 778     impl<T: fmt::Debug> fmt::Debug for OnceCell<T> {
 779         fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
 780             match self.get() {
 781                 Some(v) => f.debug_tuple("OnceCell").field(v).finish(),
 782                 None => f.write_str("OnceCell(Uninit)"),
 783             }
 784         }
 785     }
 786
 787     impl<T: Clone> Clone for OnceCell<T> {
 788         fn clone(&self) -> OnceCell<T> {
 789             let res = OnceCell::new();
 790             if let Some(value) = self.get() {
 791                 match res.set(value.clone()) {
 792                     Ok(()) => (),
 793                     Err(_) => unreachable!(),
 794                 }
 795             }
 796             res
 797         }
 798     }
 799
 800     impl<T> From<T> for OnceCell<T> {
 801         fn from(value: T) -> Self {
 802             let cell = Self::new();
 803             cell.get_or_init(|| value);
 804             cell
 805         }
 806     }
 807
 808     impl<T: PartialEq> PartialEq for OnceCell<T> {
 809         fn eq(&self, other: &OnceCell<T>) -> bool {
 810             self.get() == other.get()
 811         }
 812     }
 813
 814     impl<T: Eq> Eq for OnceCell<T> {}
 815
 816     impl<T> OnceCell<T> {
 817         /// Creates a new empty cell.
 818         pub const fn new() -> OnceCell<T> {
 819             OnceCell(Imp::new())
 820         }
 821
 822         /// Gets the reference to the underlying value.
 823         ///
 824         /// Returns `None` if the cell is empty, or being initialized. This
 825         /// method never blocks.
 826         pub fn get(&self) -> Option<&T> {
 827             if self.0.is_initialized() {
 828                 // Safe b/c value is initialized.
 829                 Some(unsafe { self.get_unchecked() })
 830             } else {
 831                 None
 832             }
 833         }
 834
 835         /// Gets the mutable reference to the underlying value.
 836         ///
 837         /// Returns `None` if the cell is empty.
 838         pub fn get_mut(&mut self) -> Option<&mut T> {
 839             self.0.get_mut()
 840         }
 841
 842         /// Get the reference to the underlying value, without checking if the
 843         /// cell is initialized.
 844         ///
 845         /// # Safety
 846         ///
 847         /// Caller must ensure that the cell is in initialized state, and that
 848         /// the contents are acquired by (synchronized to) this thread.
 849         pub unsafe fn get_unchecked(&self) -> &T {
 850             self.0.get_unchecked()
 851         }
 852
 853         /// Sets the contents of this cell to `value`.
 854         ///
 855         /// Returns `Ok(())` if the cell was empty and `Err(value)` if it was
 856         /// full.
 857         ///
 858         /// # Example
 859         ///
 860         /// ```
 861         /// use once_cell::sync::OnceCell;
 862         ///
 863         /// static CELL: OnceCell<i32> = OnceCell::new();
 864         ///
 865         /// fn main() {
 866         ///     assert!(CELL.get().is_none());
 867         ///
 868         ///     std::thread::spawn(|| {
 869         ///         assert_eq!(CELL.set(92), Ok(()));
 870         ///     }).join().unwrap();
 871         ///
 872         ///     assert_eq!(CELL.set(62), Err(62));
 873         ///     assert_eq!(CELL.get(), Some(&92));
 874         /// }
 875         /// ```
 876         pub fn set(&self, value: T) -> Result<(), T> {
 877             match self.try_insert(value) {
 878                 Ok(_) => Ok(()),
 879                 Err((_, value)) => Err(value),
 880             }
 881         }
 882
 883         /// Like [`set`](Self::set), but also returns a reference to the final cell value.
 884         ///
 885         /// # Example
 886         ///
 887         /// ```
 888         /// use once_cell::unsync::OnceCell;
 889         ///
 890         /// let cell = OnceCell::new();
 891         /// assert!(cell.get().is_none());
 892         ///
 893         /// assert_eq!(cell.try_insert(92), Ok(&92));
 894         /// assert_eq!(cell.try_insert(62), Err((&92, 62)));
 895         ///
 896         /// assert!(cell.get().is_some());
 897         /// ```
 898         pub fn try_insert(&self, value: T) -> Result<&T, (&T, T)> {
 899             let mut value = Some(value);
 900             let res = self.get_or_init(|| value.take().unwrap());
 901             match value {
 902                 None => Ok(res),
 903                 Some(value) => Err((res, value)),
 904             }
 905         }
 906
 907         /// Gets the contents of the cell, initializing it with `f` if the cell
 908         /// was empty.
 909         ///
 910         /// Many threads may call `get_or_init` concurrently with different
 911         /// initializing functions, but it is guaranteed that only one function
 912         /// will be executed.
 913         ///
 914         /// # Panics
 915         ///
 916         /// If `f` panics, the panic is propagated to the caller, and the cell
 917         /// remains uninitialized.
 918         ///
 919         /// It is an error to reentrantly initialize the cell from `f`. The
 920         /// exact outcome is unspecified. Current implementation deadlocks, but
 921         /// this may be changed to a panic in the future.
 922         ///
 923         /// # Example
 924         /// ```
 925         /// use once_cell::sync::OnceCell;
 926         ///
 927         /// let cell = OnceCell::new();
 928         /// let value = cell.get_or_init(|| 92);
 929         /// assert_eq!(value, &92);
 930         /// let value = cell.get_or_init(|| unreachable!());
 931         /// assert_eq!(value, &92);
 932         /// ```
 933         pub fn get_or_init<F>(&self, f: F) -> &T
 934         where
 935             F: FnOnce() -> T,
 936         {
 937             enum Void {}
 938             match self.get_or_try_init(|| Ok::<T, Void>(f())) {
 939                 Ok(val) => val,
 940                 Err(void) => match void {},
 941             }
 942         }
 943
 944         /// Gets the contents of the cell, initializing it with `f` if
 945         /// the cell was empty. If the cell was empty and `f` failed, an
 946         /// error is returned.
 947         ///
 948         /// # Panics
 949         ///
 950         /// If `f` panics, the panic is propagated to the caller, and
 951         /// the cell remains uninitialized.
 952         ///
 953         /// It is an error to reentrantly initialize the cell from `f`.
 954         /// The exact outcome is unspecified. Current implementation
 955         /// deadlocks, but this may be changed to a panic in the future.
 956         ///
 957         /// # Example
 958         /// ```
 959         /// use once_cell::sync::OnceCell;
 960         ///
 961         /// let cell = OnceCell::new();
 962         /// assert_eq!(cell.get_or_try_init(|| Err(())), Err(()));
 963         /// assert!(cell.get().is_none());
 964         /// let value = cell.get_or_try_init(|| -> Result<i32, ()> {
 965         ///     Ok(92)
 966         /// });
 967         /// assert_eq!(value, Ok(&92));
 968         /// assert_eq!(cell.get(), Some(&92))
 969         /// ```
 970         pub fn get_or_try_init<F, E>(&self, f: F) -> Result<&T, E>
 971         where
 972             F: FnOnce() -> Result<T, E>,
 973         {
 974             // Fast path check
 975             if let Some(value) = self.get() {
 976                 return Ok(value);
 977             }
 978             self.0.initialize(f)?;
 979
 980             // Safe b/c value is initialized.
 981             debug_assert!(self.0.is_initialized());
 982             Ok(unsafe { self.get_unchecked() })
 983         }
 984
 985         /// Takes the value out of this `OnceCell`, moving it back to an uninitialized state.
 986         ///
 987         /// Has no effect and returns `None` if the `OnceCell` hasn't been initialized.
 988         ///
 989         /// # Examples
 990         ///
 991         /// ```
 992         /// use once_cell::sync::OnceCell;
 993         ///
 994         /// let mut cell: OnceCell<String> = OnceCell::new();
 995         /// assert_eq!(cell.take(), None);
 996         ///
 997         /// let mut cell = OnceCell::new();
 998         /// cell.set("hello".to_string()).unwrap();
 999         /// assert_eq!(cell.take(), Some("hello".to_string()));
1000         /// assert_eq!(cell.get(), None);
1001         /// ```
1002         pub fn take(&mut self) -> Option<T> {
1003             mem::replace(self, Self::default()).into_inner()
1004         }
1005
1006         /// Consumes the `OnceCell`, returning the wrapped value. Returns
1007         /// `None` if the cell was empty.
1008         ///
1009         /// # Examples
1010         ///
1011         /// ```
1012         /// use once_cell::sync::OnceCell;
1013         ///
1014         /// let cell: OnceCell<String> = OnceCell::new();
1015         /// assert_eq!(cell.into_inner(), None);
1016         ///
1017         /// let cell = OnceCell::new();
1018         /// cell.set("hello".to_string()).unwrap();
1019         /// assert_eq!(cell.into_inner(), Some("hello".to_string()));
1020         /// ```
1021         pub fn into_inner(self) -> Option<T> {
1022             self.0.into_inner()
1023         }
1024     }
1025
1026     /// A value which is initialized on the first access.
1027     ///
1028     /// This type is thread-safe and can be used in statics.
1029     ///
1030     /// # Example
1031     ///
1032     /// ```
1033     /// use std::collections::HashMap;
1034     ///
1035     /// use once_cell::sync::Lazy;
1036     ///
1037     /// static HASHMAP: Lazy<HashMap<i32, String>> = Lazy::new(|| {
1038     ///     println!("initializing");
1039     ///     let mut m = HashMap::new();
1040     ///     m.insert(13, "Spica".to_string());
1041     ///     m.insert(74, "Hoyten".to_string());
1042     ///     m
1043     /// });
1044     ///
1045     /// fn main() {
1046     ///     println!("ready");
1047     ///     std::thread::spawn(|| {
1048     ///         println!("{:?}", HASHMAP.get(&13));
1049     ///     }).join().unwrap();
1050     ///     println!("{:?}", HASHMAP.get(&74));
1051     ///
1052     ///     // Prints:
1053     ///     //   ready
1054     ///     //   initializing
1055     ///     //   Some("Spica")
1056     ///     //   Some("Hoyten")
1057     /// }
1058     /// ```
1059     pub struct Lazy<T, F = fn() -> T> {
1060         cell: OnceCell<T>,
1061         init: Cell<Option<F>>,
1062     }
1063
1064     impl<T: fmt::Debug, F> fmt::Debug for Lazy<T, F> {
1065         fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
1066             f.debug_struct("Lazy").field("cell", &self.cell).field("init", &"..").finish()
1067         }
1068     }
1069
1070     // We never create a `&F` from a `&Lazy<T, F>` so it is fine to not impl
1071     // `Sync` for `F`. we do create a `&mut Option<F>` in `force`, but this is
1072     // properly synchronized, so it only happens once so it also does not
1073     // contribute to this impl.
1074     unsafe impl<T, F: Send> Sync for Lazy<T, F> where OnceCell<T>: Sync {}
1075     // auto-derived `Send` impl is OK.
1076
1077     #[cfg(feature = "std")]
1078     impl<T, F: RefUnwindSafe> RefUnwindSafe for Lazy<T, F> where OnceCell<T>: RefUnwindSafe {}
1079
1080     impl<T, F> Lazy<T, F> {
1081         /// Creates a new lazy value with the given initializing
1082         /// function.
1083         pub const fn new(f: F) -> Lazy<T, F> {
1084             Lazy { cell: OnceCell::new(), init: Cell::new(Some(f)) }
1085         }
1086
1087         /// Consumes this `Lazy` returning the stored value.
1088         ///
1089         /// Returns `Ok(value)` if `Lazy` is initialized and `Err(f)` otherwise.
1090         pub fn into_value(this: Lazy<T, F>) -> Result<T, F> {
1091             let cell = this.cell;
1092             let init = this.init;
1093             cell.into_inner().ok_or_else(|| {
1094                 init.take().unwrap_or_else(|| panic!("Lazy instance has previously been poisoned"))
1095             })
1096         }
1097     }
1098
1099     impl<T, F: FnOnce() -> T> Lazy<T, F> {
1100         /// Forces the evaluation of this lazy value and
1101         /// returns a reference to the result. This is equivalent
1102         /// to the `Deref` impl, but is explicit.
1103         ///
1104         /// # Example
1105         /// ```
1106         /// use once_cell::sync::Lazy;
1107         ///
1108         /// let lazy = Lazy::new(|| 92);
1109         ///
1110         /// assert_eq!(Lazy::force(&lazy), &92);
1111         /// assert_eq!(&*lazy, &92);
1112         /// ```
1113         pub fn force(this: &Lazy<T, F>) -> &T {
1114             this.cell.get_or_init(|| match this.init.take() {
1115                 Some(f) => f(),
1116                 None => panic!("Lazy instance has previously been poisoned"),
1117             })
1118         }
1119     }
1120
1121     impl<T, F: FnOnce() -> T> Deref for Lazy<T, F> {
1122         type Target = T;
1123         fn deref(&self) -> &T {
1124             Lazy::force(self)
1125         }
1126     }
1127
1128     impl<T, F: FnOnce() -> T> DerefMut for Lazy<T, F> {
1129         fn deref_mut(&mut self) -> &mut T {
1130             Lazy::force(self);
1131             self.cell.get_mut().unwrap_or_else(|| unreachable!())
1132         }
1133     }
1134
1135     impl<T: Default> Default for Lazy<T> {
1136         /// Creates a new lazy value using `Default` as the initializing function.
1137         fn default() -> Lazy<T> {
1138             Lazy::new(T::default)
1139         }
1140     }
1141
1142     /// ```compile_fail
1143     /// struct S(*mut ());
1144     /// unsafe impl Sync for S {}
1145     ///
1146     /// fn share<T: Sync>(_: &T) {}
1147     /// share(&once_cell::sync::OnceCell::<S>::new());
1148     /// ```
1149     ///
1150     /// ```compile_fail
1151     /// struct S(*mut ());
1152     /// unsafe impl Sync for S {}
1153     ///
1154     /// fn share<T: Sync>(_: &T) {}
1155     /// share(&once_cell::sync::Lazy::<S>::new(|| unimplemented!()));
1156     /// ```
1157     fn _dummy() {}
1158 }
1159
1160 #[cfg(feature = "race")]
1161 pub mod race;
1162
1163 #[cfg(feature = "std")]
1164 unsafe fn take_unchecked<T>(val: &mut Option<T>) -> T {
1165     match val.take() {
1166         Some(it) => it,
1167         None => {
1168             debug_assert!(false);
1169             std::hint::unreachable_unchecked()
1170         }
1171     }
1172 }