Trait Watcher

Source

pub trait Watcher {
    // Required methods
    fn new<F: EventHandler>(event_handler: F, config: Config) -> Result<Self>
       where Self: Sized;
    fn watch(
        &mut self,
        path: &Path,
        recursive_mode: RecursiveMode,
    ) -> Result<()>;
    fn unwatch(&mut self, path: &Path) -> Result<()>;
    fn kind() -> WatcherKind
       where Self: Sized;

    // Provided methods
    fn watch_with(&mut self, path: &Path, config: WatchPathConfig) -> Result<()> { ... }
    fn update_paths(&mut self, ops: Vec<PathOp>) -> Result<(), UpdatePathsError> { ... }
    fn configure(&mut self, _option: Config) -> Result<bool> { ... }
    fn watched_paths(&self) -> Result<Vec<(PathBuf, RecursiveMode)>> { ... }
}

Expand description

Type that can deliver file activity notifications

Watcher is implemented per platform using the best implementation available on that platform. In addition to such event driven implementations, a polling implementation is also provided that should work on any platform.

§Creating a watcher

Because Watcher is a trait, Rust usually can’t infer the concrete watcher type when calling Watcher::new(...) directly. Prefer recommended_watcher / RecommendedWatcher (or a specific backend like PollWatcher) when constructing a watcher.

use notify::{Event, RecursiveMode, Result, Watcher};
use std::{path::Path, sync::mpsc};

fn main() -> Result<()> {
    let (tx, _rx) = mpsc::channel::<Result<Event>>();
    let mut watcher = notify::recommended_watcher(tx)?;
    watcher.watch(Path::new("."), RecursiveMode::Recursive)?;
    Ok(())
}

Required Methods§

Source

fn new<F: EventHandler>(event_handler: F, config: Config) -> Result<Self>
where Self: Sized,

Create a new watcher with an initial Config.

Source

fn watch(&mut self, path: &Path, recursive_mode: RecursiveMode) -> Result<()>

Begin watching a new path.

If the path is a directory, recursive_mode will be evaluated. If recursive_mode is RecursiveMode::Recursive events will be delivered for all files in that tree. Otherwise only the directory and its immediate children will be watched.

If the path is a file, recursive_mode will be ignored and events will be delivered only for the file.

Event paths are reported using the same root representation as path. If path is relative, emitted event paths are relative to the process current directory at the time this method is called. If path is absolute, emitted event paths are absolute. Convert path before calling this method if your application needs a specific representation.

On success, calling this method again for the same backend-resolved path replaces the existing watch for that path. The recursive mode is updated to the new value, a second independent watch is not added, and a single call to Watcher::unwatch removes the watched path.

To add many paths at once, use Watcher::update_paths. On macOS, this avoids rebuilding the FSEvents stream for each path.

On some platforms, if the path is renamed or removed while being watched, behaviour may be unexpected. See discussions in #165 and #166. If less surprising behaviour is wanted one may non-recursively watch the parent directory as well and manage related events.

Source

fn unwatch(&mut self, path: &Path) -> Result<()>

Stop watching a path.

§Errors

Returns an error in the case that path has not been watched or if removing the watch fails.

Source

fn kind() -> WatcherKind
where Self: Sized,

Returns the watcher kind, allowing to perform backend-specific tasks

Provided Methods§

Source

fn watch_with(&mut self, path: &Path, config: WatchPathConfig) -> Result<()>

Begin watching a path with per-path settings.

Behaves like Watcher::watch, with the options in config applied to this watch alone. Backends that do not implement a given option ignore it, so the default implementation applies only WatchPathConfig::recursive_mode.

§Errors

Returns an error in the case that path does not exist or if adding the watch fails.

Source

fn update_paths(&mut self, ops: Vec<PathOp>) -> Result<(), UpdatePathsError>

Add/remove paths to watch in batch.

For some Watcher implementations this method provides better performance than multiple calls to Watcher::watch and Watcher::unwatch if you want to add/remove many paths at once. In particular, the FSEvents backend on macOS rebuilds its stream only once for the whole batch.

§Errors

Returns UpdatePathsError if any operation fails. Operations are applied sequentially. When an error occurs, processing stops: operations before origin have been applied, origin is the operation that failed (if known), and remaining are the operations that were not attempted. remaining does not include origin.

§Examples

let mut watcher = notify::NullWatcher;
let mut batch = Vec::new();

for path in many_paths_to_add {
    batch.push(PathOp::watch_recursive(path));
}

for path in many_paths_to_remove {
    batch.push(PathOp::unwatch(path));
}

// real work is done there
watcher.update_paths(batch)?;

Source