#include"wtr/watcher.hpp" #include<iostream> #include<string>usingnamespacestd;usingnamespacewtr;// 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.autoshow(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} automain() -> 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')# Buildeval c++ -std=c++17 -Iinclude src/wtr/tiny_watcher/main.cpp -o watcher $PLATFORM_EXTRAS# Run ./watcher

#include"wtr/watcher-c.h"#include<stdio.h>voidcallback(structwtr_watcher_eventevent, 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.associated_path_name ? event.associated_path_name : "" )} intmain(){void*watcher=wtr_watcher_open(".", callback, NULL); getchar(); return ! wtr_watcher_close(watcher)}

pip install wtr-watcher

fromwatcherimportWatchwithWatch(".", print): input()

cargo add wtr-watcher tokio futures

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

import*aswatcherfrom'watcher';varw=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-go" ) funcmain(){w:=watcher.NewWatcher("/path/to/dir", func(e*watcher.Event){slog.Info("filesystem event", "event", e) }) deferw.Close() // Wait for a new line to exit_, _=fmt.Scanln() }

The output of each above will be something like this, depending on the example:

modify file /home/e-dant/dev/watcher/.git/refs/heads/next.lock rename file /home/e-dant/dev/watcher/.git/refs/heads/next.lock -> /home/e-dant/dev/watcher/.git/refs/heads/next create file /home/e-dant/dev/watcher/.git/HEAD.lock 

Enjoy!

A filesystem event watcher which is

1. Friendly

I try to keep the 1579 lines that make up the runtime of Watcherrelatively simple and the API practical:

auto w = watch(path, [](event ev){cout << ev});

wtr.watcher ~

2. Modular

Watcher may be used as a library, a program, or both. If you aren't looking to create something with the library, no worries. Just use ours and you've got yourself a filesystem watcher which prints filesystem events as JSON. Neat. Here's how:

# The main branch is the (latest) release branch. git clone https://github.com/e-dant/watcher.git &&cd watcher # Via Nix nix run | grep -oE 'cmake-is-tough'# With the build script tool/build --no-build-test --no-run &&cd out/this/Release # Build the release version for the host platform. ./wtr.watcher | grep -oE 'needle-in-a-haystack/.+"'# Use it, pipe it, whatever. (This is an .exe on Windows.)

3. Efficient

You can watch an entire filesystem with this project. In almost all cases, we use a near-zero amount of resources and make efficient use of the cache. We regularly test that the overhead of detecting and sending an event to the user is an order of magnitude less than the filesystem operations being measured.

4. Well Tested

We run this project through unit tests against all available sanitiziers. This code tries hard to be thread, memory, bounds, type and resource-safe. What we lack from the language, we try to make up for with testing. For some practical definition of safety, this project probably fits.

5. Dependency Minimal

Watcher depends on the C++ Standard Library. For efficiency, we leverage the OS when possible on Linux, Darwin and Windows. For testing and debugging, we use Snitch and Sanitizers.

6. Portable

Watcher is runnable almost anywhere. The only requirement is a filesystem.

The important pieces are the (header-only) library and the (optional) CLI program.

• C++ Header-Only Library: include/wtr/watcher.hpp. Include this to use Watcher in your C++ project. Copying this into your project, and including it as #include "wtr/watcher.hpp" (or similar) is sufficient to get up and running in this language. Some extra documentation and high-level library internals can be found in the event and watch headers.
• C Library: watcher-c. Build this to use Watcher from C or through an FFI in other languages.
• Full CLI Program: src/wtr/watcher/main.cpp. Build this to use Watcher from the command line. The output is an exhaustive JSON stream.
• Minimal CLI Program: src/wtr/tiny_watcher/main.cpp. A very minimal, more human-readable, CLI program. The source for this is almost identical to the example usage for C++.

A directory tree is in the notes below.

The two fundamental building blocks here are:

• The watch function or class (depending on the language)
• The event object (or similarly named, again depending on the language)

watch takes a path, which is a string-like thing, and a callback, with is a function-like thing. For example, passing watch a character array and a closure would work well in C++.

Examples for a variety of languages can be found in the Quick Start. The API is relatively consistent across languages.

The watcher will happily continue watching until you stop it or it hits an unrecoverable error.

The event object is used to pass information about filesystem events to the callback given (by you) to watch.

The event object will contain:

• path_name, which is an absolute path to the event.
• path_type, the type of path. One of:
  • dir
  • file
  • hard_link
  • sym_link
  • watcher
  • other
• effect_type, "what happened". One of:
  • rename
  • modify
  • create
  • destroy
  • owner
  • other
• effect_time, the time of the event in nanoseconds since epoch.
• associated (an event, C++) or associated_path_name (all other implementations, a single path name):
  • For the C++ implementation, this is a recursive structure. Another event, associated with "this" one, is stored here. The only events stored here, currently, are the renamed-to part of rename events.
  • For all other implementations, this field represents the path name of an associated event.
  • The implementation in C++, a recursive structure, was chosen to future-proof the library in the event that we need to support other associated events.

(Note that, for JavaScript, we use the camel-case, to be consistent with that language's ecosystem.)

The watcher type is special.

Events with this type will include messages from the watcher. You may recieve error messages or important status updates.

This format was chosen to support asynchronous messages from the watcher in a generic, portable format.

Two of the most important "watcher" events are the initial "live" event and the final "die" event.

The message appears prepended to the watched base path.

For example, after opening a watcher at /a/path, you may receive these messages from the watcher:

• s/self/live@/a/path
• e/self/die@/a/path

The messages always begin with either an s, indicating a successful operation, a w, indicating a non-fatal warning, or an e, indicating a fatal error.

Importantly, closing the watcher will always produce an error if

• The self/live message has not yet been sent; or, in other words, if the watcher has not fully started. In this case, the watcher will immediately close after fully opening and report an error in all calls to close.
• Any repeated calls to close the watcher. In other words, it is considered an error to close a watcher which has already been closed, or which does not exist. For the C API, this is also true for passing a null object to close.

The last event will always be a destroy event from the watcher. You can parse it like this, for some event ev:

ev.path_type == path_type::watcher && ev.effect_type == effect_type::destroy;

Happy hacking.

This project tries to make it easy for you to work with filesystem events. I think good tools are easy to use. If this project is not ergonomic, file an issue.

Here is a snapshot of the output taken while preparing this commit, right before writing this paragraph.

{"1666393024210001000":{"path_name": "/home/edant/dev/watcher/.git/logs/HEAD", "effect_type": "modify", "path_type": "file" }, "1666393024210026000":{"path_name": "/home/edant/dev/watcher/.git/logs/refs/heads/next", "effect_type": "modify", "path_type": "file" }, "1666393024210032000":{"path_name": "/home/edant/dev/watcher/.git/refs/heads/next.lock", "effect_type": "create", "path_type": "other" } }

Which is pretty cool.

A capable program is here.

This project is accessible through:

• Conan: Includes the C++ header/library
• Nix: Provides isolation, determinism, includes header, cli, test and benchmark targets
• Bazel: Provides isolation, includes the C++ header/library and cli targets
• tool/build: Includes the C++ header/library, cli, test and benchmark targets
• tool/cross: Includes the watcher-c shared library and header, cross-compiled for many platforms
• CMake: Includes the single-header C++ library, the watcher-c library (static and shared), cli, test and benchmark targets
• Just copying the header file

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

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

For the header-only library and the tiny-watcher, C++17 and up should be fine.

We might use C++20 coroutines someday.

$ tool/gen-event/dir & $ tool/gen-event/file & $ valgrind --tool=cachegrind wtr.watcher ~ -s 30

I refs: 797,368,564 I1 misses: 6,807 LLi misses: 2,799 I1 miss rate: 0.00% LLi miss rate: 0.00% D refs: 338,544,669 (224,680,988 rd + 113,863,681 wr) D1 misses: 35,331 ( 24,823 rd + 10,508 wr) LLd misses: 11,884 ( 8,121 rd + 3,763 wr) D1 miss rate: 0.0% ( 0.0% + 0.0% ) LLd miss rate: 0.0% ( 0.0% + 0.0% ) LL refs: 42,138 ( 31,630 rd + 10,508 wr) LL misses: 14,683 ( 10,920 rd + 3,763 wr) LL miss rate: 0.0% ( 0.0% + 0.0% )

Namespaces and symbols closely follow the directories in the devel/include folder. Inline namespaces are in directories with the - affix.

For example, wtr::watch is inside the file devel/include/wtr/watcher-/watch.hpp. The namespace watcher in wtr::watcher::watch is anonymous by this convention.

More in depth: the function ::detail::wtr::watcher::adapter::watch() is defined inside one (and only one!) of the files devel/include/detail/wtr/watcher/adapter/*/watch.hpp, where * is decided at compile-time (depending on the host's operating system).

All of the headers in devel/include are amalgamated into include/wtr/watcher.hpp and an include guard is added to the top. The include guard doesn't change with the release version. In the future, it might.

watcher ├── src │ └── wtr │ ├── watcher │ │ └── main.cpp │ └── tiny_watcher │ └── main.cpp ├── out ├── include │ └── wtr │ └── watcher.hpp └── devel ├── src │ └── wtr └── include ├── wtr │ ├── watcher.hpp │ └── watcher- │ ├── watch.hpp │ └── event.hpp └── detail └── wtr └── watcher ├── semabin.hpp └── adapter ├── windows │ └── watch.hpp ├── warthog │ └── watch.hpp ├── linux │ ├── watch.hpp │ ├── sysres.hpp │ ├── inotify │ │ └── watch.hpp │ └── fanotify │ └── watch.hpp └── darwin └── watch.hpp 

You can run tool/tree to view this tree locally.

https://github.com/notify-rs/notify: lines of code: 2799lines of tests: 475lines of docs: 1071implementation languages: rustinterface languages: rustsupported platforms: linux, windows, darwin, bsdkernel apis: inotify, readdirectorychanges, fsevents, kqueuenon-blocking: yesdependencies: nonetests: yesstatic analysis: yes (borrow checked, memory and concurrency safe language)https://github.com/e-dant/watcher: lines of code: 1579lines of tests: 881lines of docs: 1977implementation languages: cppinterface languages: cpp, shellssupported platforms: linux, darwin, windows, bsdkernel apis: inotify, fanotify, fsevents, readdirectorychangesnon-blocking: yesdependencies: nonetests: yesstatic analysis: yeshttps://github.com/facebook/watchman.git: lines of code: 37435lines of tests: unknownlines of docs: unknownimplementation languages: cpp, cinterface languages: cpp, js, java, python, ruby, rust, shellssupported platforms: linux, darwin, windows, maybe bsdkernel apis: inotify, fsevents, readdirectorychangesnon-blocking: yesdependencies: nonetests: yes (many)static analysis: yes (all available)https://github.com/p-ranav/fswatch: lines of code: 245lines of tests: 19lines of docs: 114implementation languages: cppinterface languages: cpp, shellssupported platforms: linux, darwin, windows, bsdkernel apis: inotifynon-blocking: maybedependencies: nonetests: somestatic analysis: nonehttps://github.com/tywkeene/go-fsevents: lines of code: 413lines of tests: 401lines of docs: 384implementation languages: gointerface languages: gosupported platforms: linuxkernel apis: inotifynon-blocking: yesdependencies: yestests: yesstatic analysis: none (gc language)https://github.com/radovskyb/watcher: lines of code: 552lines of tests: 767lines of docs: 399implementation languages: gointerface languages: gosupported platforms: linux, darwin, windowskernel apis: nonenon-blocking: nodependencies: nonetests: yesstatic analysis: nonehttps://github.com/parcel-bundler/watcher: lines of code: 2862lines of tests: 474lines of docs: 791implementation languages: cppinterface languages: jssupported platforms: linux, darwin, windows, maybe bsdkernel apis: fsevents, inotify, readdirectorychangesnon-blocking: yesdependencies: nonetests: some (js bindings)static analysis: none (interpreted language)https://github.com/atom/watcher: lines of code: 7789lines of tests: 1864lines of docs: 1334implementation languages: cppinterface languages: jssupported platforms: linux, darwin, windows, maybe bsdkernel apis: inotify, fsevents, readdirectorychangesnon-blocking: yesdependencies: nonetests: some (js bindings)static analysis: nonehttps://github.com/paulmillr/chokidar: lines of code: 1544lines of tests: 1823lines of docs: 1377implementation languages: jsinterface languages: jssupported platforms: linux, darwin, windows, bsdkernel apis: fseventsnon-blocking: maybedependencies: yestests: yes (many)static analysis: none (interpreted language)https://github.com/Axosoft/nsfw: lines of code: 2536lines of tests: 1085lines of docs: 148implementation languages: cppinterface languages: jssupported platforms: linux, darwin, windows, maybe bsdkernel apis: fseventsnon-blocking: maybedependencies: yes (many)tests: yes (js bindings)static analysis: nonehttps://github.com/canton7/SyncTrayzor: lines of code: 17102lines of tests: 0lines of docs: 2303implementation languages: c#interface languages: c#supported platforms: windowskernel apis: unknownnon-blocking: yesdependencies: unknowntests: nonestatic analysis: none (managed language)https://github.com/g0t4/Rx-FileSystemWatcher: lines of code: 360lines of tests: 0lines of docs: 46implementation languages: c#interface languages: c#supported platforms: windowskernel apis: unknownnon-blocking: yesdependencies: unknowntests: yesstatic analysis: none (managed language)