¯Š'°)®*4Ó&;BF¥…“á,Ôaüäît # OverviewÁËüJG `once_cell` provides two new cell-like types, [`unsync::OnceCell`] andÁü^PM [`sync::OnceCell`]. A `OnceCell` might store arbitrary non-`Copy` types, canÁü¯HE be assigned to at most once and provides direct access to the storedÁüøKH contents. The core API looks *roughly* like this (and there's much moreÁ´Ä inside, read on!):ÁÛË”ß ```rust,ignoreÁÌò impl<T> OnceCell<T> {ÁüŒ-* const fn new() -> OnceCell<T> { ... }Áüº85 fn set(&self, value: T) -> Result<(), T> { ... }Áüó+( fn get(&self) -> Option<&T> { ... }Á,Ÿ }Á<¥ ```ÁËü±MJ Note that, like with [`RefCell`] and [`Mutex`], the `set` method requiresÁüÿOL only a shared reference. Because of the single assignment restriction `get`ÁüÏ=: can return a `&T` instead of `Ref<T>` or `MutexGuard<T>`.Á�Ëü‘NK The `sync` flavor is thread-safe (that is, implements the [`Sync`] trait),Áüà" while the `unsync` one is not.ÁƒËü‡52 [`unsync::OnceCell`]: unsync/struct.OnceCell.htmlÁü½1. [`sync::OnceCell`]: sync/struct.OnceCell.htmlÁüïGD [`RefCell`]: https://doc.rust-lang.org/std/cell/struct.RefCell.htmlÁü·C@ [`Mutex`]: https://doc.rust-lang.org/std/sync/struct.Mutex.htmlÁüûB? [`Sync`]: https://doc.rust-lang.org/std/marker/trait.Sync.htmlÁ¾ ËlÂ
# RecipesÁÐ ËüÔ 96 `OnceCell` might be useful for a variety of patterns.ÁŽ
Ëü’
)& ## Safe Initialization of Global DataÁ¼
Ë\À
```rustÁ¼Ì
use std::{env, io};Áä
Ëüè
" use once_cell::sync::OnceCell;Á‹Ë¤� #[derive(Debug)]Á¼¤ pub struct Logger {Át¼ // ...Á,˹\üÑ85 static INSTANCE: OnceCell<Logger> = OnceCell::new();ÁŠËŒŽ impl Logger {Áü ,) pub fn global() -> &'static Logger {ÁüÍ>; INSTANCE.get().expect("logger is not initialized")ÁLŒ
}Á–
Ëüš
HE fn from_cli(args: env::Args) -> Result<Logger, std::io::Error> {ÁŒã
})?;Áä³! Ok(cfg.as_str())ÁLÐ!°g,Ú!¹\<à!Æ\è!Ëäì! ## Lazily Compiled RegexÁ‰"Ëü�"HE This is a `regex!` macro which takes a string literal and returns anÁüÖ"63 *expression* that evaluates to a `&'static Regex`:Á�#Ë<‘#Æ\Ä™# macro_rules! regex {Áü²#! ($re:literal $(,)?) => {{ÁüÔ#b_ static RE: once_cell::sync::OnceCell<regex::Regex> = once_cell::sync::OnceCell::new();Áü·$>; RE.get_or_init(|| regex::Regex::new($re).unwrap())Á\ö$ }};Á,‚%¹\<ˆ%Æ\�%
deadlock.Á–OËüšO&# **Does this crate support async?**ÁÁO˼ÅO No, but you can useÁüÝOJG [`async_once_cell`](https://crates.io/crates/async_once_cell) instead.Á¨PËü¬P)& **Does this crate support `no_std`?**ÁÖPËüÚPJG Yes, but with caveats. `OnceCell` is a synchronization primitive whichÁü¥QMJ _semantically_ relies on blocking. `OnceCell` guarantees that at most oneÁüóQMJ `f` will be called to compute the value. If two threads of execution callÁüÁR85 `get_or_init` concurrently, one of them has to wait.ÁúRËüþRMJ Waiting fundamentally requires OS support. Execution environment needs toÁüÌSPM understand who waits on whom to prevent deadlocks due to priority inversion.Áü�TMJ You _could_ make code to compile by blindly using pure spinlocks, but theÁüëT+( runtime behavior would be subtly wrong.Á—UËü›UHE Given these constraints, `once_cell` provides the following options:ÁäUËüèUPM - The `race` module provides similar, but distinct synchronization primitiveÁü¹VMJ which is compatible with `no_std`. With `race`, the `f` function can beÁü‡WNK called multiple times by different threads, but only one thread will winÁÜÖW to install the value.ÁüòWNK - `critical-section` feature (with a `-`, not `_`) uses `critical_section`ÁäÁX to implement blocking.ÁÞXËüâX! **Can I bring my own mutex?**Á„YËüˆYOL There is [generic_once_cell](https://crates.io/crates/generic_once_cell) toÁ¤ØY allow just that.ÁíYËüñYJG **Should I use `std::cell::OnceCell`, `once_cell`, or `lazy_static`?**Á¼ZËüÀZPM If you can use `std` version (your MSRV is at least 1.70, and you don't needÁü‘[PM extra features `once_cell` provides), use `std`. Otherwise, use `once_cell`.Áäâ[ Don't use `lazy_static`.Áÿ[ˤƒ\ # Related cratesÁ˜\Ëüœ\LI * Most of this crate's functionality is available in `std` starting withÁüé\EB Rust 1.70. See `std::cell::OnceCell` and `std::sync::OnceLock`.Áü¯]KH * [double-checked-cell](https://github.com/niklasf/double-checked-cell)Áüû]52 * [lazy-init](https://crates.io/crates/lazy-init)Áü±^30 * [lazycell](https://crates.io/crates/lazycell)Áüå^;8 * [mitochondria](https://crates.io/crates/mitochondria)Áü¡_96 * [lazy_static](https://crates.io/crates/lazy_static)ÁüÛ_A> * [async_once_cell](https://crates.io/crates/async_once_cell)Áü�`LI * [generic_once_cell](https://crates.io/crates/generic_once_cell) (bringÁ¬ê` your own mutex)ÁF¥…“Ž+áž+Ž+Ž+Ž+”Çaž+<äc»”c—cÊc8à˜c›cÉc8¶<œc¤c7“,¦c$«c8Æc°cÈc8¶<±c¹c7†l»cü’c:èc()*+,-.29;>þq$ÀÉ,£4TÆÇ.
CŠ'Åç÷ŠKþ—K‡K`bt™düîc*' Single-threaded version of `OnceCell`.Á4¡dS}q$ÉdÉ,FI£4TÏdÇ.FJÍädÁ]FKmemÁédÕFL†,üdìFNDerefMutÁDƒeùFO�ÌlžeÀ±FQ±ÌTe¿±FRü²d�¬®�ŸŽ�|~oqXZ"JL9;´ÒjüÆeDA A cell which can be written to only once. It is not thread safe.Á�fËü—fC@ Unlike [`std::cell::RefCell`], a `OnceCell` provides simple `&`Áüßf references to the contents.ÁƒgËü‹gRO [`std::cell::RefCell`]: https://doc.rust-lang.org/std/cell/struct.RefCell.htmlÁâgËlêg
# ExampleÁ<ügÆ\üˆh$Æ|±hËü¹h let cell = OnceCell::new();ÁüÝh" assert!(cell.get().is_none());Á„iËüŒi.+ let value: &String = cell.get_or_init(|| {Áü¿i# "Hello, World!".to_string()Á<çiásüói'$ assert_eq!(value, "Hello, World!");ÁüŸj" assert!(cell.get().is_some());Á<ÆjÆ\DÝj™TTƒÏæj‚(PÔMÄB|Uä¢k,¢kFSS™5üªmA™WWƒÏ¯m¢Ðl²m²ÐTÂm‚(üóm.™YYƒÏøm²ÐTûm‚(üªn™[[ƒÏ¯n‚(\Å\¤Ôn<×n‚(ZZ
kŠ'˜,¬wœýw™mmƒÏ‚x‚(nopqrstx{|üÁx!ì›x Creates a new empty cell.ÁÎx‚(ll¿?üÚy0ü®y# Creates a new initialized cell.ÁTçyŠ'‚(ll
oŠ'˜Åüâ{üÝz-* Gets a reference to the underlying value.Á“{ËüŸ{(% Returns `None` if the cell is empty.Áé{££‚(ø°ú°û°Ðü°ý°�þ°ìH�ˈXêE>£Š'lí{l
pŠ'$î{ü‡„+üÙ~52 Gets a mutable reference to the underlying value.Á—Ëü£(àüÔËüàNK This method is allowed to violate the invariant of writing to a `OnceCell`Áü·€IF at most once because it requires `&mut` access to `self`. As with allÁü‰�FC interior mutability, `&mut` access permits arbitrary modification:ÁØ�Ë<ä�Æ\üô�$Æ|¡‚Ëü‚2/ let mut cell: OnceCell<u32> = OnceCell::new();ÁÔè‚ cell.set(92).unwrap();Áü‹ƒ" *cell.get_mut().unwrap() = 93;Áü¶ƒ&# assert_eq!(cell.get(), Some(&93));Á<åƒÆ\<Ž„¤¤‚(ø°ú°û°Ðü°ý°�þ°ìH�ˈXêE>¤Š'l–„l
{Š'$‘±üƒ¶$üâ±96 Consumes the `OnceCell`, returning the wrapped value.Á¤²Ëü°²)& Returns `None` if the cell was empty.Áâ²Ëtž…³Ë<‘³Æ\ü¡³$Æ|γËüÚ³1. let cell: OnceCell<String> = OnceCell::new();Áü”´(% assert_eq!(cell.into_inner(), None);ÁÅ´ËüÑ´ÿìüù´+‰ üµ=: assert_eq!(cell.into_inner(), Some("hello".to_string()));Á<óµÆ\TŠ¶‚(«3ll
‹Š‹ƒÏ�¿ÏÔ“¿ƒ)Œ�üÐÂ'ü«¿B? Creates a new lazy value with the given initializing function.Áö¿Ël‚ÀÇì<˜ÀÆ\Œ¨À # fn main() {ÁüÂÀ¨xëÀËü÷À,) let hello = "Hello, World!".to_string();Á¬ÁËü¸Á2/ let lazy = Lazy::new(|| hello.to_uppercase());ÁóÁËüÿÁ(% assert_eq!(&*lazy, "HELLO, WORLD!");Á<°Â # }Á<ÀÂÆ\Ý»)ƒ)‰‰
“Š'»)«¶$–ËÓË“ºÕ”ÒÕ”ïÕ””“”Š'»)°MŠ'ƒ)üÏÐ1üÿÌOL Forces the evaluation of this lazy value and returns a mutable reference toÁ|×Íâ¹ïÍËüûÍ?< This is equivalent to the `DerefMut` impl, but is explicit.ÁÃÎËlÏÎÇì<åÎÆ\üõΨxžÏËüªÏ$! let mut lazy = Lazy::new(|| 92);Á×ÏËüãÏ0- assert_eq!(Lazy::force_mut(&mut lazy), &92);ÁԜРassert_eq!(*lazy, 92);Á<¿ÐÆ\LÖЮ®ƒ)®Š'�æÐ�
•Š'»)«¶$àÐðÓ•ºÕ–ÒÕ–ïÕ––•–Š'»)°MŠ'°MüÉ×+ü–Ô:7 Gets the reference to the result of this lazy value ifÁüÙÔ1. it was initialized, otherwise returns `None`.Á“ÕËlŸÕÇì<µÕÆ\üÅÕ¨xîÕËüúÕ‹»£ÖËü¯Ö'$ assert_eq!(Lazy::get(&lazy), None);ÁäßÖò»ü„×,) assert_eq!(Lazy::get(&lazy), Some(&92));Á<¹×Æ\Ðׯ¯ƒ)ø°ú°û°Ðü°ý°�þ°ìH�ˈXêE>¯Š'�Ú×�
—Š'»)«¶$Ô×ü÷Û7ü¦ØB? Gets the mutable reference to the result of this lazy value ifÁüñØ1²Ã«ÙËl·ÙÇì<ÍÙÆ\üÝÙ¨x†ÚËü’Ú$õ¿¿ÚËüËÚ/, assert_eq!(Lazy::get_mut(&mut lazy), None);ÁÔƒÛèÀü¦Û85 assert_eq!(Lazy::get_mut(&mut lazy), Some(&mut 92));Á<çÛÆ\<þÛ°°ƒ)ø°ú°û°Ðü°ý°�þ°ìH�ˈXêE>°Š'�ŒÜ�
ÈŠ'˜p"ü›ùüê÷/, Gets the reference to the underlying value.Á¢øËü®øC@ Returns `None` if the cell is empty, or being initialized. ThisÁÄúø method never blocks.Á¢ù»»®*ø°ú°û°Ðü°ý°�þ°ìH�ˈXêE>»Š'ŦùÅ
ÉŠ'$§ùį�ü™ûDA Gets the reference to the underlying value, blocking the currentÁÜæû thread until it is set.ÁŠüË<–üÆ\ü¦ü"¾dÑüËüÝü85 let mut cell = std::sync::Arc::new(OnceCell::new());Áüžý let t = std::thread::spawn({Á
ØŠ'$»¾ü£Æ!ü…¿5¶§¿¿ËüÇ¿85 This type is thread-safe and can be used in statics.Á„ÀËlŒÀÇìžÀË<¦ÀÆ\ü²À" use std::collections::HashMap;ÁÙÀËôáÀq„ÁËüŒÁ?< static HASHMAP: Lazy<HashMap<i32, String>> = Lazy::new(|| {ÁüÐÁ!å¨üöÁ#²rüžÂ*ÞrüÍÂ+‘sLý mÁ<‹Ãás—ÃË|ŸÃ÷hԳà println!("ready");ÁüÒÃúüöÃ/, println!("{:?}", HASHMAP.get(&13));ÁܪČûüÊÄ+( println!("{:?}", HASHMAP.get(&74));ÁúÄË”‚Å // Prints:Á”™Å // readyÁÌ°Å // initializingÁÔÎÅ // Some("Spica")ÁÜíÅ // Some("Hoyten")Á,�ƹ\<—ÆÆ\$®Æ™Ú²
ññðñ“žÒÏÔ�ÒðÔl’҃όҡ+òôö÷35üãÕ%ü¶Ò0- Forces the evaluation of this lazy value andÁüïÒ96 returns a reference to the result. This is equivalentÁü±Ó)& to the `Deref` impl, but is explicit.ÁãÓËlïÓÇì<…ÔÆ\ô•Ôq¼ÔËüÈÔ‹»ñÔËüýÔ(Á»ä®Õò»<ÓÕÆ\,êÕÇÇ¡+ÇŠ'ïöÕï
„d×î»ÀîÃîÔî8¶<ÄîÌî7Î4ÎîľîüEB Thread-safe, non-blocking, "first one wins" flavor of `OnceCell`.ÁFËüJIF If two threads race to initialize a type from the `race` module, theyÁü”JG don't block, execute initialization function together, but only one ofÁÜß them stores the result.ÁûËüÿ/, This module does not require `std` feature.Á¯Ë´³ # Atomic orderingsÁÊËüÎ85 All types in this module use `Acquire` and `Release`Áü‡LI [atomic orderings](Ordering) for all their operations. While this is notÁüÔPM strictly necessary for types other than `OnceBox`, it is useful for users asÁü¥MJ it allows them to be certain that after `get` or `get_or_init` returns onÁüóJG one thread, any side-effects caused by the setter thread prior to themÁü¾OL calling `set` or `get_or_init` will be made visible to that thread; withoutÁüŽOL it, it's possible for it to appear as if they haven't happened yet from theÁüÞMJ getter thread's perspective. This is an acceptable tradeoff to make sinceÁü¬IF `Acquire` and `Release` have very little performance overhead on mostÁüö# architectures versus `Relaxed`.Á$ßî¯Ó…‹¹4ßÓZ…†\L¸
–$¥"˜,«"üì%aüÒ#KH Gets the contents of the cell, initializing it with `f` if the cell wasÁT¢$ empty.Á±$Ëü¹$LI If several threads concurrently run `get_or_init`, more than one `f` canÁüŠ%KH be called. However, all threads will return the same value, produced byÁlÚ%
