Notify

^{(Windows) (Linux and OS X)}

Cross-platform filesystem notification library for Rust.

Install

[dependencies]
notify = "2.6.2"

Usage

extern crate notify;
use std::sync::mpsc::Receiver;
use std::sync::mpsc::sync_channel;
use std::thread;
use notify::{RecommendedWatcher, Watcher};
use std::sync::mpsc::channel;

fn watch() -> notify::Result<()> {
  // Create a channel to receive the events.
  let (tx, rx) = channel();

  // Automatically select the best implementation for your platform.
  // You can also access each implementation directly e.g. INotifyWatcher.
  let mut watcher: RecommendedWatcher = try!(Watcher::new(tx));

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

  // This is a simple loop, but you may want to use more complex logic here,
  // for example to handle I/O.
  loop {
      match rx.recv() {
        Ok(notify::Event{ path: Some(path),op:Ok(op) }) => {
            println!("{:?} {:?}", op, path);
        },
        Err(e) => println!("watch error {}", e),
        _ => ()
      }
  }
}

fn main() {
  if let Err(err) = watch() {
    println!("Error! {:?}", err)
  }
}

Migration

From v2.x to v3.x

• The watch(..) function used to watch a file or a directory now takes an additional argument. In order to use that argument you first need to import notify::RecursiveMode via the use keyword. To keep the old behavior, use RecursiveMode::Recursive, for more information see the docs.
• The inotify back-end used to add watches recursively to a directory but it wouldn't remove them recursively. From v3.0.0 on inotify removes watches recursively if they were added recursively.
• The inotify back-end didn't use to watch newly created directories. From v3.0.0 on inotify watches newly created directories if their parent directories were added recursively.

Platforms

• Linux / Android: inotify
• OS X: FSEvents
• Windows: ReadDirectoryChangesW
• All platforms: polling

Limitations

FSEvents

Due to the inner security model of FSEvents (see FileSystemEventSecurity), some event cannot be observed easily when trying to follow files that do not belong to you. In this case, reverting to the pollwatcher can fix the issue, with a slight performance cost.

Todo

• BSD / OS X / iOS: kqueue
• Solaris 11: FEN

Pull requests and bug reports happily accepted!

Origins

Inspired by Go's fsnotify, born out of need for cargo watch, and general frustration at the non-existence of C/Rust cross-platform notify libraries.

Written by Félix Saparelli and awesome contributors, and released in the Public Domain using the Creative Commons Zero Declaration.