Crate notify

Source
Expand description

Cross-platform file system notification library

§Installation

[dependencies]
notify = "6.1.1"

If you want debounced events (or don’t need them in-order), see notify-debouncer-mini or notify-debouncer-full.

§Features

List of compilation features, see below for details

  • serde for serialization of events
  • macos_fsevent enabled by default, for fsevent backend on macos
  • macos_kqueue for kqueue backend on macos
  • serialization-compat-6 restores the serialization behavior of notify 6, off by default

§Serde

Events are serializable via serde if the serde feature is enabled:

notify = { version = "6.1.1", features = ["serde"] }

§Known Problems

§Network filesystems

Network mounted filesystems like NFS may not emit any events for notify to listen to. This applies especially to WSL programs watching windows paths (issue #254).

A workaround is the PollWatcher backend.

§Docker with Linux on macOS M1

Docker on macOS M1 throws Function not implemented (os error 38). You have to manually use the PollWatcher, as the native backend isn’t available inside the emulation.

§macOS, FSEvents and unowned files

Due to the inner security model of FSEvents (see FileSystemEventSecurity), some events 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.

§Editor Behaviour

If you rely on precise events (Write/Delete/Create..), you will notice that the actual events can differ a lot between file editors. Some truncate the file on save, some create a new one and replace the old one. See also this and this issues for example.

§Parent folder deletion

If you want to receive an event for a deletion of folder b for the path /a/b/.., you will have to watch its parent /a. See here for more details.

§Pseudo Filesystems like /proc, /sys

Some filesystems like /proc and /sys on *nix do not emit change events or use correct file change dates. To circumvent that problem you can use the PollWatcher with the compare_contents option.

§Linux: Bad File Descriptor / No space left on device

This may be the case of running into the max-files watched limits of your user or system. (Files also includes folders.) Note that for recursive watched folders each file and folder inside counts towards the limit.

You may increase this limit in linux via

sudo sysctl fs.inotify.max_user_instances=8192 # example number
sudo sysctl fs.inotify.max_user_watches=524288 # example number
sudo sysctl -p

Note that the PollWatcher is not restricted by this limitation, so it may be an alternative if your users can’t increase the limit.

§Watching large directories

When watching a very large amount of files, notify may fail to receive all events. For example the linux backend is documented to not be a 100% reliable source. See also issue #412.

§Examples

For more examples visit the examples folder in the repository.

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

fn main() -> Result<()> {
    let (tx, rx) = mpsc::channel::<Result<Event>>();

    // Use recommended_watcher() to automatically select the best implementation
    // for your platform. The `EventHandler` passed to this constructor can be a
    // closure, a `std::sync::mpsc::Sender`, a `crossbeam_channel::Sender`, or
    // another type the trait is implemented for.
    let mut watcher = notify::recommended_watcher(tx)?;

    // Add a path to be watched. All files and directories at that path and
    // below will be monitored for changes.
    watcher.watch(Path::new("."), RecursiveMode::Recursive)?;
    // Block forever, printing out events as they come in
    for res in rx {
        match res {
            Ok(event) => println!("event: {:?}", event),
            Err(e) => println!("watch error: {:?}", e),
        }
    }

    Ok(())
}

§With different configurations

It is possible to create several watchers with different configurations or implementations that all call the same event function. This can accommodate advanced behaviour or work around limits.

      fn event_fn(res: Result<notify::Event>) {
          match res {
             Ok(event) => println!("event: {:?}", event),
             Err(e) => println!("watch error: {:?}", e),
          }
      }

      let mut watcher1 = notify::recommended_watcher(event_fn)?;
      // we will just use the same watcher kind again here
      let mut watcher2 = notify::recommended_watcher(event_fn)?;
      // dropping the watcher1/2 here (no loop etc) will end the program

Re-exports§

Modules§

  • event
    The Event type and the hierarchical EventKind descriptor.
  • null
    Stub Watcher implementation
  • poll
    Generic Watcher implementation based on polling
  • windows
    Watcher implementation for Windows’ directory management APIs

Structs§

Enums§

Traits§

  • EventHandler
    The set of requirements for watcher event handling functions.
  • Watcher
    Type that can deliver file activity notifications

Functions§

Type Aliases§