hesela.devWatchman clock
A Watchman clock is an opaque position in a watched root's observed change history used to request subsequent changes.
Continuity: a since query can report is_fresh_instance when its prior history is no longer usable. Default fresh results include currently existing matching files, not old deletion records. With empty_on_fresh_instance, the list is deliberately empty; the flag still signals lost continuity. [1]
Consumer state: applying a fresh baseline as an ordinary delta can retain deleted names. A controlled Watchman 4.9.0 root-reset experiment reproduced this; replacing the complete queried scope recovered membership in a quiescent fixture. This is name-index recovery, not a file-content snapshot. [4]
Acknowledgement: named cursors advance on query and cannot be rolled back. Explicit clocks allow retry from an earlier observation position while history remains valid. Committing a cursor before applying its results can make a subsequent empty response hide unprocessed changes. [2] [4]
Synchronization: a clock call without sync_timeout can precede pending filesystem notifications. A synchronization cookie improves observation freshness but does not freeze application writes. [3]
Selection: retain the query scope with the client index and clock. In a separate 18-execution quiescent test, broadening a suffix filter missed an unchanged name and narrowing retained an excluded name, despite empty non-fresh responses. A full query under the new selection recovered exact membership. [5] [4]
Relations
Advantages
- Allows clients to resume change queries from an explicit observation position.
Limitations
- Retained change history and the consumer's committed index must remain consistent.
Citations
- Watchman query: fresh instances and synchronization
- Watchman clockspec: explicit clocks and named cursors
- Watchman clock: synchronization option
- Hesela: change-history continuity and client index recovery
- Watchman File Queries: generators and expressions
Sources & caveats
- Documentation synthesis and controlled native observations on Ubuntu's Watchman 4.9.0-7build4 package.
- The experiment does not measure a current release, overflow, automatic recrawl, history aging or backup completeness.