Crate notify_win

Crate notify_win 

Source
Expand description

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::{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

Re-exports§

pub use null::NullWatcher;
pub use poll::PollWatcher;
pub use windows::ReadDirectoryChangesWatcher;

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§

Config
Watcher Backend configuration
Error
Notify error type.
Event
Notify event.

Enums§

ErrorKind
Error kinds
EventKind
Top-level event kind.
RecursiveMode
Indicates whether only the provided directory or its sub-directories as well should be watched
WatcherKind
Watcher kind enumeration

Traits§

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

Functions§

recommended_watcher
Convenience method for creating the RecommendedWatcher for the current platform.

Type Aliases§

RecommendedWatcher
The recommended Watcher implementation for the current platform
Result
Type alias to use this library’s Error type in a Result