How to install the kovan crate // Lib.rs

Adding `kovan` library as a dependency

Run this command in a terminal, in your project's directory:

cargo add kovan

To add it manually, edit your project's Cargo.toml file and add to the [dependencies] section:

kovan = "0.1.6"

The kovan library will be automatically available globally. Read the kovan library documentation.

Back to the crate overview.

Readme

High-performance wait-free memory reclamation for lock-free data structures. Bounded memory usage, predictable latency.

What is Kovan?

Kovan solves the hardest problem in lock-free programming: when is it safe to free memory?

When multiple threads access shared data without locks, you can't just drop() or free() - another thread might still be using it. Kovan tracks this automatically with zero overhead on reads.

Why Kovan?

Zero read overhead: Just one atomic load, nothing else
Bounded memory: Never grows unbounded like epoch-based schemes
Simple API: Three functions: pin(), load(), retire()

Quick Start

[dependencies]
kovan = "0.1"

Basic Usage

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

// Create shared atomic pointer
let shared = Atomic::new(Box::into_raw(Box::new(42)));

// Read safely
let guard = pin();  // Enter critical section
let ptr = shared.load(Ordering::Acquire, &guard);
unsafe {
    if let Some(value) = ptr.as_ref() {
        println!("Value: {}", value);
    }
}
drop(guard);  // Exit critical section

// Update safely
let guard = pin();
let new_value = Box::into_raw(Box::new(100));
let old = shared.swap(
    unsafe { kovan::Shared::from_raw(new_value) },
    Ordering::Release,
    &guard
);

// Schedule old value for reclamation
if !old.is_null() {
    unsafe { retire(old.as_raw()); }
}

How It Works

pin() - Enter critical section, get a guard
load() - Read pointer (zero overhead!)
retire() - Schedule memory for safe reclamation

The guard ensures any pointers you load stay valid. When all guards are dropped, retired memory is freed automatically.

Examples

See the examples/ directory for complete implementations.

Performance

10x faster than naive implementations
Competitive with Crossbeam-Epoch on reads
Better memory bounds than epoch-based schemes

Optional Features

# Nightly optimizations (~5% faster)
kovan = { version = "0.1", features = ["nightly"] }

# Handle stalled threads
kovan = { version = "0.1", features = ["robust"] }

License

Licensed under Apache License 2.0.

Adding kovan library as a dependency

Adding `kovan` library as a dependency