The Zuri Standard Library Zuri

The Machine

os.watch

import os
Zuri

Everything here is re-exported by os, so import os is enough and the names are called as os.*. Importing os.watch on its own works too and reaches the same definitions.

Filesystem events, which tell you when files and directories change, so you don't have to keep checking.

A Watcher asks the operating system to report changes as they happen, using the mechanism that each platform provides: inotify on Linux, FSEvents on macOS, ReadDirectoryChangesW on Windows and kqueue on the BSDs. Nothing is polled. A watcher waiting for a change uses no CPU until one happens, and the change is reported as soon as the operating system delivers it.

import os

var watcher = os.Watcher()

watcher.add('templates')
watcher.add('config.toml')

for event in watcher {
  echo '${event.kind} ${event.path}'
}
Zuri

What's reported

Every event has a kind:

  • 'create': there's now an entry at path. It was created, or renamed or moved there, which includes a file renamed over an existing one. Many editors save a file in exactly that way, by writing a new copy and renaming it over the original, so saving in those editors is reported as 'create'.
  • 'modify': the file or directory at path changed in place, either its contents or its metadata, such as permissions, ownership or modification time. A touch of an existing file is a 'modify'.
  • 'remove': there's nothing at path any more. It was deleted, or renamed or moved away. On every platform, a rename is a 'remove' of the old path and a 'create' of the new one.
  • 'rescan': the operating system dropped events, usually because too many changes arrived too quickly for it to queue them. Anything under path might have changed, or anything being watched at all if path is nil.
  • 'exit': a process that the watcher follows has exited. See follow().

Reading a file, or opening one without writing to it, is never reported.

A file saved by an editor, a formatter or git is reported as soon as it's saved, on every platform. The platforms only differ for a file that a program writes through a handle it keeps open between writes, such as a log file it keeps appending to. Linux reports each write, macOS reports the change when the program closes the file, and Windows reports it when the program closes the file or the system flushes its cache to disk.

On macOS, a change made just before add() can be reported after it, because FSEvents delivers changes asynchronously. To discard anything that's already on its way, call next() with a short timeout until it returns nil.

Each event is checked against the filesystem when next() returns it, so it describes the path as it is at that moment. A file that was created and removed again before the events were read is only reported as removed. A file that was removed and then created again is only reported as created. Changes that haven't been returned yet are merged, so a file written in several steps while nothing was reading is reported once.

Paths

Every path is resolved through any links when it's added, and every event names the resolved path, so a watch added as './src' reports /home/ada/project/src/main.zu. On Windows and macOS, whose filesystems ignore case when they look up names, a path matches however its case was written when it was added.

Limits

Each platform limits how many directories a process can watch, and add() raises an error once the limit is reached. On macOS, the limit is about a twelfth of the process's limit on open files, so the first watcher a process creates raises the soft limit as far as the hard limit and the kernel allow. Processes that it starts afterwards inherit the raised limit.

Signals

A signal with a callback registered through os.on_signal() ends a wait early: next() returns nil immediately, and the callback runs, as it would between any two statements. So a watcher can wait as long as it likes and still shut down promptly when you press Ctrl+C.

Isolates

A watcher belongs to the isolate that created it, and can't be sent to another isolate. An isolate that wants to watch for changes creates its own watcher. Signal callbacks only run on the main thread, so a signal doesn't end a wait inside an isolate, but cancelling the isolate does: next() returns nil within the pool's cancellation interval, and isolate.is_cancelled() tells you why.

Classes

WatchEvent

class os.WatchEvent
Zuri

One change a Watcher reports.

Note: constructed only by a Watcher.

Fields

Field Type Description
kind What happened: 'create', 'modify', 'remove', 'rescan' or 'exit'.
path The absolute path it happened at.
process The process that exited, for 'exit'.

Constructor

os.WatchEvent(kind: string, path: ?string, process)
Zuri

Parameters

  • kind (string)
  • path (?string)
  • process (?Process)

Watcher

class os.Watcher
Zuri

Watches files and directories for changes, and child processes for their exit, and reports both as WatchEvent objects in the order they happen.

A new watcher doesn't watch anything. add() gives it paths, follow() gives it processes, and next() waits for whatever happens first. Looping over a watcher with for calls next() for you, and continues until the watcher is closed.

Every watcher holds operating system resources until it's closed or garbage collected. Call close() when you no longer need a watcher, instead of leaving it to the garbage collector.

import os

var watcher = os.Watcher()
watcher.add('src')

var event = watcher.next(5000)

if event == nil {
  echo 'nothing changed in five seconds'
} else {
  echo event
}

watcher.close()
Zuri

Constructor

os.Watcher()
Zuri

Creates a watcher that is watching nothing yet.

Raises Error if the operating system refuses to create another watch, which on Linux means the per-user limit on inotify instances (fs.inotify.max_user_instances) has been reached.

Watcher.add()

os.Watcher.add(path: string, recursive: ?bool)
Zuri

Starts watching path.

A directory is watched with everything under it, however deep, including directories created inside it later. Pass false for recursive to watch only the directory itself and the entries directly inside it.

A file is watched on its own, through the directory that holds it. That is what keeps a file saved by renaming a new copy over it reported: a watch on the file itself would end with the original, where a watch on its directory sees the new copy arrive. recursive has no meaning for a file and is ignored.

Adding a path that is already watched takes the new recursive value and otherwise leaves its watch alone, without a moment in which a change could be missed. It is also how a watch comes back after the operating system dropped it: when a watched directory is removed, its watch ends with it, and adding it again once it exists again restores it. The same holds for a watched file whose directory was removed.

Parameters

  • path (string) — absolute, or relative to the working directory.
  • recursive (?bool) — Default true.

Returns — Watcher: this same watcher, for chaining.

Raises Error if nothing exists at path, if the watcher is closed, or if the system's limit on watched directories has been reached. On Linux that limit is fs.inotify.max_user_watches, and a recursive watch uses one per directory it covers.

Watcher.remove()

os.Watcher.remove(path: string)
Zuri

Stops watching path, which is named the way it was added. Events for it that were already queued are still handed over by next().

Parameters

  • path (string)

Returns — bool: true if path was being watched, false if it was not.

Raises Error if the watcher is closed.

Watcher.follow()

os.Watcher.follow(process)
Zuri

Starts following process, a child started with os.spawn(), so that its exit is reported as an 'exit' event, in the same wait as the filesystem changes.

Following a process does not reap it. The 'exit' event's process is the same Process, and its wait() returns the exit status at once. A process that has already been waited for is reported as exited straight away.

Each exit is reported once, after which the process is no longer followed. Following the same process twice reports its exit twice.

var server = os.spawn('zuri', ['run', 'app'], { stdout: 'inherit' })
var watcher = os.Watcher().add('app').follow(server)

for event in watcher {
  if event.kind == 'exit' {
    echo 'the server stopped with status ${event.process.wait()}'
    watcher.close()
  }
}
Zuri

Parameters

  • process (Process)

Returns — Watcher: this same watcher, for chaining.

Raises TypeError if process is not a Process.

Raises Error if the watcher is closed.

Watcher.paths()

os.Watcher.paths() -> list
Zuri

Every path being watched, resolved through its links the way it was when it was added. Empty for a closed watcher.

Returns list

Watcher.next()

os.Watcher.next(timeout: ?number) -> ?WatchEvent
Zuri

Waits for the next event and returns it.

Without a timeout this waits for as long as it takes. With one it gives up after timeout milliseconds and returns nil, and a timeout of 0 returns at once with whatever is already waiting. It also returns nil as soon as a signal with an os.on_signal() callback arrives, so the callback runs without waiting for the next change, and, inside an isolate, once that isolate is cancelled. A caller that cannot tell these apart does not need to: in each case, nothing changed.

Parameters

  • timeout (?number) — in milliseconds. Default: wait as long as it takes.

Returns ?WatchEvent

Raises Error if the watcher is closed.

Watcher.close()

os.Watcher.close()
Zuri

Stops every watch and releases what the watcher holds. Closing a closed watcher does nothing. A for loop over the watcher ends at the next event it would have waited for, which is how a signal callback stops one.

Returns

Watcher.is_closed()

os.Watcher.is_closed() -> bool
Zuri

Whether close() has been called.

Returns bool


2026, Richard Ore and Zuri contributors