std::watch
std/src/watch.mo
File-system watching over Linux's inotify, with the event decoding written
in Monad (Watch.decode) so it is unit-testable with no filesystem.
A watch IS an FdStream over the inotify queue: Watch.new creates it,
Stream.close releases it, and Watch.add registers one DIRECTORY. The
kernel reports that directory's children by bare name, and a new
subdirectory must be added explicitly (WatchEvent.is_dir marks the event
that announced it) -- there is no recursive watch in inotify itself. The
recursive walker, the coalescing and the moon live-reload swap are later
phases of plans/implementations/inotify-file-watching.md.
Watch DIRECTORIES, not files: an inotify watch is per inode, so an editor
that saves by writing a temporary file and renaming it over the target
silently kills a file watch (WatchEvent.ignored is what a dead watch
reports).
Linux-only. On any other POSIX target the four natives report ENOSYS and
Watch.new fails with an ordinary StreamError, so a caller that has a
polling fallback keeps working; on wasm the target gate refuses a reachable
call at compile time.
pub def Watch.access : I64pub def Watch.modify : I64pub def Watch.attrib : I64pub def Watch.close_write : I64pub def Watch.close_nowrite : I64pub def Watch.opened : I64IN_OPEN: a child was opened (named opened -- Watch.new is the
constructor).
pub def Watch.moved_from : I64pub def Watch.moved_to : I64pub def Watch.create : I64pub def Watch.delete : I64pub def Watch.delete_self : I64pub def Watch.move_self : I64pub def Watch.unmount : I64pub def Watch.overflow : I64pub def Watch.ignored_bit : I64pub def Watch.only_dir : I64pub def Watch.dont_follow : I64pub def Watch.is_dir_bit : I64pub def Watch.changes : I64The mask a general consumer asks for: creation, deletion, metadata and
content writes, close-for-write, renames, and the watched directory's own
removal (0xFCE).
Deliberately WITHOUT the read events (IN_ACCESS, IN_OPEN,
IN_CLOSE_NOWRITE): a dev server reads the very files it watches, so
asking for those makes the watcher wake on its own traffic -- the event
storm this API exists to avoid. The is_dir/ignored/overflow bits are
not requests either; they arrive on events as the kernel reports them.
pub def Watch.init_flags : I64The inotify_init1 flags Watch.new passes: IN_NONBLOCK (a drain loop
polls, then reads, and must never block on an empty queue) and
IN_CLOEXEC (a spawned child must not inherit the queue).
pub def Watch.read_bytes : I64The largest event is 16 header bytes + a NAME_MAX+1 name; inotify_read
fails with EINVAL rather than split an event, so this buffer can never
truncate one, and one 4 KiB read usually carries a whole burst.
pub def Watch.new : IO (Result StreamError FdStream)Create a watch. Close it with Stream.close.
pub def Watch.add (w : FdStream) (dir : Path) (mask : I64) : IO (Result StreamError I64)Watch dir (one directory, not its subtree) for the events in mask;
the returned handle is what Watch.remove takes.
pub def Watch.remove (w : FdStream) (handle : I64) : IO (Result StreamError Unit)Stop watching a handle from Watch.add.
pub def Watch.next (w : FdStream) (timeout_ms : I64)
: IO (Result StreamError (List WatchEvent))Wait up to timeout_ms for events (negative waits forever) and return
every COMPLETE event the kernel had queued -- an empty list is a timeout,
never an error. Call it again to drain the rest of a burst.
One reader per watch: two fibers calling this race for the same events.
pub struct WatchEvent {
watch : I64,
mask : I64,
cookie : I64,
name : String
}One inotify_event. watch is the handle Watch.add returned, mask
the event bits (test them with WatchEvent.has/the predicates), cookie
pairs a moved_from with its moved_to, and name is the child's bare
name (empty for an event about the watched directory itself).
pub instance Copy WatchEvent {
def copy (e : WatchEvent) : Pair WatchEvent WatchEvent := Pair.pair e e
}A decoded event is a pure value -- I64s and a Copy String -- so
sharing one (a predicate reads two bits of the same mask) is a bit-copy,
not an ownership move.
pub def WatchEvent.has (e : WatchEvent) (bit : I64) : BoolWhether mask carries bit.
pub def WatchEvent.created (e : WatchEvent) : BoolA child was created (Watch.create).
pub def WatchEvent.modified (e : WatchEvent) : BoolA child's contents or metadata changed. Fires MID-WRITE -- wait for
closed_for_write before reading the file.
pub def WatchEvent.closed_for_write (e : WatchEvent) : BoolA writer closed the file: its contents are complete.
pub def WatchEvent.deleted (e : WatchEvent) : BoolA child was deleted (Watch.delete).
pub def WatchEvent.moved_from (e : WatchEvent) : BoolThe old half of a rename; cookie names the pair.
pub def WatchEvent.moved_to (e : WatchEvent) : BoolThe new half of a rename -- an atomic save looks like this, not
closed_for_write.
pub def WatchEvent.self_deleted (e : WatchEvent) : BoolThe watched directory itself was DELETED (IN_DELETE_SELF): the watch is
finished, and Watch.drain drops its descriptor.
pub def WatchEvent.self_moved (e : WatchEvent) : BoolThe watched directory itself was renamed or moved (IN_MOVE_SELF). The
watch SURVIVES -- it is bound to the inode, not the name -- so this is not a
close signal. A rename within the tree is followed by a moved_to on the
new parent, which is what re-resolves the path.
pub def WatchEvent.removed_self (e : WatchEvent) : BoolThe watched directory itself went away, by deletion or by a move. Only
self_deleted means the watch is finished.
pub def WatchEvent.is_dir (e : WatchEvent) : BoolThe event is about a directory (a new one needs its own Watch.add).
pub def WatchEvent.overflowed (e : WatchEvent) : BoolEvents were lost: the queue overflowed, so the caller must rescan.
pub def WatchEvent.ignored (e : WatchEvent) : BoolThe kernel dropped this watch (IN_IGNORED: the inode is gone, or it was
removed). Nothing more will arrive on that handle.
pub def Watch.decode (bytes : List U8) : List WatchEventDecode a byte run of inotify_event records. An incomplete tail is
dropped: the kernel reports EINVAL instead of splitting an event, so
only a caller that passes a short hand-built buffer can see one.
pub struct Watch {
stream : FdStream,
root : Path,
ignored : List String,
dirs : Ref (List (Pair I64 Path))
}A watched tree: the queue, the root it was walked from, the directory names
it skips, and the descriptor -> directory map. Watch.drain updates the map
as directories appear and disappear, so one value serves the watcher's whole
lifetime.
pub def Watch.default_ignored : List StringDirectory names the walker never watches: Monad's build output (target/,
and target-* by Watch.ignore_dir) plus the VCS and dependency caches.
Pass List.empty to watch every directory.
pub def Watch.ignore_dir (name : String) (ignored : List String) : BoolWhether the walker skips a directory named name: an exact entry in
ignored, or the target-* build-output convention.
pub def Watch.recursive (root : Path) (ignored : List String)
: IO (Result StreamError Watch)Watch root and every non-ignored directory under it. Close the result
with Watch.close.
pub def Watch.close (w : Watch) : IO UnitRelease the queue. Nothing may use w afterwards.
pub def Watch.dir_of (dirs : List (Pair I64 Path)) (handle : I64) : Option PathThe directory a descriptor names, if it is still watched.
pub def Watch.event_path (dirs : List (Pair I64 Path)) (root : Path) (e : WatchEvent) : PathAn event's full path: the watched directory joined with the child's name, the directory itself for a zero-length name (an event about the directory), and the root when its descriptor is no longer known.
pub def Watch.any_overflow (evs : List WatchEvent) : BoolWhether any event reports a kernel queue overflow: events were lost, so the caller must rescan rather than trust the batch.
pub struct WatchBatch {
/// Every event with the path it concerns, in the order the kernel reported
/// them. Overflow events are not here -- they set `overflow`.
events : List (Pair WatchEvent Path),
/// The kernel dropped events (`/proc/sys/fs/inotify/max_queued_events`):
/// anything could have changed, so rescan the tree.
overflow : Bool
}One Watch.drain result.
pub def Watch.max_reads : I64How many reads one Watch.drain may do before returning. A tree under a
build emits events faster than a quiet window closes; the caller drains
again rather than the watcher starving.
pub def Watch.drain (w : Shared Watch) (timeout_ms : I64) (quiet_ms : I64)
: IO (Result StreamError WatchBatch)Wait up to timeout_ms for the first event (negative waits forever), then
keep reading until a quiet_ms window passes with nothing new, so one
save's several masks come back as ONE batch. Watches for newly created or
moved-in directories are added before returning, and descriptors the kernel
retired are dropped from the map.
One reader per watch: two fibers calling this race for the same events. An error means the batch was DISCARDED (a native failure, or a directory the walk could not enter): rescan rather than retrying, since the events are already consumed off the queue.
A directory moved OUT of the tree keeps its watch (inotify binds watches to
inodes, not paths) and its map entry therefore names a path that no longer
exists; its events still arrive until Watch.close. Rescan when that
matters -- WatchBatch.overflow is the kernel's version of the same answer.
Takes the watch by Shared: draining only reads the handle's fields
(it updates the map through the Ref cell), so the caller keeps
ownership for a later Watch.close.