Struct KOnceCell 

pub struct KOnceCell<T, Class> { /* private fields */ }

A cell that provides lazy/one-time initialization synchronized by a lock class Class.

KOnceCell holds data of type T that is uninitialized when created, and can be initialized at most once by presenting proof (LockToken) of holding a lock of class Class.

Because access is token-gated by Class, initialization is completely free of atomic overhead.

Implementations

impl<T, Class> KOnceCell<T, Class>

pub const fn new() -> Self

Creates a new uninitialized KOnceCell.

pub unsafe fn is_initialized(&self, _token: &LockToken<'_, Class>) -> bool

Returns true if the cell has been initialized.

Safety

The caller must guarantee that the provided LockToken belongs to the specific lock instance that guards this KOnceCell (rather than a different lock of the same lock class Class).

pub unsafe fn get<'b>(&self, _token: &'b LockToken<'_, Class>) -> Option<&'b T>

Accesses the initialized value immutably using a shared lock token. Returns None if not yet initialized.

Safety

The caller must guarantee that the provided LockToken belongs to the specific lock instance that guards this KOnceCell (rather than a different lock of the same lock class Class).

pub unsafe fn get_mut<'b>( &self, _token: &'b mut LockToken<'_, Class>, ) -> Option<&'b mut T>

Accesses the initialized value mutably using a mutable lock token. Returns None if not yet initialized.

Safety

The caller must guarantee that the provided LockToken belongs to the specific lock instance that guards this KOnceCell (rather than a different lock of the same lock class Class).

pub unsafe fn set( &self, value: T, _token: &mut LockToken<'_, Class>, ) -> Result<(), T>

Sets the value of the cell if uninitialized, returning Err(value) if already initialized.

Safety

The caller must guarantee that the provided LockToken belongs to the specific lock instance that guards this KOnceCell (rather than a different lock of the same lock class Class).

pub unsafe fn get_or_init<'b>( &self, f: impl FnOnce() -> T, _token: &'b mut LockToken<'_, Class>, ) -> &'b mut T

Initializes the cell with the given closure if uninitialized, returning a mutable reference to the contained value.

Safety

The caller must guarantee that the provided LockToken belongs to the specific lock instance that guards this KOnceCell (rather than a different lock of the same lock class Class).

pub unsafe fn get_or_try_init<'b, E>( &self, f: impl FnOnce() -> Result<T, E>, _token: &'b mut LockToken<'_, Class>, ) -> Result<&'b mut T, E>

Initializes the cell with the given fallible closure if uninitialized, returning a mutable reference to the contained value or the error.

Safety

The caller must guarantee that the provided LockToken belongs to the specific lock instance that guards this KOnceCell (rather than a different lock of the same lock class Class).

pub unsafe fn get_or_pin_init<'b, E>( &self, init: impl PinInit<T, E>, _token: &'b mut LockToken<'_, Class>, ) -> Result<&'b mut T, E>

Initializes the cell in-place with PinInit if uninitialized, returning a mutable reference to the contained value or the initialization error.

Safety

The caller must guarantee that the provided LockToken belongs to the specific lock instance that guards this KOnceCell (rather than a different lock of the same lock class Class).

pub unsafe fn get_unchecked(&self) -> Option<&T>

Accesses the initialized value immutably without checking for a LockToken. Returns None if not yet initialized.

Safety

The caller must guarantee that the specific lock instance guarding this KOnceCell is held.

pub unsafe fn get_mut_unchecked(&self) -> Option<&mut T>

Accesses the initialized value mutably without checking for a LockToken. Returns None if not yet initialized.

Safety

The caller must guarantee that the specific lock instance guarding this KOnceCell is held exclusively without concurrent access.

pub unsafe fn get_or_init_unchecked(&self, f: impl FnOnce() -> T) -> &mut T

Initializes the cell with the given closure without requiring a LockToken.

Safety

The caller must guarantee that the specific lock instance guarding this KOnceCell is held exclusively without concurrent access.

pub unsafe fn get_or_try_init_unchecked<E>( &self, f: impl FnOnce() -> Result<T, E>, ) -> Result<&mut T, E>

Initializes the cell with the given fallible closure without requiring a LockToken.

Safety

The caller must guarantee that the specific lock instance guarding this KOnceCell is held exclusively without concurrent access.

pub unsafe fn get_or_pin_init_unchecked<E>( &self, init: impl PinInit<T, E>, ) -> Result<&mut T, E>

Initializes the cell in-place with PinInit without requiring a LockToken.

Safety

The caller must guarantee that the specific lock instance guarding this KOnceCell is held exclusively without concurrent access.

pub fn get_inner_mut(&mut self) -> Option<&mut T>

Accesses the inner value mutably by bypassing locking requirements using unique borrow ownership.

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

Unwraps the cell, returning the inner value if initialized.

pub unsafe fn guard<'a>( &'a self, token: &'a mut LockToken<'_, Class>, ) -> KOnceCellGuard<'a, T, Class>

Returns a safe guard proxy for this cell using an exclusive lock token.

Safety

The caller must guarantee that the provided LockToken belongs to the specific lock instance that guards this KOnceCell (rather than a different lock of the same lock class Class).

Trait Implementations

impl<T, Class> Debug for KOnceCell<T, Class>

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

Formats the value using the given formatter.

impl<T, Class> Default for KOnceCell<T, Class>

fn default() -> Self

Returns the “default value” for a type.

impl<T, Class> Drop for KOnceCell<T, Class>

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.

impl<T: Send, Class> Send for KOnceCell<T, Class>

impl<T: Send, Class> Sync for KOnceCell<T, Class>