Watching Files

A development loop wants to know when a source file changed. Polling for it means walking the tree and hashing every file on a timer; std::watch asks the operating system instead. On Linux it is inotify: one file descriptor per watched tree, and a blocking poll(2) that stays asleep until something happens.

The library is std::watch. It has two layers: the queue itself (one fd, the same kind of value std::stream hands back) and a tree form that walks a directory once and resolves every event's bare name back to a full path.

Watching a tree

This one opts out of scripts/check-docs.sh's type check (monad,ignore): one_batch hands the same Watch to Watch.drain and then to Watch.close, and the affine rule -- an unannotated binder is used at most once unless its type is Copy -- is enforced as an error on every check path while std still migrates (std/mote.toml runs [affine] mode = "warn", and cli's script --watch loop, this example's real-world twin, relies on the same window). The shape is the one a program actually writes; the fence goes back to being checked the day the watch API can express it.

use std::list {}
use std::path {Path}
use std::stream {StreamError}
use std::watch {
  Watch, Watch.default_ignored, Watch.drain, Watch.recursive, WatchBatch, WatchEvent,
}

def WatchBatch.changed (b : WatchBatch) : I64 := List.length b.events

def show (r : Result StreamError WatchBatch) : IO Unit :=
  match r {
    Result.err e => IO.write_stderr (String.concat "watch: " e.message),
    Result.ok b => IO.println (String.concat "events: " (I64.to_string (WatchBatch.changed b))),
  }

def one_batch (w : Watch) : IO Unit := do {
  let batch <- Watch.drain (Shared.of w) 1000 50;
  let _ <- Watch.close w;
  show batch
}

def main (args : List String) : IO Unit := do {
  let opened <- Watch.recursive (Path.path ".") Watch.default_ignored;
  match opened {
    Result.err e => IO.write_stderr (String.concat "watch: " e.message),
    Result.ok w => one_batch w,
  }
}

Watch.recursive walks the directory once, adds one watch per directory (the directories named by Watch.default_ignored and target-* are skipped), and returns a Watch carrying the queue, the root and a descriptor → directory map. Path.path "." is the tree to watch; pass the directory you care about.

Watch.drain takes the watch by Shared — draining only reads the handle and updates the map through its Ref cell, so the handle is still yours to close. It waits up to its first argument for something to happen, then keeps reading until a quiet window of the second argument passes with nothing new, so one editor save arrives as one batch -- not as its IN_MODIFY, IN_CLOSE_WRITE and IN_MOVED_TO events separately.

Watch.close releases the queue when the loop is done with it; a Watch is affine, so a drain-and-close loop keeps the watch inside one def that owns it for its lifetime (monad script --watch's script_watch_loop is the in-tree example) -- the sample above drains one batch and stops.

The events

A batch has events : List (Pair WatchEvent Path) and overflow : Bool. WatchEvent is the kernel's record, decoded: the descriptor, the mask, the cookie (which pairs the two halves of a rename) and the child's bare name -- already joined onto its directory for you. The mask has named predicates:

Predicate Means
WatchEvent.created a child appeared
WatchEvent.closed_for_write a writer finished -- the file is complete
WatchEvent.modified contents or metadata changed (fires MID-write)
WatchEvent.deleted, moved_from, moved_to removal and the two halves of a rename
WatchEvent.is_dir the entry is a directory (a new one is watched from then on)
WatchEvent.self_deleted, self_moved the watched directory itself was deleted / moved
WatchEvent.overflowed the kernel lost events

WatchBatch.overflow is true when the kernel's queue overflowed: events were lost, so rescan the tree rather than trusting what the batch reports.

What the tree form does for you

Portability

inotify is Linux's. On any other POSIX target the four natives report ENOSYS and Watch.recursive fails with an ordinary StreamError; on wasm the target gate refuses a reachable Watch.recursive at compile time rather than failing at link. Callers that need a watcher everywhere keep a polling signature as the fallback -- that is exactly what motes/moon's live reload does, and the monad script --watch mode below reports the error instead of guessing.

monad script --watch

monad script dev --watch

builds the named [[script]] and runs it, then watches the tree its manifest lives in: a change kills the running child (SIGKILL, reaped), the build runs again -- the store decides whether that compiles -- and the new binary starts with the same arguments. A failed build is not fatal: the watcher stays alive with no child, so fixing the error reruns it.

Everything under target/ (and target-*) is ignored, which is what keeps the build from retriggering itself. A script that writes into the watched tree will retrigger, so generated files belong under target/ or outside the tree.

The child is spawned with Proc.spawn, so its three standard streams are pipes: stdout and stderr are copied through to yours (line by line, as they are written), but it sees a pipe rather than a terminal -- no TTY detection -- and its stdin is a pipe it never reads from, so an interactive script should not be run under --watch.

The watch root is the manifest's directory. A --mote that names a path dependency outside that tree still builds correctly, but edits under it do not trigger a rerun. A child that exits on its own is reaped at the next change, not the moment it exits.

Caveats