Trait Reader

Source

pub trait Reader: Send + Sync {
    // Required method
    fn read(&mut self, from: &Path) -> Result<Option<Record>, Error>;

    // Provided method
    fn read_children(
        &mut self,
        from: &Path,
    ) -> Result<Option<Vec<String>>, Error> { ... }
}

Expand description

Read records from paths.

This is the semantic read interface. Paths are validated Unicode identifiers, and the returned Record can be either raw bytes or parsed values.

§Mutability

Both Reader::read and Writer::write take &mut self. This is intentional:

Stateful stores exist: Some stores maintain state that changes on read. For example:
- HTTP broker caches responses after first read
- Filesystem store tracks file position
Uniformity: A single trait signature works for all stores. Stores that don’t mutate on read simply ignore the mutability—the compiler optimizes this away.
No interior mutability tax: Stores don’t need Mutex or RefCell internally just to satisfy the trait. This avoids runtime overhead and potential deadlocks.

§Concurrent Access

For concurrent access to a store, wrap it explicitly:

use std::sync::{Arc, Mutex};

let store = Arc::new(Mutex::new(MyStore::new()));

// In thread 1:
let mut guard = store.lock().unwrap();
guard.read(&path)?;

// In thread 2:
let mut guard = store.lock().unwrap();
guard.read(&other_path)?;

This makes synchronization explicit at the usage site rather than hidden in the trait design.

§Object Safety

This trait is object-safe: you can use Box<dyn Reader>.

Required Methods§

Source

fn read(&mut self, from: &Path) -> Result<Option<Record>, Error>

Read a record from a path.

Returns Ok(Some(record)) if data exists at the path, Ok(None) if the path doesn’t exist, or Err if an error occurred.

Provided Methods§

Source

fn read_children(&mut self, from: &Path) -> Result<Option<Vec<String>>, Error>

Enumerate the child names directly under a path.

Returns Ok(None) if the path doesn’t exist, and Ok(Some(names)) otherwise — an empty vec for leaf values.

The default implementation reads the path and projects children from the parsed value: map keys, or indices for arrays. Stores that can enumerate more cheaply (or that serve Record::Raw) should override this.