Crate notify[][src]

Cross-platform file system notification library

Source is on GitHub: https://github.com/notify-rs/notify

Installation

[dependencies]
notify = "4.0.16"

Examples

Notify provides two APIs. The default API debounces events (if the backend reports two similar events in close succession, Notify will only report one). The raw API emits file changes as soon as they happen. For more details, see Watcher::new_raw and Watcher::new.

Default (debounced) API

extern crate notify;

use notify::{Watcher, RecursiveMode, watcher};
use std::sync::mpsc::channel;
use std::time::Duration;

fn main() {
    // Create a channel to receive the events.
    let (tx, rx) = channel();

    // Create a watcher object, delivering debounced events.
    // The notification back-end is selected based on the platform.
    let mut watcher = watcher(tx, Duration::from_secs(10)).unwrap();

    // Add a path to be watched. All files and directories at that path and
    // below will be monitored for changes.
    watcher.watch("/home/test/notify", RecursiveMode::Recursive).unwrap();

    loop {
        match rx.recv() {
           Ok(event) => println!("{:?}", event),
           Err(e) => println!("watch error: {:?}", e),
        }
    }
}

Using the default API is easy, all possible events are described in the DebouncedEvent documentation. But in order to understand the subtleties of the event delivery, you should read the op documentation as well.

Raw API

extern crate notify;

use notify::{Watcher, RecursiveMode, RawEvent, raw_watcher};
use std::sync::mpsc::channel;

fn main() {
    // Create a channel to receive the events.
    let (tx, rx) = channel();

    // Create a watcher object, delivering raw events.
    // The notification back-end is selected based on the platform.
    let mut watcher = raw_watcher(tx).unwrap();

    // Add a path to be watched. All files and directories at that path and
    // below will be monitored for changes.
    watcher.watch("/home/test/notify", RecursiveMode::Recursive).unwrap();

    loop {
        match rx.recv() {
           Ok(RawEvent{path: Some(path), op: Ok(op), cookie}) => {
               println!("{:?} {:?} ({:?})", op, path, cookie)
           },
           Ok(event) => println!("broken event: {:?}", event),
           Err(e) => println!("watch error: {:?}", e),
        }
    }
}

The event structure is described in the RawEvent documentation, all possible operations delivered in an event are described in the op documentation.

Re-exports

pub use self::op::Op;
pub use self::inotify::INotifyWatcher;
pub use self::null::NullWatcher;
pub use self::poll::PollWatcher;

Modules

inotify

Watcher implementation for the inotify Linux API

null

Stub Watcher implementation

op

Contains the Op type which describes the actions for an event.

poll

Generic Watcher implementation based on polling

Structs

RawEvent

Event delivered when action occurs on a watched path in raw mode

Enums

DebouncedEvent

Event delivered when action occurs on a watched path in debounced mode

Error

Errors generated from the notify crate

RecursiveMode

Indicates whether only the provided directory or its sub-directories as well should be watched

Traits

Watcher

Type that can deliver file activity notifications

Functions

raw_watcher

Convenience method for creating the RecommendedWatcher for the current platform in raw mode.

watcher

Convenience method for creating the RecommendedWatcher for the current platform in default (debounced) mode.

Type Definitions

RecommendedWatcher

The recommended Watcher implementation for the current platform

Result

Type alias to use this library’s Error type in a Result