diff options
Diffstat (limited to 'vendor/once_cell/src')
| -rw-r--r-- | vendor/once_cell/src/imp_cs.rs | 78 | ||||
| -rw-r--r-- | vendor/once_cell/src/imp_pl.rs | 174 | ||||
| -rw-r--r-- | vendor/once_cell/src/imp_std.rs | 415 | ||||
| -rw-r--r-- | vendor/once_cell/src/lib.rs | 1412 | ||||
| -rw-r--r-- | vendor/once_cell/src/race.rs | 419 |
5 files changed, 0 insertions, 2498 deletions
diff --git a/vendor/once_cell/src/imp_cs.rs b/vendor/once_cell/src/imp_cs.rs deleted file mode 100644 index 7d05e50..0000000 --- a/vendor/once_cell/src/imp_cs.rs +++ /dev/null @@ -1,78 +0,0 @@ -use core::panic::{RefUnwindSafe, UnwindSafe}; - -use portable_atomic::{AtomicBool, Ordering}; -use critical_section::{CriticalSection, Mutex}; - -use crate::unsync; - -pub(crate) struct OnceCell<T> { - initialized: AtomicBool, - // Use `unsync::OnceCell` internally since `Mutex` does not provide - // interior mutability and to be able to re-use `get_or_try_init`. - value: Mutex<unsync::OnceCell<T>>, -} - -// Why do we need `T: Send`? -// Thread A creates a `OnceCell` and shares it with -// scoped thread B, which fills the cell, which is -// then destroyed by A. That is, destructor observes -// a sent value. -unsafe impl<T: Sync + Send> Sync for OnceCell<T> {} -unsafe impl<T: Send> Send for OnceCell<T> {} - -impl<T: RefUnwindSafe + UnwindSafe> RefUnwindSafe for OnceCell<T> {} -impl<T: UnwindSafe> UnwindSafe for OnceCell<T> {} - -impl<T> OnceCell<T> { - pub(crate) const fn new() -> OnceCell<T> { - OnceCell { initialized: AtomicBool::new(false), value: Mutex::new(unsync::OnceCell::new()) } - } - - pub(crate) const fn with_value(value: T) -> OnceCell<T> { - OnceCell { - initialized: AtomicBool::new(true), - value: Mutex::new(unsync::OnceCell::with_value(value)), - } - } - - #[inline] - pub(crate) fn is_initialized(&self) -> bool { - self.initialized.load(Ordering::Acquire) - } - - #[cold] - pub(crate) fn initialize<F, E>(&self, f: F) -> Result<(), E> - where - F: FnOnce() -> Result<T, E>, - { - critical_section::with(|cs| { - let cell = self.value.borrow(cs); - cell.get_or_try_init(f).map(|_| { - self.initialized.store(true, Ordering::Release); - }) - }) - } - - /// Get the reference to the underlying value, without checking if the cell - /// is initialized. - /// - /// # Safety - /// - /// Caller must ensure that the cell is in initialized state, and that - /// the contents are acquired by (synchronized to) this thread. - pub(crate) unsafe fn get_unchecked(&self) -> &T { - debug_assert!(self.is_initialized()); - // SAFETY: The caller ensures that the value is initialized and access synchronized. - self.value.borrow(CriticalSection::new()).get().unwrap_unchecked() - } - - #[inline] - pub(crate) fn get_mut(&mut self) -> Option<&mut T> { - self.value.get_mut().get_mut() - } - - #[inline] - pub(crate) fn into_inner(self) -> Option<T> { - self.value.into_inner().into_inner() - } -} diff --git a/vendor/once_cell/src/imp_pl.rs b/vendor/once_cell/src/imp_pl.rs deleted file mode 100644 index 37a8554..0000000 --- a/vendor/once_cell/src/imp_pl.rs +++ /dev/null @@ -1,174 +0,0 @@ -use std::{ - cell::UnsafeCell, - panic::{RefUnwindSafe, UnwindSafe}, - sync::atomic::{AtomicU8, Ordering}, -}; - -pub(crate) struct OnceCell<T> { - state: AtomicU8, - value: UnsafeCell<Option<T>>, -} - -const INCOMPLETE: u8 = 0x0; -const RUNNING: u8 = 0x1; -const COMPLETE: u8 = 0x2; - -// Why do we need `T: Send`? -// Thread A creates a `OnceCell` and shares it with -// scoped thread B, which fills the cell, which is -// then destroyed by A. That is, destructor observes -// a sent value. -unsafe impl<T: Sync + Send> Sync for OnceCell<T> {} -unsafe impl<T: Send> Send for OnceCell<T> {} - -impl<T: RefUnwindSafe + UnwindSafe> RefUnwindSafe for OnceCell<T> {} -impl<T: UnwindSafe> UnwindSafe for OnceCell<T> {} - -impl<T> OnceCell<T> { - pub(crate) const fn new() -> OnceCell<T> { - OnceCell { state: AtomicU8::new(INCOMPLETE), value: UnsafeCell::new(None) } - } - - pub(crate) const fn with_value(value: T) -> OnceCell<T> { - OnceCell { state: AtomicU8::new(COMPLETE), value: UnsafeCell::new(Some(value)) } - } - - /// Safety: synchronizes with store to value via Release/Acquire. - #[inline] - pub(crate) fn is_initialized(&self) -> bool { - self.state.load(Ordering::Acquire) == COMPLETE - } - - /// Safety: synchronizes with store to value via `is_initialized` or mutex - /// lock/unlock, writes value only once because of the mutex. - #[cold] - pub(crate) fn initialize<F, E>(&self, f: F) -> Result<(), E> - where - F: FnOnce() -> Result<T, E>, - { - let mut f = Some(f); - let mut res: Result<(), E> = Ok(()); - let slot: *mut Option<T> = self.value.get(); - initialize_inner(&self.state, &mut || { - // We are calling user-supplied function and need to be careful. - // - if it returns Err, we unlock mutex and return without touching anything - // - if it panics, we unlock mutex and propagate panic without touching anything - // - if it calls `set` or `get_or_try_init` re-entrantly, we get a deadlock on - // mutex, which is important for safety. We *could* detect this and panic, - // but that is more complicated - // - finally, if it returns Ok, we store the value and store the flag with - // `Release`, which synchronizes with `Acquire`s. - let f = unsafe { f.take().unwrap_unchecked() }; - match f() { - Ok(value) => unsafe { - // Safe b/c we have a unique access and no panic may happen - // until the cell is marked as initialized. - debug_assert!((*slot).is_none()); - *slot = Some(value); - true - }, - Err(err) => { - res = Err(err); - false - } - } - }); - res - } - - #[cold] - pub(crate) fn wait(&self) { - let key = &self.state as *const _ as usize; - unsafe { - parking_lot_core::park( - key, - || self.state.load(Ordering::Acquire) != COMPLETE, - || (), - |_, _| (), - parking_lot_core::DEFAULT_PARK_TOKEN, - None, - ); - } - } - - /// Get the reference to the underlying value, without checking if the cell - /// is initialized. - /// - /// # Safety - /// - /// Caller must ensure that the cell is in initialized state, and that - /// the contents are acquired by (synchronized to) this thread. - pub(crate) unsafe fn get_unchecked(&self) -> &T { - debug_assert!(self.is_initialized()); - let slot = &*self.value.get(); - slot.as_ref().unwrap_unchecked() - } - - /// Gets the mutable reference to the underlying value. - /// Returns `None` if the cell is empty. - pub(crate) fn get_mut(&mut self) -> Option<&mut T> { - // Safe b/c we have an exclusive access - let slot: &mut Option<T> = unsafe { &mut *self.value.get() }; - slot.as_mut() - } - - /// Consumes this `OnceCell`, returning the wrapped value. - /// Returns `None` if the cell was empty. - pub(crate) fn into_inner(self) -> Option<T> { - self.value.into_inner() - } -} - -struct Guard<'a> { - state: &'a AtomicU8, - new_state: u8, -} - -impl<'a> Drop for Guard<'a> { - fn drop(&mut self) { - self.state.store(self.new_state, Ordering::Release); - unsafe { - let key = self.state as *const AtomicU8 as usize; - parking_lot_core::unpark_all(key, parking_lot_core::DEFAULT_UNPARK_TOKEN); - } - } -} - -// Note: this is intentionally monomorphic -#[inline(never)] -fn initialize_inner(state: &AtomicU8, init: &mut dyn FnMut() -> bool) { - loop { - let exchange = - state.compare_exchange_weak(INCOMPLETE, RUNNING, Ordering::Acquire, Ordering::Acquire); - match exchange { - Ok(_) => { - let mut guard = Guard { state, new_state: INCOMPLETE }; - if init() { - guard.new_state = COMPLETE; - } - return; - } - Err(COMPLETE) => return, - Err(RUNNING) => unsafe { - let key = state as *const AtomicU8 as usize; - parking_lot_core::park( - key, - || state.load(Ordering::Relaxed) == RUNNING, - || (), - |_, _| (), - parking_lot_core::DEFAULT_PARK_TOKEN, - None, - ); - }, - Err(INCOMPLETE) => (), - Err(_) => debug_assert!(false), - } - } -} - -#[test] -fn test_size() { - use std::mem::size_of; - - assert_eq!(size_of::<OnceCell<bool>>(), 1 * size_of::<bool>() + size_of::<u8>()); -} diff --git a/vendor/once_cell/src/imp_std.rs b/vendor/once_cell/src/imp_std.rs deleted file mode 100644 index 3b9e6d2..0000000 --- a/vendor/once_cell/src/imp_std.rs +++ /dev/null @@ -1,415 +0,0 @@ -// There's a lot of scary concurrent code in this module, but it is copied from -// `std::sync::Once` with two changes: -// * no poisoning -// * init function can fail - -use std::{ - cell::{Cell, UnsafeCell}, - panic::{RefUnwindSafe, UnwindSafe}, - sync::atomic::{AtomicBool, AtomicPtr, Ordering}, - thread::{self, Thread}, -}; - -#[derive(Debug)] -pub(crate) struct OnceCell<T> { - // This `queue` field is the core of the implementation. It encodes two - // pieces of information: - // - // * The current state of the cell (`INCOMPLETE`, `RUNNING`, `COMPLETE`) - // * Linked list of threads waiting for the current cell. - // - // State is encoded in two low bits. Only `INCOMPLETE` and `RUNNING` states - // allow waiters. - queue: AtomicPtr<Waiter>, - value: UnsafeCell<Option<T>>, -} - -// Why do we need `T: Send`? -// Thread A creates a `OnceCell` and shares it with -// scoped thread B, which fills the cell, which is -// then destroyed by A. That is, destructor observes -// a sent value. -unsafe impl<T: Sync + Send> Sync for OnceCell<T> {} -unsafe impl<T: Send> Send for OnceCell<T> {} - -impl<T: RefUnwindSafe + UnwindSafe> RefUnwindSafe for OnceCell<T> {} -impl<T: UnwindSafe> UnwindSafe for OnceCell<T> {} - -impl<T> OnceCell<T> { - pub(crate) const fn new() -> OnceCell<T> { - OnceCell { queue: AtomicPtr::new(INCOMPLETE_PTR), value: UnsafeCell::new(None) } - } - - pub(crate) const fn with_value(value: T) -> OnceCell<T> { - OnceCell { queue: AtomicPtr::new(COMPLETE_PTR), value: UnsafeCell::new(Some(value)) } - } - - /// Safety: synchronizes with store to value via Release/(Acquire|SeqCst). - #[inline] - pub(crate) fn is_initialized(&self) -> bool { - // An `Acquire` load is enough because that makes all the initialization - // operations visible to us, and, this being a fast path, weaker - // ordering helps with performance. This `Acquire` synchronizes with - // `SeqCst` operations on the slow path. - self.queue.load(Ordering::Acquire) == COMPLETE_PTR - } - - /// Safety: synchronizes with store to value via SeqCst read from state, - /// writes value only once because we never get to INCOMPLETE state after a - /// successful write. - #[cold] - pub(crate) fn initialize<F, E>(&self, f: F) -> Result<(), E> - where - F: FnOnce() -> Result<T, E>, - { - let mut f = Some(f); - let mut res: Result<(), E> = Ok(()); - let slot: *mut Option<T> = self.value.get(); - initialize_or_wait( - &self.queue, - Some(&mut || { - let f = unsafe { f.take().unwrap_unchecked() }; - match f() { - Ok(value) => { - unsafe { *slot = Some(value) }; - true - } - Err(err) => { - res = Err(err); - false - } - } - }), - ); - res - } - - #[cold] - pub(crate) fn wait(&self) { - initialize_or_wait(&self.queue, None); - } - - /// Get the reference to the underlying value, without checking if the cell - /// is initialized. - /// - /// # Safety - /// - /// Caller must ensure that the cell is in initialized state, and that - /// the contents are acquired by (synchronized to) this thread. - pub(crate) unsafe fn get_unchecked(&self) -> &T { - debug_assert!(self.is_initialized()); - let slot = &*self.value.get(); - slot.as_ref().unwrap_unchecked() - } - - /// Gets the mutable reference to the underlying value. - /// Returns `None` if the cell is empty. - pub(crate) fn get_mut(&mut self) -> Option<&mut T> { - // Safe b/c we have a unique access. - unsafe { &mut *self.value.get() }.as_mut() - } - - /// Consumes this `OnceCell`, returning the wrapped value. - /// Returns `None` if the cell was empty. - #[inline] - pub(crate) fn into_inner(self) -> Option<T> { - // Because `into_inner` takes `self` by value, the compiler statically - // verifies that it is not currently borrowed. - // So, it is safe to move out `Option<T>`. - self.value.into_inner() - } -} - -// Three states that a OnceCell can be in, encoded into the lower bits of `queue` in -// the OnceCell structure. -const INCOMPLETE: usize = 0x0; -const RUNNING: usize = 0x1; -const COMPLETE: usize = 0x2; -const INCOMPLETE_PTR: *mut Waiter = INCOMPLETE as *mut Waiter; -const COMPLETE_PTR: *mut Waiter = COMPLETE as *mut Waiter; - -// Mask to learn about the state. All other bits are the queue of waiters if -// this is in the RUNNING state. -const STATE_MASK: usize = 0x3; - -/// Representation of a node in the linked list of waiters in the RUNNING state. -/// A waiters is stored on the stack of the waiting threads. -#[repr(align(4))] // Ensure the two lower bits are free to use as state bits. -struct Waiter { - thread: Cell<Option<Thread>>, - signaled: AtomicBool, - next: *mut Waiter, -} - -/// Drains and notifies the queue of waiters on drop. -struct Guard<'a> { - queue: &'a AtomicPtr<Waiter>, - new_queue: *mut Waiter, -} - -impl Drop for Guard<'_> { - fn drop(&mut self) { - let queue = self.queue.swap(self.new_queue, Ordering::AcqRel); - - let state = strict::addr(queue) & STATE_MASK; - assert_eq!(state, RUNNING); - - unsafe { - let mut waiter = strict::map_addr(queue, |q| q & !STATE_MASK); - while !waiter.is_null() { - let next = (*waiter).next; - let thread = (*waiter).thread.take().unwrap(); - (*waiter).signaled.store(true, Ordering::Release); - waiter = next; - thread.unpark(); - } - } - } -} - -// Corresponds to `std::sync::Once::call_inner`. -// -// Originally copied from std, but since modified to remove poisoning and to -// support wait. -// -// Note: this is intentionally monomorphic -#[inline(never)] -fn initialize_or_wait(queue: &AtomicPtr<Waiter>, mut init: Option<&mut dyn FnMut() -> bool>) { - let mut curr_queue = queue.load(Ordering::Acquire); - - loop { - let curr_state = strict::addr(curr_queue) & STATE_MASK; - match (curr_state, &mut init) { - (COMPLETE, _) => return, - (INCOMPLETE, Some(init)) => { - let exchange = queue.compare_exchange( - curr_queue, - strict::map_addr(curr_queue, |q| (q & !STATE_MASK) | RUNNING), - Ordering::Acquire, - Ordering::Acquire, - ); - if let Err(new_queue) = exchange { - curr_queue = new_queue; - continue; - } - let mut guard = Guard { queue, new_queue: INCOMPLETE_PTR }; - if init() { - guard.new_queue = COMPLETE_PTR; - } - return; - } - (INCOMPLETE, None) | (RUNNING, _) => { - wait(queue, curr_queue); - curr_queue = queue.load(Ordering::Acquire); - } - _ => debug_assert!(false), - } - } -} - -fn wait(queue: &AtomicPtr<Waiter>, mut curr_queue: *mut Waiter) { - let curr_state = strict::addr(curr_queue) & STATE_MASK; - loop { - let node = Waiter { - thread: Cell::new(Some(thread::current())), - signaled: AtomicBool::new(false), - next: strict::map_addr(curr_queue, |q| q & !STATE_MASK), - }; - let me = &node as *const Waiter as *mut Waiter; - - let exchange = queue.compare_exchange( - curr_queue, - strict::map_addr(me, |q| q | curr_state), - Ordering::Release, - Ordering::Relaxed, - ); - if let Err(new_queue) = exchange { - if strict::addr(new_queue) & STATE_MASK != curr_state { - return; - } - curr_queue = new_queue; - continue; - } - - while !node.signaled.load(Ordering::Acquire) { - thread::park(); - } - break; - } -} - -// Polyfill of strict provenance from https://crates.io/crates/sptr. -// -// Use free-standing function rather than a trait to keep things simple and -// avoid any potential conflicts with future stabile std API. -mod strict { - #[must_use] - #[inline] - pub(crate) fn addr<T>(ptr: *mut T) -> usize - where - T: Sized, - { - // FIXME(strict_provenance_magic): I am magic and should be a compiler intrinsic. - // SAFETY: Pointer-to-integer transmutes are valid (if you are okay with losing the - // provenance). - unsafe { core::mem::transmute(ptr) } - } - - #[must_use] - #[inline] - pub(crate) fn with_addr<T>(ptr: *mut T, addr: usize) -> *mut T - where - T: Sized, - { - // FIXME(strict_provenance_magic): I am magic and should be a compiler intrinsic. - // - // In the mean-time, this operation is defined to be "as if" it was - // a wrapping_offset, so we can emulate it as such. This should properly - // restore pointer provenance even under today's compiler. - let self_addr = self::addr(ptr) as isize; - let dest_addr = addr as isize; - let offset = dest_addr.wrapping_sub(self_addr); - - // This is the canonical desugarring of this operation, - // but `pointer::cast` was only stabilized in 1.38. - // self.cast::<u8>().wrapping_offset(offset).cast::<T>() - (ptr as *mut u8).wrapping_offset(offset) as *mut T - } - - #[must_use] - #[inline] - pub(crate) fn map_addr<T>(ptr: *mut T, f: impl FnOnce(usize) -> usize) -> *mut T - where - T: Sized, - { - self::with_addr(ptr, f(addr(ptr))) - } -} - -// These test are snatched from std as well. -#[cfg(test)] -mod tests { - use std::panic; - use std::{sync::mpsc::channel, thread}; - - use super::OnceCell; - - impl<T> OnceCell<T> { - fn init(&self, f: impl FnOnce() -> T) { - enum Void {} - let _ = self.initialize(|| Ok::<T, Void>(f())); - } - } - - #[test] - fn smoke_once() { - static O: OnceCell<()> = OnceCell::new(); - let mut a = 0; - O.init(|| a += 1); - assert_eq!(a, 1); - O.init(|| a += 1); - assert_eq!(a, 1); - } - - #[test] - fn stampede_once() { - static O: OnceCell<()> = OnceCell::new(); - static mut RUN: bool = false; - - let (tx, rx) = channel(); - for _ in 0..10 { - let tx = tx.clone(); - thread::spawn(move || { - for _ in 0..4 { - thread::yield_now() - } - unsafe { - O.init(|| { - assert!(!RUN); - RUN = true; - }); - assert!(RUN); - } - tx.send(()).unwrap(); - }); - } - - unsafe { - O.init(|| { - assert!(!RUN); - RUN = true; - }); - assert!(RUN); - } - - for _ in 0..10 { - rx.recv().unwrap(); - } - } - - #[test] - fn poison_bad() { - static O: OnceCell<()> = OnceCell::new(); - - // poison the once - let t = panic::catch_unwind(|| { - O.init(|| panic!()); - }); - assert!(t.is_err()); - - // we can subvert poisoning, however - let mut called = false; - O.init(|| { - called = true; - }); - assert!(called); - - // once any success happens, we stop propagating the poison - O.init(|| {}); - } - - #[test] - fn wait_for_force_to_finish() { - static O: OnceCell<()> = OnceCell::new(); - - // poison the once - let t = panic::catch_unwind(|| { - O.init(|| panic!()); - }); - assert!(t.is_err()); - - // make sure someone's waiting inside the once via a force - let (tx1, rx1) = channel(); - let (tx2, rx2) = channel(); - let t1 = thread::spawn(move || { - O.init(|| { - tx1.send(()).unwrap(); - rx2.recv().unwrap(); - }); - }); - - rx1.recv().unwrap(); - - // put another waiter on the once - let t2 = thread::spawn(|| { - let mut called = false; - O.init(|| { - called = true; - }); - assert!(!called); - }); - - tx2.send(()).unwrap(); - - assert!(t1.join().is_ok()); - assert!(t2.join().is_ok()); - } - - #[test] - #[cfg(target_pointer_width = "64")] - fn test_size() { - use std::mem::size_of; - - assert_eq!(size_of::<OnceCell<u32>>(), 4 * size_of::<u32>()); - } -} diff --git a/vendor/once_cell/src/lib.rs b/vendor/once_cell/src/lib.rs deleted file mode 100644 index 90d3657..0000000 --- a/vendor/once_cell/src/lib.rs +++ /dev/null @@ -1,1412 +0,0 @@ -//! # Overview -//! -//! `once_cell` provides two new cell-like types, [`unsync::OnceCell`] and -//! [`sync::OnceCell`]. A `OnceCell` might store arbitrary non-`Copy` types, can -//! be assigned to at most once and provides direct access to the stored -//! 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> { ... } -//! fn set(&self, value: T) -> Result<(), T> { ... } -//! fn get(&self) -> Option<&T> { ... } -//! } -//! ``` -//! -//! Note that, like with [`RefCell`] and [`Mutex`], the `set` method requires -//! only a shared reference. Because of the single assignment restriction `get` -//! can return a `&T` instead of `Ref<T>` or `MutexGuard<T>`. -//! -//! The `sync` flavor is thread-safe (that is, implements the [`Sync`] trait), -//! while the `unsync` one is not. -//! -//! [`unsync::OnceCell`]: unsync/struct.OnceCell.html -//! [`sync::OnceCell`]: sync/struct.OnceCell.html -//! [`RefCell`]: https://doc.rust-lang.org/std/cell/struct.RefCell.html -//! [`Mutex`]: https://doc.rust-lang.org/std/sync/struct.Mutex.html -//! [`Sync`]: https://doc.rust-lang.org/std/marker/trait.Sync.html -//! -//! # Recipes -//! -//! `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 { -//! // ... -//! } -//! static INSTANCE: OnceCell<Logger> = OnceCell::new(); -//! -//! impl Logger { -//! pub fn global() -> &'static Logger { -//! INSTANCE.get().expect("logger is not initialized") -//! } -//! -//! fn from_cli(args: env::Args) -> Result<Logger, std::io::Error> { -//! // ... -//! # Ok(Logger {}) -//! } -//! } -//! -//! fn main() { -//! let logger = Logger::from_cli(env::args()).unwrap(); -//! INSTANCE.set(logger).unwrap(); -//! // use `Logger::global()` from now on -//! } -//! ``` -//! -//! ## Lazy Initialized Global Data -//! -//! This is essentially the `lazy_static!` macro, but without a macro. -//! -//! ```rust -//! use std::{sync::Mutex, collections::HashMap}; -//! -//! use once_cell::sync::OnceCell; -//! -//! fn global_data() -> &'static Mutex<HashMap<i32, String>> { -//! static INSTANCE: OnceCell<Mutex<HashMap<i32, String>>> = OnceCell::new(); -//! INSTANCE.get_or_init(|| { -//! let mut m = HashMap::new(); -//! m.insert(13, "Spica".to_string()); -//! m.insert(74, "Hoyten".to_string()); -//! Mutex::new(m) -//! }) -//! } -//! ``` -//! -//! There are also the [`sync::Lazy`] and [`unsync::Lazy`] convenience types to -//! streamline this pattern: -//! -//! ```rust -//! use std::{sync::Mutex, collections::HashMap}; -//! use once_cell::sync::Lazy; -//! -//! static GLOBAL_DATA: Lazy<Mutex<HashMap<i32, String>>> = Lazy::new(|| { -//! let mut m = HashMap::new(); -//! m.insert(13, "Spica".to_string()); -//! m.insert(74, "Hoyten".to_string()); -//! Mutex::new(m) -//! }); -//! -//! fn main() { -//! println!("{:?}", GLOBAL_DATA.lock().unwrap()); -//! } -//! ``` -//! -//! Note that the variable that holds `Lazy` is declared as `static`, *not* -//! `const`. This is important: using `const` instead compiles, but works wrong. -//! -//! [`sync::Lazy`]: sync/struct.Lazy.html -//! [`unsync::Lazy`]: unsync/struct.Lazy.html -//! -//! ## General purpose lazy evaluation -//! -//! Unlike `lazy_static!`, `Lazy` works with local variables. -//! -//! ```rust -//! use once_cell::unsync::Lazy; -//! -//! fn main() { -//! let ctx = vec![1, 2, 3]; -//! let thunk = Lazy::new(|| { -//! ctx.iter().sum::<i32>() -//! }); -//! assert_eq!(*thunk, 6); -//! } -//! ``` -//! -//! If you need a lazy field in a struct, you probably should use `OnceCell` -//! directly, because that will allow you to access `self` during -//! initialization. -//! -//! ```rust -//! use std::{fs, path::PathBuf}; -//! -//! use once_cell::unsync::OnceCell; -//! -//! struct Ctx { -//! config_path: PathBuf, -//! config: OnceCell<String>, -//! } -//! -//! impl Ctx { -//! pub fn get_config(&self) -> Result<&str, std::io::Error> { -//! let cfg = self.config.get_or_try_init(|| { -//! fs::read_to_string(&self.config_path) -//! })?; -//! Ok(cfg.as_str()) -//! } -//! } -//! ``` -//! -//! ## Lazily Compiled Regex -//! -//! This is a `regex!` macro which takes a string literal and returns an -//! *expression* that evaluates to a `&'static Regex`: -//! -//! ``` -//! macro_rules! regex { -//! ($re:literal $(,)?) => {{ -//! static RE: once_cell::sync::OnceCell<regex::Regex> = once_cell::sync::OnceCell::new(); -//! RE.get_or_init(|| regex::Regex::new($re).unwrap()) -//! }}; -//! } -//! ``` -//! -//! This macro can be useful to avoid the "compile regex on every loop -//! iteration" problem. -//! -//! ## Runtime `include_bytes!` -//! -//! The `include_bytes` macro is useful to include test resources, but it slows -//! down test compilation a lot. An alternative is to load the resources at -//! runtime: -//! -//! ``` -//! use std::path::Path; -//! -//! use once_cell::sync::OnceCell; -//! -//! pub struct TestResource { -//! path: &'static str, -//! cell: OnceCell<Vec<u8>>, -//! } -//! -//! impl TestResource { -//! pub const fn new(path: &'static str) -> TestResource { -//! TestResource { path, cell: OnceCell::new() } -//! } -//! pub fn bytes(&self) -> &[u8] { -//! self.cell.get_or_init(|| { -//! let dir = std::env::var("CARGO_MANIFEST_DIR").unwrap(); -//! let path = Path::new(dir.as_str()).join(self.path); -//! std::fs::read(&path).unwrap_or_else(|_err| { -//! panic!("failed to load test resource: {}", path.display()) -//! }) -//! }).as_slice() -//! } -//! } -//! -//! static TEST_IMAGE: TestResource = TestResource::new("test_data/lena.png"); -//! -//! #[test] -//! fn test_sobel_filter() { -//! let rgb: &[u8] = TEST_IMAGE.bytes(); -//! // ... -//! # drop(rgb); -//! } -//! ``` -//! -//! ## `lateinit` -//! -//! `LateInit` type for delayed initialization. It is reminiscent of Kotlin's -//! `lateinit` keyword and allows construction of cyclic data structures: -//! -//! -//! ``` -//! use once_cell::sync::OnceCell; -//! -//! pub struct LateInit<T> { cell: OnceCell<T> } -//! -//! impl<T> LateInit<T> { -//! pub fn init(&self, value: T) { -//! assert!(self.cell.set(value).is_ok()) -//! } -//! } -//! -//! impl<T> Default for LateInit<T> { -//! fn default() -> Self { LateInit { cell: OnceCell::default() } } -//! } -//! -//! impl<T> std::ops::Deref for LateInit<T> { -//! type Target = T; -//! fn deref(&self) -> &T { -//! self.cell.get().unwrap() -//! } -//! } -//! -//! #[derive(Default)] -//! struct A<'a> { -//! b: LateInit<&'a B<'a>>, -//! } -//! -//! #[derive(Default)] -//! struct B<'a> { -//! a: LateInit<&'a A<'a>> -//! } -//! -//! -//! fn build_cycle() { -//! let a = A::default(); -//! let b = B::default(); -//! a.b.init(&b); -//! b.a.init(&a); -//! -//! let _a = &a.b.a.b.a; -//! } -//! ``` -//! -//! # Comparison with std -//! -//! |`!Sync` types | Access Mode | Drawbacks | -//! |----------------------|------------------------|-----------------------------------------------| -//! |`Cell<T>` | `T` | requires `T: Copy` for `get` | -//! |`RefCell<T>` | `RefMut<T>` / `Ref<T>` | may panic at runtime | -//! |`unsync::OnceCell<T>` | `&T` | assignable only once | -//! -//! |`Sync` types | Access Mode | Drawbacks | -//! |----------------------|------------------------|-----------------------------------------------| -//! |`AtomicT` | `T` | works only with certain `Copy` types | -//! |`Mutex<T>` | `MutexGuard<T>` | may deadlock at runtime, may block the thread | -//! |`sync::OnceCell<T>` | `&T` | assignable only once, may block the thread | -//! -//! Technically, calling `get_or_init` will also cause a panic or a deadlock if -//! it recursively calls itself. However, because the assignment can happen only -//! once, such cases should be more rare than equivalents with `RefCell` and -//! `Mutex`. -//! -//! # Minimum Supported `rustc` Version -//! -//! If only the `std`, `alloc`, or `race` features are enabled, MSRV will be -//! updated conservatively, supporting at least latest 8 versions of the compiler. -//! When using other features, like `parking_lot`, MSRV might be updated more -//! frequently, up to the latest stable. In both cases, increasing MSRV is *not* -//! considered a semver-breaking change and requires only a minor version bump. -//! -//! # Implementation details -//! -//! The implementation is based on the -//! [`lazy_static`](https://github.com/rust-lang-nursery/lazy-static.rs/) and -//! [`lazy_cell`](https://github.com/indiv0/lazycell/) crates and -//! [`std::sync::Once`]. In some sense, `once_cell` just streamlines and unifies -//! those APIs. -//! -//! To implement a sync flavor of `OnceCell`, this crates uses either a custom -//! re-implementation of `std::sync::Once` or `parking_lot::Mutex`. This is -//! controlled by the `parking_lot` feature (disabled by default). Performance -//! is the same for both cases, but the `parking_lot` based `OnceCell<T>` is -//! smaller by up to 16 bytes. -//! -//! This crate uses `unsafe`. -//! -//! [`std::sync::Once`]: https://doc.rust-lang.org/std/sync/struct.Once.html -//! -//! # F.A.Q. -//! -//! **Should I use the sync or unsync flavor?** -//! -//! Because Rust compiler checks thread safety for you, it's impossible to -//! accidentally use `unsync` where `sync` is required. So, use `unsync` in -//! single-threaded code and `sync` in multi-threaded. It's easy to switch -//! between the two if code becomes multi-threaded later. -//! -//! At the moment, `unsync` has an additional benefit that reentrant -//! initialization causes a panic, which might be easier to debug than a -//! deadlock. -//! -//! **Does this crate support async?** -//! -//! No, but you can use -//! [`async_once_cell`](https://crates.io/crates/async_once_cell) instead. -//! -//! **Does this crate support `no_std`?** -//! -//! Yes, but with caveats. `OnceCell` is a synchronization primitive which -//! _semantically_ relies on blocking. `OnceCell` guarantees that at most one -//! `f` will be called to compute the value. If two threads of execution call -//! `get_or_init` concurrently, one of them has to wait. -//! -//! Waiting fundamentally requires OS support. Execution environment needs to -//! understand who waits on whom to prevent deadlocks due to priority inversion. -//! You _could_ make code to compile by blindly using pure spinlocks, but the -//! runtime behavior would be subtly wrong. -//! -//! Given these constraints, `once_cell` provides the following options: -//! -//! - The `race` module provides similar, but distinct synchronization primitive -//! which is compatible with `no_std`. With `race`, the `f` function can be -//! called multiple times by different threads, but only one thread will win -//! to install the value. -//! - `critical-section` feature (with a `-`, not `_`) uses `critical_section` -//! to implement blocking. -//! -//! **Can I bring my own mutex?** -//! -//! There is [generic_once_cell](https://crates.io/crates/generic_once_cell) to -//! allow just that. -//! -//! **Should I use `std::cell::OnceCell`, `once_cell`, or `lazy_static`?** -//! -//! If you can use `std` version (your MSRV is at least 1.70, and you don't need -//! extra features `once_cell` provides), use `std`. Otherwise, use `once_cell`. -//! Don't use `lazy_static`. -//! -//! # Related crates -//! -//! * Most of this crate's functionality is available in `std` starting with -//! Rust 1.70. See `std::cell::OnceCell` and `std::sync::OnceLock`. -//! * [double-checked-cell](https://github.com/niklasf/double-checked-cell) -//! * [lazy-init](https://crates.io/crates/lazy-init) -//! * [lazycell](https://crates.io/crates/lazycell) -//! * [mitochondria](https://crates.io/crates/mitochondria) -//! * [lazy_static](https://crates.io/crates/lazy_static) -//! * [async_once_cell](https://crates.io/crates/async_once_cell) -//! * [generic_once_cell](https://crates.io/crates/generic_once_cell) (bring -//! your own mutex) - -#![cfg_attr(not(feature = "std"), no_std)] - -#[cfg(feature = "alloc")] -extern crate alloc; - -#[cfg(all(feature = "critical-section", not(feature = "std")))] -#[path = "imp_cs.rs"] -mod imp; - -#[cfg(all(feature = "std", feature = "parking_lot"))] -#[path = "imp_pl.rs"] -mod imp; - -#[cfg(all(feature = "std", not(feature = "parking_lot")))] -#[path = "imp_std.rs"] -mod imp; - -/// Single-threaded version of `OnceCell`. -pub mod unsync { - use core::{ - cell::{Cell, UnsafeCell}, - fmt, mem, - ops::{Deref, DerefMut}, - panic::{RefUnwindSafe, UnwindSafe}, - }; - - /// A cell which can be written to only once. It is not thread safe. - /// - /// Unlike [`std::cell::RefCell`], a `OnceCell` provides simple `&` - /// references to the contents. - /// - /// [`std::cell::RefCell`]: https://doc.rust-lang.org/std/cell/struct.RefCell.html - /// - /// # Example - /// ``` - /// use once_cell::unsync::OnceCell; - /// - /// let cell = OnceCell::new(); - /// assert!(cell.get().is_none()); - /// - /// let value: &String = cell.get_or_init(|| { - /// "Hello, World!".to_string() - /// }); - /// assert_eq!(value, "Hello, World!"); - /// assert!(cell.get().is_some()); - /// ``` - pub struct OnceCell<T> { - // Invariant: written to at most once. - inner: UnsafeCell<Option<T>>, - } - - // Similarly to a `Sync` bound on `sync::OnceCell`, we can use - // `&unsync::OnceCell` to sneak a `T` through `catch_unwind`, - // by initializing the cell in closure and extracting the value in the - // `Drop`. - impl<T: RefUnwindSafe + UnwindSafe> RefUnwindSafe for OnceCell<T> {} - impl<T: UnwindSafe> UnwindSafe for OnceCell<T> {} - - impl<T> Default for OnceCell<T> { - fn default() -> Self { - Self::new() - } - } - - impl<T: fmt::Debug> fmt::Debug for OnceCell<T> { - fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { - match self.get() { - Some(v) => f.debug_tuple("OnceCell").field(v).finish(), - None => f.write_str("OnceCell(Uninit)"), - } - } - } - - impl<T: Clone> Clone for OnceCell<T> { - fn clone(&self) -> OnceCell<T> { - match self.get() { - Some(value) => OnceCell::with_value(value.clone()), - None => OnceCell::new(), - } - } - - fn clone_from(&mut self, source: &Self) { - match (self.get_mut(), source.get()) { - (Some(this), Some(source)) => this.clone_from(source), - _ => *self = source.clone(), - } - } - } - - impl<T: PartialEq> PartialEq for OnceCell<T> { - fn eq(&self, other: &Self) -> bool { - self.get() == other.get() - } - } - - impl<T: Eq> Eq for OnceCell<T> {} - - impl<T> From<T> for OnceCell<T> { - fn from(value: T) -> Self { - OnceCell::with_value(value) - } - } - - impl<T> OnceCell<T> { - /// Creates a new empty cell. - pub const fn new() -> OnceCell<T> { - OnceCell { inner: UnsafeCell::new(None) } - } - - /// Creates a new initialized cell. - pub const fn with_value(value: T) -> OnceCell<T> { - OnceCell { inner: UnsafeCell::new(Some(value)) } - } - - /// Gets a reference to the underlying value. - /// - /// Returns `None` if the cell is empty. - #[inline] - pub fn get(&self) -> Option<&T> { - // Safe due to `inner`'s invariant of being written to at most once. - // Had multiple writes to `inner` been allowed, a reference to the - // value we return now would become dangling by a write of a - // different value later. - unsafe { &*self.inner.get() }.as_ref() - } - - /// Gets a mutable reference to the underlying value. - /// - /// Returns `None` if the cell is empty. - /// - /// This method is allowed to violate the invariant of writing to a `OnceCell` - /// at most once because it requires `&mut` access to `self`. As with all - /// interior mutability, `&mut` access permits arbitrary modification: - /// - /// ``` - /// use once_cell::unsync::OnceCell; - /// - /// let mut cell: OnceCell<u32> = OnceCell::new(); - /// cell.set(92).unwrap(); - /// *cell.get_mut().unwrap() = 93; - /// assert_eq!(cell.get(), Some(&93)); - /// ``` - #[inline] - pub fn get_mut(&mut self) -> Option<&mut T> { - // Safe because we have unique access - unsafe { &mut *self.inner.get() }.as_mut() - } - - /// Sets the contents of this cell to `value`. - /// - /// Returns `Ok(())` if the cell was empty and `Err(value)` if it was - /// full. - /// - /// # Example - /// ``` - /// use once_cell::unsync::OnceCell; - /// - /// let cell = OnceCell::new(); - /// assert!(cell.get().is_none()); - /// - /// assert_eq!(cell.set(92), Ok(())); - /// assert_eq!(cell.set(62), Err(62)); - /// - /// assert!(cell.get().is_some()); - /// ``` - pub fn set(&self, value: T) -> Result<(), T> { - match self.try_insert(value) { - Ok(_) => Ok(()), - Err((_, value)) => Err(value), - } - } - - /// Like [`set`](Self::set), but also returns a reference to the final cell value. - /// - /// # Example - /// ``` - /// use once_cell::unsync::OnceCell; - /// - /// let cell = OnceCell::new(); - /// assert!(cell.get().is_none()); - /// - /// assert_eq!(cell.try_insert(92), Ok(&92)); - /// assert_eq!(cell.try_insert(62), Err((&92, 62))); - /// - /// assert!(cell.get().is_some()); - /// ``` - pub fn try_insert(&self, value: T) -> Result<&T, (&T, T)> { - if let Some(old) = self.get() { - return Err((old, value)); - } - - let slot = unsafe { &mut *self.inner.get() }; - // This is the only place where we set the slot, no races - // due to reentrancy/concurrency are possible, and we've - // checked that slot is currently `None`, so this write - // maintains the `inner`'s invariant. - *slot = Some(value); - Ok(unsafe { slot.as_ref().unwrap_unchecked() }) - } - - /// Gets the contents of the cell, initializing it with `f` - /// if the cell was empty. - /// - /// # Panics - /// - /// If `f` panics, the panic is propagated to the caller, and the cell - /// remains uninitialized. - /// - /// It is an error to reentrantly initialize the cell from `f`. Doing - /// so results in a panic. - /// - /// # Example - /// ``` - /// use once_cell::unsync::OnceCell; - /// - /// let cell = OnceCell::new(); - /// let value = cell.get_or_init(|| 92); - /// assert_eq!(value, &92); - /// let value = cell.get_or_init(|| unreachable!()); - /// assert_eq!(value, &92); - /// ``` - pub fn get_or_init<F>(&self, f: F) -> &T - where - F: FnOnce() -> T, - { - enum Void {} - match self.get_or_try_init(|| Ok::<T, Void>(f())) { - Ok(val) => val, - Err(void) => match void {}, - } - } - - /// Gets the contents of the cell, initializing it with `f` if - /// the cell was empty. If the cell was empty and `f` failed, an - /// error is returned. - /// - /// # Panics - /// - /// If `f` panics, the panic is propagated to the caller, and the cell - /// remains uninitialized. - /// - /// It is an error to reentrantly initialize the cell from `f`. Doing - /// so results in a panic. - /// - /// # Example - /// ``` - /// use once_cell::unsync::OnceCell; - /// - /// let cell = OnceCell::new(); - /// assert_eq!(cell.get_or_try_init(|| Err(())), Err(())); - /// assert!(cell.get().is_none()); - /// let value = cell.get_or_try_init(|| -> Result<i32, ()> { - /// Ok(92) - /// }); - /// assert_eq!(value, Ok(&92)); - /// assert_eq!(cell.get(), Some(&92)) - /// ``` - pub fn get_or_try_init<F, E>(&self, f: F) -> Result<&T, E> - where - F: FnOnce() -> Result<T, E>, - { - if let Some(val) = self.get() { - return Ok(val); - } - let val = f()?; - // Note that *some* forms of reentrant initialization might lead to - // UB (see `reentrant_init` test). I believe that just removing this - // `assert`, while keeping `set/get` would be sound, but it seems - // better to panic, rather than to silently use an old value. - assert!(self.set(val).is_ok(), "reentrant init"); - Ok(unsafe { self.get().unwrap_unchecked() }) - } - - /// Takes the value out of this `OnceCell`, moving it back to an uninitialized state. - /// - /// Has no effect and returns `None` if the `OnceCell` hasn't been initialized. - /// - /// # Examples - /// - /// ``` - /// use once_cell::unsync::OnceCell; - /// - /// let mut cell: OnceCell<String> = OnceCell::new(); - /// assert_eq!(cell.take(), None); - /// - /// let mut cell = OnceCell::new(); - /// cell.set("hello".to_string()).unwrap(); - /// assert_eq!(cell.take(), Some("hello".to_string())); - /// assert_eq!(cell.get(), None); - /// ``` - /// - /// This method is allowed to violate the invariant of writing to a `OnceCell` - /// at most once because it requires `&mut` access to `self`. As with all - /// interior mutability, `&mut` access permits arbitrary modification: - /// - /// ``` - /// use once_cell::unsync::OnceCell; - /// - /// let mut cell: OnceCell<u32> = OnceCell::new(); - /// cell.set(92).unwrap(); - /// cell = OnceCell::new(); - /// ``` - pub fn take(&mut self) -> Option<T> { - mem::take(self).into_inner() - } - - /// Consumes the `OnceCell`, returning the wrapped value. - /// - /// Returns `None` if the cell was empty. - /// - /// # Examples - /// - /// ``` - /// use once_cell::unsync::OnceCell; - /// - /// let cell: OnceCell<String> = OnceCell::new(); - /// assert_eq!(cell.into_inner(), None); - /// - /// let cell = OnceCell::new(); - /// cell.set("hello".to_string()).unwrap(); - /// assert_eq!(cell.into_inner(), Some("hello".to_string())); - /// ``` - pub fn into_inner(self) -> Option<T> { - // Because `into_inner` takes `self` by value, the compiler statically verifies - // that it is not currently borrowed. So it is safe to move out `Option<T>`. - self.inner.into_inner() - } - } - - /// A value which is initialized on the first access. - /// - /// # Example - /// ``` - /// use once_cell::unsync::Lazy; - /// - /// let lazy: Lazy<i32> = Lazy::new(|| { - /// println!("initializing"); - /// 92 - /// }); - /// println!("ready"); - /// println!("{}", *lazy); - /// println!("{}", *lazy); - /// - /// // Prints: - /// // ready - /// // initializing - /// // 92 - /// // 92 - /// ``` - pub struct Lazy<T, F = fn() -> T> { - cell: OnceCell<T>, - init: Cell<Option<F>>, - } - - impl<T, F: RefUnwindSafe> RefUnwindSafe for Lazy<T, F> where OnceCell<T>: RefUnwindSafe {} - - impl<T: fmt::Debug, F> fmt::Debug for Lazy<T, F> { - fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { - f.debug_struct("Lazy").field("cell", &self.cell).field("init", &"..").finish() - } - } - - impl<T, F> Lazy<T, F> { - /// Creates a new lazy value with the given initializing function. - /// - /// # Example - /// ``` - /// # fn main() { - /// use once_cell::unsync::Lazy; - /// - /// let hello = "Hello, World!".to_string(); - /// - /// let lazy = Lazy::new(|| hello.to_uppercase()); - /// - /// assert_eq!(&*lazy, "HELLO, WORLD!"); - /// # } - /// ``` - pub const fn new(init: F) -> Lazy<T, F> { - Lazy { cell: OnceCell::new(), init: Cell::new(Some(init)) } - } - - /// Consumes this `Lazy` returning the stored value. - /// - /// Returns `Ok(value)` if `Lazy` is initialized and `Err(f)` otherwise. - pub fn into_value(this: Lazy<T, F>) -> Result<T, F> { - let cell = this.cell; - let init = this.init; - cell.into_inner().ok_or_else(|| { - init.take().unwrap_or_else(|| panic!("Lazy instance has previously been poisoned")) - }) - } - } - - impl<T, F: FnOnce() -> T> Lazy<T, F> { - /// Forces the evaluation of this lazy value and returns a reference to - /// the result. - /// - /// This is equivalent to the `Deref` impl, but is explicit. - /// - /// # Example - /// ``` - /// use once_cell::unsync::Lazy; - /// - /// let lazy = Lazy::new(|| 92); - /// - /// assert_eq!(Lazy::force(&lazy), &92); - /// assert_eq!(&*lazy, &92); - /// ``` - pub fn force(this: &Lazy<T, F>) -> &T { - this.cell.get_or_init(|| match this.init.take() { - Some(f) => f(), - None => panic!("Lazy instance has previously been poisoned"), - }) - } - - /// Forces the evaluation of this lazy value and returns a mutable reference to - /// the result. - /// - /// This is equivalent to the `DerefMut` impl, but is explicit. - /// - /// # Example - /// ``` - /// use once_cell::unsync::Lazy; - /// - /// let mut lazy = Lazy::new(|| 92); - /// - /// assert_eq!(Lazy::force_mut(&mut lazy), &92); - /// assert_eq!(*lazy, 92); - /// ``` - pub fn force_mut(this: &mut Lazy<T, F>) -> &mut T { - if this.cell.get_mut().is_none() { - let value = match this.init.get_mut().take() { - Some(f) => f(), - None => panic!("Lazy instance has previously been poisoned"), - }; - this.cell = OnceCell::with_value(value); - } - this.cell.get_mut().unwrap_or_else(|| unreachable!()) - } - - /// Gets the reference to the result of this lazy value if - /// it was initialized, otherwise returns `None`. - /// - /// # Example - /// ``` - /// use once_cell::unsync::Lazy; - /// - /// let lazy = Lazy::new(|| 92); - /// - /// assert_eq!(Lazy::get(&lazy), None); - /// assert_eq!(&*lazy, &92); - /// assert_eq!(Lazy::get(&lazy), Some(&92)); - /// ``` - pub fn get(this: &Lazy<T, F>) -> Option<&T> { - this.cell.get() - } - - /// Gets the mutable reference to the result of this lazy value if - /// it was initialized, otherwise returns `None`. - /// - /// # Example - /// ``` - /// use once_cell::unsync::Lazy; - /// - /// let mut lazy = Lazy::new(|| 92); - /// - /// assert_eq!(Lazy::get_mut(&mut lazy), None); - /// assert_eq!(*lazy, 92); - /// assert_eq!(Lazy::get_mut(&mut lazy), Some(&mut 92)); - /// ``` - pub fn get_mut(this: &mut Lazy<T, F>) -> Option<&mut T> { - this.cell.get_mut() - } - } - - impl<T, F: FnOnce() -> T> Deref for Lazy<T, F> { - type Target = T; - fn deref(&self) -> &T { - Lazy::force(self) - } - } - - impl<T, F: FnOnce() -> T> DerefMut for Lazy<T, F> { - fn deref_mut(&mut self) -> &mut T { - Lazy::force_mut(self) - } - } - - impl<T: Default> Default for Lazy<T> { - /// Creates a new lazy value using `Default` as the initializing function. - fn default() -> Lazy<T> { - Lazy::new(T::default) - } - } -} - -/// Thread-safe, blocking version of `OnceCell`. -#[cfg(any(feature = "std", feature = "critical-section"))] -pub mod sync { - use core::{ - cell::Cell, - fmt, mem, - ops::{Deref, DerefMut}, - panic::RefUnwindSafe, - }; - - use super::imp::OnceCell as Imp; - - /// A thread-safe cell which can be written to only once. - /// - /// `OnceCell` provides `&` references to the contents without RAII guards. - /// - /// Reading a non-`None` value out of `OnceCell` establishes a - /// happens-before relationship with a corresponding write. For example, if - /// thread A initializes the cell with `get_or_init(f)`, and thread B - /// subsequently reads the result of this call, B also observes all the side - /// effects of `f`. - /// - /// # Example - /// ``` - /// use once_cell::sync::OnceCell; - /// - /// static CELL: OnceCell<String> = OnceCell::new(); - /// assert!(CELL.get().is_none()); - /// - /// std::thread::spawn(|| { - /// let value: &String = CELL.get_or_init(|| { - /// "Hello, World!".to_string() - /// }); - /// assert_eq!(value, "Hello, World!"); - /// }).join().unwrap(); - /// - /// let value: Option<&String> = CELL.get(); - /// assert!(value.is_some()); - /// assert_eq!(value.unwrap().as_str(), "Hello, World!"); - /// ``` - pub struct OnceCell<T>(Imp<T>); - - impl<T> Default for OnceCell<T> { - fn default() -> OnceCell<T> { - OnceCell::new() - } - } - - impl<T: fmt::Debug> fmt::Debug for OnceCell<T> { - fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { - match self.get() { - Some(v) => f.debug_tuple("OnceCell").field(v).finish(), - None => f.write_str("OnceCell(Uninit)"), - } - } - } - - impl<T: Clone> Clone for OnceCell<T> { - fn clone(&self) -> OnceCell<T> { - match self.get() { - Some(value) => Self::with_value(value.clone()), - None => Self::new(), - } - } - - fn clone_from(&mut self, source: &Self) { - match (self.get_mut(), source.get()) { - (Some(this), Some(source)) => this.clone_from(source), - _ => *self = source.clone(), - } - } - } - - impl<T> From<T> for OnceCell<T> { - fn from(value: T) -> Self { - Self::with_value(value) - } - } - - impl<T: PartialEq> PartialEq for OnceCell<T> { - fn eq(&self, other: &OnceCell<T>) -> bool { - self.get() == other.get() - } - } - - impl<T: Eq> Eq for OnceCell<T> {} - - impl<T> OnceCell<T> { - /// Creates a new empty cell. - pub const fn new() -> OnceCell<T> { - OnceCell(Imp::new()) - } - - /// Creates a new initialized cell. - pub const fn with_value(value: T) -> OnceCell<T> { - OnceCell(Imp::with_value(value)) - } - - /// Gets the reference to the underlying value. - /// - /// Returns `None` if the cell is empty, or being initialized. This - /// method never blocks. - pub fn get(&self) -> Option<&T> { - if self.0.is_initialized() { - // Safe b/c value is initialized. - Some(unsafe { self.get_unchecked() }) - } else { - None - } - } - - /// Gets the reference to the underlying value, blocking the current - /// thread until it is set. - /// - /// ``` - /// use once_cell::sync::OnceCell; - /// - /// let mut cell = std::sync::Arc::new(OnceCell::new()); - /// let t = std::thread::spawn({ - /// let cell = std::sync::Arc::clone(&cell); - /// move || cell.set(92).unwrap() - /// }); - /// - /// // Returns immediately, but might return None. - /// let _value_or_none = cell.get(); - /// - /// // Will return 92, but might block until the other thread does `.set`. - /// let value: &u32 = cell.wait(); - /// assert_eq!(*value, 92); - /// t.join().unwrap(); - /// ``` - #[cfg(feature = "std")] - pub fn wait(&self) -> &T { - if !self.0.is_initialized() { - self.0.wait() - } - debug_assert!(self.0.is_initialized()); - // Safe b/c of the wait call above and the fact that we didn't - // relinquish our borrow. - unsafe { self.get_unchecked() } - } - - /// Gets the mutable reference to the underlying value. - /// - /// Returns `None` if the cell is empty. - /// - /// This method is allowed to violate the invariant of writing to a `OnceCell` - /// at most once because it requires `&mut` access to `self`. As with all - /// interior mutability, `&mut` access permits arbitrary modification: - /// - /// ``` - /// use once_cell::sync::OnceCell; - /// - /// let mut cell: OnceCell<u32> = OnceCell::new(); - /// cell.set(92).unwrap(); - /// cell = OnceCell::new(); - /// ``` - #[inline] - pub fn get_mut(&mut self) -> Option<&mut T> { - self.0.get_mut() - } - - /// Get the reference to the underlying value, without checking if the - /// cell is initialized. - /// - /// # Safety - /// - /// Caller must ensure that the cell is in initialized state, and that - /// the contents are acquired by (synchronized to) this thread. - #[inline] - pub unsafe fn get_unchecked(&self) -> &T { - self.0.get_unchecked() - } - - /// Sets the contents of this cell to `value`. - /// - /// Returns `Ok(())` if the cell was empty and `Err(value)` if it was - /// full. - /// - /// # Example - /// - /// ``` - /// use once_cell::sync::OnceCell; - /// - /// static CELL: OnceCell<i32> = OnceCell::new(); - /// - /// fn main() { - /// assert!(CELL.get().is_none()); - /// - /// std::thread::spawn(|| { - /// assert_eq!(CELL.set(92), Ok(())); - /// }).join().unwrap(); - /// - /// assert_eq!(CELL.set(62), Err(62)); - /// assert_eq!(CELL.get(), Some(&92)); - /// } - /// ``` - pub fn set(&self, value: T) -> Result<(), T> { - match self.try_insert(value) { - Ok(_) => Ok(()), - Err((_, value)) => Err(value), - } - } - - /// Like [`set`](Self::set), but also returns a reference to the final cell value. - /// - /// # Example - /// - /// ``` - /// use once_cell::unsync::OnceCell; - /// - /// let cell = OnceCell::new(); - /// assert!(cell.get().is_none()); - /// - /// assert_eq!(cell.try_insert(92), Ok(&92)); - /// assert_eq!(cell.try_insert(62), Err((&92, 62))); - /// - /// assert!(cell.get().is_some()); - /// ``` - pub fn try_insert(&self, value: T) -> Result<&T, (&T, T)> { - let mut value = Some(value); - let res = self.get_or_init(|| unsafe { value.take().unwrap_unchecked() }); - match value { - None => Ok(res), - Some(value) => Err((res, value)), - } - } - - /// Gets the contents of the cell, initializing it with `f` if the cell - /// was empty. - /// - /// Many threads may call `get_or_init` concurrently with different - /// initializing functions, but it is guaranteed that only one function - /// will be executed. - /// - /// # Panics - /// - /// If `f` panics, the panic is propagated to the caller, and the cell - /// remains uninitialized. - /// - /// It is an error to reentrantly initialize the cell from `f`. The - /// exact outcome is unspecified. Current implementation deadlocks, but - /// this may be changed to a panic in the future. - /// - /// # Example - /// ``` - /// use once_cell::sync::OnceCell; - /// - /// let cell = OnceCell::new(); - /// let value = cell.get_or_init(|| 92); - /// assert_eq!(value, &92); - /// let value = cell.get_or_init(|| unreachable!()); - /// assert_eq!(value, &92); - /// ``` - pub fn get_or_init<F>(&self, f: F) -> &T - where - F: FnOnce() -> T, - { - enum Void {} - match self.get_or_try_init(|| Ok::<T, Void>(f())) { - Ok(val) => val, - Err(void) => match void {}, - } - } - - /// Gets the contents of the cell, initializing it with `f` if - /// the cell was empty. If the cell was empty and `f` failed, an - /// error is returned. - /// - /// # Panics - /// - /// If `f` panics, the panic is propagated to the caller, and - /// the cell remains uninitialized. - /// - /// It is an error to reentrantly initialize the cell from `f`. - /// The exact outcome is unspecified. Current implementation - /// deadlocks, but this may be changed to a panic in the future. - /// - /// # Example - /// ``` - /// use once_cell::sync::OnceCell; - /// - /// let cell = OnceCell::new(); - /// assert_eq!(cell.get_or_try_init(|| Err(())), Err(())); - /// assert!(cell.get().is_none()); - /// let value = cell.get_or_try_init(|| -> Result<i32, ()> { - /// Ok(92) - /// }); - /// assert_eq!(value, Ok(&92)); - /// assert_eq!(cell.get(), Some(&92)) - /// ``` - pub fn get_or_try_init<F, E>(&self, f: F) -> Result<&T, E> - where - F: FnOnce() -> Result<T, E>, - { - // Fast path check - if let Some(value) = self.get() { - return Ok(value); - } - - self.0.initialize(f)?; - - // Safe b/c value is initialized. - debug_assert!(self.0.is_initialized()); - Ok(unsafe { self.get_unchecked() }) - } - - /// Takes the value out of this `OnceCell`, moving it back to an uninitialized state. - /// - /// Has no effect and returns `None` if the `OnceCell` hasn't been initialized. - /// - /// # Examples - /// - /// ``` - /// use once_cell::sync::OnceCell; - /// - /// let mut cell: OnceCell<String> = OnceCell::new(); - /// assert_eq!(cell.take(), None); - /// - /// let mut cell = OnceCell::new(); - /// cell.set("hello".to_string()).unwrap(); - /// assert_eq!(cell.take(), Some("hello".to_string())); - /// assert_eq!(cell.get(), None); - /// ``` - /// - /// This method is allowed to violate the invariant of writing to a `OnceCell` - /// at most once because it requires `&mut` access to `self`. As with all - /// interior mutability, `&mut` access permits arbitrary modification: - /// - /// ``` - /// use once_cell::sync::OnceCell; - /// - /// let mut cell: OnceCell<u32> = OnceCell::new(); - /// cell.set(92).unwrap(); - /// cell = OnceCell::new(); - /// ``` - pub fn take(&mut self) -> Option<T> { - mem::take(self).into_inner() - } - - /// Consumes the `OnceCell`, returning the wrapped value. Returns - /// `None` if the cell was empty. - /// - /// # Examples - /// - /// ``` - /// use once_cell::sync::OnceCell; - /// - /// let cell: OnceCell<String> = OnceCell::new(); - /// assert_eq!(cell.into_inner(), None); - /// - /// let cell = OnceCell::new(); - /// cell.set("hello".to_string()).unwrap(); - /// assert_eq!(cell.into_inner(), Some("hello".to_string())); - /// ``` - #[inline] - pub fn into_inner(self) -> Option<T> { - self.0.into_inner() - } - } - - /// A value which is initialized on the first access. - /// - /// This type is thread-safe and can be used in statics. - /// - /// # Example - /// - /// ``` - /// use std::collections::HashMap; - /// - /// use once_cell::sync::Lazy; - /// - /// static HASHMAP: Lazy<HashMap<i32, String>> = Lazy::new(|| { - /// println!("initializing"); - /// let mut m = HashMap::new(); - /// m.insert(13, "Spica".to_string()); - /// m.insert(74, "Hoyten".to_string()); - /// m - /// }); - /// - /// fn main() { - /// println!("ready"); - /// std::thread::spawn(|| { - /// println!("{:?}", HASHMAP.get(&13)); - /// }).join().unwrap(); - /// println!("{:?}", HASHMAP.get(&74)); - /// - /// // Prints: - /// // ready - /// // initializing - /// // Some("Spica") - /// // Some("Hoyten") - /// } - /// ``` - pub struct Lazy<T, F = fn() -> T> { - cell: OnceCell<T>, - init: Cell<Option<F>>, - } - - impl<T: fmt::Debug, F> fmt::Debug for Lazy<T, F> { - fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { - f.debug_struct("Lazy").field("cell", &self.cell).field("init", &"..").finish() - } - } - - // We never create a `&F` from a `&Lazy<T, F>` so it is fine to not impl - // `Sync` for `F`. We do create a `&mut Option<F>` in `force`, but this is - // properly synchronized, so it only happens once so it also does not - // contribute to this impl. - unsafe impl<T, F: Send> Sync for Lazy<T, F> where OnceCell<T>: Sync {} - // auto-derived `Send` impl is OK. - - impl<T, F: RefUnwindSafe> RefUnwindSafe for Lazy<T, F> where OnceCell<T>: RefUnwindSafe {} - - impl<T, F> Lazy<T, F> { - /// Creates a new lazy value with the given initializing - /// function. - pub const fn new(f: F) -> Lazy<T, F> { - Lazy { cell: OnceCell::new(), init: Cell::new(Some(f)) } - } - - /// Consumes this `Lazy` returning the stored value. - /// - /// Returns `Ok(value)` if `Lazy` is initialized and `Err(f)` otherwise. - pub fn into_value(this: Lazy<T, F>) -> Result<T, F> { - let cell = this.cell; - let init = this.init; - cell.into_inner().ok_or_else(|| { - init.take().unwrap_or_else(|| panic!("Lazy instance has previously been poisoned")) - }) - } - } - - impl<T, F: FnOnce() -> T> Lazy<T, F> { - /// Forces the evaluation of this lazy value and - /// returns a reference to the result. This is equivalent - /// to the `Deref` impl, but is explicit. - /// - /// # Example - /// ``` - /// use once_cell::sync::Lazy; - /// - /// let lazy = Lazy::new(|| 92); - /// - /// assert_eq!(Lazy::force(&lazy), &92); - /// assert_eq!(&*lazy, &92); - /// ``` - pub fn force(this: &Lazy<T, F>) -> &T { - this.cell.get_or_init(|| match this.init.take() { - Some(f) => f(), - None => panic!("Lazy instance has previously been poisoned"), - }) - } - - /// Forces the evaluation of this lazy value and - /// returns a mutable reference to the result. This is equivalent - /// to the `Deref` impl, but is explicit. - /// - /// # Example - /// ``` - /// use once_cell::sync::Lazy; - /// - /// let mut lazy = Lazy::new(|| 92); - /// - /// assert_eq!(Lazy::force_mut(&mut lazy), &mut 92); - /// ``` - pub fn force_mut(this: &mut Lazy<T, F>) -> &mut T { - if this.cell.get_mut().is_none() { - let value = match this.init.get_mut().take() { - Some(f) => f(), - None => panic!("Lazy instance has previously been poisoned"), - }; - this.cell = OnceCell::with_value(value); - } - this.cell.get_mut().unwrap_or_else(|| unreachable!()) - } - - /// Gets the reference to the result of this lazy value if - /// it was initialized, otherwise returns `None`. - /// - /// # Example - /// ``` - /// use once_cell::sync::Lazy; - /// - /// let lazy = Lazy::new(|| 92); - /// - /// assert_eq!(Lazy::get(&lazy), None); - /// assert_eq!(&*lazy, &92); - /// assert_eq!(Lazy::get(&lazy), Some(&92)); - /// ``` - pub fn get(this: &Lazy<T, F>) -> Option<&T> { - this.cell.get() - } - - /// Gets the reference to the result of this lazy value if - /// it was initialized, otherwise returns `None`. - /// - /// # Example - /// ``` - /// use once_cell::sync::Lazy; - /// - /// let mut lazy = Lazy::new(|| 92); - /// - /// assert_eq!(Lazy::get_mut(&mut lazy), None); - /// assert_eq!(&*lazy, &92); - /// assert_eq!(Lazy::get_mut(&mut lazy), Some(&mut 92)); - /// ``` - pub fn get_mut(this: &mut Lazy<T, F>) -> Option<&mut T> { - this.cell.get_mut() - } - } - - impl<T, F: FnOnce() -> T> Deref for Lazy<T, F> { - type Target = T; - fn deref(&self) -> &T { - Lazy::force(self) - } - } - - impl<T, F: FnOnce() -> T> DerefMut for Lazy<T, F> { - fn deref_mut(&mut self) -> &mut T { - Lazy::force_mut(self) - } - } - - impl<T: Default> Default for Lazy<T> { - /// Creates a new lazy value using `Default` as the initializing function. - fn default() -> Lazy<T> { - Lazy::new(T::default) - } - } - - /// ```compile_fail - /// struct S(*mut ()); - /// unsafe impl Sync for S {} - /// - /// fn share<T: Sync>(_: &T) {} - /// share(&once_cell::sync::OnceCell::<S>::new()); - /// ``` - /// - /// ```compile_fail - /// struct S(*mut ()); - /// unsafe impl Sync for S {} - /// - /// fn share<T: Sync>(_: &T) {} - /// share(&once_cell::sync::Lazy::<S>::new(|| unimplemented!())); - /// ``` - fn _dummy() {} -} - -#[cfg(feature = "race")] -pub mod race; diff --git a/vendor/once_cell/src/race.rs b/vendor/once_cell/src/race.rs deleted file mode 100644 index da8a2fc..0000000 --- a/vendor/once_cell/src/race.rs +++ /dev/null @@ -1,419 +0,0 @@ -//! Thread-safe, non-blocking, "first one wins" flavor of `OnceCell`. -//! -//! If two threads race to initialize a type from the `race` module, they -//! don't block, execute initialization function together, but only one of -//! them stores the result. -//! -//! This module does not require `std` feature. -//! -//! # Atomic orderings -//! -//! All types in this module use `Acquire` and `Release` -//! [atomic orderings](Ordering) for all their operations. While this is not -//! strictly necessary for types other than `OnceBox`, it is useful for users as -//! it allows them to be certain that after `get` or `get_or_init` returns on -//! one thread, any side-effects caused by the setter thread prior to them -//! calling `set` or `get_or_init` will be made visible to that thread; without -//! it, it's possible for it to appear as if they haven't happened yet from the -//! getter thread's perspective. This is an acceptable tradeoff to make since -//! `Acquire` and `Release` have very little performance overhead on most -//! architectures versus `Relaxed`. - -#[cfg(feature = "critical-section")] -use portable_atomic as atomic; -#[cfg(not(feature = "critical-section"))] -use core::sync::atomic; - -use atomic::{AtomicPtr, AtomicUsize, Ordering}; -use core::cell::UnsafeCell; -use core::marker::PhantomData; -use core::num::NonZeroUsize; -use core::ptr; - -/// A thread-safe cell which can be written to only once. -#[derive(Default, Debug)] -pub struct OnceNonZeroUsize { - inner: AtomicUsize, -} - -impl OnceNonZeroUsize { - /// Creates a new empty cell. - #[inline] - pub const fn new() -> OnceNonZeroUsize { - OnceNonZeroUsize { inner: AtomicUsize::new(0) } - } - - /// Gets the underlying value. - #[inline] - pub fn get(&self) -> Option<NonZeroUsize> { - let val = self.inner.load(Ordering::Acquire); - NonZeroUsize::new(val) - } - - /// Sets the contents of this cell to `value`. - /// - /// Returns `Ok(())` if the cell was empty and `Err(())` if it was - /// full. - #[inline] - pub fn set(&self, value: NonZeroUsize) -> Result<(), ()> { - let exchange = - self.inner.compare_exchange(0, value.get(), Ordering::AcqRel, Ordering::Acquire); - match exchange { - Ok(_) => Ok(()), - Err(_) => Err(()), - } - } - - /// Gets the contents of the cell, initializing it with `f` if the cell was - /// empty. - /// - /// If several threads concurrently run `get_or_init`, more than one `f` can - /// be called. However, all threads will return the same value, produced by - /// some `f`. - pub fn get_or_init<F>(&self, f: F) -> NonZeroUsize - where - F: FnOnce() -> NonZeroUsize, - { - enum Void {} - match self.get_or_try_init(|| Ok::<NonZeroUsize, Void>(f())) { - Ok(val) => val, - Err(void) => match void {}, - } - } - - /// Gets the contents of the cell, initializing it with `f` if - /// the cell was empty. If the cell was empty and `f` failed, an - /// error is returned. - /// - /// If several threads concurrently run `get_or_init`, more than one `f` can - /// be called. However, all threads will return the same value, produced by - /// some `f`. - pub fn get_or_try_init<F, E>(&self, f: F) -> Result<NonZeroUsize, E> - where - F: FnOnce() -> Result<NonZeroUsize, E>, - { - let val = self.inner.load(Ordering::Acquire); - let res = match NonZeroUsize::new(val) { - Some(it) => it, - None => { - let mut val = f()?.get(); - let exchange = - self.inner.compare_exchange(0, val, Ordering::AcqRel, Ordering::Acquire); - if let Err(old) = exchange { - val = old; - } - unsafe { NonZeroUsize::new_unchecked(val) } - } - }; - Ok(res) - } -} - -/// A thread-safe cell which can be written to only once. -#[derive(Default, Debug)] -pub struct OnceBool { - inner: OnceNonZeroUsize, -} - -impl OnceBool { - /// Creates a new empty cell. - #[inline] - pub const fn new() -> OnceBool { - OnceBool { inner: OnceNonZeroUsize::new() } - } - - /// Gets the underlying value. - #[inline] - pub fn get(&self) -> Option<bool> { - self.inner.get().map(OnceBool::from_usize) - } - - /// Sets the contents of this cell to `value`. - /// - /// Returns `Ok(())` if the cell was empty and `Err(())` if it was - /// full. - #[inline] - pub fn set(&self, value: bool) -> Result<(), ()> { - self.inner.set(OnceBool::to_usize(value)) - } - - /// Gets the contents of the cell, initializing it with `f` if the cell was - /// empty. - /// - /// If several threads concurrently run `get_or_init`, more than one `f` can - /// be called. However, all threads will return the same value, produced by - /// some `f`. - pub fn get_or_init<F>(&self, f: F) -> bool - where - F: FnOnce() -> bool, - { - OnceBool::from_usize(self.inner.get_or_init(|| OnceBool::to_usize(f()))) - } - - /// Gets the contents of the cell, initializing it with `f` if - /// the cell was empty. If the cell was empty and `f` failed, an - /// error is returned. - /// - /// If several threads concurrently run `get_or_init`, more than one `f` can - /// be called. However, all threads will return the same value, produced by - /// some `f`. - pub fn get_or_try_init<F, E>(&self, f: F) -> Result<bool, E> - where - F: FnOnce() -> Result<bool, E>, - { - self.inner.get_or_try_init(|| f().map(OnceBool::to_usize)).map(OnceBool::from_usize) - } - - #[inline] - fn from_usize(value: NonZeroUsize) -> bool { - value.get() == 1 - } - - #[inline] - fn to_usize(value: bool) -> NonZeroUsize { - unsafe { NonZeroUsize::new_unchecked(if value { 1 } else { 2 }) } - } -} - -/// A thread-safe cell which can be written to only once. -pub struct OnceRef<'a, T> { - inner: AtomicPtr<T>, - ghost: PhantomData<UnsafeCell<&'a T>>, -} - -// TODO: Replace UnsafeCell with SyncUnsafeCell once stabilized -unsafe impl<'a, T: Sync> Sync for OnceRef<'a, T> {} - -impl<'a, T> core::fmt::Debug for OnceRef<'a, T> { - fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result { - write!(f, "OnceRef({:?})", self.inner) - } -} - -impl<'a, T> Default for OnceRef<'a, T> { - fn default() -> Self { - Self::new() - } -} - -impl<'a, T> OnceRef<'a, T> { - /// Creates a new empty cell. - pub const fn new() -> OnceRef<'a, T> { - OnceRef { inner: AtomicPtr::new(ptr::null_mut()), ghost: PhantomData } - } - - /// Gets a reference to the underlying value. - pub fn get(&self) -> Option<&'a T> { - let ptr = self.inner.load(Ordering::Acquire); - unsafe { ptr.as_ref() } - } - - /// Sets the contents of this cell to `value`. - /// - /// Returns `Ok(())` if the cell was empty and `Err(value)` if it was - /// full. - pub fn set(&self, value: &'a T) -> Result<(), ()> { - let ptr = value as *const T as *mut T; - let exchange = - self.inner.compare_exchange(ptr::null_mut(), ptr, Ordering::AcqRel, Ordering::Acquire); - match exchange { - Ok(_) => Ok(()), - Err(_) => Err(()), - } - } - - /// Gets the contents of the cell, initializing it with `f` if the cell was - /// empty. - /// - /// If several threads concurrently run `get_or_init`, more than one `f` can - /// be called. However, all threads will return the same value, produced by - /// some `f`. - pub fn get_or_init<F>(&self, f: F) -> &'a T - where - F: FnOnce() -> &'a T, - { - enum Void {} - match self.get_or_try_init(|| Ok::<&'a T, Void>(f())) { - Ok(val) => val, - Err(void) => match void {}, - } - } - - /// Gets the contents of the cell, initializing it with `f` if - /// the cell was empty. If the cell was empty and `f` failed, an - /// error is returned. - /// - /// If several threads concurrently run `get_or_init`, more than one `f` can - /// be called. However, all threads will return the same value, produced by - /// some `f`. - pub fn get_or_try_init<F, E>(&self, f: F) -> Result<&'a T, E> - where - F: FnOnce() -> Result<&'a T, E>, - { - let mut ptr = self.inner.load(Ordering::Acquire); - - if ptr.is_null() { - // TODO replace with `cast_mut` when MSRV reaches 1.65.0 (also in `set`) - ptr = f()? as *const T as *mut T; - let exchange = self.inner.compare_exchange( - ptr::null_mut(), - ptr, - Ordering::AcqRel, - Ordering::Acquire, - ); - if let Err(old) = exchange { - ptr = old; - } - } - - Ok(unsafe { &*ptr }) - } - - /// ```compile_fail - /// use once_cell::race::OnceRef; - /// - /// let mut l = OnceRef::new(); - /// - /// { - /// let y = 2; - /// let mut r = OnceRef::new(); - /// r.set(&y).unwrap(); - /// core::mem::swap(&mut l, &mut r); - /// } - /// - /// // l now contains a dangling reference to y - /// eprintln!("uaf: {}", l.get().unwrap()); - /// ``` - fn _dummy() {} -} - -#[cfg(feature = "alloc")] -pub use self::once_box::OnceBox; - -#[cfg(feature = "alloc")] -mod once_box { - use super::atomic::{AtomicPtr, Ordering}; - use core::{marker::PhantomData, ptr}; - - use alloc::boxed::Box; - - /// A thread-safe cell which can be written to only once. - pub struct OnceBox<T> { - inner: AtomicPtr<T>, - ghost: PhantomData<Option<Box<T>>>, - } - - impl<T> core::fmt::Debug for OnceBox<T> { - fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result { - write!(f, "OnceBox({:?})", self.inner.load(Ordering::Relaxed)) - } - } - - impl<T> Default for OnceBox<T> { - fn default() -> Self { - Self::new() - } - } - - impl<T> Drop for OnceBox<T> { - fn drop(&mut self) { - let ptr = *self.inner.get_mut(); - if !ptr.is_null() { - drop(unsafe { Box::from_raw(ptr) }) - } - } - } - - impl<T> OnceBox<T> { - /// Creates a new empty cell. - pub const fn new() -> OnceBox<T> { - OnceBox { inner: AtomicPtr::new(ptr::null_mut()), ghost: PhantomData } - } - - /// Gets a reference to the underlying value. - pub fn get(&self) -> Option<&T> { - let ptr = self.inner.load(Ordering::Acquire); - if ptr.is_null() { - return None; - } - Some(unsafe { &*ptr }) - } - - /// Sets the contents of this cell to `value`. - /// - /// Returns `Ok(())` if the cell was empty and `Err(value)` if it was - /// full. - pub fn set(&self, value: Box<T>) -> Result<(), Box<T>> { - let ptr = Box::into_raw(value); - let exchange = self.inner.compare_exchange( - ptr::null_mut(), - ptr, - Ordering::AcqRel, - Ordering::Acquire, - ); - if exchange.is_err() { - let value = unsafe { Box::from_raw(ptr) }; - return Err(value); - } - Ok(()) - } - - /// Gets the contents of the cell, initializing it with `f` if the cell was - /// empty. - /// - /// If several threads concurrently run `get_or_init`, more than one `f` can - /// be called. However, all threads will return the same value, produced by - /// some `f`. - pub fn get_or_init<F>(&self, f: F) -> &T - where - F: FnOnce() -> Box<T>, - { - enum Void {} - match self.get_or_try_init(|| Ok::<Box<T>, Void>(f())) { - Ok(val) => val, - Err(void) => match void {}, - } - } - - /// Gets the contents of the cell, initializing it with `f` if - /// the cell was empty. If the cell was empty and `f` failed, an - /// error is returned. - /// - /// If several threads concurrently run `get_or_init`, more than one `f` can - /// be called. However, all threads will return the same value, produced by - /// some `f`. - pub fn get_or_try_init<F, E>(&self, f: F) -> Result<&T, E> - where - F: FnOnce() -> Result<Box<T>, E>, - { - let mut ptr = self.inner.load(Ordering::Acquire); - - if ptr.is_null() { - let val = f()?; - ptr = Box::into_raw(val); - let exchange = self.inner.compare_exchange( - ptr::null_mut(), - ptr, - Ordering::AcqRel, - Ordering::Acquire, - ); - if let Err(old) = exchange { - drop(unsafe { Box::from_raw(ptr) }); - ptr = old; - } - }; - Ok(unsafe { &*ptr }) - } - } - - unsafe impl<T: Sync + Send> Sync for OnceBox<T> {} - - /// ```compile_fail - /// struct S(*mut ()); - /// unsafe impl Sync for S {} - /// - /// fn share<T: Sync>(_: &T) {} - /// share(&once_cell::race::OnceBox::<S>::new()); - /// ``` - fn _dummy() {} -} |