Win Notify

Windows filesystem notification library for Rust.

Fork of notify

• Notify Documentation
• Minimum supported Rust version: 1.77

Platforms

• Windows: ReadDirectoryChangesW
• All platforms: polling

License

notify-win is licensed under the CC Zero 1.0.

win-file-id is licensed under the MIT or Apache-2.0 license.

lib.rs:

Windows file system notification library

Fork of notify

Installation

[dependencies]
notify-win = "0.1.0"

Features

List of compilation features, see below for details

• serde for serialization of events
• 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-win = { version = "0.1.0", 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.

A workaround is the PollWatcher backend.

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.

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.

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.

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.

use notify_win::{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_win::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_win::Event>) {
          match res {
             Ok(event) => println!("event: {:?}", event),
             Err(e) => println!("watch error: {:?}", e),
          }
      }

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