neurocyte/nightwatch
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

build: allow selecting a backend at comptime instead of via a build flag

Browse source
This commit is contained in:
CJ van den Berg 2026-03-09 10:46:29 +01:00
parent 6930adae7f
commit aa4e2920dd
Signed by: neurocyte
GPG key ID: 8EB1E1BB660E3FB9
6 changed files with 457 additions and 372 deletions
Download patch file Download diff file Expand all files Collapse all files

16
build.zig
View file

@ -8,26 +8,12 @@ pub fn build(b: *std.Build) void {
break :blk b.option(
bool,
"macos_fsevents",
"Use the FSEvents backend on macOS instead of kqueue (requires Xcode frameworks)",
"Add the FSEvents backend on macOS (requires Xcode frameworks)",
) orelse false;
} else false;
const linux_read_thread = b.option(
bool,
"linux_read_thread",
"Use a background thread on Linux (like macOS/Windows) instead of requiring the caller to drive the event loop via poll_fd/handle_read_ready",
) orelse true;
const kqueue_dir_only = b.option(
bool,
"kqueue_dir_only",
"Use directory-only kqueue watches (lower fd usage, no real-time file modification detection). Default: false",
) orelse false;
const options = b.addOptions();
options.addOption(bool, "macos_fsevents", macos_fsevents);
options.addOption(bool, "linux_read_thread", linux_read_thread);
options.addOption(bool, "kqueue_dir_only", kqueue_dir_only);
const options_mod = options.createModule();
const mod = b.addModule("nightwatch", .{

45
src/backend/INotify.zig
View file

@ -1,12 +1,8 @@
const std = @import("std");
const build_options = @import("build_options");
const types = @import("../types.zig");
const Handler = types.Handler;
const EventType = types.EventType;
const ObjectType = types.ObjectType;
pub const watches_recursively = false;
pub const detects_file_modifications = true;
const InterfaceType = types.InterfaceType;
const PendingRename = struct {
cookie: u32,
@ -14,13 +10,28 @@ const PendingRename = struct {
object_type: ObjectType,
};
pub fn Create(comptime variant: InterfaceType) type {
return struct {
handler: *Handler,
inotify_fd: std.posix.fd_t,
watches: std.AutoHashMapUnmanaged(i32, []u8), // wd -> owned path
pending_renames: std.ArrayListUnmanaged(PendingRename),
// Used only in linux_read_thread mode:
stop_pipe: if (build_options.linux_read_thread) [2]std.posix.fd_t else void,
thread: if (build_options.linux_read_thread) ?std.Thread else void,
stop_pipe: switch (variant) {
.threaded => [2]std.posix.fd_t,
.polling => void,
},
thread: switch (variant) {
.threaded => ?std.Thread,
.polling => void,
},
pub const watches_recursively = false;
pub const detects_file_modifications = true;
const Handler = switch (variant) {
.threaded => types.Handler,
.polling => types.PollingHandler,
};
const IN = std.os.linux.IN;
@ -33,7 +44,8 @@ const in_flags: std.os.linux.O = .{ .NONBLOCK = true };
pub fn init(handler: *Handler) !@This() {
const inotify_fd = try std.posix.inotify_init1(@bitCast(in_flags));
errdefer std.posix.close(inotify_fd);
if (comptime build_options.linux_read_thread) {
switch (variant) {
.threaded => {
const stop_pipe = try std.posix.pipe();
return .{
.handler = handler,
@ -43,7 +55,8 @@ pub fn init(handler: *Handler) !@This() {
.stop_pipe = stop_pipe,
.thread = null,
};
} else {
},
.polling => {
return .{
.handler = handler,
.inotify_fd = inotify_fd,
@ -52,11 +65,12 @@ pub fn init(handler: *Handler) !@This() {
.stop_pipe = {},
.thread = {},
};
},
}
}
pub fn deinit(self: *@This(), allocator: std.mem.Allocator) void {
if (comptime build_options.linux_read_thread) {
if (comptime variant == .threaded) {
// Signal thread to stop and wait for it to exit.
_ = std.posix.write(self.stop_pipe[1], "x") catch {};
if (self.thread) |t| t.join();
@ -72,15 +86,18 @@ pub fn deinit(self: *@This(), allocator: std.mem.Allocator) void {
}
pub fn arm(self: *@This(), allocator: std.mem.Allocator) error{HandlerFailed}!void {
if (comptime build_options.linux_read_thread) {
switch (variant) {
.threaded => {
if (self.thread != null) return; // already running
self.thread = std.Thread.spawn(.{}, thread_fn, .{ self, allocator }) catch return error.HandlerFailed;
} else {
},
.polling => {
return switch (self.handler.wait_readable() catch |e| switch (e) {
error.HandlerFailed => |e_| return e_,
}) {
.will_notify => {},
};
},
}
}
@ -229,3 +246,5 @@ pub fn handle_read_ready(self: *@This(), allocator: std.mem.Allocator) (std.posi
}
}
}
};
}

8
src/main.zig
View file

@ -3,8 +3,9 @@ const builtin = @import("builtin");
const nightwatch = @import("nightwatch");
const is_posix = switch (builtin.os.tag) {
.linux, .macos, .freebsd => true,
else => false,
.linux, .macos, .freebsd, .openbsd, .netbsd, .dragonfly => true,
.windows => false,
else => @compileError("unsupported OS"),
};
// Self-pipe: signal handler writes a byte so poll() / read() unblocks cleanly.
@ -22,7 +23,6 @@ const CliHandler = struct {
const vtable = nightwatch.Handler.VTable{
.change = change_cb,
.rename = rename_cb,
.wait_readable = if (nightwatch.linux_poll_mode) wait_readable_cb else {},
};
fn change_cb(h: *nightwatch.Handler, path: []const u8, event_type: nightwatch.EventType, object_type: nightwatch.ObjectType) error{HandlerFailed}!void {
@ -215,7 +215,7 @@ pub fn main() !void {
.ignore = ignore_list.items,
};
var watcher = try nightwatch.init(allocator, &cli_handler.handler);
var watcher = try nightwatch.Default.init(allocator, &cli_handler.handler);
defer watcher.deinit();
for (watch_paths.items) |path| {

99
src/nightwatch.zig
View file

@ -7,25 +7,61 @@ pub const EventType = types.EventType;
pub const ObjectType = types.ObjectType;
pub const Error = types.Error;
pub const ReadableStatus = types.ReadableStatus;
pub const linux_poll_mode = types.linux_poll_mode;
pub const InterfaceType = types.InterfaceType;
pub const Handler = types.Handler;
pub const PollingHandler = types.PollingHandler;
pub const Variant = switch (builtin.os.tag) {
.linux => InterfaceType,
.macos => if (build_options.macos_fsevents) enum { fsevents, kqueue, kqueuedir } else enum { kqueue, kqueuedir },
.freebsd, .openbsd, .netbsd, .dragonfly => enum { kqueue, kqueuedir },
.windows => enum { windows },
else => @compileError("unsupported OS"),
};
pub const defaultVariant: Variant = switch (builtin.os.tag) {
.linux => .threaded,
.macos, .freebsd, .openbsd, .netbsd, .dragonfly => .kqueue,
.windows => .windows,
else => @compileError("unsupported OS"),
};
pub const Default: type = Create(defaultVariant);
pub fn Create(comptime variant: Variant) type {
return struct {
pub const Backend = switch (builtin.os.tag) {
.linux => @import("backend/INotify.zig").Create(variant),
.macos => if (build_options.macos_fsevents) switch (variant) {
.fsevents => @import("backend/FSEvents.zig"),
.kqueue => @import("backend/KQueue.zig"),
.kqueuedir => @import("backend/KQueueDir.zig"),
} else switch (variant) {
.kqueue => @import("backend/KQueue.zig"),
.kqueuedir => @import("backend/KQueueDir.zig"),
},
.freebsd, .openbsd, .netbsd, .dragonfly => switch (variant) {
.kqueue => @import("backend/KQueue.zig"),
.kqueuedir => @import("backend/KQueueDir.zig"),
},
.windows => switch (variant) {
.windows => @import("backend/Windows.zig"),
},
else => @compileError("unsupported OS"),
};
pub const interfaceType: InterfaceType = switch (builtin.os.tag) {
.linux => variant,
else => .threaded,
};
allocator: std.mem.Allocator,
interceptor: *Interceptor,
/// True if the current backend detects file content modifications in real time.
/// False only when kqueue_dir_only=true, where directory-level watches are used
/// and file writes do not trigger a directory NOTE_WRITE event.
pub const detects_file_modifications = Backend.detects_file_modifications;
const Backend = switch (builtin.os.tag) {
.linux => @import("backend/INotify.zig"),
.macos => if (build_options.macos_fsevents) @import("backend/FSEvents.zig") else if (build_options.kqueue_dir_only) @import("backend/KQueueDir.zig") else @import("backend/KQueue.zig"),
.freebsd, .openbsd, .netbsd, .dragonfly => if (build_options.kqueue_dir_only) @import("backend/KQueueDir.zig") else @import("backend/KQueue.zig"),
.windows => @import("backend/Windows.zig"),
else => @compileError("file_watcher: unsupported OS"),
};
allocator: std.mem.Allocator,
interceptor: *Interceptor,
pub fn init(allocator: std.mem.Allocator, handler: *Handler) !@This() {
const ic = try allocator.create(Interceptor);
errdefer allocator.destroy(ic);
@ -76,7 +112,7 @@ pub fn unwatch(self: *@This(), path: []const u8) void {
/// Drive event delivery by reading from the inotify fd.
/// Only available in Linux poll mode (linux_poll_mode == true).
pub fn handle_read_ready(self: *@This()) !void {
comptime if (!linux_poll_mode) @compileError("handle_read_ready is only available in Linux poll mode; use linux_read_thread=true for a background-thread model");
comptime if (@hasDecl(Backend, "polling") and Backend.polling) @compileError("handle_read_ready is only available in polling backends");
try self.interceptor.backend.handle_read_ready(self.allocator);
}
@ -84,7 +120,7 @@ pub fn handle_read_ready(self: *@This()) !void {
/// before calling handle_read_ready().
/// Only available in Linux poll mode (linux_poll_mode == true).
pub fn poll_fd(self: *const @This()) std.posix.fd_t {
comptime if (!linux_poll_mode) @compileError("poll_fd is only available in Linux poll mode; use linux_read_thread=true for a background-thread model");
comptime if (@hasDecl(Backend, "polling") and Backend.polling) @compileError("poll_fd is only available in polling backends");
return self.interceptor.backend.inotify_fd;
}
@ -101,7 +137,38 @@ const Interceptor = struct {
const vtable = Handler.VTable{
.change = change_cb,
.rename = rename_cb,
.wait_readable = if (linux_poll_mode) wait_readable_cb else {},
};
fn change_cb(h: *Handler, path: []const u8, event_type: EventType, object_type: ObjectType) error{HandlerFailed}!void {
const self: *Interceptor = @fieldParentPtr("handler", h);
if (event_type == .created and object_type == .dir and !Backend.watches_recursively) {
self.backend.add_watch(self.allocator, path) catch {};
recurse_watch(&self.backend, self.allocator, path);
}
return self.user_handler.change(path, event_type, object_type);
}
fn rename_cb(h: *Handler, src: []const u8, dst: []const u8, object_type: ObjectType) error{HandlerFailed}!void {
const self: *Interceptor = @fieldParentPtr("handler", h);
return self.user_handler.rename(src, dst, object_type);
}
fn wait_readable_cb(h: *Handler) error{HandlerFailed}!ReadableStatus {
const self: *Interceptor = @fieldParentPtr("handler", h);
return self.user_handler.wait_readable();
}
};
const PollingInterceptor = struct {
handler: PollingHandler,
user_handler: *PollingHandler,
allocator: std.mem.Allocator,
backend: Backend,
const vtable = PollingHandler.VTable{
.change = change_cb,
.rename = rename_cb,
.wait_readable = wait_readable_cb,
};
fn change_cb(h: *Handler, path: []const u8, event_type: EventType, object_type: ObjectType) error{HandlerFailed}!void {
@ -137,3 +204,5 @@ fn recurse_watch(backend: *Backend, allocator: std.mem.Allocator, dir_path: []co
recurse_watch(backend, allocator, sub);
}
}
};
}

18
src/nightwatch_test.zig
View file

@ -49,7 +49,6 @@ const TestHandler = struct {
const vtable = nw.Handler.VTable{
.change = change_cb,
.rename = rename_cb,
.wait_readable = if (nw.linux_poll_mode) wait_readable_cb else {},
};
fn change_cb(handler: *nw.Handler, path: []const u8, event_type: nw.EventType, object_type: nw.ObjectType) error{HandlerFailed}!void {
@ -135,7 +134,7 @@ const TestHandler = struct {
// ---------------------------------------------------------------------------
// Watcher type alias - nightwatch.zig is itself a struct type.
// ---------------------------------------------------------------------------
const Watcher = nw;
const Watcher = nw.Default;
// ---------------------------------------------------------------------------
// Test utilities
@ -178,13 +177,12 @@ fn removeTempDir(path: []const u8) void {
}
/// Drive event delivery:
/// - Linux: call handle_read_ready() so inotify events are processed.
/// - Others: the backend uses its own thread/callback; sleep briefly.
/// - polling watchers: call handle_read_ready() so events are processed.
/// - threaded watchers: the backend uses its own thread/callback; sleep briefly.
fn drainEvents(watcher: *Watcher) !void {
if (nw.linux_poll_mode) {
try watcher.handle_read_ready();
} else {
std.Thread.sleep(300 * std.time.ns_per_ms);
switch (Watcher.interfaceType) {
.polling => try watcher.handle_read_ready(),
.threaded => std.Thread.sleep(300 * std.time.ns_per_ms),
}
}
@ -223,7 +221,7 @@ test "creating a file emits a 'created' event" {
test "writing to a file emits a 'modified' event" {
// kqueue watches directories only; file writes don't trigger a directory event,
// so modifications are not reliably detectable in real time on this backend.
if (comptime !nw.detects_file_modifications) return error.SkipZigTest;
if (comptime !Watcher.detects_file_modifications) return error.SkipZigTest;
const allocator = std.testing.allocator;
@ -516,7 +514,7 @@ test "rename-then-modify: rename event precedes the subsequent modify event" {
// After renaming a file, a write to the new name should produce events in
// the order [rename/old-name, rename/new-name, modify] so that a consumer
// always knows the current identity of the file before seeing changes to it.
if (comptime !nw.detects_file_modifications) return error.SkipZigTest;
if (comptime !Watcher.detects_file_modifications) return error.SkipZigTest;
const allocator = std.testing.allocator;

43
src/types.zig
View file

@ -1,6 +1,5 @@
const std = @import("std");
const builtin = @import("builtin");
const build_options = @import("build_options");
pub const EventType = enum {
created,
@ -25,14 +24,9 @@ pub const Error = error{
WatchFailed,
};
/// True when the Linux inotify backend runs in poll mode (caller drives the
/// event loop via poll_fd / handle_read_ready). False on all other platforms
/// and on Linux when the `linux_read_thread` build option is set.
pub const linux_poll_mode = builtin.os.tag == .linux and !build_options.linux_read_thread;
pub const ReadableStatus = enum {
// TODO: is_readable, // backend may now read from fd (blocking mode)
will_notify, // backend must wait for a handle_read_ready call
pub const InterfaceType = enum {
polling,
threaded,
};
pub const Handler = struct {
@ -41,8 +35,31 @@ pub const Handler = struct {
pub const VTable = struct {
change: *const fn (handler: *Handler, path: []const u8, event_type: EventType, object_type: ObjectType) error{HandlerFailed}!void,
rename: *const fn (handler: *Handler, src_path: []const u8, dst_path: []const u8, object_type: ObjectType) error{HandlerFailed}!void,
/// Only present in Linux poll mode (linux_poll_mode == true).
wait_readable: if (linux_poll_mode) *const fn (handler: *Handler) error{HandlerFailed}!ReadableStatus else void,
};
pub fn change(handler: *Handler, path: []const u8, event_type: EventType, object_type: ObjectType) error{HandlerFailed}!void {
return handler.vtable.change(handler, path, event_type, object_type);
}
pub fn rename(handler: *Handler, src_path: []const u8, dst_path: []const u8, object_type: ObjectType) error{HandlerFailed}!void {
return handler.vtable.rename(handler, src_path, dst_path, object_type);
}
};
/// Used only by the inotify backend in poll mode (caller drives the event
/// loop via poll_fd / handle_read_ready)
pub const PollingHandler = struct {
vtable: *const VTable,
pub const ReadableStatus = enum {
// TODO: is_readable, // backend may now read from fd (blocking mode)
will_notify, // backend must wait for a handle_read_ready call
};
pub const VTable = struct {
change: *const fn (handler: *Handler, path: []const u8, event_type: EventType, object_type: ObjectType) error{HandlerFailed}!void,
rename: *const fn (handler: *Handler, src_path: []const u8, dst_path: []const u8, object_type: ObjectType) error{HandlerFailed}!void,
wait_readable: *const fn (handler: *Handler) error{HandlerFailed}!ReadableStatus,
};
pub fn change(handler: *Handler, path: []const u8, event_type: EventType, object_type: ObjectType) error{HandlerFailed}!void {
@ -54,10 +71,6 @@ pub const Handler = struct {
}
pub fn wait_readable(handler: *Handler) error{HandlerFailed}!ReadableStatus {
if (comptime linux_poll_mode) {
return handler.vtable.wait_readable(handler);
} else {
unreachable;
}
}
};