Struct Atomic

Source

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

Expand description

A pointer to a heap-allocated value with atomic operations.

This type provides atomic load, store, and compare-exchange operations on pointers to T. Memory reclamation is handled automatically through the guard-based protocol.

§Examples

use kovan::{Atomic, pin};
use std::sync::atomic::Ordering;

let atomic = Atomic::new(Box::into_raw(Box::new(42)));
let guard = pin();
let ptr = atomic.load(Ordering::Acquire, &guard);

Implementations§

Source §

impl<T> Atomic<T>

Source

pub fn new(ptr: *mut T) -> Self

Creates a new atomic pointer.

§Examples

use kovan::Atomic;

let atomic: Atomic<i32> = Atomic::new(std::ptr::null_mut());

Source

pub fn null() -> Self

Creates a null atomic pointer.

Source

pub fn load<'g>(&self, order: Ordering, _guard: &'g Guard) -> Shared<'g, T>

Loads a pointer from the atomic.

Performs era tracking: reads the pointer, then checks the global epoch. If the epoch has advanced since the last check, the thread’s slot era is updated so try_retire() counts this thread as protecting the loaded pointer’s batch.

Fast path cost: 3 words (1 atomic load, 2 word compares)

§Examples

use kovan::{Atomic, pin};
use std::sync::atomic::Ordering;

let atomic = Atomic::new(Box::into_raw(Box::new(42)));
let guard = pin();
let ptr = atomic.load(Ordering::Acquire, &guard);

Source

pub fn store(&self, ptr: Shared<'_, T>, order: Ordering)

Stores a pointer into the atomic.

Unlike load, this does not require a Guard because no pointer is returned that needs lifetime protection. The caller is responsible for ensuring the stored pointer is valid and that any previously-stored pointer is properly retired.

§Examples

use kovan::{Atomic, Shared};
use std::sync::atomic::Ordering;

let atomic = Atomic::new(std::ptr::null_mut());
let ptr = Box::into_raw(Box::new(42));
unsafe {
    atomic.store(Shared::from_raw(ptr), Ordering::Release);
}

Source

pub fn compare_exchange<'g>( &self, current: Shared<'_, T>, new: Shared<'_, T>, success: Ordering, failure: Ordering, _guard: &'g Guard, ) -> Result<Shared<'g, T>, Shared<'g, T>>

Compares and exchanges the pointer.

§Examples

use kovan::{Atomic, Shared, pin};
use std::sync::atomic::Ordering;

let atomic = Atomic::new(Box::into_raw(Box::new(42)));
let guard = pin();
let current = atomic.load(Ordering::Acquire, &guard);
let new = Box::into_raw(Box::new(43));
unsafe {
    atomic.compare_exchange(
        current,
        Shared::from_raw(new),
        Ordering::AcqRel,
        Ordering::Acquire,
        &guard
    );
}