Struct Rcu

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

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

The pointer should be a non-null pointer with type P, which implements NonNullPtr. For example, P can be Box<T> or Arc<T>.

Overview

Read-Copy-Update (RCU) is a synchronization mechanism designed for high- performance, low-latency read operations in concurrent systems. It allows multiple readers to access shared data simultaneously without contention, while writers can update the data safely in a way that does not disrupt ongoing reads. RCU is particularly suited for situations where reads are far more frequent than writes.

The original design and implementation of RCU is described in paper The Read-Copy-Update Mechanism for Supporting Real-Time Applications on Shared- Memory Multiprocessor Systems with Linux published on IBM Systems Journal 47.2 (2008).

Examples

use ostd::sync::Rcu;

let rcu = Rcu::new(Box::new(42));

let rcu_guard = rcu.read();

assert_eq!(*rcu_guard, Some(&42));

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

let rcu_guard = rcu.read();

assert_eq!(*rcu_guard, Some(&43));

Implementations

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

pub fn new(pointer: P) -> Self

Creates a new RCU primitive with the given pointer.

pub fn update(&self, new_ptr: P)

Replaces the current pointer with a null pointer.

This function updates the pointer to the new pointer regardless of the original pointer. The original pointer will be dropped after the grace period.

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

pub fn read(&self) -> RcuReadGuard<'_, 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.

pub fn read_with<'a, G: AsAtomicModeGuard + ?Sized>( &'a self, guard: &'a G, ) -> 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 RcuReadGuard::compare_exchange to synchronize the writers. You may do it via a super::SpinLock.