#include "wtr/watcher.hpp"
#include <iostream>
#include <string>
using namespace std; using namespace wtr;
// The event type, and every field within it, has // string conversions and stream operators. All // kinds of strings -- Narrow, wide and weird ones. // If we don't want particular formatting, we can // json-serialize and show the event like this: //   some_stream << event // Here, we'll apply our own formatting. auto show(event e) {   cout << to<string>(e.effect_type) + ' '         + to<string>(e.path_type)   + ' '         + to<string>(e.path_name)         + (e.associated ? " -> " + to<string>(e.associated->path_name) : "")        << endl; }
auto main() -> int {   // Watch the current directory asynchronously,   // calling the provided function on each event.   auto watcher = watch(".", show);
// Do some work. (We'll just wait for a newline.)   getchar();
// The watcher would close itself around here,   // though we can check and close it ourselves.   return watcher.close() ? 0 : 1; }

# Sigh
PLATFORM_EXTRAS=$(test "$(uname)" = Darwin && echo '-isysroot /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk -framework CoreFoundation -framework CoreServices')
Build
eval c++ -std=c++17 -Iinclude src/wtr/tinywatcher/main.cpp -o watcher $PLATFORMEXTRAS
Run
./watcher

#include "wtr/watcher-c.h"
#include <stdio.h>
void callback(struct wtrwatcherevent event, void* _ctx) {     printf(         "path name: %s, effect type: %d path type: %d, effect time: %lld, associated path name: %s\n",         event.path_name,         event.effect_type,         event.path_type,         event.effect_time,         event.associatedpathname ? event.associatedpathname : ""     ); }
int main() {     void* watcher = wtrwatcheropen(".", callback, NULL);     getchar();     return ! wtrwatcherclose(watcher); }

pip install wtr-watcher

from watcher import Watch
with Watch(".", print):     input()

cargo add wtr-watcher tokio futures

use futures::StreamExt;
use wtr_watcher::Watch;
#[tokio::main(flavor = "current_thread")] async fn main() -> Result<(), Box<dyn std::error::Error>> {     let show = |e| async move { println!("{e:?}") };     let events = Watch::try_new(".")?;     events.for_each(show).await;     Ok(()) }

import * as watcher from 'watcher';
var w = watcher.watch('.', (event) => {   console.log(event); });
process.stdin.on('data', () => {   w.close();   process.exit(); });

package main
import ( 	"fmt" 	"log/slog"
"github.com/e-dant/watcher/watcher-go" )
func main() { 	w := watcher.NewWatcher("/path/to/dir", func(e *watcher.Event) { 		slog.Info("filesystem event", "event", e) 	}) 	defer w.Close()
// Wait for a new line to exit 	,  = fmt.Scanln() }

See the package here.

nix build # To just build
nix run # Build the default target, then run without arguments
nix run . -- / | jq # Build and run, watch the root directory, pipe it to jq
nix develop # Enter an isolated development shell with everything needed to explore this project

bazel build cli # Build, but don't run, the cli
bazel build hdr # Ditto, for the single-header
bazel run cli # Run the cli program without arguments

tool/build
cd out/this/Release
watches the current directory forever
./wtr.watcher
watches some path for 10 seconds
./wtr.watcher 'your/favorite/path' -s 10

This will take care of some platform-specifics, building the release, debug, and sanitizer variants, and running some tests.

cmake -S . -B out
cmake --build out --config Release
cd out
watches the current directory forever
./wtr.watcher
watches some path for 10 seconds
./wtr.watcher 'your/favorite/path' -s 10

Watchers on all platforms intentionally ignore modification events which only change the access time on a file or directory.

The utility of those events was questionable.

It seemed more harmful than good. Other watchers, like Microsoft's C# watcher, ignore them by default. Some user applications rely on modification events to know when themselves to reload a file.

Better, more complete solutions exist, and these defaults might again change.

Providing a way to ignore events from a process-id, a shorthand from "this" process, and a way to specify which kinds of event sources we are interested in are good candidates for more complete solutions.

I was comfortable with C++ when I first wrote this. I later rewrote this project in Rust as an experiment. There are benefits and drawbacks to Rust. Some things were a bit safer to express, other things were definitely not. The necessity of doing pointer math on some variably-sized opaque types from the kernel, for example, is not safer to express in Rust. Other things are safer, but this project doesn't benefit much from them.

Rust really shines in usability and expression. That might be enough of a reason to use it. Among other things, we could work with async traits and algebraic types for great good.

I'm not sure if there is a language that can "just" make the majority of the code in this project safe by definition.

The guts of this project, the adapters, talk to the kernel. They are bound to use unsafe, ill-typed, caveat-rich system-level interfaces.

The public API is just around 100 lines, is well-typed, well-tested, and human-verifiable. Not much happens there.

Creating an FFI by exposing the adapters with a C ABI might be worthwhile. Most languages should be able to hook into that.

The safety of the platform adapters necessarily depends on each platform's documentation for their interfaces. Like with all system-level interfaces, as long as we ensure the correct pre-and-post-conditions, and those conditions are well-defined, we should be fine.

Among the platform-specific implementations, the FSEvents API is used on Darwin and the ReadDirectoryChanges API is used on Windows. There is some extra work we do to select the best adapter on Linux. The fanotify adapter is used when the kernel version is greater than 5.9, the containing process has root priveleges, and the necessary system calls are otherwise allowed. The system calls associated with fanotify may be disallowed when inside a container or cgroup, despite the necessary priviledges and kernel version. The inotify adapter is used otherwise. You can find the selection code for Linux here.

The namespaces for our adapters are inline. When the (internal) detail::...::watch() function is invoked, it resolves to one (and only one) platform-specifc implementation of the watch() function. One symbol, many platforms, where the platforms are inline namespaces.

Efficiency takes a hit when we bring out the warthog, our platform-independent adapter. This adapter is used on platforms that lack better alternatives, such as (not Darwin) BSD and Solaris (because warthog beats kqueue).

Watcher is still relatively efficient when it has no alternative better than warthog. As a thumb-rule, scanning more than one-hundred-thousand paths with warthog might stutter.

I'll keep my eyes open for better kernel APIs on BSD.

There is no reliable way to communicate when a watcher is ready to send events to the callback.

For a few thousand paths, this may take a few milliseconds. For tens-of-thousands of paths, consider waiting a few seconds.

None of the platform-specific implementations provide information on what attributes were changed from. This makes supporting those events dependant on storing this information ourselves. Storing maps of paths to stat structures, diffing them on attribute changes, is a non-insignificant memory commitment.

The owner and attribute events are unsupported because I'm not sure how to support those events efficienty.

Special filesystems, including /proc and /sys, cannot be watched with inotify, fanotify or the warthog. Future work may involve dispatching ebpf programs for the kernel to use. This would allow us to monitor for modify events on some of those special filesystem.

The number of watched files is limited when inotify is used.

• inotify
• fanotify
• epoll
• eventfd

• FSEvents
• dispatch

• ReadDirectoryChangesW
• IoCompletionPort

https://github.com/notify-rs/notify:
  lines of code: 2799
  lines of tests: 475
  lines of docs: 1071
  implementation languages: rust
  interface languages: rust
  supported platforms: linux, windows, darwin, bsd
  kernel apis: inotify, readdirectorychanges, fsevents, kqueue
  non-blocking: yes
  dependencies: none
  tests: yes
  static analysis: yes (borrow checked, memory and concurrency safe language)
https://github.com/e-dant/watcher:   lines of code: 1579   lines of tests: 881   lines of docs: 1977   implementation languages: cpp   interface languages: cpp, shells   supported platforms: linux, darwin, windows, bsd   kernel apis: inotify, fanotify, fsevents, readdirectorychanges   non-blocking: yes   dependencies: none   tests: yes   static analysis: yes
https://github.com/facebook/watchman.git:   lines of code: 37435   lines of tests: unknown   lines of docs: unknown   implementation languages: cpp, c   interface languages: cpp, js, java, python, ruby, rust, shells   supported platforms: linux, darwin, windows, maybe bsd   kernel apis: inotify, fsevents, readdirectorychanges   non-blocking: yes   dependencies: none   tests: yes (many)   static analysis: yes (all available)
https://github.com/p-ranav/fswatch:   lines of code: 245   lines of tests: 19   lines of docs: 114   implementation languages: cpp   interface languages: cpp, shells   supported platforms: linux, darwin, windows, bsd   kernel apis: inotify   non-blocking: maybe   dependencies: none   tests: some   static analysis: none
https://github.com/tywkeene/go-fsevents:   lines of code: 413   lines of tests: 401   lines of docs: 384   implementation languages: go   interface languages: go   supported platforms: linux   kernel apis: inotify   non-blocking: yes   dependencies: yes   tests: yes   static analysis: none (gc language)
https://github.com/radovskyb/watcher:   lines of code: 552   lines of tests: 767   lines of docs: 399   implementation languages: go   interface languages: go   supported platforms: linux, darwin, windows   kernel apis: none   non-blocking: no   dependencies: none   tests: yes   static analysis: none
https://github.com/parcel-bundler/watcher:   lines of code: 2862   lines of tests: 474   lines of docs: 791   implementation languages: cpp   interface languages: js   supported platforms: linux, darwin, windows, maybe bsd   kernel apis: fsevents, inotify, readdirectorychanges   non-blocking: yes   dependencies: none   tests: some (js bindings)   static analysis: none (interpreted language)
https://github.com/atom/watcher:   lines of code: 7789   lines of tests: 1864   lines of docs: 1334   implementation languages: cpp   interface languages: js   supported platforms: linux, darwin, windows, maybe bsd   kernel apis: inotify, fsevents, readdirectorychanges   non-blocking: yes   dependencies: none   tests: some (js bindings)   static analysis: none
https://github.com/paulmillr/chokidar:   lines of code: 1544   lines of tests: 1823   lines of docs: 1377   implementation languages: js   interface languages: js   supported platforms: linux, darwin, windows, bsd   kernel apis: fsevents   non-blocking: maybe   dependencies: yes   tests: yes (many)   static analysis: none (interpreted language)
https://github.com/Axosoft/nsfw:   lines of code: 2536   lines of tests: 1085   lines of docs: 148   implementation languages: cpp   interface languages: js   supported platforms: linux, darwin, windows, maybe bsd   kernel apis: fsevents   non-blocking: maybe   dependencies: yes (many)   tests: yes (js bindings)   static analysis: none
https://github.com/canton7/SyncTrayzor:   lines of code: 17102   lines of tests: 0   lines of docs: 2303   implementation languages: c#   interface languages: c#   supported platforms: windows   kernel apis: unknown   non-blocking: yes   dependencies: unknown   tests: none   static analysis: none (managed language)
https://github.com/g0t4/Rx-FileSystemWatcher:   lines of code: 360   lines of tests: 0   lines of docs: 46   implementation languages: c#   interface languages: c#   supported platforms: windows   kernel apis: unknown   non-blocking: yes   dependencies: unknown   tests: yes   static analysis: none (managed language)