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> {
default() -> Self386 fn default() -> Self {
387 Self::new()
388 }
389 }
390
391 impl<T: fmt::Debug> fmt::Debug for OnceCell<T> {
fmt(&self, f: &mut fmt::Formatter) -> fmt::Result392 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> {
clone(&self) -> 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> {
eq(&self, other: &Self) -> bool414 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> {
from(value: T) -> Self422 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.
new() -> OnceCell<T>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.
get(&self) -> Option<&T>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 ///
445 /// This method is allowed to violate the invariant of writing to a `OnceCell`
446 /// at most once because it requires `&mut` access to `self`. As with all
447 /// interior mutability, `&mut` access permits arbitrary modification:
448 ///
449 /// ```
450 /// use once_cell::unsync::OnceCell;
451 ///
452 /// let mut cell: OnceCell<u32> = OnceCell::new();
453 /// cell.set(92).unwrap();
454 /// cell = OnceCell::new();
455 /// ```
get_mut(&mut self) -> Option<&mut T>456 pub fn get_mut(&mut self) -> Option<&mut T> {
457 // Safe because we have unique access
458 unsafe { &mut *self.inner.get() }.as_mut()
459 }
460
461 /// Sets the contents of this cell to `value`.
462 ///
463 /// Returns `Ok(())` if the cell was empty and `Err(value)` if it was
464 /// full.
465 ///
466 /// # Example
467 /// ```
468 /// use once_cell::unsync::OnceCell;
469 ///
470 /// let cell = OnceCell::new();
471 /// assert!(cell.get().is_none());
472 ///
473 /// assert_eq!(cell.set(92), Ok(()));
474 /// assert_eq!(cell.set(62), Err(62));
475 ///
476 /// assert!(cell.get().is_some());
477 /// ```
set(&self, value: T) -> Result<(), T>478 pub fn set(&self, value: T) -> Result<(), T> {
479 match self.try_insert(value) {
480 Ok(_) => Ok(()),
481 Err((_, value)) => Err(value),
482 }
483 }
484
485 /// Like [`set`](Self::set), but also returns a referce to the final cell value.
486 ///
487 /// # Example
488 /// ```
489 /// use once_cell::unsync::OnceCell;
490 ///
491 /// let cell = OnceCell::new();
492 /// assert!(cell.get().is_none());
493 ///
494 /// assert_eq!(cell.try_insert(92), Ok(&92));
495 /// assert_eq!(cell.try_insert(62), Err((&92, 62)));
496 ///
497 /// assert!(cell.get().is_some());
498 /// ```
try_insert(&self, value: T) -> Result<&T, (&T, T)>499 pub fn try_insert(&self, value: T) -> Result<&T, (&T, T)> {
500 if let Some(old) = self.get() {
501 return Err((old, value));
502 }
503 let slot = unsafe { &mut *self.inner.get() };
504 // This is the only place where we set the slot, no races
505 // due to reentrancy/concurrency are possible, and we've
506 // checked that slot is currently `None`, so this write
507 // maintains the `inner`'s invariant.
508 *slot = Some(value);
509 Ok(match &*slot {
510 Some(value) => value,
511 None => unsafe { hint::unreachable_unchecked() },
512 })
513 }
514
515 /// Gets the contents of the cell, initializing it with `f`
516 /// if the cell was empty.
517 ///
518 /// # Panics
519 ///
520 /// If `f` panics, the panic is propagated to the caller, and the cell
521 /// remains uninitialized.
522 ///
523 /// It is an error to reentrantly initialize the cell from `f`. Doing
524 /// so results in a panic.
525 ///
526 /// # Example
527 /// ```
528 /// use once_cell::unsync::OnceCell;
529 ///
530 /// let cell = OnceCell::new();
531 /// let value = cell.get_or_init(|| 92);
532 /// assert_eq!(value, &92);
533 /// let value = cell.get_or_init(|| unreachable!());
534 /// assert_eq!(value, &92);
535 /// ```
get_or_init<F>(&self, f: F) -> &T where F: FnOnce() -> T,536 pub fn get_or_init<F>(&self, f: F) -> &T
537 where
538 F: FnOnce() -> T,
539 {
540 enum Void {}
541 match self.get_or_try_init(|| Ok::<T, Void>(f())) {
542 Ok(val) => val,
543 Err(void) => match void {},
544 }
545 }
546
547 /// Gets the contents of the cell, initializing it with `f` if
548 /// the cell was empty. If the cell was empty and `f` failed, an
549 /// error is returned.
550 ///
551 /// # Panics
552 ///
553 /// If `f` panics, the panic is propagated to the caller, and the cell
554 /// remains uninitialized.
555 ///
556 /// It is an error to reentrantly initialize the cell from `f`. Doing
557 /// so results in a panic.
558 ///
559 /// # Example
560 /// ```
561 /// use once_cell::unsync::OnceCell;
562 ///
563 /// let cell = OnceCell::new();
564 /// assert_eq!(cell.get_or_try_init(|| Err(())), Err(()));
565 /// assert!(cell.get().is_none());
566 /// let value = cell.get_or_try_init(|| -> Result<i32, ()> {
567 /// Ok(92)
568 /// });
569 /// assert_eq!(value, Ok(&92));
570 /// assert_eq!(cell.get(), Some(&92))
571 /// ```
get_or_try_init<F, E>(&self, f: F) -> Result<&T, E> where F: FnOnce() -> Result<T, E>,572 pub fn get_or_try_init<F, E>(&self, f: F) -> Result<&T, E>
573 where
574 F: FnOnce() -> Result<T, E>,
575 {
576 if let Some(val) = self.get() {
577 return Ok(val);
578 }
579 let val = f()?;
580 // Note that *some* forms of reentrant initialization might lead to
581 // UB (see `reentrant_init` test). I believe that just removing this
582 // `assert`, while keeping `set/get` would be sound, but it seems
583 // better to panic, rather than to silently use an old value.
584 assert!(self.set(val).is_ok(), "reentrant init");
585 Ok(self.get().unwrap())
586 }
587
588 /// Takes the value out of this `OnceCell`, moving it back to an uninitialized state.
589 ///
590 /// Has no effect and returns `None` if the `OnceCell` hasn't been initialized.
591 ///
592 /// # Examples
593 ///
594 /// ```
595 /// use once_cell::unsync::OnceCell;
596 ///
597 /// let mut cell: OnceCell<String> = OnceCell::new();
598 /// assert_eq!(cell.take(), None);
599 ///
600 /// let mut cell = OnceCell::new();
601 /// cell.set("hello".to_string()).unwrap();
602 /// assert_eq!(cell.take(), Some("hello".to_string()));
603 /// assert_eq!(cell.get(), None);
604 /// ```
605 ///
606 /// This method is allowed to violate the invariant of writing to a `OnceCell`
607 /// at most once because it requires `&mut` access to `self`. As with all
608 /// interior mutability, `&mut` access permits arbitrary modification:
609 ///
610 /// ```
611 /// use once_cell::unsync::OnceCell;
612 ///
613 /// let mut cell: OnceCell<u32> = OnceCell::new();
614 /// cell.set(92).unwrap();
615 /// cell = OnceCell::new();
616 /// ```
take(&mut self) -> Option<T>617 pub fn take(&mut self) -> Option<T> {
618 mem::replace(self, Self::default()).into_inner()
619 }
620
621 /// Consumes the `OnceCell`, returning the wrapped value.
622 ///
623 /// Returns `None` if the cell was empty.
624 ///
625 /// # Examples
626 ///
627 /// ```
628 /// use once_cell::unsync::OnceCell;
629 ///
630 /// let cell: OnceCell<String> = OnceCell::new();
631 /// assert_eq!(cell.into_inner(), None);
632 ///
633 /// let cell = OnceCell::new();
634 /// cell.set("hello".to_string()).unwrap();
635 /// assert_eq!(cell.into_inner(), Some("hello".to_string()));
636 /// ```
into_inner(self) -> Option<T>637 pub fn into_inner(self) -> Option<T> {
638 // Because `into_inner` takes `self` by value, the compiler statically verifies
639 // that it is not currently borrowed. So it is safe to move out `Option<T>`.
640 self.inner.into_inner()
641 }
642 }
643
644 /// A value which is initialized on the first access.
645 ///
646 /// # Example
647 /// ```
648 /// use once_cell::unsync::Lazy;
649 ///
650 /// let lazy: Lazy<i32> = Lazy::new(|| {
651 /// println!("initializing");
652 /// 92
653 /// });
654 /// println!("ready");
655 /// println!("{}", *lazy);
656 /// println!("{}", *lazy);
657 ///
658 /// // Prints:
659 /// // ready
660 /// // initializing
661 /// // 92
662 /// // 92
663 /// ```
664 pub struct Lazy<T, F = fn() -> T> {
665 cell: OnceCell<T>,
666 init: Cell<Option<F>>,
667 }
668
669 #[cfg(feature = "std")]
670 impl<T, F: RefUnwindSafe> RefUnwindSafe for Lazy<T, F> where OnceCell<T>: RefUnwindSafe {}
671
672 impl<T: fmt::Debug, F> fmt::Debug for Lazy<T, F> {
fmt(&self, f: &mut fmt::Formatter) -> fmt::Result673 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
674 f.debug_struct("Lazy").field("cell", &self.cell).field("init", &"..").finish()
675 }
676 }
677
678 impl<T, F> Lazy<T, F> {
679 /// Creates a new lazy value with the given initializing function.
680 ///
681 /// # Example
682 /// ```
683 /// # fn main() {
684 /// use once_cell::unsync::Lazy;
685 ///
686 /// let hello = "Hello, World!".to_string();
687 ///
688 /// let lazy = Lazy::new(|| hello.to_uppercase());
689 ///
690 /// assert_eq!(&*lazy, "HELLO, WORLD!");
691 /// # }
692 /// ```
new(init: F) -> Lazy<T, F>693 pub const fn new(init: F) -> Lazy<T, F> {
694 Lazy { cell: OnceCell::new(), init: Cell::new(Some(init)) }
695 }
696
697 /// Consumes this `Lazy` returning the stored value.
698 ///
699 /// Returns `Ok(value)` if `Lazy` is initialized and `Err(f)` otherwise.
into_value(this: Lazy<T, F>) -> Result<T, F>700 pub fn into_value(this: Lazy<T, F>) -> Result<T, F> {
701 let cell = this.cell;
702 let init = this.init;
703 cell.into_inner().ok_or_else(|| {
704 init.take().unwrap_or_else(|| panic!("Lazy instance has previously been poisoned"))
705 })
706 }
707 }
708
709 impl<T, F: FnOnce() -> T> Lazy<T, F> {
710 /// Forces the evaluation of this lazy value and returns a reference to
711 /// the result.
712 ///
713 /// This is equivalent to the `Deref` impl, but is explicit.
714 ///
715 /// # Example
716 /// ```
717 /// use once_cell::unsync::Lazy;
718 ///
719 /// let lazy = Lazy::new(|| 92);
720 ///
721 /// assert_eq!(Lazy::force(&lazy), &92);
722 /// assert_eq!(&*lazy, &92);
723 /// ```
force(this: &Lazy<T, F>) -> &T724 pub fn force(this: &Lazy<T, F>) -> &T {
725 this.cell.get_or_init(|| match this.init.take() {
726 Some(f) => f(),
727 None => panic!("Lazy instance has previously been poisoned"),
728 })
729 }
730 }
731
732 impl<T, F: FnOnce() -> T> Deref for Lazy<T, F> {
733 type Target = T;
deref(&self) -> &T734 fn deref(&self) -> &T {
735 Lazy::force(self)
736 }
737 }
738
739 impl<T, F: FnOnce() -> T> DerefMut for Lazy<T, F> {
deref_mut(&mut self) -> &mut T740 fn deref_mut(&mut self) -> &mut T {
741 Lazy::force(self);
742 self.cell.get_mut().unwrap_or_else(|| unreachable!())
743 }
744 }
745
746 impl<T: Default> Default for Lazy<T> {
747 /// Creates a new lazy value using `Default` as the initializing function.
default() -> Lazy<T>748 fn default() -> Lazy<T> {
749 Lazy::new(T::default)
750 }
751 }
752 }
753
754 /// Thread-safe, blocking version of `OnceCell`.
755 #[cfg(feature = "std")]
756 pub mod sync {
757 use std::{
758 cell::Cell,
759 fmt, mem,
760 ops::{Deref, DerefMut},
761 panic::RefUnwindSafe,
762 };
763
764 use crate::{imp::OnceCell as Imp, take_unchecked};
765
766 /// A thread-safe cell which can be written to only once.
767 ///
768 /// `OnceCell` provides `&` references to the contents without RAII guards.
769 ///
770 /// Reading a non-`None` value out of `OnceCell` establishes a
771 /// happens-before relationship with a corresponding write. For example, if
772 /// thread A initializes the cell with `get_or_init(f)`, and thread B
773 /// subsequently reads the result of this call, B also observes all the side
774 /// effects of `f`.
775 ///
776 /// # Example
777 /// ```
778 /// use once_cell::sync::OnceCell;
779 ///
780 /// static CELL: OnceCell<String> = OnceCell::new();
781 /// assert!(CELL.get().is_none());
782 ///
783 /// std::thread::spawn(|| {
784 /// let value: &String = CELL.get_or_init(|| {
785 /// "Hello, World!".to_string()
786 /// });
787 /// assert_eq!(value, "Hello, World!");
788 /// }).join().unwrap();
789 ///
790 /// let value: Option<&String> = CELL.get();
791 /// assert!(value.is_some());
792 /// assert_eq!(value.unwrap().as_str(), "Hello, World!");
793 /// ```
794 pub struct OnceCell<T>(Imp<T>);
795
796 impl<T> Default for OnceCell<T> {
default() -> OnceCell<T>797 fn default() -> OnceCell<T> {
798 OnceCell::new()
799 }
800 }
801
802 impl<T: fmt::Debug> fmt::Debug for OnceCell<T> {
fmt(&self, f: &mut fmt::Formatter) -> fmt::Result803 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
804 match self.get() {
805 Some(v) => f.debug_tuple("OnceCell").field(v).finish(),
806 None => f.write_str("OnceCell(Uninit)"),
807 }
808 }
809 }
810
811 impl<T: Clone> Clone for OnceCell<T> {
clone(&self) -> OnceCell<T>812 fn clone(&self) -> OnceCell<T> {
813 let res = OnceCell::new();
814 if let Some(value) = self.get() {
815 match res.set(value.clone()) {
816 Ok(()) => (),
817 Err(_) => unreachable!(),
818 }
819 }
820 res
821 }
822 }
823
824 impl<T> From<T> for OnceCell<T> {
from(value: T) -> Self825 fn from(value: T) -> Self {
826 let cell = Self::new();
827 cell.get_or_init(|| value);
828 cell
829 }
830 }
831
832 impl<T: PartialEq> PartialEq for OnceCell<T> {
eq(&self, other: &OnceCell<T>) -> bool833 fn eq(&self, other: &OnceCell<T>) -> bool {
834 self.get() == other.get()
835 }
836 }
837
838 impl<T: Eq> Eq for OnceCell<T> {}
839
840 impl<T> OnceCell<T> {
841 /// Creates a new empty cell.
new() -> OnceCell<T>842 pub const fn new() -> OnceCell<T> {
843 OnceCell(Imp::new())
844 }
845
846 /// Gets the reference to the underlying value.
847 ///
848 /// Returns `None` if the cell is empty, or being initialized. This
849 /// method never blocks.
get(&self) -> Option<&T>850 pub fn get(&self) -> Option<&T> {
851 if self.0.is_initialized() {
852 // Safe b/c value is initialized.
853 Some(unsafe { self.get_unchecked() })
854 } else {
855 None
856 }
857 }
858
859 /// Gets the mutable reference to the underlying value.
860 ///
861 /// Returns `None` if the cell is empty.
862 ///
863 /// This method is allowed to violate the invariant of writing to a `OnceCell`
864 /// at most once because it requires `&mut` access to `self`. As with all
865 /// interior mutability, `&mut` access permits arbitrary modification:
866 ///
867 /// ```
868 /// use once_cell::sync::OnceCell;
869 ///
870 /// let mut cell: OnceCell<u32> = OnceCell::new();
871 /// cell.set(92).unwrap();
872 /// cell = OnceCell::new();
873 /// ```
get_mut(&mut self) -> Option<&mut T>874 pub fn get_mut(&mut self) -> Option<&mut T> {
875 self.0.get_mut()
876 }
877
878 /// Get the reference to the underlying value, without checking if the
879 /// cell is initialized.
880 ///
881 /// # Safety
882 ///
883 /// Caller must ensure that the cell is in initialized state, and that
884 /// the contents are acquired by (synchronized to) this thread.
get_unchecked(&self) -> &T885 pub unsafe fn get_unchecked(&self) -> &T {
886 self.0.get_unchecked()
887 }
888
889 /// Sets the contents of this cell to `value`.
890 ///
891 /// Returns `Ok(())` if the cell was empty and `Err(value)` if it was
892 /// full.
893 ///
894 /// # Example
895 ///
896 /// ```
897 /// use once_cell::sync::OnceCell;
898 ///
899 /// static CELL: OnceCell<i32> = OnceCell::new();
900 ///
901 /// fn main() {
902 /// assert!(CELL.get().is_none());
903 ///
904 /// std::thread::spawn(|| {
905 /// assert_eq!(CELL.set(92), Ok(()));
906 /// }).join().unwrap();
907 ///
908 /// assert_eq!(CELL.set(62), Err(62));
909 /// assert_eq!(CELL.get(), Some(&92));
910 /// }
911 /// ```
set(&self, value: T) -> Result<(), T>912 pub fn set(&self, value: T) -> Result<(), T> {
913 match self.try_insert(value) {
914 Ok(_) => Ok(()),
915 Err((_, value)) => Err(value),
916 }
917 }
918
919 /// Like [`set`](Self::set), but also returns a reference to the final cell value.
920 ///
921 /// # Example
922 ///
923 /// ```
924 /// use once_cell::unsync::OnceCell;
925 ///
926 /// let cell = OnceCell::new();
927 /// assert!(cell.get().is_none());
928 ///
929 /// assert_eq!(cell.try_insert(92), Ok(&92));
930 /// assert_eq!(cell.try_insert(62), Err((&92, 62)));
931 ///
932 /// assert!(cell.get().is_some());
933 /// ```
try_insert(&self, value: T) -> Result<&T, (&T, T)>934 pub fn try_insert(&self, value: T) -> Result<&T, (&T, T)> {
935 let mut value = Some(value);
936 let res = self.get_or_init(|| unsafe { take_unchecked(&mut value) });
937 match value {
938 None => Ok(res),
939 Some(value) => Err((res, value)),
940 }
941 }
942
943 /// Gets the contents of the cell, initializing it with `f` if the cell
944 /// was empty.
945 ///
946 /// Many threads may call `get_or_init` concurrently with different
947 /// initializing functions, but it is guaranteed that only one function
948 /// will be executed.
949 ///
950 /// # Panics
951 ///
952 /// If `f` panics, the panic is propagated to the caller, and the cell
953 /// remains uninitialized.
954 ///
955 /// It is an error to reentrantly initialize the cell from `f`. The
956 /// exact outcome is unspecified. Current implementation deadlocks, but
957 /// this may be changed to a panic in the future.
958 ///
959 /// # Example
960 /// ```
961 /// use once_cell::sync::OnceCell;
962 ///
963 /// let cell = OnceCell::new();
964 /// let value = cell.get_or_init(|| 92);
965 /// assert_eq!(value, &92);
966 /// let value = cell.get_or_init(|| unreachable!());
967 /// assert_eq!(value, &92);
968 /// ```
get_or_init<F>(&self, f: F) -> &T where F: FnOnce() -> T,969 pub fn get_or_init<F>(&self, f: F) -> &T
970 where
971 F: FnOnce() -> T,
972 {
973 enum Void {}
974 match self.get_or_try_init(|| Ok::<T, Void>(f())) {
975 Ok(val) => val,
976 Err(void) => match void {},
977 }
978 }
979
980 /// Gets the contents of the cell, initializing it with `f` if
981 /// the cell was empty. If the cell was empty and `f` failed, an
982 /// error is returned.
983 ///
984 /// # Panics
985 ///
986 /// If `f` panics, the panic is propagated to the caller, and
987 /// the cell remains uninitialized.
988 ///
989 /// It is an error to reentrantly initialize the cell from `f`.
990 /// The exact outcome is unspecified. Current implementation
991 /// deadlocks, but this may be changed to a panic in the future.
992 ///
993 /// # Example
994 /// ```
995 /// use once_cell::sync::OnceCell;
996 ///
997 /// let cell = OnceCell::new();
998 /// assert_eq!(cell.get_or_try_init(|| Err(())), Err(()));
999 /// assert!(cell.get().is_none());
1000 /// let value = cell.get_or_try_init(|| -> Result<i32, ()> {
1001 /// Ok(92)
1002 /// });
1003 /// assert_eq!(value, Ok(&92));
1004 /// assert_eq!(cell.get(), Some(&92))
1005 /// ```
get_or_try_init<F, E>(&self, f: F) -> Result<&T, E> where F: FnOnce() -> Result<T, E>,1006 pub fn get_or_try_init<F, E>(&self, f: F) -> Result<&T, E>
1007 where
1008 F: FnOnce() -> Result<T, E>,
1009 {
1010 // Fast path check
1011 if let Some(value) = self.get() {
1012 return Ok(value);
1013 }
1014 self.0.initialize(f)?;
1015
1016 // Safe b/c value is initialized.
1017 debug_assert!(self.0.is_initialized());
1018 Ok(unsafe { self.get_unchecked() })
1019 }
1020
1021 /// Takes the value out of this `OnceCell`, moving it back to an uninitialized state.
1022 ///
1023 /// Has no effect and returns `None` if the `OnceCell` hasn't been initialized.
1024 ///
1025 /// # Examples
1026 ///
1027 /// ```
1028 /// use once_cell::sync::OnceCell;
1029 ///
1030 /// let mut cell: OnceCell<String> = OnceCell::new();
1031 /// assert_eq!(cell.take(), None);
1032 ///
1033 /// let mut cell = OnceCell::new();
1034 /// cell.set("hello".to_string()).unwrap();
1035 /// assert_eq!(cell.take(), Some("hello".to_string()));
1036 /// assert_eq!(cell.get(), None);
1037 /// ```
1038 ///
1039 /// This method is allowed to violate the invariant of writing to a `OnceCell`
1040 /// at most once because it requires `&mut` access to `self`. As with all
1041 /// interior mutability, `&mut` access permits arbitrary modification:
1042 ///
1043 /// ```
1044 /// use once_cell::sync::OnceCell;
1045 ///
1046 /// let mut cell: OnceCell<u32> = OnceCell::new();
1047 /// cell.set(92).unwrap();
1048 /// cell = OnceCell::new();
1049 /// ```
take(&mut self) -> Option<T>1050 pub fn take(&mut self) -> Option<T> {
1051 mem::replace(self, Self::default()).into_inner()
1052 }
1053
1054 /// Consumes the `OnceCell`, returning the wrapped value. Returns
1055 /// `None` if the cell was empty.
1056 ///
1057 /// # Examples
1058 ///
1059 /// ```
1060 /// use once_cell::sync::OnceCell;
1061 ///
1062 /// let cell: OnceCell<String> = OnceCell::new();
1063 /// assert_eq!(cell.into_inner(), None);
1064 ///
1065 /// let cell = OnceCell::new();
1066 /// cell.set("hello".to_string()).unwrap();
1067 /// assert_eq!(cell.into_inner(), Some("hello".to_string()));
1068 /// ```
into_inner(self) -> Option<T>1069 pub fn into_inner(self) -> Option<T> {
1070 self.0.into_inner()
1071 }
1072 }
1073
1074 /// A value which is initialized on the first access.
1075 ///
1076 /// This type is thread-safe and can be used in statics.
1077 ///
1078 /// # Example
1079 ///
1080 /// ```
1081 /// use std::collections::HashMap;
1082 ///
1083 /// use once_cell::sync::Lazy;
1084 ///
1085 /// static HASHMAP: Lazy<HashMap<i32, String>> = Lazy::new(|| {
1086 /// println!("initializing");
1087 /// let mut m = HashMap::new();
1088 /// m.insert(13, "Spica".to_string());
1089 /// m.insert(74, "Hoyten".to_string());
1090 /// m
1091 /// });
1092 ///
1093 /// fn main() {
1094 /// println!("ready");
1095 /// std::thread::spawn(|| {
1096 /// println!("{:?}", HASHMAP.get(&13));
1097 /// }).join().unwrap();
1098 /// println!("{:?}", HASHMAP.get(&74));
1099 ///
1100 /// // Prints:
1101 /// // ready
1102 /// // initializing
1103 /// // Some("Spica")
1104 /// // Some("Hoyten")
1105 /// }
1106 /// ```
1107 pub struct Lazy<T, F = fn() -> T> {
1108 cell: OnceCell<T>,
1109 init: Cell<Option<F>>,
1110 }
1111
1112 impl<T: fmt::Debug, F> fmt::Debug for Lazy<T, F> {
fmt(&self, f: &mut fmt::Formatter) -> fmt::Result1113 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
1114 f.debug_struct("Lazy").field("cell", &self.cell).field("init", &"..").finish()
1115 }
1116 }
1117
1118 // We never create a `&F` from a `&Lazy<T, F>` so it is fine to not impl
1119 // `Sync` for `F`. we do create a `&mut Option<F>` in `force`, but this is
1120 // properly synchronized, so it only happens once so it also does not
1121 // contribute to this impl.
1122 unsafe impl<T, F: Send> Sync for Lazy<T, F> where OnceCell<T>: Sync {}
1123 // auto-derived `Send` impl is OK.
1124
1125 #[cfg(feature = "std")]
1126 impl<T, F: RefUnwindSafe> RefUnwindSafe for Lazy<T, F> where OnceCell<T>: RefUnwindSafe {}
1127
1128 impl<T, F> Lazy<T, F> {
1129 /// Creates a new lazy value with the given initializing
1130 /// function.
new(f: F) -> Lazy<T, F>1131 pub const fn new(f: F) -> Lazy<T, F> {
1132 Lazy { cell: OnceCell::new(), init: Cell::new(Some(f)) }
1133 }
1134
1135 /// Consumes this `Lazy` returning the stored value.
1136 ///
1137 /// Returns `Ok(value)` if `Lazy` is initialized and `Err(f)` otherwise.
into_value(this: Lazy<T, F>) -> Result<T, F>1138 pub fn into_value(this: Lazy<T, F>) -> Result<T, F> {
1139 let cell = this.cell;
1140 let init = this.init;
1141 cell.into_inner().ok_or_else(|| {
1142 init.take().unwrap_or_else(|| panic!("Lazy instance has previously been poisoned"))
1143 })
1144 }
1145 }
1146
1147 impl<T, F: FnOnce() -> T> Lazy<T, F> {
1148 /// Forces the evaluation of this lazy value and
1149 /// returns a reference to the result. This is equivalent
1150 /// to the `Deref` impl, but is explicit.
1151 ///
1152 /// # Example
1153 /// ```
1154 /// use once_cell::sync::Lazy;
1155 ///
1156 /// let lazy = Lazy::new(|| 92);
1157 ///
1158 /// assert_eq!(Lazy::force(&lazy), &92);
1159 /// assert_eq!(&*lazy, &92);
1160 /// ```
force(this: &Lazy<T, F>) -> &T1161 pub fn force(this: &Lazy<T, F>) -> &T {
1162 this.cell.get_or_init(|| match this.init.take() {
1163 Some(f) => f(),
1164 None => panic!("Lazy instance has previously been poisoned"),
1165 })
1166 }
1167 }
1168
1169 impl<T, F: FnOnce() -> T> Deref for Lazy<T, F> {
1170 type Target = T;
deref(&self) -> &T1171 fn deref(&self) -> &T {
1172 Lazy::force(self)
1173 }
1174 }
1175
1176 impl<T, F: FnOnce() -> T> DerefMut for Lazy<T, F> {
deref_mut(&mut self) -> &mut T1177 fn deref_mut(&mut self) -> &mut T {
1178 Lazy::force(self);
1179 self.cell.get_mut().unwrap_or_else(|| unreachable!())
1180 }
1181 }
1182
1183 impl<T: Default> Default for Lazy<T> {
1184 /// Creates a new lazy value using `Default` as the initializing function.
default() -> Lazy<T>1185 fn default() -> Lazy<T> {
1186 Lazy::new(T::default)
1187 }
1188 }
1189
1190 /// ```compile_fail
1191 /// struct S(*mut ());
1192 /// unsafe impl Sync for S {}
1193 ///
1194 /// fn share<T: Sync>(_: &T) {}
1195 /// share(&once_cell::sync::OnceCell::<S>::new());
1196 /// ```
1197 ///
1198 /// ```compile_fail
1199 /// struct S(*mut ());
1200 /// unsafe impl Sync for S {}
1201 ///
1202 /// fn share<T: Sync>(_: &T) {}
1203 /// share(&once_cell::sync::Lazy::<S>::new(|| unimplemented!()));
1204 /// ```
_dummy()1205 fn _dummy() {}
1206 }
1207
1208 #[cfg(feature = "race")]
1209 pub mod race;
1210
1211 #[cfg(feature = "std")]
take_unchecked<T>(val: &mut Option<T>) -> T1212 unsafe fn take_unchecked<T>(val: &mut Option<T>) -> T {
1213 match val.take() {
1214 Some(it) => it,
1215 None => {
1216 debug_assert!(false);
1217 std::hint::unreachable_unchecked()
1218 }
1219 }
1220 }
1221