Struct GraphHandle 

pub struct GraphHandle { /* private fields */ }

Wait-free read / serialized-write handle to the graph.

Readers load a frozen ReadSnapshot via read (lock-free via ArcSwap). Writers take a [Mutex] lock, mutate the underlying KnowledgeGraph, and publish a fresh snapshot on unlock via the WriteGuard drop glue.

A background thread calls fsync on the WAL file every 1 second so that write handlers never block on disk I/O. The thread is stopped on Drop.

The sync thread uses its own Arc<File> handle (cloned from the WAL file) so that fsync never contends with the graph mutex. A Condvar notifies the thread immediately after every write, ensuring low-latency sync without polling.

Implementations

impl GraphHandle

pub fn new(path: &Path, durability: Durability) -> Result<Self>

Open or create the graph at path, seeding the initial snapshot. Spawns a background thread that fsyncs the WAL so that write handlers never block on disk I/O.

pub fn read_graph_cached(&self) -> Arc<str>

Return the cached full-graph JSON, or build and cache it on first call. Invalidated by any write (see WriteGuard::publish).

pub fn read(&self) -> ReadSnapshot

Lock-free read snapshot. Holds an Arc reference to the frozen graph data.

pub fn write(&self) -> WriteGuard<'_>

Serialised write access. Returns a guard that publishes a fresh snapshot when dropped (or when WriteGuard::publish is called eagerly).

Trait Implementations

impl Drop for GraphHandle

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.