Struct SetOnce 

pub struct SetOnce<T> {
    value_set: AtomicBool,
    value: UnsafeCell<MaybeUninit<T>>,
    notify: Notify,
}

A thread-safe cell that can be written to only once.

A SetOnce is inspired from python’s asyncio.Event type. It can be used to wait until the value of the SetOnce is set like a “Event” mechanism.

Example

use tokio::sync::{SetOnce, SetOnceError};

static ONCE: SetOnce<u32> = SetOnce::const_new();


// set the value inside a task somewhere...
tokio::spawn(async move { ONCE.set(20) });

// checking with .get doesn't block main thread
println!("{:?}", ONCE.get());

// wait until the value is set, blocks the thread
println!("{:?}", ONCE.wait().await);

Ok(())

A SetOnce is typically used for global variables that need to be initialized once on first use, but need no further changes. The SetOnce in Tokio allows the initialization procedure to be asynchronous.

Example

use tokio::sync::{SetOnce, SetOnceError};
use std::sync::Arc;

let once = SetOnce::new();

let arc = Arc::new(once);
let first_cl = Arc::clone(&arc);
let second_cl = Arc::clone(&arc);

// set the value inside a task
tokio::spawn(async move { first_cl.set(20) }).await.unwrap()?;

// wait inside task to not block the main thread
tokio::spawn(async move {
    // wait inside async context for the value to be set
    assert_eq!(*second_cl.wait().await, 20);
}).await.unwrap();

// subsequent set calls will fail
assert!(arc.set(30).is_err());

println!("{:?}", arc.get());

Ok(())

Fields

value_set: AtomicBool

value: UnsafeCell<MaybeUninit<T>>

notify: Notify

Implementations

impl<T> SetOnce<T>

pub fn new() -> SetOnce<T>

Creates a new empty SetOnce instance.

pub const fn const_new() -> SetOnce<T>

Creates a new empty SetOnce instance.

Equivalent to SetOnce::new, except that it can be used in static variables.

When using the tracing unstable feature, a SetOnce created with const_new will not be instrumented. As such, it will not be visible in tokio-console. Instead, SetOnce::new should be used to create an instrumented object if that is needed.

Example

use tokio::sync::{SetOnce, SetOnceError};

static ONCE: SetOnce<u32> = SetOnce::const_new();

fn get_global_integer() -> Result<Option<&'static u32>, SetOnceError<u32>> {
    ONCE.set(2)?;
    Ok(ONCE.get())
}

let result = get_global_integer()?;

assert_eq!(result, Some(&2));
Ok(())

pub fn new_with(value: Option<T>) -> SetOnce<T>

Creates a new SetOnce that contains the provided value, if any.

If the Option is None, this is equivalent to SetOnce::new.

pub const fn const_new_with(value: T) -> SetOnce<T>

Creates a new SetOnce that contains the provided value.

Example

When using the tracing unstable feature, a SetOnce created with const_new_with will not be instrumented. As such, it will not be visible in tokio-console. Instead, SetOnce::new_with should be used to create an instrumented object if that is needed.

use tokio::sync::SetOnce;

static ONCE: SetOnce<u32> = SetOnce::const_new_with(1);

fn get_global_integer() -> Option<&'static u32> {
    ONCE.get()
}

let result = get_global_integer();

assert_eq!(result, Some(&1));

pub fn initialized(&self) -> bool

Returns true if the SetOnce currently contains a value, and false otherwise.

pub fn get(&self) -> Option<&T>

Returns a reference to the value currently stored in the SetOnce, or None if the SetOnce is empty.

pub fn set(&self, value: T) -> Result<(), SetOnceError<T>>

Sets the value of the SetOnce to the given value if the SetOnce is empty.

If the SetOnce already has a value, this call will fail with an SetOnceError.

pub fn into_inner(self) -> Option<T>

Takes the value from the cell, destroying the cell in the process. Returns None if the cell is empty.

pub async fn wait(&self) -> &T

Waits until the value is set.

If the SetOnce is already initialized, it will return the value immediately.

Cancel safety

This method is cancel safe.

Trait Implementations

impl<T> Clone for SetOnce<T>

where T: Clone,

fn clone(&self) -> SetOnce<T>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T> Debug for SetOnce<T>

where T: Debug,

fn fmt(&self, fmt: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<T> Default for SetOnce<T>

fn default() -> SetOnce<T>

Returns the “default value” for a type.

impl<T> Drop for SetOnce<T>

fn drop(&mut self)

Executes the destructor for this type.

impl<T> From<T> for SetOnce<T>

fn from(value: T) -> SetOnce<T>

Converts to this type from the input type.

impl<T> PartialEq for SetOnce<T>

where T: PartialEq,

fn eq(&self, other: &SetOnce<T>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T> Eq for SetOnce<T>

where T: Eq,

impl<T> Send for SetOnce<T>

where T: Send,

impl<T> Sync for SetOnce<T>

where T: Sync + Send,