Module sys/events

Signature of a poll callback: (events, status, user_data), where events is the OR of the POLL_* bits that fired and status is 0 or a negative errno.

It runs on the EVENT-LOOP thread, from the loop's tick, so it must not block. Polling is level-triggered: a readable descriptor fires on every tick until it is drained.

A poll registration. handle is the runtime's own C allocation, not a Yo-owned one — copying the struct copies the pointer, and poll_close invalidates every copy.

Signature of a filesystem-watch callback: (path, events, user_data).

path is the ENTRY NAME relative to the watched directory (the file's own name when a file is watched), not a full path, and it is a borrowed C string valid only for the duration of the call — copy it if you keep it. events is FS_EVENT_RENAME and/or FS_EVENT_CHANGE. Like PollCallback it runs on the event-loop thread.

A filesystem-watch registration, with the same "the pointer is the runtime's" caveat as PollHandle.

Allocate a poll handle bound to fd. Nothing is watched until poll_start, and the descriptor is not validated here.

There is no error return, so an allocation failure is not observable at this layer — see the module's Stability note.

Start watching for events (an OR of POLL_READABLE, POLL_WRITABLE and POLL_PRIORITIZED — POLL_DISCONNECT is report-only). Returns 0 on success, -EINVAL for a null callback.

user_data is handed back to the callback unchanged, which is how a callback finds its owning object. While started, the handle keeps the event loop ALIVE: a program whose only remaining work is a started poll will not exit.

Stop watching and release the loop reference. Returns 0 on success, -EINVAL for a null handle. Idempotent: stopping a handle that is already stopped returns 0 without doing anything.

Stop (if needed) and FREE the handle. The PollHandle and every copy of it dangle afterwards. It does not close the descriptor — that is the caller's.

Allocate a filesystem-watch handle. No path is attached until fs_event_start, and as with poll_init there is no error return.

Start watching path — a directory or a single file. Returns 0 on success, a negative errno on failure (-EINVAL for a null path or callback, -ENOENT for a missing path, -ENOTSUP on wasm, which has no filesystem events).

flags is FS_EVENT_RECURSIVE or 0; see that constant for which platforms honour it. user_data is passed back to the callback. While started, the handle keeps the event loop alive.

The backends are genuinely different mechanisms, which is why event delivery is coarse: inotify on Linux (mask IN_MODIFY | IN_CREATE | IN_DELETE | IN_MOVED_FROM | IN_MOVED_TO | IN_ATTRIB), a kqueue EVFILT_VNODE watch on macOS backed by a directory SNAPSHOT that the loop diffs to work out which entry changed, and ReadDirectoryChangesW on Windows.

Stop watching and release the loop reference, tearing down the platform watch (the inotify watch, the kqueue and its snapshot, the directory handle). Returns 0 on success, -EINVAL for a null handle; idempotent.

Stop (if needed) and FREE the handle. Every copy dangles afterwards. Calling this is what stops the loop calling back into memory the owner has dropped — std/fs/watch's Watcher does it from Dispose for exactly that reason.

UV_TTY_MODE_NORMAL — restore the mode that std/sys/tty's tty_init saved: echo on, line-buffered, Ctrl-C generates a signal.

UV_TTY_MODE_RAW — no echo, no line buffering, no signal generation, so each keystroke is readable immediately and Ctrl-C arrives as a byte. What a full-screen or key-at-a-time UI wants.

UV_TTY_MODE_IO — binary mode: output post-processing and input translation off, but echo and canonical input left as they are. The setting for moving bytes through a terminal without newline mangling.

UV_READABLE — ask to be told when the descriptor has data (POLLIN).

UV_WRITABLE — ask to be told when the descriptor can accept data (POLLOUT).

UV_DISCONNECT — the peer hung up (POLLHUP). Report-only: it is delivered to the callback but cannot be REQUESTED, because poll(2) reports POLLHUP in revents regardless of what was asked for. Passing it to poll_start has no effect.

UV_PRIORITIZED — out-of-band / priority data is available (POLLPRI); on a TCP socket, urgent data.

UV_FS_EVENT_WATCH_ENTRY — accepted for libuv parity and read by NO backend in this tree. Passing it changes nothing.

UV_FS_EVENT_STAT — accepted for libuv parity and read by NO backend in this tree. Passing it changes nothing.

UV_FS_EVENT_RECURSIVE — watch the whole subtree, not just the directory itself. Honoured on Windows ONLY, where it becomes ReadDirectoryChangesW's bWatchSubtree. Linux adds IN_ISDIR to the inotify mask, which does not make inotify recurse, and macOS ignores it — so on both, a recursive watch has to be built by watching each directory.

The events bit meaning an entry was created, removed or moved — libuv's "rename" class. Backends cannot always tell the three apart, which is why they share one bit.

The events bit meaning an entry's contents or metadata changed. A single write may surface as one or several of these depending on how the platform coalesces.