pub struct OnceCell<T>(_);
ast
only.Expand description
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!");
Implementations
sourceimpl<T> OnceCell<T>
impl<T> OnceCell<T>
sourcepub const fn with_value(value: T) -> OnceCell<T>
pub const fn with_value(value: T) -> OnceCell<T>
Creates a new initialized cell.
sourcepub fn get(&self) -> Option<&T>
pub fn get(&self) -> Option<&T>
Gets the reference to the underlying value.
Returns None
if the cell is empty, or being initialized. This
method never blocks.
sourcepub fn wait(&self) -> &T
pub fn wait(&self) -> &T
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();;
sourcepub fn get_mut(&mut self) -> Option<&mut T>
pub fn get_mut(&mut self) -> Option<&mut T>
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();
sourcepub unsafe fn get_unchecked(&self) -> &T
pub unsafe fn get_unchecked(&self) -> &T
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.
sourcepub fn set(&self, value: T) -> Result<(), T>
pub fn set(&self, value: T) -> Result<(), T>
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));
}
sourcepub fn try_insert(&self, value: T) -> Result<&T, (&T, T)>
pub fn try_insert(&self, value: T) -> Result<&T, (&T, T)>
sourcepub fn get_or_init<F>(&self, f: F) -> &T where
F: FnOnce() -> T,
pub fn get_or_init<F>(&self, f: F) -> &T where
F: FnOnce() -> T,
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);
sourcepub fn get_or_try_init<F, E>(&self, f: F) -> Result<&T, E> where
F: FnOnce() -> Result<T, E>,
pub fn get_or_try_init<F, E>(&self, f: F) -> Result<&T, E> where
F: FnOnce() -> Result<T, E>,
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))
sourcepub fn take(&mut self) -> Option<T>
pub fn take(&mut self) -> Option<T>
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();
sourcepub fn into_inner(self) -> Option<T>
pub fn into_inner(self) -> Option<T>
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()));
Trait Implementations
sourceimpl<T> PartialEq<OnceCell<T>> for OnceCell<T> where
T: PartialEq<T>,
impl<T> PartialEq<OnceCell<T>> for OnceCell<T> where
T: PartialEq<T>,
impl<T> Eq for OnceCell<T> where
T: Eq,
Auto Trait Implementations
impl<T> RefUnwindSafe for OnceCell<T> where
T: UnwindSafe + RefUnwindSafe,
impl<T> Send for OnceCell<T> where
T: Send,
impl<T> Sync for OnceCell<T> where
T: Send + Sync,
impl<T> Unpin for OnceCell<T> where
T: Unpin,
impl<T> UnwindSafe for OnceCell<T> where
T: UnwindSafe,
Blanket Implementations
impl<T> ArchivePointee for T
impl<T> ArchivePointee for T
type ArchivedMetadata = ()
type ArchivedMetadata = ()
The archived version of the pointer metadata for this type.
fn pointer_metadata(
&<T as ArchivePointee>::ArchivedMetadata
) -> <T as Pointee>::Metadata
fn pointer_metadata(
&<T as ArchivePointee>::ArchivedMetadata
) -> <T as Pointee>::Metadata
Converts some archived metadata to the pointer metadata for itself.
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcefn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more
impl<F, W, T, D> Deserialize<With<T, W>, D> for F where
W: DeserializeWith<F, T, D>,
D: Fallible + ?Sized,
F: ?Sized,
impl<F, W, T, D> Deserialize<With<T, W>, D> for F where
W: DeserializeWith<F, T, D>,
D: Fallible + ?Sized,
F: ?Sized,
fn deserialize(
&self,
deserializer: &mut D
) -> Result<With<T, W>, <D as Fallible>::Error>
fn deserialize(
&self,
deserializer: &mut D
) -> Result<With<T, W>, <D as Fallible>::Error>
Deserializes using the given deserializer
sourceimpl<Q, K> Equivalent<K> for Q where
Q: Eq + ?Sized,
K: Borrow<Q> + ?Sized,
impl<Q, K> Equivalent<K> for Q where
Q: Eq + ?Sized,
K: Borrow<Q> + ?Sized,
sourcefn equivalent(&self, key: &K) -> bool
fn equivalent(&self, key: &K) -> bool
Compare self to key
and return true
if they are equal.
sourceimpl<T> ImplicitClone for T where
T: Clone,
impl<T> ImplicitClone for T where
T: Clone,
sourcefn clone_quote_var(&self) -> Self
fn clone_quote_var(&self) -> Self
quote
only.sourceimpl<T> Instrument for T
impl<T> Instrument for T
sourcefn instrument(self, span: Span) -> Instrumented<Self>
fn instrument(self, span: Span) -> Instrumented<Self>
sourcefn in_current_span(self) -> Instrumented<Self>
fn in_current_span(self) -> Instrumented<Self>
impl<D> OwoColorize for D
impl<D> OwoColorize for D
fn fg<C>(&self) -> FgColorDisplay<'_, C, Self> where
C: Color,
fn fg<C>(&self) -> FgColorDisplay<'_, C, Self> where
C: Color,
Set the foreground color generically Read more
fn bg<C>(&self) -> BgColorDisplay<'_, C, Self> where
C: Color,
fn bg<C>(&self) -> BgColorDisplay<'_, C, Self> where
C: Color,
Set the background color generically. Read more
fn black(&'a self) -> FgColorDisplay<'a, Black, Self>
fn black(&'a self) -> FgColorDisplay<'a, Black, Self>
Change the foreground color to black
fn on_black(&'a self) -> BgColorDisplay<'a, Black, Self>
fn on_black(&'a self) -> BgColorDisplay<'a, Black, Self>
Change the background color to black
fn red(&'a self) -> FgColorDisplay<'a, Red, Self>
fn red(&'a self) -> FgColorDisplay<'a, Red, Self>
Change the foreground color to red
fn on_red(&'a self) -> BgColorDisplay<'a, Red, Self>
fn on_red(&'a self) -> BgColorDisplay<'a, Red, Self>
Change the background color to red
fn green(&'a self) -> FgColorDisplay<'a, Green, Self>
fn green(&'a self) -> FgColorDisplay<'a, Green, Self>
Change the foreground color to green
fn on_green(&'a self) -> BgColorDisplay<'a, Green, Self>
fn on_green(&'a self) -> BgColorDisplay<'a, Green, Self>
Change the background color to green
fn yellow(&'a self) -> FgColorDisplay<'a, Yellow, Self>
fn yellow(&'a self) -> FgColorDisplay<'a, Yellow, Self>
Change the foreground color to yellow
fn on_yellow(&'a self) -> BgColorDisplay<'a, Yellow, Self>
fn on_yellow(&'a self) -> BgColorDisplay<'a, Yellow, Self>
Change the background color to yellow
fn blue(&'a self) -> FgColorDisplay<'a, Blue, Self>
fn blue(&'a self) -> FgColorDisplay<'a, Blue, Self>
Change the foreground color to blue
fn on_blue(&'a self) -> BgColorDisplay<'a, Blue, Self>
fn on_blue(&'a self) -> BgColorDisplay<'a, Blue, Self>
Change the background color to blue
fn magenta(&'a self) -> FgColorDisplay<'a, Magenta, Self>
fn magenta(&'a self) -> FgColorDisplay<'a, Magenta, Self>
Change the foreground color to magenta
fn on_magenta(&'a self) -> BgColorDisplay<'a, Magenta, Self>
fn on_magenta(&'a self) -> BgColorDisplay<'a, Magenta, Self>
Change the background color to magenta
fn purple(&'a self) -> FgColorDisplay<'a, Magenta, Self>
fn purple(&'a self) -> FgColorDisplay<'a, Magenta, Self>
Change the foreground color to purple
fn on_purple(&'a self) -> BgColorDisplay<'a, Magenta, Self>
fn on_purple(&'a self) -> BgColorDisplay<'a, Magenta, Self>
Change the background color to purple
fn cyan(&'a self) -> FgColorDisplay<'a, Cyan, Self>
fn cyan(&'a self) -> FgColorDisplay<'a, Cyan, Self>
Change the foreground color to cyan
fn on_cyan(&'a self) -> BgColorDisplay<'a, Cyan, Self>
fn on_cyan(&'a self) -> BgColorDisplay<'a, Cyan, Self>
Change the background color to cyan
fn white(&'a self) -> FgColorDisplay<'a, White, Self>
fn white(&'a self) -> FgColorDisplay<'a, White, Self>
Change the foreground color to white
fn on_white(&'a self) -> BgColorDisplay<'a, White, Self>
fn on_white(&'a self) -> BgColorDisplay<'a, White, Self>
Change the background color to white
fn default_color(&'a self) -> FgColorDisplay<'a, Default, Self>
fn default_color(&'a self) -> FgColorDisplay<'a, Default, Self>
Change the foreground color to the terminal default
fn on_default_color(&'a self) -> BgColorDisplay<'a, Default, Self>
fn on_default_color(&'a self) -> BgColorDisplay<'a, Default, Self>
Change the background color to the terminal default
fn bright_black(&'a self) -> FgColorDisplay<'a, BrightBlack, Self>
fn bright_black(&'a self) -> FgColorDisplay<'a, BrightBlack, Self>
Change the foreground color to bright black
fn on_bright_black(&'a self) -> BgColorDisplay<'a, BrightBlack, Self>
fn on_bright_black(&'a self) -> BgColorDisplay<'a, BrightBlack, Self>
Change the background color to bright black
fn bright_red(&'a self) -> FgColorDisplay<'a, BrightRed, Self>
fn bright_red(&'a self) -> FgColorDisplay<'a, BrightRed, Self>
Change the foreground color to bright red
fn on_bright_red(&'a self) -> BgColorDisplay<'a, BrightRed, Self>
fn on_bright_red(&'a self) -> BgColorDisplay<'a, BrightRed, Self>
Change the background color to bright red
fn bright_green(&'a self) -> FgColorDisplay<'a, BrightGreen, Self>
fn bright_green(&'a self) -> FgColorDisplay<'a, BrightGreen, Self>
Change the foreground color to bright green
fn on_bright_green(&'a self) -> BgColorDisplay<'a, BrightGreen, Self>
fn on_bright_green(&'a self) -> BgColorDisplay<'a, BrightGreen, Self>
Change the background color to bright green
fn bright_yellow(&'a self) -> FgColorDisplay<'a, BrightYellow, Self>
fn bright_yellow(&'a self) -> FgColorDisplay<'a, BrightYellow, Self>
Change the foreground color to bright yellow
fn on_bright_yellow(&'a self) -> BgColorDisplay<'a, BrightYellow, Self>
fn on_bright_yellow(&'a self) -> BgColorDisplay<'a, BrightYellow, Self>
Change the background color to bright yellow
fn bright_blue(&'a self) -> FgColorDisplay<'a, BrightBlue, Self>
fn bright_blue(&'a self) -> FgColorDisplay<'a, BrightBlue, Self>
Change the foreground color to bright blue
fn on_bright_blue(&'a self) -> BgColorDisplay<'a, BrightBlue, Self>
fn on_bright_blue(&'a self) -> BgColorDisplay<'a, BrightBlue, Self>
Change the background color to bright blue
fn bright_magenta(&'a self) -> FgColorDisplay<'a, BrightMagenta, Self>
fn bright_magenta(&'a self) -> FgColorDisplay<'a, BrightMagenta, Self>
Change the foreground color to bright magenta
fn on_bright_magenta(&'a self) -> BgColorDisplay<'a, BrightMagenta, Self>
fn on_bright_magenta(&'a self) -> BgColorDisplay<'a, BrightMagenta, Self>
Change the background color to bright magenta
fn bright_purple(&'a self) -> FgColorDisplay<'a, BrightMagenta, Self>
fn bright_purple(&'a self) -> FgColorDisplay<'a, BrightMagenta, Self>
Change the foreground color to bright purple
fn on_bright_purple(&'a self) -> BgColorDisplay<'a, BrightMagenta, Self>
fn on_bright_purple(&'a self) -> BgColorDisplay<'a, BrightMagenta, Self>
Change the background color to bright purple
fn bright_cyan(&'a self) -> FgColorDisplay<'a, BrightCyan, Self>
fn bright_cyan(&'a self) -> FgColorDisplay<'a, BrightCyan, Self>
Change the foreground color to bright cyan
fn on_bright_cyan(&'a self) -> BgColorDisplay<'a, BrightCyan, Self>
fn on_bright_cyan(&'a self) -> BgColorDisplay<'a, BrightCyan, Self>
Change the background color to bright cyan
fn bright_white(&'a self) -> FgColorDisplay<'a, BrightWhite, Self>
fn bright_white(&'a self) -> FgColorDisplay<'a, BrightWhite, Self>
Change the foreground color to bright white
fn on_bright_white(&'a self) -> BgColorDisplay<'a, BrightWhite, Self>
fn on_bright_white(&'a self) -> BgColorDisplay<'a, BrightWhite, Self>
Change the background color to bright white
fn bold(&'a self) -> BoldDisplay<'a, Self>
fn bold(&'a self) -> BoldDisplay<'a, Self>
Make the text bold
fn dimmed(&'a self) -> DimDisplay<'a, Self>
fn dimmed(&'a self) -> DimDisplay<'a, Self>
Make the text dim
fn italic(&'a self) -> ItalicDisplay<'a, Self>
fn italic(&'a self) -> ItalicDisplay<'a, Self>
Make the text italicized
fn underline(&'a self) -> UnderlineDisplay<'a, Self>
fn underline(&'a self) -> UnderlineDisplay<'a, Self>
Make the text italicized
fn blink(&'a self) -> BlinkDisplay<'a, Self>
fn blink(&'a self) -> BlinkDisplay<'a, Self>
Make the text blink
fn blink_fast(&'a self) -> BlinkFastDisplay<'a, Self>
fn blink_fast(&'a self) -> BlinkFastDisplay<'a, Self>
Make the text blink (but fast!)
fn reversed(&'a self) -> ReversedDisplay<'a, Self>
fn reversed(&'a self) -> ReversedDisplay<'a, Self>
Swap the foreground and background colors
Hide the text
fn strikethrough(&'a self) -> StrikeThroughDisplay<'a, Self>
fn strikethrough(&'a self) -> StrikeThroughDisplay<'a, Self>
Cross out the text
fn color<Color>(&self, color: Color) -> FgDynColorDisplay<'_, Color, Self> where
Color: DynColor,
fn color<Color>(&self, color: Color) -> FgDynColorDisplay<'_, Color, Self> where
Color: DynColor,
Set the foreground color at runtime. Only use if you do not know which color will be used at
compile-time. If the color is constant, use either OwoColorize::fg
or
a color-specific method, such as OwoColorize::green
, Read more
fn on_color<Color>(&self, color: Color) -> BgDynColorDisplay<'_, Color, Self> where
Color: DynColor,
fn on_color<Color>(&self, color: Color) -> BgDynColorDisplay<'_, Color, Self> where
Color: DynColor,
Set the background color at runtime. Only use if you do not know what color to use at
compile-time. If the color is constant, use either OwoColorize::bg
or
a color-specific method, such as OwoColorize::on_yellow
, Read more
fn fg_rgb<const R: u8, const G: u8, const B: u8>(
&self
) -> FgColorDisplay<'_, CustomColor<R, G, B>, Self>
fn fg_rgb<const R: u8, const G: u8, const B: u8>(
&self
) -> FgColorDisplay<'_, CustomColor<R, G, B>, Self>
Set the foreground color to a specific RGB value.
fn bg_rgb<const R: u8, const G: u8, const B: u8>(
&self
) -> BgColorDisplay<'_, CustomColor<R, G, B>, Self>
fn bg_rgb<const R: u8, const G: u8, const B: u8>(
&self
) -> BgColorDisplay<'_, CustomColor<R, G, B>, Self>
Set the background color to a specific RGB value.
fn truecolor(&self, r: u8, g: u8, b: u8) -> FgDynColorDisplay<'_, Rgb, Self>
fn truecolor(&self, r: u8, g: u8, b: u8) -> FgDynColorDisplay<'_, Rgb, Self>
Sets the foreground color to an RGB value.
fn on_truecolor(&self, r: u8, g: u8, b: u8) -> BgDynColorDisplay<'_, Rgb, Self>
fn on_truecolor(&self, r: u8, g: u8, b: u8) -> BgDynColorDisplay<'_, Rgb, Self>
Sets the background color to an RGB value.
impl<T> Pointable for T
impl<T> Pointable for T
sourceimpl<T> WithSubscriber for T
impl<T> WithSubscriber for T
sourcefn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> where
S: Into<Dispatch>,
fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> where
S: Into<Dispatch>,
Attaches the provided Subscriber
to this type, returning a
WithDispatch
wrapper. Read more
sourcefn with_current_subscriber(self) -> WithDispatch<Self>
fn with_current_subscriber(self) -> WithDispatch<Self>
Attaches the current default Subscriber
to this type, returning a
WithDispatch
wrapper. Read more