watch/watch
public watcher API.
watch-supported?
(watch-supported?)
1 if a real backend is compiled in.
watch-open-one
(watch-open-one [path : cstr opts : int])
open a watcher on a single file path.
| path | file path (absolute or relative) to observe | |
| opts | options handle from watch/opts (may be 0 for defaults) |
watch-tree-dir-count
(watch-tree-dir-count [watcher : int])
number of directories under tree-mode watch.
watch-tree-dir-at
(watch-tree-dir-at [watcher : int idx : int])
get the i-th registered directory (read-only borrow).
watch-close
(watch-close [watcher : int])
release a watcher. Safe on 0.
watch-open-tree
(watch-open-tree [root : cstr opts : int])
recursively watch a directory and all subdirs.
watch-open
(watch-open [path : cstr opts : int])
open a watcher on a path with auto-dispatch.
watch-add-path
(watch-add-path [watcher : int path : cstr])
v0.1.0 stub. Multi-path explicit list lands with v0.2.
watch-remove-path
(watch-remove-path [watcher : int path : cstr])
v0.1.0 stub. Multi-path explicit list lands with v0.2.
watch-refresh
(watch-refresh [watcher : int])
re-walk a tree-mode watcher's root and register any
watch-next
(watch-next [watcher : int timeout-ms : int])
block until the next event, return its handle or 0.
| watcher | handle from watch-open | |
| timeout-ms | -1 = forever, 0 = poll, N = bounded wait |
Event handle (free via watch-event-free), or 0 on timeout. Algorithm: 1. backend-wait(timeout-ms) 2. drain backend events; record overflow if any 3. sleep for debounce-ms (lets atomic-save bursts settle) 4. drain again 5. re-stat the target and classify the change 6. emit a watch-event for the classified kind
watch-drain
(watch-drain [watcher : int timeout-ms : int debounce-ms : int])
gather a debounced batch (see watch/debounce).
Internal definitions
__watcher-make-- internal: allocate a watcher record around a backend.__watcher-backend__watcher-dir__watcher-full-path__watcher-debounce-ms__watcher-sleep-ms-- sleep for ms milliseconds.__watcher-reclassify-- re-stat the target and return a kind value.__watcher-split-dir-- return malloc'd dir component of an absolute or__watcher-split-base-- return malloc'd basename component.__watcher-free-cstr-- release a string returned by the splitters.__watcher-path-is-dir?-- 1 if `path` exists and is a directory.__watcher-release-storage-- free strings + struct (without backend).__watcher-mode-- 0 for single-file, 1 for tree.__watcher-make-tree-- allocate an empty tree-mode watcher.__watcher-tree-add-dir-- register a directory with the tree watcher.__watcher-tree-walk-- recursively register all directories under root.__watcher-tree-poll-fired-- poll all backend fds for events.__watcher-tree-dir-backend-- the backend handle for the i-th dir.__tree-close-backends-- close every backend handle in a tree watcher.__watcher-tree-snap-init-- (re-)take a snapshot for every registered dir.__watcher-tree-root-- tree-mode root path (read-only borrow).__watcher-pending-push-- append an event to the tail of the pending queue.__watcher-pending-pop-- remove and return the oldest event (FIFO), or 0.__watcher-tree-mk-event-- build a watch-event for a tree-mode file hit.__watcher-tree-produce-events-- drain the fired backend and push__watch-next-single-- the single-file case.__watch-next-tree-- the recursive-tree case.__watch-make-cons-- internal: wrap a single event handle in a cons cell.