Struct Musefs 

pub struct Musefs { /* private fields */ }

The composed read-only filesystem: the store, the rendered tree, and the lazy synthesis cache. All methods take &self; the tree is swapped atomically on refresh, the cache is internally sharded (each shard mutex-guarded), and the data-version stamp is atomic. This makes Musefs Sync, so the FUSE layer can later share it across a worker pool.

Implementations

impl Musefs

pub fn refresh_for_test(&self) -> Result<()>

Force an unconditional rebuild of the tree from the current DB contents. Test-only: production code refreshes via poll_refresh.

Serialized against poll_refresh (and itself) through the same refreshing single-flight gate the production path uses, so overlapping rebuilds can’t publish a stale tree or race the content_version snapshot the change-diff relies on. Unlike poll_refresh, it blocks until it owns the gate rather than bailing out, so the forced rebuild always happens.

pub fn poll_due(&self) -> bool

Cheap, synchronous “is a data_version poll worth dispatching?” predicate for the FUSE dispatch thread to gate fire_poll_refresh on, so a metadata-op storm doesn’t flood the worker pool with no-op poll tasks (#89). Shares the poll_debounced gate with poll_refresh_notify. Advisory only: no DB access, no data_version read, no rebuild. A stale true costs at most one task the inner gate short-circuits, and needs_rebuild is checked first so a self-heal is never debounced away.

pub fn poll_refresh(&self) -> Result<bool>

See poll_refresh_notify; this is the no-callback form.

pub fn poll_refresh_notify(&self, on_changed: impl FnMut(u64)) -> Result<bool>

Cheap check for external DB commits via PRAGMA data_version. On a change, rebuild the tree, prune cached resolutions to the live track set, invoke on_changed(inode) for every inode whose track’s content_version changed (its served bytes changed but its path/inode is stable), then return true. The version stamp is committed only after a successful rebuild.

Single-flighted: if a rebuild is already in progress, concurrent callers return Ok(false) immediately.

impl Musefs

pub fn open(db: Db, config: MountConfig) -> Result<Musefs>

pub fn lookup(&self, parent: u64, name: &str) -> Option<u64>

pub fn parent(&self, inode: u64) -> Option<u64>

The parent inode of inode (root’s parent is itself). Forwards to the tree.

pub fn getattr(&self, inode: u64) -> Result<Attr>

pub fn readdir(&self, inode: u64) -> Result<Vec<(String, u64, bool)>>

Directory entries as (name, child_inode, is_dir).

pub fn read_into( &self, inode: u64, fh: Option<Fh>, offset: u64, size: u64, out: &mut Vec<u8>, ) -> Result<()>

pub fn read( &self, inode: u64, fh: Option<Fh>, offset: u64, size: u64, ) -> Result<Vec<u8>>

Allocating form of read_into.

pub fn open_handle(&self, inode: u64) -> Result<Fh>

Open a file handle: resolve + validate the layout and open the backing fd once, store it, and return a handle. Subsequent reads with this handle reuse the fd (no per-read open/stat).

pub fn release_handle(&self, fh: Fh)

Drop an open handle (closes its backing fd when the last reference goes).

pub fn passthrough_fd(&self, fh: Fh) -> Option<PassthroughFd>

The backing fd behind fh, for kernel passthrough registration. Some only in StructureOnly mode, where the served bytes ARE the backing file; in Synthesis mode the bytes are spliced, so no single fd represents them. None also for a stale or released handle.

pub fn mode(&self) -> Mode

The mount’s serving mode (how file contents are produced).

pub fn entry_counts(&self) -> (u64, u64)

(files, directories) in the current virtual tree — the operator’s “is it serving the right library?” answer, surfaced on a successful mount so an empty or wrong DB is not silent (#522).

pub fn telemetry(&self) -> CoreTelemetry

Snapshot the core-owned telemetry for the .musefs-metrics surface (#394). Cheap: atomic loads plus three length reads (the inodes mutex is taken briefly; a poisoned lock flags needs_rebuild via lock_or_flag, the same self-heal contract as every other VFS-state lock site).