The Machine
os.watch
import os
ZuriEverything here is re-exported by
os, soimport osis enough and the names are called asos.*. Importingos.watchon 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}'
}
ZuriWhat's reported
Every event has a kind:
'create': there's now an entry atpath. 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 atpathchanged in place, either its contents or its metadata, such as permissions, ownership or modification time. Atouchof an existing file is a'modify'.'remove': there's nothing atpathany 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 underpathmight have changed, or anything being watched at all ifpathisnil.'exit': a process that the watcher follows has exited. Seefollow().
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
ZuriOne 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)
ZuriParameters
kind(string)path(?string)process(?Process)
Watcher
class os.Watcher
ZuriWatches 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()
ZuriConstructor
os.Watcher()
ZuriCreates 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)
ZuriStarts 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) — Defaulttrue.
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)
ZuriStops 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)
ZuriStarts 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()
}
}
ZuriParameters
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
ZuriEvery 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
ZuriWaits 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()
ZuriStops 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
ZuriWhether close() has been called.
Returns bool
2026, Richard Ore and Zuri contributors