From daf58bd4dcd8a023e5fb6ffef7473387999f1c7c Mon Sep 17 00:00:00 2001 From: CJ van den Berg Date: Sun, 29 Mar 2026 18:02:33 +0200 Subject: [PATCH] docs: improve rename docs --- src/backend/KQueue.zig | 2 +- src/backend/KQueueDir.zig | 6 +++--- src/types.zig | 29 ++++++++++++++++------------- 3 files changed, 20 insertions(+), 17 deletions(-) diff --git a/src/backend/KQueue.zig b/src/backend/KQueue.zig index aeee5fd..b7e38b6 100644 --- a/src/backend/KQueue.zig +++ b/src/backend/KQueue.zig @@ -189,7 +189,7 @@ fn scan_dir(self: *@This(), allocator: std.mem.Allocator, dir_path: []const u8) var dir = std.fs.openDirAbsolute(dir_path, .{ .iterate = true }) catch return; defer dir.close(); - // Arena for all temporaries — freed in one shot at the end. + // Arena for all temporaries - freed in one shot at the end. var arena = std.heap.ArenaAllocator.init(allocator); defer arena.deinit(); const tmp = arena.allocator(); diff --git a/src/backend/KQueueDir.zig b/src/backend/KQueueDir.zig index 0cf816f..c1a8139 100644 --- a/src/backend/KQueueDir.zig +++ b/src/backend/KQueueDir.zig @@ -173,7 +173,7 @@ fn scan_dir(self: *@This(), allocator: std.mem.Allocator, dir_path: []const u8) var dir = std.fs.openDirAbsolute(dir_path, .{ .iterate = true }) catch return; defer dir.close(); - // Arena for all temporaries — freed in one shot at the end. + // Arena for all temporaries - freed in one shot at the end. var arena = std.heap.ArenaAllocator.init(allocator); defer arena.deinit(); const tmp = arena.allocator(); @@ -242,13 +242,13 @@ fn scan_dir(self: *@This(), allocator: std.mem.Allocator, dir_path: []const u8) var cit = current_files.iterator(); while (cit.next()) |entry| { if (snapshot.getPtr(entry.key_ptr.*)) |stored_mtime| { - // File exists in both — check for modification via mtime change. + // File exists in both - check for modification via mtime change. if (stored_mtime.* != entry.value_ptr.*) { stored_mtime.* = entry.value_ptr.*; try to_modify.append(tmp, entry.key_ptr.*); // from current_files (tmp) } } else { - // New file — add to snapshot and to_create list. + // New file - add to snapshot and to_create list. const owned = allocator.dupe(u8, entry.key_ptr.*) catch |e| { return e; }; diff --git a/src/types.zig b/src/types.zig index b3627ba..5af8794 100644 --- a/src/types.zig +++ b/src/types.zig @@ -18,22 +18,25 @@ pub const EventType = enum { /// /// Delivery varies by backend: /// - /// - **INotify**: renames within the watched tree are delivered as a - /// single atomic `rename` callback with both source and destination - /// paths. A move out of the tree appears as `deleted`; a move into - /// the tree appears as `created`. + /// - **INotify**: all watches share a single inotify file descriptor, so + /// moves are paired by cookie across all watched roots. Renames between + /// two watched directories - even separate watch roots on the same + /// watcher instance - are delivered as a single atomic `rename` + /// callback. A move out of all watched paths appears as `deleted`; a + /// move in from an unwatched path appears as `created`. + /// + /// - **Windows**: renames within a single watched root are delivered as a + /// single atomic `rename` callback. However, each root uses an + /// independent `ReadDirectoryChangesW` handle with no shared cookie, so + /// a move between two separately watched roots cannot be paired: it + /// appears as `deleted` on the source side and `created` on the + /// destination side. /// /// - **kqueue / kqueuedir**: when a watched *directory* is itself /// renamed, a `renamed` change event is emitted for the old directory /// path (the new path is not known). Renames of *files inside* a /// watched directory are detected indirectly via directory-level - /// `NOTE_WRITE` events and appear as a `deleted` event for the old - /// name followed by a `created` event for the new name. - /// - /// - **Windows**: renames within the watched tree are delivered as a - /// single atomic `rename` callback, matching INotify behaviour. A - /// move out of the tree appears as `deleted`; a move into the tree - /// appears as `created`. + /// `NOTE_WRITE` events and appear as `deleted` + `created`. /// /// - **FSEvents**: each path involved in a rename receives its own /// `renamed` change event; the two sides are not paired. @@ -61,9 +64,9 @@ pub const Error = error{ /// Selects how the watcher delivers events to the caller. /// -/// - `.threaded` — the backend spawns an internal thread that calls the +/// - `.threaded` - the backend spawns an internal thread that calls the /// handler directly. The caller just needs to keep the `Watcher` alive. -/// - `.polling` — no internal thread is created. The caller must poll +/// - `.polling` - no internal thread is created. The caller must poll /// `poll_fd()` for readability and call `handle_read_ready()` whenever /// data is available. Currently only supported on Linux (inotify). pub const InterfaceType = enum { polling, threaded };