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