remove usingnamespace from main.zig

This should be 100% API compatible, and I wrote a comptime test to help
ensure that. Still, I suppose something could slip through.

The major churn in this PR is to avoid a circular dependency when
verifying that the API didn't change. We remove the dependency on
main.zig from the backends, which is cleaner in general, but it makes
for a big diff.

Author: mitchellh

docs/xev-zig.7.scd

@@ -17,10 +17,7 @@ over the C API. For example, all callbacks in the Zig API must be available
 at comptime because the callback call is always inlined -- this results in
 a noticable performance improvement over equivalent C consumption of libxev.
 
-The primary Zig API is visible in `src/main.zig` in the libxev source. The main file uses a somewhat convoluted `usingnamespace` to setup the
-API so it isn't immediately obvious, but the API is provided by the `Xev`
-function. For example, available consts are: `xev.Loop`, `xev.Completion`,
-etc.
+The primary Zig API is visible in `src/main.zig` in the libxev source. 
 
 # INSTALLATION
 

src/api.zig

@@ -0,0 +1,88 @@
+const builtin = @import("builtin");
+const stream = @import("watcher/stream.zig");
+const Backend = @import("backend.zig").Backend;
+
+/// Creates the Xev API based on a backend type.
+///
+/// For the default backend type for your system (i.e. io_uring on Linux),
+/// this is the main API you interact with. It is forwarded into the main
+/// the "xev" package so you'd use types such as `xev.Loop`, `xev.Completion`,
+/// etc.
+///
+/// Unless you're using a custom or specific backend type, you do NOT ever
+/// need to call the Xev function itself.
+pub fn Xev(comptime be: Backend, comptime T: type) type {
+    return struct {
+        const Self = @This();
+        const loop = @import("loop.zig");
+
+        /// This is used to detect a static vs dynamic API at comptime.
+        pub const dynamic = false;
+
+        /// The backend that this is. This is supplied at comptime so
+        /// it is up to the caller to say the right thing. This lets custom
+        /// implementations also "quack" like an implementation.
+        pub const backend = be;
+
+        /// A function to test if this API is available on the
+        /// current system.
+        pub const available = T.available;
+
+        /// The core loop APIs.
+        pub const Loop = T.Loop;
+        pub const Completion = T.Completion;
+        pub const Result = T.Result;
+        pub const ReadBuffer = T.ReadBuffer;
+        pub const WriteBuffer = T.WriteBuffer;
+        pub const Options = loop.Options;
+        pub const RunMode = loop.RunMode;
+        pub const CallbackAction = loop.CallbackAction;
+        pub const CompletionState = loop.CompletionState;
+
+        /// Error types
+        pub const AcceptError = T.AcceptError;
+        pub const CancelError = T.CancelError;
+        pub const CloseError = T.CloseError;
+        pub const ConnectError = T.ConnectError;
+        pub const ShutdownError = T.ShutdownError;
+        pub const WriteError = T.WriteError;
+        pub const ReadError = T.ReadError;
+
+        /// Shared stream types
+        const SharedStream = stream.Shared(Self);
+        pub const PollError = SharedStream.PollError;
+        pub const PollEvent = SharedStream.PollEvent;
+        pub const WriteQueue = SharedStream.WriteQueue;
+        pub const WriteRequest = SharedStream.WriteRequest;
+
+        /// The high-level helper interfaces that make it easier to perform
+        /// common tasks. These may not work with all possible Loop implementations.
+        pub const Async = @import("watcher/async.zig").Async(Self);
+        pub const File = @import("watcher/file.zig").File(Self);
+        pub const Process = @import("watcher/process.zig").Process(Self);
+        pub const Stream = stream.GenericStream(Self);
+        pub const Timer = @import("watcher/timer.zig").Timer(Self);
+        pub const TCP = @import("watcher/tcp.zig").TCP(Self);
+        pub const UDP = @import("watcher/udp.zig").UDP(Self);
+
+        /// The callback of the main Loop operations. Higher level interfaces may
+        /// use a different callback mechanism.
+        pub const Callback = loop.Callback(T);
+
+        /// A callback that does nothing and immediately disarms. This
+        /// implements xev.Callback and is the default value for completions.
+        pub const noopCallback = loop.NoopCallback(T);
+
+        /// A way to access the raw type.
+        pub const Sys = T;
+
+        test {
+            @import("std").testing.refAllDecls(@This());
+        }
+
+        test "completion is zero-able" {
+            const c: Self.Completion = .{};
+            _ = c;
+        }
+    };
+}

src/backend.zig

@@ -0,0 +1,52 @@
+const builtin = @import("builtin");
+const stream = @import("watcher/stream.zig");
+
+/// The backend types.
+pub const Backend = enum {
+    io_uring,
+    epoll,
+    kqueue,
+    wasi_poll,
+    iocp,
+
+    /// Returns a recommend default backend from inspecting the system.
+    pub fn default() Backend {
+        return switch (builtin.os.tag) {
+            .linux => .io_uring,
+            .ios, .macos => .kqueue,
+            .freebsd => .kqueue,
+            .wasi => .wasi_poll,
+            .windows => .iocp,
+            else => {
+                @compileLog(builtin.os);
+                @compileError("no default backend for this target");
+            },
+        };
+    }
+
+    /// Candidate backends for this platform in priority order.
+    pub fn candidates() []const Backend {
+        return switch (builtin.os.tag) {
+            .linux => &.{ .io_uring, .epoll },
+            .ios, .macos => &.{.kqueue},
+            .freebsd => &.{.kqueue},
+            .wasi => &.{.wasi_poll},
+            .windows => &.{.iocp},
+            else => {
+                @compileLog(builtin.os);
+                @compileError("no candidate backends for this target");
+            },
+        };
+    }
+
+    /// Returns the Api (return value of Xev) for the given backend type.
+    pub fn Api(comptime self: Backend) type {
+        return switch (self) {
+            .io_uring => @import("main.zig").IO_Uring,
+            .epoll => @import("main.zig").Epoll,
+            .kqueue => @import("main.zig").Kqueue,
+            .wasi_poll => @import("main.zig").WasiPoll,
+            .iocp => @import("main.zig").IOCP,
+        };
+    }
+};