Struct FileSystemWatcher 

pub struct FileSystemWatcher { /* private fields */ }

Filesystem watcher that emits debounced batches of dirty paths.

Uses notify-debouncer-mini for event coalescing. All paths within the debounce window are collected, de-duplicated, sorted, and emitted as a single WatcherBatch.

Implementations

impl FileSystemWatcher

pub fn new( path: PathBuf, config: WatcherConfig, shutdown: Arc<AtomicBool>, ) -> Result<Self>

Create a new watcher for the given directory.

Arguments

• path - Directory to watch recursively (also used as root_path for validation)
• config - Watcher configuration
• shutdown - AtomicBool for graceful shutdown

Returns

A watcher that can be polled for batch events

pub fn recv_batch(&self) -> Option<WatcherBatch>

Receive the next batch, blocking until available.

Returns

None if the watcher thread has terminated

pub fn try_recv_batch(&self) -> Option<WatcherBatch>

Try to receive a batch without blocking.

Returns

• Some(batch) if a batch is available
• None if no batch is available or watcher terminated

pub fn recv_batch_timeout( &self, timeout: Duration, ) -> Result<Option<WatcherBatch>, ()>

Receive the next batch with a timeout.

Returns

• Ok(Some(batch)) if a batch is available
• Ok(None) if the watcher thread has terminated
• Err if timeout elapsed

pub fn try_recv_event(&self) -> Result<Option<FileEvent>>

Legacy: Try to receive a single event without blocking (DEPRECATED).

This method converts batch events to single events for backward compatibility. Paths from each batch are returned one at a time in sorted order.

Deprecated

Use try_recv_batch() instead for deterministic batch processing.

Errors

Returns an error if a mutex is poisoned (thread panicked while holding the lock).

pub fn recv_event(&self) -> Result<Option<FileEvent>>

Legacy: Receive the next event, blocking until available (DEPRECATED).

This method converts batch events to single events for backward compatibility. Paths from each batch are returned one at a time in sorted order.

Deprecated

Use recv_batch() instead for deterministic batch processing.

Errors

Returns an error if a mutex is poisoned (thread panicked while holding the lock).

pub fn shutdown(self)

Explicitly shut down the watcher and join all background threads.

This method consumes the watcher, ensuring that:

1. The pub/sub receiver is shut down cleanly (if present)
2. The watcher thread is joined (waits for clean termination)

Note

This method should be called during graceful shutdown to ensure all threads have terminated before the program exits.

Trait Implementations

impl Drop for FileSystemWatcher

fn drop(&mut self)

Executes the destructor for this type.