tigerbeetle 0.0.40 → 0.17.8

data/src/tigerbeetle/client.rb

@@ -0,0 +1,129 @@
+module TigerBeetle
+  # TigerBeetle client.
+  #
+  # A client can be shared by concurrent threads and fibers for request methods.
+  # Public request methods are synchronous and return after the request
+  # completes. When a fiber scheduler is active, waiting for a response yields
+  # to the scheduler.
+  #
+  # Prefer {.open} for lifecycle management so the client is closed once after
+  # concurrent work completes. Instantiate multiple clients when connecting to
+  # more than one TigerBeetle cluster.
+  class Client
+    Client::COMPLETION_DISPATCHER = CompletionDispatcher.new
+    private_constant :COMPLETION_DISPATCHER
+
+    # Opens a client for the duration of the block and closes it before
+    # returning.
+    #
+    # Yields the open client and returns the block return value.
+    def self.open(cluster_id:, replica_addresses:)
+      client = new(cluster_id: cluster_id, replica_addresses: replica_addresses)
+      yield client
+    ensure
+      client&.close
+    end
+
+    # Initializes a TigerBeetle client.
+    #
+    # @raise [TigerBeetle::InitError] if the native client cannot be
+    #   initialized.
+    def initialize(cluster_id:, replica_addresses:)
+      @native = NativeClient.new(cluster_id, replica_addresses, COMPLETION_DISPATCHER.write_fileno)
+      @closed = false
+    end
+
+    # Closes the client. This method waits for all in-flight requests to finish.
+    #
+    # @raise [TigerBeetle::ClientClosedError] if the client is already closed.
+    def close
+      raise ClientClosedError, "client is already closed" if closed?
+
+      @closed = true
+      @native.close
+    end
+
+    # Returns whether the client has been closed.
+    def closed?
+      @closed
+    end
+
+    # Submits a batch of new accounts to be created.
+    #
+    # The returned array contains one {TigerBeetle::CreateAccountResult} for
+    # each submitted account.
+    #
+    # @raise [TigerBeetle::PacketError] if the entire request fails.
+    # @raise [TigerBeetle::ClientClosedError] if the client is closed.
+    def create_accounts(accounts) = native_submit(Operation::CREATE_ACCOUNTS, accounts)
+
+    # Submits a batch of new transfers to be created.
+    #
+    # The returned array contains one {TigerBeetle::CreateTransferResult} for
+    # each submitted transfer.
+    #
+    # @raise [TigerBeetle::PacketError] if the entire request fails.
+    # @raise [TigerBeetle::ClientClosedError] if the client is closed.
+    def create_transfers(transfers) = native_submit(Operation::CREATE_TRANSFERS, transfers)
+
+    # Looks up a batch of accounts.
+    #
+    # The returned array contains all accounts found. Accounts not found are
+    # omitted.
+    #
+    # @raise [TigerBeetle::PacketError] if the entire request fails.
+    # @raise [TigerBeetle::ClientClosedError] if the client is closed.
+    def lookup_accounts(ids) = native_submit(Operation::LOOKUP_ACCOUNTS, ids)
+
+    # Looks up a batch of transfers.
+    #
+    # The returned array contains all transfers found. Transfers not found are
+    # omitted.
+    #
+    # @raise [TigerBeetle::PacketError] if the entire request fails.
+    # @raise [TigerBeetle::ClientClosedError] if the client is closed.
+    def lookup_transfers(ids) = native_submit(Operation::LOOKUP_TRANSFERS, ids)
+
+    # Fetches transfers from a given account.
+    #
+    # Returns transfers that match the query parameters.
+    # @raise [TigerBeetle::PacketError] if the entire request fails.
+    # @raise [TigerBeetle::ClientClosedError] if the client is closed.
+    def get_account_transfers(filter) = native_submit(Operation::GET_ACCOUNT_TRANSFERS, [filter])
+
+    # Fetches balance history from a given account.
+    #
+    # Returns balances that match the query parameters.
+    # @raise [TigerBeetle::PacketError] if the entire request fails.
+    # @raise [TigerBeetle::ClientClosedError] if the client is closed.
+    def get_account_balances(filter) = native_submit(Operation::GET_ACCOUNT_BALANCES, [filter])
+
+    # Queries accounts.
+    #
+    # Returns accounts that match the query parameters.
+    # @raise [TigerBeetle::PacketError] if the entire request fails.
+    # @raise [TigerBeetle::ClientClosedError] if the client is closed.
+    def query_accounts(filter) = native_submit(Operation::QUERY_ACCOUNTS, [filter])
+
+    # Queries transfers.
+    #
+    # Returns transfers that match the query parameters.
+    # @raise [TigerBeetle::PacketError] if the entire request fails.
+    # @raise [TigerBeetle::ClientClosedError] if the client is closed.
+    def query_transfers(filter) = native_submit(Operation::QUERY_TRANSFERS, [filter])
+
+    private
+
+    def native_submit(operation, payload)
+      raise ClientClosedError if closed?
+
+      req = COMPLETION_DISPATCHER.submit_and_wait_for(@native, operation, payload)
+
+      status, result = req.result
+      raise ClientClosedError if status == PACKET_CLIENT_SHUTDOWN
+      raise PacketError, status unless status == PACKET_OK
+
+      result
+    end
+  end
+end

data/src/tigerbeetle/completion_dispatcher.rb

@@ -0,0 +1,108 @@
+module TigerBeetle
+  class CompletionDispatcher
+    COMPLETION_ID_BYTES = 8
+
+    class Completion
+      def initialize
+        @mutex = Mutex.new
+        @condition = ConditionVariable.new
+        @done = false
+      end
+
+      def done?
+        @done
+      end
+
+      def wait
+        @mutex.synchronize { @condition.wait(@mutex) until done? }
+      end
+
+      def complete
+        @mutex.synchronize do
+          @done = true
+          @condition.broadcast
+        end
+      end
+    end
+
+    def initialize
+      @read_io, @write_io = IO.pipe
+      @pending = {}
+      @completed_ids = {}
+      @cancelled_ids = {}
+      @mutex = Mutex.new
+      @thread = Thread.new { dispatch_completions }
+    end
+
+    def write_fileno
+      @write_io.fileno
+    end
+
+    def completion_for(request_id)
+      completion = Completion.new
+      completion.complete if register(request_id, completion)
+      completion
+    end
+
+    def submit_and_wait_for(native, operation, payload)
+      request = native.submit(operation, payload)
+      completion = completion_for(request.id)
+      completion.wait
+      request
+    ensure
+      unregister(request.id, completion) if request
+    end
+
+    def unregister(request_id, completion)
+      @mutex.synchronize do
+        @pending.delete(request_id)
+        @completed_ids.delete(request_id)
+        @cancelled_ids[request_id] = true unless completion&.done?
+      end
+    end
+
+    private
+
+    def register(request_id, completion)
+      @mutex.synchronize do
+        if @completed_ids.delete(request_id)
+          true
+        else
+          @pending[request_id] = completion
+          false
+        end
+      end
+    end
+
+    def dispatch_completions
+      loop do
+        request_id = read_completion_id
+        completion = @mutex.synchronize do
+          completion = @pending[request_id]
+          if completion
+            completion
+          elsif @cancelled_ids.delete(request_id)
+            nil
+          else
+            @completed_ids[request_id] = true
+            nil
+          end
+        end
+
+        completion&.complete
+      end
+
+    rescue IOError, ClientClosedError
+      nil
+    end
+
+    def read_completion_id
+      bytes = @read_io.read(COMPLETION_ID_BYTES)
+      raise ClientClosedError unless bytes
+
+      bytes.unpack1("Q")
+    end
+  end
+
+  private_constant :CompletionDispatcher
+end

data/src/tigerbeetle/id.rb

@@ -0,0 +1,40 @@
+require "securerandom"
+
+module TigerBeetle
+  class ID
+    RANDOM_MAX = 2 ** 80
+    TIMESTAMP_MAX = 2 ** 48
+
+    def initialize
+      @last_ms = Process.clock_gettime(Process::CLOCK_REALTIME, :millisecond)
+      @random = next_random
+    end
+
+    def generate
+      ms = Process.clock_gettime(Process::CLOCK_REALTIME, :millisecond)
+      if ms <= @last_ms
+        ms = @last_ms
+      else
+        @last_ms = ms
+        @random = next_random
+      end
+
+      @random += 1
+      if @random >= RANDOM_MAX
+        @last_ms += 1
+        raise "Timestamp bits overflow on monotonic increment" if @last_ms >= TIMESTAMP_MAX
+        @random = 0
+      end
+
+      (@last_ms << 80) | @random
+    end
+
+    private
+
+    def next_random
+      # See: https://docs.ruby-lang.org/en/4.0/language/packed_data_rdoc.html#label-For+Integers
+      lo, hi = SecureRandom.bytes(10).unpack("Q<S<")
+      lo | (hi << 64)
+    end
+  end
+end

data/src/tigerbeetle/tb.rb

@@ -0,0 +1,3 @@
+require "tigerbeetle"
+
+TB = TigerBeetle

data/src/tigerbeetle/version.rb

@@ -0,0 +1,3 @@
+module TigerBeetle
+  VERSION = "0.17.8"
+end

data/src/tigerbeetle.rb

@@ -0,0 +1,39 @@
+require_relative "tigerbeetle/version"
+require_relative "tigerbeetle/bindings"
+require_relative "tigerbeetle/id"
+require_relative "tigerbeetle/completion_dispatcher"
+require_relative "tigerbeetle/client"
+
+native_extension = "tigerbeetle/tigerbeetle"
+
+# Since we ship a fat binary gem, enable the bundled DLL path before loading the extension.
+if Gem.win_platform?
+  dll_path = File.expand_path("ext/tigerbeetle/lib/x86_64-windows", __dir__)
+
+  begin
+    require "ruby_installer/runtime"
+    RubyInstaller::Runtime.add_dll_directory(dll_path) do
+      require native_extension
+    end
+  rescue LoadError
+    old_path = ENV["PATH"]
+    ENV["PATH"] = "#{dll_path};#{old_path}"
+    require native_extension
+  ensure
+    ENV["PATH"] = old_path if defined?(old_path)
+  end
+else
+  require native_extension
+end
+
+module TigerBeetle
+  private_constant :NativeClient
+  private_constant :Request
+
+  @id_generator = ID.new
+
+  # Generates a 128-bit, time-based, monotonically increasing ID.
+  def self.id
+    @id_generator.generate
+  end
+end