tigerbeetle-node 0.5.2 → 0.8.1

package/src/tigerbeetle/src/{demo_04_create_transfers_two_phase_commit.zig → demo_04_create_pending_transfers.zig}

@@ -12,42 +12,48 @@ pub fn main() !void {
             .debit_account_id = 1,
             .credit_account_id = 2,
             .user_data = 0,
-            .reserved = [_]u8{0} ** 32,
+            .reserved = 0,
+            .pending_id = 0,
             .timeout = std.time.ns_per_hour,
-            .code = 0,
+            .ledger = 710,
+            .code = 1,
             .flags = .{
-                .two_phase_commit = true,
+                .pending = true, // Set this transfer to be two-phase.
             },
-            .amount = 9000,
+            .amount = 8000,
         },
         Transfer{
             .id = 1002,
             .debit_account_id = 1,
             .credit_account_id = 2,
             .user_data = 0,
-            .reserved = [_]u8{0} ** 32,
+            .reserved = 0,
+            .pending_id = 0,
             .timeout = std.time.ns_per_hour,
-            .code = 0,
+            .ledger = 710,
+            .code = 1,
             .flags = .{
-                .two_phase_commit = true,
+                .pending = true, // Set this transfer to be two-phase.
                 .linked = true, // Link this transfer with the next transfer 1003.
             },
-            .amount = 1,
+            .amount = 500,
         },
         Transfer{
             .id = 1003,
             .debit_account_id = 1,
             .credit_account_id = 2,
             .user_data = 0,
-            .reserved = [_]u8{0} ** 32,
+            .reserved = 0,
+            .pending_id = 0,
             .timeout = std.time.ns_per_hour,
-            .code = 0,
+            .ledger = 710,
+            .code = 1,
             .flags = .{
-                .two_phase_commit = true,
+                .pending = true, // Set this transfer to be two-phase.
                 // The last transfer in a linked chain has .linked set to false to close the chain.
                 // This transfer will succeed or fail together with transfer 1002 above.
             },
-            .amount = 1,
+            .amount = 500,
         },
     };
 

package/src/tigerbeetle/src/demo_05_post_pending_transfers.zig

@@ -0,0 +1,37 @@
+const tb = @import("tigerbeetle.zig");
+const demo = @import("demo.zig");
+
+const Transfer = tb.Transfer;
+
+pub fn main() !void {
+    const commits = [_]Transfer{
+        Transfer{
+            .id = 2001,
+            .debit_account_id = 1,
+            .credit_account_id = 2,
+            .user_data = 0,
+            .reserved = 0,
+            .pending_id = 1001,
+            .timeout = 0,
+            .ledger = 0,// Honor original Transfer ledger.
+            .code = 0,// Honor original Transfer code.
+            .flags = .{ .post_pending_transfer = true }, // Post the pending two-phase transfer.
+            .amount = 0, // Inherit the amount from the pending transfer.
+        },
+        Transfer{
+            .id = 2002,
+            .debit_account_id = 1,
+            .credit_account_id = 2,
+            .user_data = 0,
+            .reserved = 0,
+            .pending_id = 1002,
+            .timeout = 0,
+            .ledger = 0,
+            .code = 0,
+            .flags = .{ .post_pending_transfer = true }, // Post the pending two-phase transfer.
+            .amount = 0, // Inherit the amount from the pending transfer.
+        },
+    };
+
+    try demo.request(.create_transfers, commits, demo.on_create_transfers);
+}

package/src/tigerbeetle/src/demo_06_void_pending_transfers.zig

@@ -0,0 +1,24 @@
+const tb = @import("tigerbeetle.zig");
+const demo = @import("demo.zig");
+
+const Transfer = tb.Transfer;
+
+pub fn main() !void {
+    const commits = [_]Transfer{
+        Transfer{
+            .id = 2003,
+            .debit_account_id = 1,
+            .credit_account_id = 2,
+            .user_data = 0,
+            .reserved = 0,
+            .pending_id = 1003,
+            .timeout = 0,
+            .ledger = 0,
+            .code = 0,
+            .flags = .{ .void_pending_transfer = true },
+            .amount = 0,
+        },
+    };
+
+    try demo.request(.create_transfers, commits, demo.on_create_transfers);
+}

package/src/tigerbeetle/src/demo_07_lookup_transfers.zig

@@ -1,7 +1,7 @@
 const demo = @import("demo.zig");
 
 pub fn main() !void {
-    const ids = [_]u128{ 1000, 1001, 1002 };
+    const ids = [_]u128{ 1, 1001, 1002, 1003, 2001, 2002, 2003 };
 
     try demo.request(.lookup_transfers, ids, demo.on_lookup_transfers);
 }

package/src/tigerbeetle/src/io/benchmark.zig

@@ -1,6 +1,7 @@
 const std = @import("std");
 const os = std.os;
 const assert = std.debug.assert;
+const log = std.log.scoped(.io_benchmark);
 
 const Time = @import("../time.zig").Time;
 const IO = @import("../io.zig").IO;
@@ -14,7 +15,7 @@ const run_duration = 1 * std.time.ns_per_s;
 
 pub fn main() !void {
     var gpa = std.heap.GeneralPurposeAllocator(.{}){};
-    const allocator = &gpa.allocator;
+    const allocator = gpa.allocator();
     defer {
         const leaks = gpa.deinit();
         assert(!leaks);
@@ -24,37 +25,34 @@ pub fn main() !void {
     defer allocator.free(buffer);
     std.mem.set(u8, buffer, 0);
 
-    var timer = Time{};
-    const started = timer.monotonic();
     var self = Context{
         .io = try IO.init(32, 0),
-        .timer = &timer,
-        .started = started,
-        .current = started,
         .tx = .{ .buffer = buffer[0 * buffer_size ..][0..buffer_size] },
         .rx = .{ .buffer = buffer[1 * buffer_size ..][0..buffer_size] },
     };
+    defer self.io.deinit();
 
+    var timer = Time{};
+    const started = timer.monotonic();
     defer {
-        self.io.deinit();
-        const elapsed_ns = self.current - started;
+        const elapsed_ns = timer.monotonic() - started;
         const transferred_mb = @intToFloat(f64, self.transferred) / 1024 / 1024;
 
-        std.debug.print("IO throughput test: took {}ms @ {d:.2} MB/s\n", .{
+        log.info("took {}ms @ {d:.2} MB/s\n", .{
             elapsed_ns / std.time.ns_per_ms,
             transferred_mb / (@intToFloat(f64, elapsed_ns) / std.time.ns_per_s),
         });
     }
 
     // Setup the server socket
-    self.server.fd = try IO.openSocket(os.AF_INET, os.SOCK_STREAM, os.IPPROTO_TCP);
+    self.server.fd = try self.io.open_socket(os.AF.INET, os.SOCK.STREAM, os.IPPROTO.TCP);
     defer os.closeSocket(self.server.fd);
 
     const address = try std.net.Address.parseIp4("127.0.0.1", 3131);
     try os.setsockopt(
         self.server.fd,
-        os.SOL_SOCKET,
-        os.SO_REUSEADDR,
+        os.SOL.SOCKET,
+        os.SO.REUSEADDR,
         &std.mem.toBytes(@as(c_int, 1)),
     );
     try os.bind(self.server.fd, &address.any, address.getOsSockLen());
@@ -70,7 +68,7 @@ pub fn main() !void {
     );
 
     // Setup the client connection
-    self.tx.socket.fd = try IO.openSocket(os.AF_INET, os.SOCK_STREAM, os.IPPROTO_TCP);
+    self.tx.socket.fd = try self.io.open_socket(os.AF.INET, os.SOCK.STREAM, os.IPPROTO.TCP);
     defer os.closeSocket(self.tx.socket.fd);
 
     self.io.connect(
@@ -82,22 +80,14 @@ pub fn main() !void {
         address,
     );
 
-    // Run the IO loop, calling either tick() or run_for_ns() at "pseudo-random"
-    // to benchmark each io-driving execution path
-    var tick: usize = 0xdeadbeef;
-    while (self.is_running()) : (tick +%= 1) {
-        if (tick % 61 == 0) {
-            const timeout_ns = tick % (10 * std.time.ns_per_ms);
-            try self.io.run_for_ns(@intCast(u63, timeout_ns));
-        } else {
-            try self.io.tick();
-        }
-    }
+    // Run the IO loop for the duration of the benchmark
+    log.info("running for {}", .{std.fmt.fmtDuration(run_duration)});
+    try self.io.run_for_ns(run_duration);
 
     // Assert that everything is connected
-    assert(self.server.fd != -1);
-    assert(self.tx.socket.fd != -1);
-    assert(self.rx.socket.fd != -1);
+    assert(self.server.fd != IO.INVALID_SOCKET);
+    assert(self.tx.socket.fd != IO.INVALID_SOCKET);
+    assert(self.rx.socket.fd != IO.INVALID_SOCKET);
 
     // Close the accepted client socket.
     // The actual client socket + server socket are closed by defer
@@ -108,14 +98,11 @@ const Context = struct {
     io: IO,
     tx: Pipe,
     rx: Pipe,
-    timer: *Time,
-    started: u64,
-    current: u64,
     server: Socket = .{},
     transferred: u64 = 0,
 
     const Socket = struct {
-        fd: os.socket_t = -1,
+        fd: os.socket_t = IO.INVALID_SOCKET,
         completion: IO.Completion = undefined,
     };
     const Pipe = struct {
@@ -124,21 +111,12 @@ const Context = struct {
         transferred: usize = 0,
     };
 
-    fn is_running(self: Context) bool {
-        // Make sure that we're connected
-        if (self.rx.socket.fd == -1) return true;
-
-        // Make sure that we haven't run too long as configured
-        const elapsed = self.current - self.started;
-        return elapsed < run_duration;
-    }
-
     fn on_accept(
         self: *Context,
         completion: *IO.Completion,
         result: IO.AcceptError!os.socket_t,
     ) void {
-        assert(self.rx.socket.fd == -1);
+        assert(self.rx.socket.fd == IO.INVALID_SOCKET);
         assert(&self.server.completion == completion);
         self.rx.socket.fd = result catch |err| std.debug.panic("accept error {}", .{err});
 
@@ -152,7 +130,9 @@ const Context = struct {
         completion: *IO.Completion,
         result: IO.ConnectError!void,
     ) void {
-        assert(self.tx.socket.fd != -1);
+        _ = result catch unreachable;
+
+        assert(self.tx.socket.fd != IO.INVALID_SOCKET);
         assert(&self.tx.socket.completion == completion);
 
         // Start sending data to the server's accepted client
@@ -161,8 +141,8 @@ const Context = struct {
     }
 
     const TransferType = enum {
-        read = 0,
-        write = 1,
+        read,
+        write,
     };
 
     fn do_transfer(
@@ -188,11 +168,6 @@ const Context = struct {
         assert(bytes <= buffer_size);
         self.transferred += bytes;
 
-        // Check in with the benchmark timer to stop sending/receiving data
-        self.current = self.timer.monotonic();
-        if (!self.is_running())
-            return;
-
         // Select which connection (tx or rx) depending on the type of transfer
         const pipe = &@field(self, pipe_name);
         pipe.transferred += bytes;

package/src/tigerbeetle/src/io/darwin.zig

@@ -2,7 +2,9 @@ const std = @import("std");
 const os = std.os;
 const mem = std.mem;
 const assert = std.debug.assert;
+const log = std.log.scoped(.io);
 
+const config = @import("../config.zig");
 const FIFO = @import("../fifo.zig").FIFO;
 const Time = @import("../time.zig").Time;
 const buffer_limit = @import("../io.zig").buffer_limit;
@@ -204,9 +206,6 @@ pub const IO = struct {
             address: std.net.Address,
             initiated: bool,
         },
-        fsync: struct {
-            fd: os.fd_t,
-        },
         read: struct {
             fd: os.fd_t,
             buf: [*]u8,
@@ -248,7 +247,7 @@ pub const IO = struct {
             fn onComplete(io: *IO, _completion: *Completion) void {
                 // Perform the actual operaton
                 const op_data = &@field(_completion.operation, @tagName(operation_tag));
-                const result = OperationImpl.doOperation(op_data);
+                const result = OperationImpl.do_operation(op_data);
 
                 // Requeue onto io_pending if error.WouldBlock
                 switch (operation_tag) {
@@ -310,7 +309,7 @@ pub const IO = struct {
                 .socket = socket,
             },
             struct {
-                fn doOperation(op: anytype) AcceptError!os.socket_t {
+                fn do_operation(op: anytype) AcceptError!os.socket_t {
                     const fd = try os.accept(
                         op.socket,
                         null,
@@ -368,7 +367,7 @@ pub const IO = struct {
                 .fd = fd,
             },
             struct {
-                fn doOperation(op: anytype) CloseError!void {
+                fn do_operation(op: anytype) CloseError!void {
                     return switch (os.errno(os.system.close(op.fd))) {
                         .SUCCESS => {},
                         .BADF => error.FileDescriptorInvalid,
@@ -407,7 +406,7 @@ pub const IO = struct {
                 .initiated = false,
             },
             struct {
-                fn doOperation(op: anytype) ConnectError!void {
+                fn do_operation(op: anytype) ConnectError!void {
                     // Don't call connect after being rescheduled by io_pending as it gives EISCONN.
                     // Instead, check the socket error to see if has been connected successfully.
                     const result = switch (op.initiated) {
@@ -422,36 +421,6 @@ pub const IO = struct {
         );
     }
 
-    pub const FsyncError = os.SyncError;
-
-    pub fn fsync(
-        self: *IO,
-        comptime Context: type,
-        context: Context,
-        comptime callback: fn (
-            context: Context,
-            completion: *Completion,
-            result: FsyncError!void,
-        ) void,
-        completion: *Completion,
-        fd: os.fd_t,
-    ) void {
-        self.submit(
-            context,
-            callback,
-            completion,
-            .fsync,
-            .{
-                .fd = fd,
-            },
-            struct {
-                fn doOperation(op: anytype) FsyncError!void {
-                    _ = os.fcntl(op.fd, os.F.FULLFSYNC, 1) catch return os.fsync(op.fd);
-                }
-            },
-        );
-    }
-
     pub const ReadError = error{
         WouldBlock,
         NotOpenForReading,
@@ -489,7 +458,7 @@ pub const IO = struct {
                 .offset = offset,
             },
             struct {
-                fn doOperation(op: anytype) ReadError!usize {
+                fn do_operation(op: anytype) ReadError!usize {
                     while (true) {
                         const rc = os.system.pread(
                             op.fd,
@@ -546,7 +515,7 @@ pub const IO = struct {
                 .len = @intCast(u32, buffer_limit(buffer.len)),
             },
             struct {
-                fn doOperation(op: anytype) RecvError!usize {
+                fn do_operation(op: anytype) RecvError!usize {
                     return os.recv(op.socket, op.buf[0..op.len], 0);
                 }
             },
@@ -579,7 +548,7 @@ pub const IO = struct {
                 .len = @intCast(u32, buffer_limit(buffer.len)),
             },
             struct {
-                fn doOperation(op: anytype) SendError!usize {
+                fn do_operation(op: anytype) SendError!usize {
                     return os.send(op.socket, op.buf[0..op.len], 0);
                 }
             },
@@ -609,7 +578,7 @@ pub const IO = struct {
                 .expires = self.time.monotonic() + nanoseconds,
             },
             struct {
-                fn doOperation(_: anytype) TimeoutError!void {
+                fn do_operation(_: anytype) TimeoutError!void {
                     return; // timeouts don't have errors for now
                 }
             },
@@ -644,19 +613,181 @@ pub const IO = struct {
                 .offset = offset,
             },
             struct {
-                fn doOperation(op: anytype) WriteError!usize {
+                fn do_operation(op: anytype) WriteError!usize {
                     return os.pwrite(op.fd, op.buf[0..op.len], op.offset);
                 }
             },
         );
     }
 
-    pub fn openSocket(family: u32, sock_type: u32, protocol: u32) !os.socket_t {
+    pub const INVALID_SOCKET = -1;
+
+    /// Creates a socket that can be used for async operations with the IO instance.
+    pub fn open_socket(self: *IO, family: u32, sock_type: u32, protocol: u32) !os.socket_t {
+        _ = self;
+
         const fd = try os.socket(family, sock_type | os.SOCK.NONBLOCK, protocol);
-        errdefer os.close(fd);
+        errdefer os.closeSocket(fd);
 
         // darwin doesn't support os.MSG_NOSIGNAL, but instead a socket option to avoid SIGPIPE.
         try os.setsockopt(fd, os.SOL.SOCKET, os.SO.NOSIGPIPE, &mem.toBytes(@as(c_int, 1)));
         return fd;
     }
+
+    /// Opens a directory with read only access.
+    pub fn open_dir(dir_path: [:0]const u8) !os.fd_t {
+        return os.openZ(dir_path, os.O.CLOEXEC | os.O.RDONLY, 0);
+    }
+
+    /// Opens or creates a journal file:
+    /// - For reading and writing.
+    /// - For Direct I/O (required on darwin).
+    /// - Obtains an advisory exclusive lock to the file descriptor.
+    /// - Allocates the file contiguously on disk if this is supported by the file system.
+    /// - Ensures that the file data (and file inode in the parent directory) is durable on disk.
+    ///   The caller is responsible for ensuring that the parent directory inode is durable.
+    /// - Verifies that the file size matches the expected file size before returning.
+    pub fn open_file(
+        self: *IO,
+        dir_fd: os.fd_t,
+        relative_path: [:0]const u8,
+        size: u64,
+        must_create: bool,
+    ) !os.fd_t {
+        _ = self;
+
+        assert(relative_path.len > 0);
+        assert(size >= config.sector_size);
+        assert(size % config.sector_size == 0);
+
+        // TODO Use O_EXCL when opening as a block device to obtain a mandatory exclusive lock.
+        // This is much stronger than an advisory exclusive lock, and is required on some platforms.
+
+        // Opening with O_DSYNC is essential for both durability and correctness.
+        // O_DSYNC enables us to omit fsync() calls in the data plane, since we sync to the disk on every write.
+        var flags: u32 = os.O.CLOEXEC | os.O.RDWR | os.O.DSYNC;
+        var mode: os.mode_t = 0;
+
+        // TODO Document this and investigate whether this is in fact correct to set here.
+        if (@hasDecl(os.O, "LARGEFILE")) flags |= os.O.LARGEFILE;
+
+        if (must_create) {
+            log.info("creating \"{s}\"...", .{relative_path});
+            flags |= os.O.CREAT;
+            flags |= os.O.EXCL;
+            mode = 0o666;
+        } else {
+            log.info("opening \"{s}\"...", .{relative_path});
+        }
+
+        // This is critical as we rely on O_DSYNC for fsync() whenever we write to the file:
+        assert((flags & os.O.DSYNC) > 0);
+
+        // Be careful with openat(2): "If pathname is absolute, then dirfd is ignored." (man page)
+        assert(!std.fs.path.isAbsolute(relative_path));
+        const fd = try os.openatZ(dir_fd, relative_path, flags, mode);
+        // TODO Return a proper error message when the path exists or does not exist (init/start).
+        errdefer os.close(fd);
+
+        // TODO Check that the file is actually a file.
+
+        // On darwin assume that Direct I/O is always supported.
+        // Use F_NOCACHE to disable the page cache as O_DIRECT doesn't exist.
+        if (config.direct_io) {
+            _ = try os.fcntl(fd, os.F.NOCACHE, 1);
+        }
+
+        // Obtain an advisory exclusive lock that works only if all processes actually use flock().
+        // LOCK_NB means that we want to fail the lock without waiting if another process has it.
+        os.flock(fd, os.LOCK.EX | os.LOCK.NB) catch |err| switch (err) {
+            error.WouldBlock => @panic("another process holds the data file lock"),
+            else => return err,
+        };
+
+        // Ask the file system to allocate contiguous sectors for the file (if possible):
+        // If the file system does not support `fallocate()`, then this could mean more seeks or a
+        // panic if we run out of disk space (ENOSPC).
+        if (must_create) try fs_allocate(fd, size);
+
+        // The best fsync strategy is always to fsync before reading because this prevents us from
+        // making decisions on data that was never durably written by a previously crashed process.
+        // We therefore always fsync when we open the path, also to wait for any pending O_DSYNC.
+        // Thanks to Alex Miller from FoundationDB for diving into our source and pointing this out.
+        try fs_sync(fd);
+
+        // We fsync the parent directory to ensure that the file inode is durably written.
+        // The caller is responsible for the parent directory inode stored under the grandparent.
+        // We always do this when opening because we don't know if this was done before crashing.
+        try fs_sync(dir_fd);
+
+        const stat = try os.fstat(fd);
+        if (stat.size != size) @panic("data file inode size was truncated or corrupted");
+
+        return fd;
+    }
+
+    /// Darwin's fsync() syscall does not flush past the disk cache. We must use F_FULLFSYNC instead.
+    /// https://twitter.com/TigerBeetleDB/status/1422491736224436225
+    fn fs_sync(fd: os.fd_t) !void {
+        _ = os.fcntl(fd, os.F.FULLFSYNC, 1) catch return os.fsync(fd);
+    }
+
+    /// Allocates a file contiguously using fallocate() if supported.
+    /// Alternatively, writes to the last sector so that at least the file size is correct.
+    fn fs_allocate(fd: os.fd_t, size: u64) !void {
+        log.info("allocating {}...", .{std.fmt.fmtIntSizeBin(size)});
+
+        // Darwin doesn't have fallocate() but we can simulate it using fcntl()s.
+        //
+        // https://stackoverflow.com/a/11497568
+        // https://api.kde.org/frameworks/kcoreaddons/html/posix__fallocate__mac_8h_source.html
+        // http://hg.mozilla.org/mozilla-central/file/3d846420a907/xpcom/glue/FileUtils.cpp#l61
+
+        const F_ALLOCATECONTIG = 0x2; // Allocate contiguous space.
+        const F_ALLOCATEALL = 0x4; // Allocate all or nothing.
+        const F_PEOFPOSMODE = 3; // Use relative offset from the seek pos mode.
+        const fstore_t = extern struct {
+            fst_flags: c_uint,
+            fst_posmode: c_int,
+            fst_offset: os.off_t,
+            fst_length: os.off_t,
+            fst_bytesalloc: os.off_t,
+        };
+
+        var store = fstore_t{
+            .fst_flags = F_ALLOCATECONTIG | F_ALLOCATEALL,
+            .fst_posmode = F_PEOFPOSMODE,
+            .fst_offset = 0,
+            .fst_length = @intCast(os.off_t, size),
+            .fst_bytesalloc = 0,
+        };
+
+        // Try to pre-allocate contiguous space and fall back to default non-contiguous.
+        var res = os.system.fcntl(fd, os.F.PREALLOCATE, @ptrToInt(&store));
+        if (os.errno(res) != .SUCCESS) {
+            store.fst_flags = F_ALLOCATEALL;
+            res = os.system.fcntl(fd, os.F.PREALLOCATE, @ptrToInt(&store));
+        }
+
+        switch (os.errno(res)) {
+            .SUCCESS => {},
+            .ACCES => unreachable, // F_SETLK or F_SETSIZE of F_WRITEBOOTSTRAP
+            .BADF => return error.FileDescriptorInvalid,
+            .DEADLK => unreachable, // F_SETLKW
+            .INTR => unreachable, // F_SETLKW
+            .INVAL => return error.ArgumentsInvalid, // for F_PREALLOCATE (offset invalid)
+            .MFILE => unreachable, // F_DUPFD or F_DUPED
+            .NOLCK => unreachable, // F_SETLK or F_SETLKW
+            .OVERFLOW => return error.FileTooBig,
+            .SRCH => unreachable, // F_SETOWN
+            .OPNOTSUPP => return error.OperationNotSupported, // not reported but need same error union
+            else => |errno| return os.unexpectedErrno(errno),
+        }
+
+        // Now actually perform the allocation.
+        return os.ftruncate(fd, size) catch |err| switch (err) {
+            error.AccessDenied => error.PermissionDenied,
+            else => |e| e,
+        };
+    }
 };