tigerbeetle 0.0.36 → 0.0.38

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

@@ -0,0 +1,281 @@
+const std = @import("std");
+const assert = std.debug.assert;
+
+const vsr = @import("../../vsr.zig");
+const tb = vsr.tb_client;
+const stdx = vsr.stdx;
+
+pub const tb_packet_t = tb.Packet;
+pub const tb_packet_status = tb.PacketStatus;
+
+pub const tb_client_t = extern struct {
+    @"opaque": [4]u64,
+
+    pub inline fn cast(self: *tb_client_t) *tb.ClientInterface {
+        return @ptrCast(self);
+    }
+
+    comptime {
+        assert(@sizeOf(tb_client_t) == @sizeOf(tb.ClientInterface));
+        assert(@bitSizeOf(tb_client_t) == @bitSizeOf(tb.ClientInterface));
+        assert(@alignOf(tb_client_t) == @alignOf(tb.ClientInterface));
+    }
+};
+
+pub const tb_init_status = enum(c_int) {
+    success = 0,
+    unexpected,
+    out_of_memory,
+    address_invalid,
+    address_limit_exceeded,
+    system_resources,
+    network_subsystem,
+};
+
+pub const tb_client_status = enum(c_int) {
+    ok = 0,
+    invalid,
+};
+
+pub const tb_register_log_callback_status = enum(c_int) {
+    success = 0,
+    already_registered,
+    not_registered,
+};
+
+pub const tb_log_level = enum(c_int) {
+    err = @intFromEnum(std.log.Level.err),
+    warn = @intFromEnum(std.log.Level.warn),
+    info = @intFromEnum(std.log.Level.info),
+    debug = @intFromEnum(std.log.Level.debug),
+
+    comptime {
+        assert(std.enums.values(std.log.Level).len == std.enums.values(tb_log_level).len);
+        for (std.enums.values(std.log.Level)) |std_level| {
+            const level: tb_log_level = @enumFromInt(@intFromEnum(std_level));
+            assert(std.mem.eql(u8, @tagName(std_level), @tagName(level)));
+        }
+    }
+};
+
+pub const tb_operation = tb.Operation;
+pub const tb_completion_t = tb.CompletionCallback;
+pub const tb_init_parameters = tb.InitParameters;
+
+pub const tb_account_t = vsr.tigerbeetle.Account;
+pub const tb_transfer_t = vsr.tigerbeetle.Transfer;
+pub const tb_account_flags = vsr.tigerbeetle.AccountFlags;
+pub const tb_transfer_flags = vsr.tigerbeetle.TransferFlags;
+pub const tb_create_account_result = vsr.tigerbeetle.CreateAccountResult;
+pub const tb_create_transfer_result = vsr.tigerbeetle.CreateTransferResult;
+pub const tb_create_accounts_result_t = vsr.tigerbeetle.CreateAccountsResult;
+pub const tb_create_transfers_result_t = vsr.tigerbeetle.CreateTransfersResult;
+pub const tb_account_filter_t = vsr.tigerbeetle.AccountFilter;
+pub const tb_account_filter_flags = vsr.tigerbeetle.AccountFilterFlags;
+pub const tb_account_balance_t = vsr.tigerbeetle.AccountBalance;
+pub const tb_query_filter_t = vsr.tigerbeetle.QueryFilter;
+pub const tb_query_filter_flags = vsr.tigerbeetle.QueryFilterFlags;
+
+pub fn init_error_to_status(err: tb.InitError) tb_init_status {
+    return switch (err) {
+        error.Unexpected => .unexpected,
+        error.OutOfMemory => .out_of_memory,
+        error.AddressInvalid => .address_invalid,
+        error.AddressLimitExceeded => .address_limit_exceeded,
+        error.SystemResources => .system_resources,
+        error.NetworkSubsystemFailed => .network_subsystem,
+    };
+}
+
+pub fn init(
+    tb_client_out: *tb_client_t,
+    cluster_id_ptr: *const [16]u8,
+    addresses_ptr: [*:0]const u8,
+    addresses_len: u32,
+    completion_ctx: usize,
+    completion_callback: tb_completion_t,
+) callconv(.c) tb_init_status {
+    const addresses = @as([*]const u8, @ptrCast(addresses_ptr))[0..addresses_len];
+
+    // Passing u128 by value is prone to ABI issues. Pass as a [16]u8, and explicitly copy into
+    // memory we know will be aligned correctly. Don't just use bytesToValue here, as that keeps
+    // pointer alignment, and will result in a potentially unaligned access of a
+    // `*align(1) const u128`.
+    const cluster_id: u128 = blk: {
+        var cluster_id: u128 = undefined;
+        stdx.copy_disjoint(.exact, u8, std.mem.asBytes(&cluster_id), cluster_id_ptr);
+
+        break :blk cluster_id;
+    };
+
+    tb.init(
+        std.heap.c_allocator,
+        tb_client_out.cast(),
+        cluster_id,
+        addresses,
+        completion_ctx,
+        completion_callback,
+    ) catch |err| return init_error_to_status(err);
+    return .success;
+}
+
+pub fn init_echo(
+    tb_client_out: *tb_client_t,
+    cluster_id_ptr: *const [16]u8,
+    addresses_ptr: [*:0]const u8,
+    addresses_len: u32,
+    completion_ctx: usize,
+    completion_callback: tb_completion_t,
+) callconv(.c) tb_init_status {
+    const addresses = @as([*]const u8, @ptrCast(addresses_ptr))[0..addresses_len];
+
+    // See explanation in init().
+    const cluster_id: u128 = blk: {
+        var cluster_id: u128 = undefined;
+        stdx.copy_disjoint(.exact, u8, std.mem.asBytes(&cluster_id), cluster_id_ptr);
+
+        break :blk cluster_id;
+    };
+
+    tb.init_echo(
+        std.heap.c_allocator,
+        tb_client_out.cast(),
+        cluster_id,
+        addresses,
+        completion_ctx,
+        completion_callback,
+    ) catch |err| return init_error_to_status(err);
+    return .success;
+}
+
+pub fn submit(tb_client: ?*tb_client_t, packet: *tb_packet_t) callconv(.c) tb_client_status {
+    const client: *tb.ClientInterface = if (tb_client) |ptr| ptr.cast() else return .invalid;
+    client.submit(packet) catch |err| switch (err) {
+        error.ClientInvalid => return .invalid,
+    };
+    return .ok;
+}
+
+pub fn deinit(tb_client: ?*tb_client_t) callconv(.c) tb_client_status {
+    const client: *tb.ClientInterface = if (tb_client) |ptr| ptr.cast() else return .invalid;
+    client.deinit() catch |err| switch (err) {
+        error.ClientInvalid => return .invalid,
+    };
+    return .ok;
+}
+
+pub fn init_parameters(
+    tb_client: ?*tb_client_t,
+    out_parameters: *tb_init_parameters,
+) callconv(.c) tb_client_status {
+    const client: *tb.ClientInterface = if (tb_client) |ptr| ptr.cast() else return .invalid;
+    client.init_parameters(out_parameters) catch |err| switch (err) {
+        error.ClientInvalid => return .invalid,
+    };
+    return .ok;
+}
+
+pub fn completion_context(
+    tb_client: ?*tb_client_t,
+    completion_ctx_out: *usize,
+) callconv(.c) tb_client_status {
+    const client: *tb.ClientInterface = if (tb_client) |ptr| ptr.cast() else return .invalid;
+    completion_ctx_out.* = client.completion_context() catch |err| switch (err) {
+        error.ClientInvalid => return .invalid,
+    };
+    return .ok;
+}
+
+pub fn register_log_callback(
+    callback_maybe: ?Logging.Callback,
+    debug: bool,
+) callconv(.c) tb_register_log_callback_status {
+    Logging.global.mutex.lock();
+    defer Logging.global.mutex.unlock();
+
+    if (Logging.global.callback == null) {
+        if (callback_maybe) |callback| {
+            Logging.global.callback = callback;
+            Logging.global.debug = debug;
+            return .success;
+        } else {
+            return .not_registered;
+        }
+    } else {
+        if (callback_maybe == null) {
+            Logging.global.callback = null;
+            Logging.global.debug = debug;
+            return .success;
+        } else {
+            return .already_registered;
+        }
+    }
+}
+
+pub const Logging = struct {
+    const Callback = *const fn (
+        message_level: tb_log_level,
+        message_ptr: [*]const u8,
+        message_len: u32,
+    ) callconv(.c) void;
+
+    const log_line_max = 8192;
+
+    /// Logging is global per process; it would be nice to be able to define a different logger
+    /// for each client instance, though.
+    var global: Logging = .{};
+
+    callback: ?Callback = null,
+    mutex: std.Thread.Mutex = .{},
+    buffer: [log_line_max]u8 = undefined,
+    debug: bool = false,
+
+    /// A logger which defers to an application provided handler.
+    pub fn application_logger(
+        comptime message_level: std.log.Level,
+        comptime scope: @Type(.enum_literal),
+        comptime format: []const u8,
+        args: anytype,
+    ) void {
+        // Debug logs are dropped here unless debug is set, because of the potential penalty in
+        // crossing FFI to drop them.
+        if (message_level == .debug and !Logging.global.debug) {
+            return;
+        }
+
+        // Other messages are silently dropped if no logging callback is specified - unless they're
+        // warn or err. The value in having those for debugging is too high to silence them, even
+        // until client libraries catch up and implement a callback handler.
+        if (Logging.global.callback == null and (message_level == .warn or message_level == .err)) {
+            std.log.defaultLog(message_level, scope, format, args);
+            return;
+        }
+
+        // Protect everything with a mutex - logging can be called from different threads
+        // simultaneously, and there's only one buffer for now.
+        Logging.global.mutex.lock();
+        defer Logging.global.mutex.unlock();
+
+        const callback = Logging.global.callback orelse return;
+
+        const tb_message_level: tb_log_level = @enumFromInt(@intFromEnum(message_level));
+        const prefix = if (scope == .default) ": " else "(" ++ @tagName(scope) ++ "): ";
+        const output = std.fmt.bufPrint(
+            &Logging.global.buffer,
+            prefix ++ format,
+            args,
+        ) catch |err| switch (err) {
+            error.NoSpaceLeft => blk: {
+                // Print an error indicating the log message has been truncated, before the
+                // truncated log itself.
+                const message = "the following log message has been truncated:";
+                callback(tb_message_level, message.ptr, message.len);
+
+                break :blk &Logging.global.buffer;
+            },
+            else => unreachable,
+        };
+
+        callback(tb_message_level, output.ptr, @intCast(output.len));
+    }
+};

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

@@ -0,0 +1,312 @@
+const std = @import("std");
+const assert = std.debug.assert;
+
+const vsr = @import("vsr");
+const exports = vsr.tb_client.exports;
+
+const type_mappings = .{
+    .{ exports.tb_account_flags, "TB_ACCOUNT_FLAGS" },
+    .{ exports.tb_account_t, "tb_account_t" },
+    .{ exports.tb_transfer_flags, "TB_TRANSFER_FLAGS" },
+    .{ exports.tb_transfer_t, "tb_transfer_t" },
+    .{ exports.tb_create_account_result, "TB_CREATE_ACCOUNT_RESULT" },
+    .{ exports.tb_create_transfer_result, "TB_CREATE_TRANSFER_RESULT" },
+    .{ exports.tb_create_accounts_result_t, "tb_create_accounts_result_t" },
+    .{ exports.tb_create_transfers_result_t, "tb_create_transfers_result_t" },
+    .{ exports.tb_account_filter_t, "tb_account_filter_t" },
+    .{ exports.tb_account_filter_flags, "TB_ACCOUNT_FILTER_FLAGS" },
+    .{ exports.tb_account_balance_t, "tb_account_balance_t" },
+    .{ exports.tb_query_filter_t, "tb_query_filter_t" },
+    .{ exports.tb_query_filter_flags, "TB_QUERY_FILTER_FLAGS" },
+    .{
+        exports.tb_client_t, "tb_client_t",
+        \\// Opaque struct serving as a handle for the client instance.
+        \\// This struct must be "pinned" (not copyable or movable), as its address must remain stable
+        \\// throughout the lifetime of the client instance.
+    },
+    .{
+        exports.tb_packet_t, "tb_packet_t",
+        \\// Struct containing the state of a request submitted through the client.
+        \\// This struct must be "pinned" (not copyable or movable), as its address must remain stable
+        \\// throughout the lifetime of the request.
+    },
+    .{ exports.tb_operation, "TB_OPERATION" },
+    .{ exports.tb_packet_status, "TB_PACKET_STATUS" },
+    .{ exports.tb_init_status, "TB_INIT_STATUS" },
+    .{ exports.tb_client_status, "TB_CLIENT_STATUS" },
+    .{ exports.tb_register_log_callback_status, "TB_REGISTER_LOG_CALLBACK_STATUS" },
+    .{ exports.tb_log_level, "TB_LOG_LEVEL" },
+    .{ exports.tb_init_parameters, "tb_init_parameters_t" },
+};
+
+fn resolve_c_type(comptime Type: type) []const u8 {
+    switch (@typeInfo(Type)) {
+        .array => |info| return resolve_c_type(info.child),
+        .@"enum" => |info| return resolve_c_type(info.tag_type),
+        .@"struct" => return resolve_c_type(std.meta.Int(.unsigned, @bitSizeOf(Type))),
+        .bool => return "uint8_t",
+        .int => |info| {
+            assert(info.signedness == .unsigned);
+            return switch (info.bits) {
+                8 => "uint8_t",
+                16 => "uint16_t",
+                32 => "uint32_t",
+                64 => "uint64_t",
+                128 => "tb_uint128_t",
+                else => @compileError("invalid int type"),
+            };
+        },
+        .optional => |info| switch (@typeInfo(info.child)) {
+            .pointer => return resolve_c_type(info.child),
+            else => @compileError("Unsupported optional type: " ++ @typeName(Type)),
+        },
+        .pointer => |info| {
+            assert(info.size != .slice);
+            assert(!info.is_allowzero);
+
+            inline for (type_mappings) |type_mapping| {
+                const ZigType = type_mapping[0];
+                const c_name = type_mapping[1];
+
+                if (info.child == ZigType) {
+                    const prefix = if (@typeInfo(ZigType) == .@"struct") "struct " else "";
+                    return prefix ++ c_name ++ "*";
+                }
+            }
+
+            return comptime resolve_c_type(info.child) ++ "*";
+        },
+        .void, .@"opaque" => return "void",
+        else => @compileError("Unhandled type: " ++ @typeName(Type)),
+    }
+}
+
+fn to_uppercase(comptime input: []const u8) [input.len]u8 {
+    comptime var output: [input.len]u8 = undefined;
+    inline for (&output, 0..) |*char, i| {
+        char.* = input[i];
+        char.* -= 32 * @as(u8, @intFromBool(char.* >= 'a' and char.* <= 'z'));
+    }
+    return output;
+}
+
+fn emit_enum(
+    buffer: *std.ArrayList(u8),
+    comptime Type: type,
+    comptime type_info: anytype,
+    comptime c_name: []const u8,
+    comptime skip_fields: []const []const u8,
+) !void {
+    var suffix_pos = std.mem.lastIndexOfScalar(u8, c_name, '_').?;
+    if (std.mem.count(u8, c_name, "_") == 1) suffix_pos = c_name.len;
+
+    try buffer.writer().print("typedef enum {s} {{\n", .{c_name});
+
+    inline for (type_info.fields, 0..) |field, i| {
+        if (comptime std.mem.startsWith(u8, field.name, "deprecated_")) continue;
+        comptime var skip = false;
+        inline for (skip_fields) |sf| {
+            skip = skip or comptime std.mem.eql(u8, sf, field.name);
+        }
+
+        if (!skip) {
+            const field_name = to_uppercase(field.name);
+            if (@typeInfo(Type) == .@"enum") {
+                try buffer.writer().print("    {s}_{s} = {},\n", .{
+                    c_name[0..suffix_pos],
+                    @as([]const u8, &field_name),
+                    @intFromEnum(@field(Type, field.name)),
+                });
+            } else {
+                // Packed structs.
+                try buffer.writer().print("    {s}_{s} = 1 << {},\n", .{
+                    c_name[0..suffix_pos],
+                    @as([]const u8, &field_name),
+                    i,
+                });
+            }
+        }
+    }
+
+    try buffer.writer().print("}} {s};\n\n", .{c_name});
+}
+
+fn emit_struct(
+    buffer: *std.ArrayList(u8),
+    comptime type_info: anytype,
+    comptime c_name: []const u8,
+) !void {
+    try buffer.writer().print("typedef struct {s} {{\n", .{c_name});
+
+    inline for (type_info.fields) |field| {
+        try buffer.writer().print("    {s} {s}", .{
+            resolve_c_type(field.type),
+            field.name,
+        });
+
+        switch (@typeInfo(field.type)) {
+            .array => |array| try buffer.writer().print("[{d}]", .{array.len}),
+            else => {},
+        }
+
+        try buffer.writer().print(";\n", .{});
+    }
+
+    try buffer.writer().print("}} {s};\n\n", .{c_name});
+}
+
+pub fn main() !void {
+    @setEvalBranchQuota(100_000);
+
+    var arena = std.heap.ArenaAllocator.init(std.heap.page_allocator);
+    defer arena.deinit();
+
+    const allocator = arena.allocator();
+
+    var buffer = std.ArrayList(u8).init(allocator);
+    try buffer.writer().print(
+        \\ //////////////////////////////////////////////////////////
+        \\ // This file was auto-generated by tb_client_header.zig //
+        \\ //              Do not manually modify.                 //
+        \\ //////////////////////////////////////////////////////////
+        \\
+        \\#ifndef TB_CLIENT_H
+        \\#define TB_CLIENT_H
+        \\
+        \\#ifdef __cplusplus
+        \\extern "C" {{
+        \\#endif
+        \\
+        \\#include <stddef.h>
+        \\#include <stdint.h>
+        \\#include <stdbool.h>
+        \\
+        \\typedef __uint128_t tb_uint128_t;
+        \\
+        \\
+    , .{});
+
+    // Emit C type declarations.
+    inline for (type_mappings) |type_mapping| {
+        const ZigType = type_mapping[0];
+        const c_name = type_mapping[1];
+        if (type_mapping.len == 3) {
+            const comments: []const u8 = type_mapping[2];
+            try buffer.writer().print(comments, .{});
+            try buffer.writer().print("\n", .{});
+        }
+
+        switch (@typeInfo(ZigType)) {
+            .@"struct" => |info| switch (info.layout) {
+                .auto => @compileError("Invalid C struct type: " ++ @typeName(ZigType)),
+                .@"packed" => try emit_enum(&buffer, ZigType, info, c_name, &.{"padding"}),
+                .@"extern" => try emit_struct(&buffer, info, c_name),
+            },
+            .@"enum" => |info| {
+                comptime var skip: []const []const u8 = &.{};
+                if (ZigType == exports.tb_operation) {
+                    skip = &.{ "reserved", "root", "register" };
+                }
+
+                try emit_enum(&buffer, ZigType, info, c_name, skip);
+            },
+            else => try buffer.writer().print("typedef {s} {s}; \n\n", .{
+                resolve_c_type(ZigType),
+                c_name,
+            }),
+        }
+    }
+
+    // Emit C function declarations.
+    // TODO: use `std.meta.declaractions` and generate with pub + export functions.
+    // Zig 0.9.1 has `decl.data.Fn.arg_names` but it's currently/incorrectly a zero-sized slice.
+    try buffer.writer().print(
+        \\// Per-client callback invoked every time a `tb_client_submit` completes or is canceled.
+        \\// Use `packet->userdata` to identify the specific submission.
+        \\// `result` is null iff `packet->status != TB_PACKET_OK`
+        \\// `result` is only valid for the duration of the callback itself.
+        \\typedef void (*tb_completion_t)(
+        \\    uintptr_t userdata,
+        \\    tb_packet_t* packet,
+        \\    uint64_t timestamp,
+        \\    const uint8_t *result, // nullable
+        \\    uint32_t result_size
+        \\);
+        \\
+        \\// Initialize a new TigerBeetle client which connects to the addresses provided and
+        \\// completes submitted packets by invoking the callback with the given context.
+        \\TB_INIT_STATUS tb_client_init(
+        \\    tb_client_t *client_out,
+        \\    // 128-bit unsigned integer represented as a 16-byte little-endian array.
+        \\    const uint8_t cluster_id[16],
+        \\    const char *address_ptr,
+        \\    uint32_t address_len,
+        \\    uintptr_t completion_ctx,
+        \\    tb_completion_t completion_callback
+        \\);
+        \\
+        \\// Initialize a new TigerBeetle client that echoes back any submitted data.
+        \\TB_INIT_STATUS tb_client_init_echo(
+        \\    tb_client_t *client_out,
+        \\    // 128-bit unsigned integer represented as a 16-byte little-endian array.
+        \\    const uint8_t cluster_id[16],
+        \\    const char *address_ptr,
+        \\    uint32_t address_len,
+        \\    uintptr_t completion_ctx,
+        \\    tb_completion_t completion_callback
+        \\);
+        \\
+        \\// Retrieve the parameters initially passed to `tb_client_init` or `tb_client_init_echo`.
+        \\// Return value: `TB_CLIENT_OK` on success, or `TB_CLIENT_INVALID` if the client handle was
+        \\// not initialized or has already been closed.
+        \\TB_CLIENT_STATUS tb_client_init_parameters(
+        \\    tb_client_t* client,
+        \\    tb_init_parameters_t* init_parameters_out
+        \\);
+        \\
+        \\// Retrieve the callback context initially passed to `tb_client_init` or `tb_client_init_echo`.
+        \\// Return value: `TB_CLIENT_OK` on success, or `TB_CLIENT_INVALID` if the client handle was
+        \\// not initialized or has already been closed.
+        \\TB_CLIENT_STATUS tb_client_completion_context(
+        \\    tb_client_t* client,
+        \\    uintptr_t* completion_ctx_out
+        \\);
+        \\
+        \\// Submit a packet with its `operation`, `data`, and `data_size` fields set.
+        \\// Once completed, `completion_callback` will be invoked with `completion_ctx`
+        \\// and the given packet on the `tb_client` thread (separate from the caller's thread).
+        \\// Return value: `TB_CLIENT_OK` on success, or `TB_CLIENT_INVALID` if the client handle was
+        \\// not initialized or has already been closed.
+        \\TB_CLIENT_STATUS tb_client_submit(
+        \\    tb_client_t *client,
+        \\    tb_packet_t *packet
+        \\);
+        \\
+        \\// Closes the client, causing any previously submitted packets to be completed with
+        \\// `TB_PACKET_CLIENT_SHUTDOWN` before freeing any allocated client resources from init.
+        \\// Return value: `TB_CLIENT_OK` on success, or `TB_CLIENT_INVALID` if the client handle was
+        \\// not initialized or has already been closed.
+        \\TB_CLIENT_STATUS tb_client_deinit(
+        \\    tb_client_t *client
+        \\);
+        \\
+        \\// Registers or unregisters the application log callback.
+        \\TB_REGISTER_LOG_CALLBACK_STATUS tb_client_register_log_callback(
+        \\    void (*callback)(TB_LOG_LEVEL, const uint8_t*, uint32_t),
+        \\    bool debug
+        \\);
+        \\
+        \\
+    , .{});
+
+    try buffer.writer().print(
+        \\#ifdef __cplusplus
+        \\}} // extern "C"
+        \\#endif
+        \\
+        \\#endif // TB_CLIENT_H
+        \\
+    , .{});
+
+    try std.io.getStdOut().writeAll(buffer.items);
+}