Struct RcuCell 

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

A concurrent data structure that allows for safe, read-copy-update (RCU) style access to its value.

Grace period serialization

Only one old value can be pending reclamation at a time (single ptr_counter_to_clear slot). If multiple writers call write concurrently while readers hold guards to old values, their grace periods are serialized. This is acceptable for read-heavy workloads but can cause writer stalls under heavy write contention with long-lived readers.

Implementations

impl<T> RcuCell<T>

pub fn new(value: T) -> Self

Creates a new RcuCell with the given initial value.

Example

let rcu_cell = rcu_128::RcuCell::new(42);

Examples found in repository

examples/example.rs (line 6)

fn main() {
    let x = rcu_128::RcuCell::new(0);
    std::thread::scope(|s| {
        s.spawn(|| {
            for i in 0..40 {
                let t = Instant::now();
                if i < 20 {
                    x.write(i);
                } else {
                    x.update(|v| v + 1);
                }
                println!("Update {i} used time: {:?}", t.elapsed());
                sleep((t + Duration::from_millis(100)).duration_since(Instant::now()));
            }
        });
        s.spawn(|| {
            // Always has 4 guards alive
            let mut guards = [x.read(), x.read(), x.read(), x.read()];
            for idx in 0..400 {
                let r = x.read();
                println!("Read value: {}", *r);
                guards[idx % 4] = r;
                sleep(Duration::from_millis(10));
            }
        });
    })
}

pub fn read(&self) -> RcuGuard<'_, T>

Provides read access to the value stored in the RcuCell.

This function returns an RcuGuard, which allows for safe, concurrent read access to the RcuCell’s value.

Once all RcuGuard instances referencing a particular value are dropped, the value can be safely released during an update or write.

Example

let rcu_cell = rcu_128::RcuCell::new(42);
{
    let guard = rcu_cell.read();
    assert_eq!(*guard, 42);
}

Examples found in repository

examples/example.rs (line 22)

fn main() {
    let x = rcu_128::RcuCell::new(0);
    std::thread::scope(|s| {
        s.spawn(|| {
            for i in 0..40 {
                let t = Instant::now();
                if i < 20 {
                    x.write(i);
                } else {
                    x.update(|v| v + 1);
                }
                println!("Update {i} used time: {:?}", t.elapsed());
                sleep((t + Duration::from_millis(100)).duration_since(Instant::now()));
            }
        });
        s.spawn(|| {
            // Always has 4 guards alive
            let mut guards = [x.read(), x.read(), x.read(), x.read()];
            for idx in 0..400 {
                let r = x.read();
                println!("Read value: {}", *r);
                guards[idx % 4] = r;
                sleep(Duration::from_millis(10));
            }
        });
    })
}

pub fn write(&self, value: T)

Writes a new value into the RcuCell.

The new value becomes immediately visible to subsequent readers. This method blocks until all readers of the old value have dropped their guards, then frees the old value.

Multiple concurrent write calls are allowed (last-writer-wins). Use update if you need read-modify-write semantics.

Example

let rcu_cell = rcu_128::RcuCell::new(42);
rcu_cell.write(100);
{
    let guard = rcu_cell.read();
    assert_eq!(*guard, 100);
}

Examples found in repository

examples/example.rs (line 12)

fn main() {
    let x = rcu_128::RcuCell::new(0);
    std::thread::scope(|s| {
        s.spawn(|| {
            for i in 0..40 {
                let t = Instant::now();
                if i < 20 {
                    x.write(i);
                } else {
                    x.update(|v| v + 1);
                }
                println!("Update {i} used time: {:?}", t.elapsed());
                sleep((t + Duration::from_millis(100)).duration_since(Instant::now()));
            }
        });
        s.spawn(|| {
            // Always has 4 guards alive
            let mut guards = [x.read(), x.read(), x.read(), x.read()];
            for idx in 0..400 {
                let r = x.read();
                println!("Read value: {}", *r);
                guards[idx % 4] = r;
                sleep(Duration::from_millis(10));
            }
        });
    })
}

pub fn update(&self, f: impl FnOnce(&T) -> T)

Updates the value stored in the RcuCell using a provided function.

This function applies the given closure f to the current value, replacing it with the returned value. The closure runs under an exclusive lock, so concurrent update and write calls are serialized — the closure is guaranteed to run exactly once.

Example

let rcu_cell = rcu_128::RcuCell::new(42);
rcu_cell.update(|&old_value| old_value + 1);
{
    let guard = rcu_cell.read();
    assert_eq!(*guard, 43);
}

Examples found in repository

examples/example.rs (line 14)

fn main() {
    let x = rcu_128::RcuCell::new(0);
    std::thread::scope(|s| {
        s.spawn(|| {
            for i in 0..40 {
                let t = Instant::now();
                if i < 20 {
                    x.write(i);
                } else {
                    x.update(|v| v + 1);
                }
                println!("Update {i} used time: {:?}", t.elapsed());
                sleep((t + Duration::from_millis(100)).duration_since(Instant::now()));
            }
        });
        s.spawn(|| {
            // Always has 4 guards alive
            let mut guards = [x.read(), x.read(), x.read(), x.read()];
            for idx in 0..400 {
                let r = x.read();
                println!("Read value: {}", *r);
                guards[idx % 4] = r;
                sleep(Duration::from_millis(10));
            }
        });
    })
}

Trait Implementations

impl<T: Debug> Debug for RcuCell<T>

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

Formats the value using the given formatter.

impl<T: Default> Default for RcuCell<T>

fn default() -> Self

Returns the “default value” for a type.

impl<T> Drop for RcuCell<T>

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.