Struct RcuOption

pub struct RcuOption<P: NonNullPtr>(/* private fields */);

A Read-Copy Update (RCU) cell for sharing a nullable pointer.

This is a variant of Rcu that allows the contained pointer to be null. So that it can implement Rcu<Option<P>> where P is not a nullable pointer. It is the same as Rcu in other aspects.

Examples

use ostd::sync::RcuOption;

static RCU: RcuOption<Box<usize>> = RcuOption::new_none();

assert!(RCU.read().is_none());

RCU.update(Box::new(42));

// Read the data protected by RCU
{
    let rcu_guard = RCU.read().try_get().unwrap();
    assert_eq!(*rcu_guard, 42);
}

// Update the data protected by RCU
{
    let rcu_guard = RCU.read().try_get().unwrap();

    rcu_guard.compare_exchange(Box::new(43)).unwrap();

    let rcu_guard = RCU.read().try_get().unwrap();
    assert_eq!(*rcu_guard, 43);
}

Implementations

impl<P: NonNullPtr + Send> RcuOption<P>

pub fn new(pointer: Option<P>) -> Self

Creates a new RCU primitive with the given pointer.

pub const fn new_none() -> Self

Creates a new RCU primitive that contains nothing.

This is a constant equivalence to [RcuOption::new(None)].

pub fn update(&self, new_ptr: Option<P>)

Replaces the current pointer with a null pointer.

This function updates the pointer to the new pointer regardless of the original pointer. If the original pointer is not NULL, it will be dropped after the grace period.

Oftentimes this function is not recommended unless you have synchronized writes with locks. Otherwise, you can use Self::read and then RcuOptionReadGuard::compare_exchange to update the pointer.

pub fn read(&self) -> RcuOptionReadGuard<'_, P>

Retrieves a read guard for the RCU primitive.

The guard allows read access to the data protected by RCU, as well as the ability to do compare-and-exchange.

The contained pointer can be NULL and you can only get a reference (if checked non-NULL) via RcuOptionReadGuard::get.

pub fn read_with<'a, G: AsAtomicModeGuard + ?Sized>( &'a self, guard: &'a G, ) -> Option<P::Ref<'a>>

Reads the RCU-protected value in an atomic mode.

The RCU mechanism protects reads (Self::read) by entering an atomic mode. If we are already in an atomic mode, this function can reduce the overhead of disabling preemption again.

Unlike Self::read, this function does not return a read guard, so you cannot use RcuOptionReadGuard::compare_exchange to synchronize the writers. You may do it via a super::SpinLock.