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.

defWatch.access#
pub def Watch.access : I64
defWatch.modify#
pub def Watch.modify : I64
defWatch.attrib#
pub def Watch.attrib : I64
defWatch.close_write#
pub def Watch.close_write : I64
defWatch.close_nowrite#
pub def Watch.close_nowrite : I64
defWatch.opened#
pub def Watch.opened : I64

IN_OPEN: a child was opened (named opened -- Watch.new is the constructor).

defWatch.moved_from#
pub def Watch.moved_from : I64
defWatch.moved_to#
pub def Watch.moved_to : I64
defWatch.create#
pub def Watch.create : I64
defWatch.delete#
pub def Watch.delete : I64
defWatch.delete_self#
pub def Watch.delete_self : I64
defWatch.move_self#
pub def Watch.move_self : I64
defWatch.unmount#
pub def Watch.unmount : I64
defWatch.overflow#
pub def Watch.overflow : I64
defWatch.ignored_bit#
pub def Watch.ignored_bit : I64
defWatch.only_dir#
pub def Watch.only_dir : I64
defWatch.dont_follow#
pub def Watch.dont_follow : I64
defWatch.is_dir_bit#
pub def Watch.is_dir_bit : I64
defWatch.changes#
pub def Watch.changes : I64

The 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.

defWatch.init_flags#
pub def Watch.init_flags : I64

The 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).

defWatch.read_bytes#
pub def Watch.read_bytes : I64

The 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.

defWatch.new#
pub def Watch.new : IO (Result StreamError FdStream)

Create a watch. Close it with Stream.close.

defWatch.add#
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.

defWatch.remove#
pub def Watch.remove (w : FdStream) (handle : I64) : IO (Result StreamError Unit)

Stop watching a handle from Watch.add.

defWatch.next#
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.

structWatchEvent#
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).

instance_#
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.

defWatchEvent.has#
pub def WatchEvent.has (e : WatchEvent) (bit : I64) : Bool

Whether mask carries bit.

defWatchEvent.created#
pub def WatchEvent.created (e : WatchEvent) : Bool

A child was created (Watch.create).

defWatchEvent.modified#
pub def WatchEvent.modified (e : WatchEvent) : Bool

A child's contents or metadata changed. Fires MID-WRITE -- wait for closed_for_write before reading the file.

defWatchEvent.closed_for_write#
pub def WatchEvent.closed_for_write (e : WatchEvent) : Bool

A writer closed the file: its contents are complete.

defWatchEvent.deleted#
pub def WatchEvent.deleted (e : WatchEvent) : Bool

A child was deleted (Watch.delete).

defWatchEvent.moved_from#
pub def WatchEvent.moved_from (e : WatchEvent) : Bool

The old half of a rename; cookie names the pair.

defWatchEvent.moved_to#
pub def WatchEvent.moved_to (e : WatchEvent) : Bool

The new half of a rename -- an atomic save looks like this, not closed_for_write.

defWatchEvent.self_deleted#
pub def WatchEvent.self_deleted (e : WatchEvent) : Bool

The watched directory itself was DELETED (IN_DELETE_SELF): the watch is finished, and Watch.drain drops its descriptor.

defWatchEvent.self_moved#
pub def WatchEvent.self_moved (e : WatchEvent) : Bool

The 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.

defWatchEvent.removed_self#
pub def WatchEvent.removed_self (e : WatchEvent) : Bool

The watched directory itself went away, by deletion or by a move. Only self_deleted means the watch is finished.

defWatchEvent.is_dir#
pub def WatchEvent.is_dir (e : WatchEvent) : Bool

The event is about a directory (a new one needs its own Watch.add).

defWatchEvent.overflowed#
pub def WatchEvent.overflowed (e : WatchEvent) : Bool

Events were lost: the queue overflowed, so the caller must rescan.

defWatchEvent.ignored#
pub def WatchEvent.ignored (e : WatchEvent) : Bool

The kernel dropped this watch (IN_IGNORED: the inode is gone, or it was removed). Nothing more will arrive on that handle.

defWatch.decode#
pub def Watch.decode (bytes : List U8) : List WatchEvent

Decode 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.

structWatch#
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.

defWatch.default_ignored#
pub def Watch.default_ignored : List String

Directory 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.

defWatch.ignore_dir#
pub def Watch.ignore_dir (name : String) (ignored : List String) : Bool

Whether the walker skips a directory named name: an exact entry in ignored, or the target-* build-output convention.

defWatch.recursive#
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.

defWatch.close#
pub def Watch.close (w : Watch) : IO Unit

Release the queue. Nothing may use w afterwards.

defWatch.dir_of#
pub def Watch.dir_of (dirs : List (Pair I64 Path)) (handle : I64) : Option Path

The directory a descriptor names, if it is still watched.

defWatch.event_path#
pub def Watch.event_path (dirs : List (Pair I64 Path)) (root : Path) (e : WatchEvent) : Path

An 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.

defWatch.any_overflow#
pub def Watch.any_overflow (evs : List WatchEvent) : Bool

Whether any event reports a kernel queue overflow: events were lost, so the caller must rescan rather than trust the batch.

structWatchBatch#
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.

defWatch.max_reads#
pub def Watch.max_reads : I64

How 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.

defWatch.drain#
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.