Struct SetOnce

pub struct SetOnce<T> { /* private fields */ }

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();

# #[tokio::main(flavor = "current_thread")]
# async fn main() -> Result<(), SetOnceError<u32>> {

// 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;

# #[tokio::main(flavor = "current_thread")]
# async fn main() -> Result<(), SetOnceError<u32>> {
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(())
# }

Implementations

impl<T> SetOnce<T>

fn new() -> Self

Creates a new empty SetOnce instance.

const fn const_new() -> Self

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())
}

# #[tokio::main(flavor = "current_thread")]
# async fn main() -> Result<(), SetOnceError<u32>> {
let result = get_global_integer()?;

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

fn new_with(value: Option<T>) -> Self

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

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

const fn const_new_with(value: T) -> Self

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()
}

# #[tokio::main(flavor = "current_thread")]
# async fn main() {
let result = get_global_integer();

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

fn initialized(&self) -> bool

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

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

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

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.

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.

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> Default for SetOnce<T>

fn default() -> SetOnce<T>

impl<T> Drop for SetOnce<T>

fn drop(&mut self)

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

fn from(value: T) -> Self

impl<T: Clone> Clone for SetOnce<T>

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

impl<T: Debug> Debug for SetOnce<T>

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

impl<T: Eq> Eq for SetOnce<T>

impl<T: PartialEq> PartialEq for SetOnce<T>

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

impl<T: Send> Send for SetOnce<T>

impl<T: Sync + Send> Sync for SetOnce<T>

Auto Trait Implementations

impl<T> !Freeze for SetOnce<T>

impl<T> !RefUnwindSafe for SetOnce<T>

impl<T> Unpin for SetOnce<T> where UnsafeCell<MaybeUninit<T>>: Unpin,

impl<T> UnsafeUnpin for SetOnce<T> where UnsafeCell<MaybeUninit<T>>: UnsafeUnpin,

impl<T> UnwindSafe for SetOnce<T> where UnsafeCell<MaybeUninit<T>>: UnwindSafe,

Blanket Implementations

impl<T> Any for SetOnce<T> where T: 'static + ?Sized,

fn type_id(&self) -> TypeId

impl<T> Borrow<T> for SetOnce<T> where T: ?Sized,

fn borrow(&self) -> &T

impl<T> BorrowMut<T> for SetOnce<T> where T: ?Sized,

fn borrow_mut(&mut self) -> &mut T

impl<T> CloneToUninit for SetOnce<T> where T: Clone,

unsafe fn clone_to_uninit(&self, dest: *mut u8)

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

fn from(t: T) -> T

Returns the argument unchanged.

impl<T> ToOwned for SetOnce<T> where T: Clone,

type Owned = T;
fn to_owned(&self) -> T
fn clone_into(&self, target: &mut T)

impl<T, U> Into<U> for SetOnce<T> where U: From<T>,

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of [From]<T> for U chooses to do.

impl<T, U> TryFrom<U> for SetOnce<T> where U: Into<T>,

type Error = never;
fn try_from(value: U) -> Result<T, never>

impl<T, U> TryInto<U> for SetOnce<T> where U: TryFrom<T>,

type Error = <U as TryFrom<T>>::Error;
fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>