tigerbeetle 0.0.34 → 0.0.37

data/ext/tb_client/tigerbeetle/src/clients/c/tb_client/echo_client.zig

@@ -0,0 +1,286 @@
+const std = @import("std");
+const assert = std.debug.assert;
+const mem = std.mem;
+
+const vsr = @import("../tb_client.zig").vsr;
+const Header = vsr.Header;
+const stdx = vsr.stdx;
+const constants = vsr.constants;
+const MessagePool = vsr.message_pool.MessagePool;
+const Message = MessagePool.Message;
+const Time = vsr.time.Time;
+
+pub fn EchoClientType(comptime MessageBus: type) type {
+    return struct {
+        const EchoClient = @This();
+
+        // Exposing the same types the real client does:
+        const VSRClient = vsr.ClientType(EchoOperation, MessageBus);
+        pub const Operation = VSRClient.Operation;
+        pub const Request = VSRClient.Request;
+
+        id: u128,
+        cluster: u128,
+        release: vsr.Release = vsr.Release.minimum,
+        request_number: u32 = 0,
+        reply_timestamp: u64 = 0, // Fake timestamp, just a counter.
+        request_inflight: ?Request = null,
+        message_pool: *MessagePool,
+        time: Time,
+
+        pub fn init(
+            allocator: mem.Allocator,
+            time: Time,
+            message_pool: *MessagePool,
+            options: struct {
+                id: u128,
+                cluster: u128,
+                replica_count: u8,
+                message_bus_options: MessageBus.Options,
+                eviction_callback: ?*const fn (
+                    client: *EchoClient,
+                    eviction: *const Message.Eviction,
+                ) void = null,
+                aof_recovery: bool,
+            },
+        ) !EchoClient {
+            _ = allocator;
+            _ = options.replica_count;
+            _ = options.message_bus_options;
+            assert(!options.aof_recovery);
+
+            return EchoClient{
+                .id = options.id,
+                .cluster = options.cluster,
+                .message_pool = message_pool,
+                .time = time,
+            };
+        }
+
+        pub fn deinit(self: *EchoClient, allocator: std.mem.Allocator) void {
+            _ = allocator;
+            if (self.request_inflight) |inflight| self.release_message(inflight.message.base());
+        }
+
+        pub fn tick(self: *EchoClient) void {
+            const inflight = self.request_inflight orelse return;
+            self.request_inflight = null;
+
+            self.reply_timestamp += 1;
+            const timestamp = self.reply_timestamp;
+
+            // Allocate a reply message.
+            const reply = self.get_message().build(.request);
+            defer self.release_message(reply.base());
+
+            // Copy the request message's entire content including header into the reply.
+            const operation = inflight.message.header.operation;
+            stdx.copy_disjoint(
+                .exact,
+                u8,
+                reply.buffer,
+                inflight.message.buffer,
+            );
+
+            // Similarly to the real client, release the request message before invoking the
+            // callback. This necessitates a `copy_disjoint` above.
+            self.release_message(inflight.message.base());
+
+            switch (inflight.callback) {
+                .request => |callback| {
+                    callback(inflight.user_data, operation, timestamp, reply.body_used());
+                },
+                .register => |callback| {
+                    const result = vsr.RegisterResult{
+                        .batch_size_limit = constants.message_body_size_max,
+                    };
+                    callback(inflight.user_data, &result);
+                },
+            }
+        }
+
+        pub fn register(
+            self: *EchoClient,
+            callback: Request.RegisterCallback,
+            user_data: u128,
+        ) void {
+            assert(self.request_inflight == null);
+            assert(self.request_number == 0);
+
+            const message = self.get_message().build(.request);
+            errdefer self.release_message(message.base());
+
+            // We will set parent, session, view and checksums only when sending for the first time:
+            message.header.* = .{
+                .client = self.id,
+                .request = self.request_number,
+                .cluster = self.cluster,
+                .command = .request,
+                .operation = .register,
+                .release = vsr.Release.minimum,
+                .previous_request_latency = 0,
+            };
+
+            assert(self.request_number == 0);
+            self.request_number += 1;
+
+            self.request_inflight = .{
+                .message = message,
+                .user_data = user_data,
+                .callback = .{ .register = callback },
+            };
+        }
+
+        pub fn request(
+            self: *EchoClient,
+            callback: Request.Callback,
+            user_data: u128,
+            operation: Operation,
+            events: []const u8,
+        ) void {
+            const event_size = operation.event_size();
+            assert(events.len <= constants.message_body_size_max);
+            assert(events.len % event_size == 0);
+
+            const message = self.get_message().build(.request);
+            errdefer self.release_message(message.base());
+
+            message.header.* = .{
+                .client = self.id,
+                .request = 0, // Set by raw_request() below.
+                .cluster = self.cluster,
+                .command = .request,
+                .release = vsr.Release.minimum,
+                .operation = operation.to_vsr(),
+                .size = @intCast(@sizeOf(Header) + events.len),
+                .previous_request_latency = 0,
+            };
+
+            stdx.copy_disjoint(.exact, u8, message.body_used(), events);
+            self.raw_request(callback, user_data, message);
+        }
+
+        pub fn raw_request(
+            self: *EchoClient,
+            callback: Request.Callback,
+            user_data: u128,
+            message: *Message.Request,
+        ) void {
+            assert(message.header.client == self.id);
+            assert(message.header.cluster == self.cluster);
+            assert(message.header.release.value == self.release.value);
+            assert(!message.header.operation.vsr_reserved());
+            assert(message.header.size >= @sizeOf(Header));
+            assert(message.header.size <= constants.message_size_max);
+
+            message.header.request = self.request_number;
+            self.request_number += 1;
+
+            assert(self.request_inflight == null);
+            self.request_inflight = .{
+                .message = message,
+                .user_data = user_data,
+                .callback = .{ .request = callback },
+            };
+        }
+
+        pub fn get_message(self: *EchoClient) *Message {
+            return self.message_pool.get_message(null);
+        }
+
+        pub fn release_message(self: *EchoClient, message: *Message) void {
+            self.message_pool.unref(message);
+        }
+    };
+}
+
+/// Mocks the Accounting StateMachine operation, but replaces
+/// all `Result`s with `Event`s, since the echo client replies
+/// with the same content of the input.
+pub const EchoOperation = enum(u8) {
+    const Operation = vsr.tigerbeetle.Operation;
+
+    pulse = @intFromEnum(Operation.pulse),
+
+    get_change_events = @intFromEnum(Operation.get_change_events),
+
+    create_accounts = @intFromEnum(Operation.create_accounts),
+    create_transfers = @intFromEnum(Operation.create_transfers),
+    lookup_accounts = @intFromEnum(Operation.lookup_accounts),
+    lookup_transfers = @intFromEnum(Operation.lookup_transfers),
+    get_account_transfers = @intFromEnum(Operation.get_account_transfers),
+    get_account_balances = @intFromEnum(Operation.get_account_balances),
+    query_accounts = @intFromEnum(Operation.query_accounts),
+    query_transfers = @intFromEnum(Operation.query_transfers),
+
+    comptime {
+        const operation_type_info = @typeInfo(Operation).@"enum";
+        const echo_type_info = @typeInfo(EchoOperation).@"enum";
+        assert(echo_type_info.tag_type == operation_type_info.tag_type);
+        assert(echo_type_info.is_exhaustive);
+        assert(echo_type_info.fields.len <= operation_type_info.fields.len);
+        for (echo_type_info.fields) |field| {
+            assert(@hasField(Operation, field.name));
+
+            const a = @field(Operation, field.name);
+            const b = @field(EchoOperation, field.name);
+            assert(@intFromEnum(a) == @intFromEnum(b));
+        }
+    }
+
+    inline fn cast(operation: EchoOperation) Operation {
+        return @enumFromInt(@intFromEnum(operation));
+    }
+
+    pub fn EventType(comptime operation: EchoOperation) type {
+        return operation.cast().EventType();
+    }
+
+    pub inline fn event_size(operation: EchoOperation) u32 {
+        return operation.cast().event_size();
+    }
+
+    pub inline fn is_batchable(operation: EchoOperation) bool {
+        return operation.cast().is_batchable();
+    }
+
+    pub inline fn is_multi_batch(operation: EchoOperation) bool {
+        return operation.cast().is_multi_batch();
+    }
+
+    pub inline fn event_max(operation: EchoOperation, batch_size_limit: u32) u32 {
+        return operation.cast().event_max(batch_size_limit);
+    }
+
+    pub inline fn result_count_expected(
+        operation: EchoOperation,
+        batch: []const u8,
+    ) u32 {
+        return operation.cast().result_count_expected(batch);
+    }
+
+    pub fn from_vsr(operation: vsr.Operation) ?EchoOperation {
+        if (operation == .pulse) return .pulse;
+        if (operation.vsr_reserved()) return null;
+
+        return vsr.Operation.to(EchoOperation, operation);
+    }
+
+    pub fn to_vsr(operation: EchoOperation) vsr.Operation {
+        return vsr.Operation.from(EchoOperation, operation);
+    }
+
+    // Re-exporting functions where results are equal to events.
+
+    pub fn ResultType(comptime operation: EchoOperation) type {
+        return operation.EventType();
+    }
+
+    pub inline fn result_size(operation: EchoOperation) u32 {
+        return operation.event_size();
+    }
+
+    pub inline fn result_max(operation: EchoOperation, batch_size_limit: u32) u32 {
+        return operation.event_max(batch_size_limit);
+    }
+};

data/ext/tb_client/tigerbeetle/src/clients/c/tb_client/packet.zig

@@ -0,0 +1,158 @@
+const std = @import("std");
+const assert = std.debug.assert;
+
+const tb_client = @import("../tb_client.zig");
+const stdx = tb_client.vsr.stdx;
+const maybe = stdx.maybe;
+
+const QueueType = tb_client.vsr.queue.QueueType;
+
+pub const Packet = extern struct {
+    pub const Status = enum(u8) {
+        ok,
+        too_much_data,
+        client_evicted,
+        client_release_too_low,
+        client_release_too_high,
+        client_shutdown,
+        invalid_operation,
+        invalid_data_size,
+    };
+
+    /// External packet type exposed to the user.
+    pub const Extern = extern struct {
+        user_data: ?*anyopaque,
+        data: ?*anyopaque,
+        data_size: u32,
+        user_tag: u16,
+        operation: u8,
+        status: Status,
+        @"opaque": [64]u8 = @splat(0),
+
+        pub fn cast(self: *Extern) *Packet {
+            return @ptrCast(self);
+        }
+    };
+
+    const Phase = enum(u8) {
+        submitted,
+        pending,
+        batched,
+        sent,
+        complete,
+    };
+
+    pub const Queue = QueueType(Packet);
+
+    user_data: ?*anyopaque,
+    data: ?*anyopaque,
+    data_size: u32,
+    user_tag: u16,
+    operation: u8,
+    status: Status,
+
+    link: Queue.Link,
+
+    multi_batch_time_monotonic: u64,
+    multi_batch_next: ?*Packet,
+    multi_batch_tail: ?*Packet,
+    multi_batch_count: u16,
+    multi_batch_event_count: u16,
+    multi_batch_result_count_expected: u16,
+    phase: Phase,
+    reserved: [25]u8 = @splat(0),
+
+    pub fn cast(self: *Packet) *Extern {
+        return @ptrCast(self);
+    }
+
+    pub fn slice(packet: *const Packet) []const u8 {
+        if (packet.data_size == 0) {
+            // It may be an empty array (null pointer)
+            // or a buffer with no elements (valid pointer and size == 0).
+            stdx.maybe(packet.data == null);
+            return &[0]u8{};
+        }
+
+        const data: [*]const u8 = @ptrCast(packet.data.?);
+        return data[0..packet.data_size];
+    }
+
+    /// Asserts the internal state of the packet according to its expected phase.
+    /// Inline function, so `expected` can be comptime known.
+    pub inline fn assert_phase(packet: *const Packet, expected: Phase) void {
+        assert(packet.phase == expected);
+        assert(packet.data_size == 0 or packet.data != null);
+        assert(stdx.zeroed(&packet.reserved));
+        maybe(packet.user_data == null);
+        maybe(packet.user_tag == 0);
+
+        switch (expected) {
+            .submitted => {
+                assert(packet.link.next == null);
+                assert(packet.multi_batch_next == null);
+                assert(packet.multi_batch_tail == null);
+                assert(packet.multi_batch_count == 0);
+                assert(packet.multi_batch_event_count == 0);
+                assert(packet.multi_batch_result_count_expected == 0);
+                assert(packet.multi_batch_time_monotonic == 0);
+            },
+            .pending => {
+                assert(packet.multi_batch_count >= 1);
+                assert(packet.multi_batch_next == null or packet.multi_batch_count > 1);
+                assert((packet.multi_batch_next == null) == (packet.multi_batch_tail == null));
+                maybe(packet.data_size == 0);
+                maybe(packet.multi_batch_event_count == 0);
+                maybe(packet.multi_batch_result_count_expected == 0);
+                maybe(packet.link.next == null);
+                assert(packet.multi_batch_time_monotonic != 0);
+            },
+            .batched => {
+                assert(packet.link.next == null);
+                assert(packet.multi_batch_tail == null);
+                assert(packet.multi_batch_count == 0);
+                assert(packet.multi_batch_event_count == 0);
+                assert(packet.multi_batch_result_count_expected == 0);
+                maybe(packet.multi_batch_next != null);
+                assert(packet.multi_batch_time_monotonic == 0);
+            },
+            .sent => {
+                assert(packet.link.next == null);
+                assert(packet.multi_batch_count > 0);
+                assert(packet.multi_batch_next == null or packet.multi_batch_count > 1);
+                assert((packet.multi_batch_next == null) == (packet.multi_batch_tail == null));
+                maybe(packet.multi_batch_event_count == 0);
+                maybe(packet.multi_batch_result_count_expected == 0);
+                assert(packet.multi_batch_time_monotonic != 0);
+            },
+            .complete => {
+                // The packet pointer isn't available after completed,
+                // it may be deallocated by the user;
+                unreachable;
+            },
+        }
+    }
+
+    comptime {
+        assert(@sizeOf(Extern) % @alignOf(Extern) == 0);
+        assert(@alignOf(Extern) == 8);
+
+        assert(@sizeOf(Packet) == @sizeOf(Extern));
+        assert(@alignOf(Packet) == @alignOf(Extern));
+
+        // Asserting the fields are identical.
+        for (std.meta.fields(Extern)) |field_extern| {
+            if (std.mem.eql(u8, field_extern.name, "opaque")) continue;
+            const field_packet = std.meta.fields(Packet)[
+                std.meta.fieldIndex(
+                    Packet,
+                    field_extern.name,
+                ).?
+            ];
+            assert(field_packet.type == field_extern.type);
+            assert(field_packet.alignment == field_extern.alignment);
+            assert(@offsetOf(Packet, field_extern.name) ==
+                @offsetOf(Extern, field_extern.name));
+        }
+    }
+};

data/ext/tb_client/tigerbeetle/src/clients/c/tb_client/signal.zig

@@ -0,0 +1,229 @@
+const std = @import("std");
+const assert = std.debug.assert;
+
+const vsr = @import("../tb_client.zig").vsr;
+const TimeOS = vsr.time.TimeOS;
+const IO = vsr.io.IO;
+
+const Atomic = std.atomic.Value;
+
+/// A Signal is a way to trigger a registered callback on a IO instance when notification
+/// occurs from another thread.
+pub const Signal = struct {
+    io: *IO,
+    completion: IO.Completion,
+    event: IO.Event,
+    event_state: Atomic(enum(u8) {
+        running,
+        waiting,
+        notified,
+        shutdown,
+    }),
+
+    listening: Atomic(bool),
+    on_signal_fn: *const fn (*Signal) void,
+
+    pub fn init(self: *Signal, io: *IO, on_signal_fn: *const fn (*Signal) void) !void {
+        const event = try io.open_event();
+        errdefer io.close_event(event);
+
+        self.* = .{
+            .io = io,
+            .completion = undefined,
+            .event = event,
+            .event_state = @TypeOf(self.event_state).init(.running),
+            .listening = Atomic(bool).init(true),
+            .on_signal_fn = on_signal_fn,
+        };
+
+        self.wait();
+    }
+
+    pub fn deinit(self: *Signal) void {
+        assert(self.event != IO.INVALID_EVENT);
+        assert(self.status() == .stopped);
+
+        self.io.close_event(self.event);
+        self.* = undefined;
+    }
+
+    /// Requests to stop listening for notifications.
+    /// The caller must continue processing `IO.run()` until `state() == .stopped`.
+    /// Safe to call from multiple threads.
+    pub fn stop(self: *Signal) void {
+        const listening = self.listening.swap(false, .release);
+        if (listening) {
+            self.notify();
+        }
+    }
+
+    /// Returns the current state.
+    /// Safe to call from multiple threads.
+    pub fn status(self: *const Signal) enum {
+        /// Listening for event notifications.
+        /// Call `notify()` to trigger the callback.
+        running,
+        /// `stop()` was called, but the event listener is still waiting for the IO operation
+        /// to complete. Further calls to `notify()` have no effect.
+        stop_requested,
+        /// No pending listening events. It is safe to call `deinit()`.
+        stopped,
+    } {
+        return switch (self.event_state.load(.acquire)) {
+            .shutdown => .stopped,
+            .running,
+            .waiting,
+            .notified,
+            => if (self.listening.load(.acquire))
+                .running
+            else
+                .stop_requested,
+        };
+    }
+
+    /// Schedules the `on_signal` callback to be invoked on the IO thread.
+    /// Calling `notify()` when `state() != .running` has no effect.
+    /// Safe to call from multiple threads.
+    pub fn notify(self: *Signal) void {
+        // Try to transition from `waiting` to `notified`.
+        // If it fails, analyze the current state to determine if a notification is needed.
+        var state: @TypeOf(self.event_state.raw) = .waiting;
+        while (self.event_state.cmpxchgStrong(
+            state,
+            .notified,
+            .release,
+            .acquire,
+        )) |state_actual| {
+            switch (state_actual) {
+                .waiting, .running => state = state_actual, // Try again.
+                .notified => return, // Already notified.
+                .shutdown => return, // Ignore notifications after shutdown.
+            }
+        }
+
+        if (state == .waiting) {
+            self.io.event_trigger(self.event, &self.completion);
+        }
+    }
+
+    fn wait(self: *Signal) void {
+        // It is not guaranteed to be `running` here, as another caller might have requested
+        // a stop during the callback.
+        assert(self.status() != .stopped);
+
+        const state = self.event_state.swap(.waiting, .acquire);
+        self.io.event_listen(self.event, &self.completion, on_event);
+        switch (state) {
+            // We should be the only ones who could've started waiting.
+            .waiting => unreachable,
+            // Wait for a `notify`.
+            .running => {},
+            // A `notify` was already called in the meantime,
+            // calling it again asynchronously.
+            .notified => self.notify(),
+            // Cannot be called after shutdown.
+            .shutdown => unreachable,
+        }
+    }
+
+    fn on_event(completion: *IO.Completion) void {
+        const self: *Signal = @fieldParentPtr("completion", completion);
+        const listening: bool = self.listening.load(.acquire);
+        const state = self.event_state.cmpxchgStrong(
+            .notified,
+            if (listening) .running else .shutdown,
+            .release,
+            .acquire,
+        ) orelse {
+            if (listening) {
+                (self.on_signal_fn)(self);
+                self.wait();
+            }
+            return;
+        };
+
+        switch (state) {
+            .running => unreachable, // Multiple racing calls to on_signal().
+            .waiting => unreachable, // on_signal() called without transitioning to a waking state.
+            .notified => unreachable, // Not possible due to CAS semantics.
+            .shutdown => unreachable, // Shutdown is a final state.
+        }
+    }
+};
+
+test "signal" {
+    try struct {
+        const Context = @This();
+
+        io: IO,
+        count: u32 = 0,
+        main_thread_id: std.Thread.Id,
+        signal: Signal,
+
+        const delay = 5 * std.time.ns_per_ms;
+        const events_count = 5;
+
+        fn run_test() !void {
+            var self: Context = .{
+                .io = try IO.init(32, 0),
+                .main_thread_id = std.Thread.getCurrentId(),
+                .signal = undefined,
+            };
+            defer self.io.deinit();
+
+            try Signal.init(&self.signal, &self.io, on_signal);
+            defer self.signal.deinit();
+
+            var time_os = TimeOS{};
+            const timer = time_os.time();
+            const start = timer.monotonic();
+
+            const thread = try std.Thread.spawn(.{}, Context.notify, .{&self});
+
+            // Wait for the number of events to complete.
+            while (self.count < events_count) try self.io.run();
+
+            // Begin shutdown and keep ticking until it's completed.
+            self.signal.stop();
+            while (self.signal.status() != .stopped) try self.io.run();
+            thread.join();
+
+            // Notify after shutdown should be ignored.
+            self.signal.notify();
+
+            // Make sure the event was triggered multiple times.
+            assert(self.count == events_count);
+
+            // Make sure at least some time has passed.
+            const elapsed = timer.monotonic().duration_since(start);
+            assert(elapsed.ns >= delay);
+        }
+
+        fn notify(self: *Context) void {
+            assert(std.Thread.getCurrentId() != self.main_thread_id);
+            while (self.signal.status() != .stopped) {
+                std.time.sleep(delay + 1);
+
+                // Triggering the event:
+                self.signal.notify();
+
+                // The same signal may be triggered multiple times,
+                // but it should only fire once.
+                self.signal.notify();
+            }
+        }
+
+        fn on_signal(signal: *Signal) void {
+            const self: *Context = @fieldParentPtr("signal", signal);
+            assert(std.Thread.getCurrentId() == self.main_thread_id);
+            switch (self.signal.status()) {
+                .running => {
+                    assert(self.count < events_count);
+                    self.count += 1;
+                },
+                .stop_requested => assert(self.count == events_count),
+                .stopped => unreachable,
+            }
+        }
+    }.run_test();
+}