omq-ffi 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 88e0942ce849494a8af0baa0cc5d894a27c6c64c7ea2e15a726a203df262296d
-  data.tar.gz: 4d9e966c9bbdb5317112dd1aed5f7037f4b911f3096cfe3e103f75dbd019588d
+  metadata.gz: 9b5a378abbdf658759dccc080ebec5318858fe6a20cc770014d1e18b6e5fe3ff
+  data.tar.gz: ee71fd919f1315a3590b0eb464063e0056d6b3644cfe4ec98207eb2e74aebacd
 SHA512:
-  metadata.gz: 83f0e5f7e637634e5d07a56d91f4e3887b4d542b3cad88fc2189755b3857b01693871a10f0a5a2c4939981b634acd3a7915e8cd247947694fdb9c3afe4ce74d6
-  data.tar.gz: 4f1e5da9f453d8fa90816b16c712e718e1ad7855be0dfa53fa18582cbb52c217057034e2dbe1c432b073c12a0d50debc21989321817e4462bec927637c2fdfeb
+  metadata.gz: bf6657d8e08d5f7820ca88b341baa8543f96be2d3454c8298913c3c9f056ef907c4b80b9cd73bd67dd1a62e1c9ddfcc09e14cd3d56d110a5f70642ac208c48ae
+  data.tar.gz: d74ee202abb7788a0b6f6a65151a884095bf9dd7cdc3acd46e2d438999f40a669ddd5bb66e20981975b5ae84bf0b2d97855ae1122180ff82c44bcd4fd2fa7dc2

data/README.md

@@ -1,5 +1,10 @@
 # OMQ::FFI -- libzmq Backend for OMQ
 
+[![CI](https://github.com/paddor/omq-ffi/actions/workflows/ci.yml/badge.svg)](https://github.com/paddor/omq-ffi/actions/workflows/ci.yml)
+[![Gem Version](https://img.shields.io/gem/v/omq-ffi?color=e9573f)](https://rubygems.org/gems/omq-ffi)
+[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](LICENSE)
+[![Ruby](https://img.shields.io/badge/Ruby-%3E%3D%203.3-CC342D?logo=ruby&logoColor=white)](https://www.ruby-lang.org)
+
 Use libzmq under the same OMQ socket API. Requires libzmq 4.x installed
 on the system.
 

data/lib/omq/ffi/engine.rb

@@ -13,38 +13,75 @@ module OMQ
     class Engine
       L = Libzmq
 
-      attr_reader :options, :last_endpoint, :last_tcp_port, :connections, :routing
-      attr_reader :peer_connected, :all_peers_gone
+
+      # @return [Options] socket options
+      attr_reader :options
+      # @return [String, nil] the last endpoint bound or connected
+      attr_reader :last_endpoint
+      # @return [Integer, nil] TCP port of the last endpoint, if applicable
+      attr_reader :last_tcp_port
+      # @return [Array] active connections
+      attr_reader :connections
+      # @return [RoutingStub] subscription/group routing interface
+      attr_reader :routing
+      # @return [Async::Promise] resolved when the first peer connects
+      attr_reader :peer_connected
+      # @return [Async::Promise] resolved when all peers have disconnected
+      attr_reader :all_peers_gone
+      # @param value [Boolean] enables or disables automatic reconnection
       attr_writer :reconnect_enabled
 
       # Routing stub that delegates subscribe/unsubscribe/join/leave to
       # libzmq socket options via the I/O thread.
       #
       class RoutingStub
+        # @return [Async::Promise] resolved when a subscriber joins
         attr_reader :subscriber_joined
 
+        # @param engine [Engine] the parent engine instance
         def initialize(engine)
           @engine            = engine
           @subscriber_joined = Async::Promise.new
         end
 
+
+        # Subscribes to messages matching the given prefix.
+        #
+        # @param prefix [String] subscription prefix
+        # @return [void]
         def subscribe(prefix)
           @engine.send_cmd(:subscribe, prefix.b)
         end
 
+
+        # Removes a subscription for the given prefix.
+        #
+        # @param prefix [String] subscription prefix to remove
+        # @return [void]
         def unsubscribe(prefix)
           @engine.send_cmd(:unsubscribe, prefix.b)
         end
 
+
+        # Joins a DISH group for receiving RADIO messages.
+        #
+        # @param group [String] group name
+        # @return [void]
         def join(group)
           @engine.send_cmd(:join, group)
         end
 
+
+        # Leaves a DISH group.
+        #
+        # @param group [String] group name
+        # @return [void]
         def leave(group)
           @engine.send_cmd(:leave, group)
         end
       end
 
+
       # @param socket_type [Symbol] e.g. :REQ, :PAIR
       # @param options [Options]
       #
@@ -80,8 +117,13 @@ module OMQ
         @io_thread = nil
       end
 
+
       # --- Socket lifecycle ---
 
+      # Binds the socket to the given endpoint.
+      #
+      # @param endpoint [String] ZMQ endpoint URL (e.g. "tcp://*:5555")
+      # @return [void]
       def bind(endpoint)
         sync_identity
         send_cmd(:bind, endpoint)
@@ -91,6 +133,11 @@ module OMQ
         @peer_connected.resolve(:ffi) unless @peer_connected.resolved?
       end
 
+
+      # Connects the socket to the given endpoint.
+      #
+      # @param endpoint [String] ZMQ endpoint URL
+      # @return [void]
       def connect(endpoint)
         sync_identity
         send_cmd(:connect, endpoint)
@@ -100,14 +147,28 @@ module OMQ
         @peer_connected.resolve(:ffi) unless @peer_connected.resolved?
       end
 
+
+      # Disconnects from the given endpoint.
+      #
+      # @param endpoint [String] ZMQ endpoint URL
+      # @return [void]
       def disconnect(endpoint)
         send_cmd(:disconnect, endpoint)
       end
 
+
+      # Unbinds from the given endpoint.
+      #
+      # @param endpoint [String] ZMQ endpoint URL
+      # @return [void]
       def unbind(endpoint)
         send_cmd(:unbind, endpoint)
       end
 
+
+      # Closes the socket and shuts down the I/O thread.
+      #
+      # @return [void]
       def close
         return if @closed
         @closed = true
@@ -125,6 +186,10 @@ module OMQ
         @wake_w&.close rescue nil
       end
 
+
+      # Captures the current Async task as the parent for I/O scheduling.
+      #
+      # @return [void]
       def capture_parent_task
         return if @parent_task
         if Async::Task.current?
@@ -136,16 +201,26 @@ module OMQ
         end
       end
 
+
       # --- Send ---
 
+      # Enqueues a multipart message for sending via the I/O thread.
+      #
+      # @param parts [Array<String>] message frames
+      # @return [void]
       def enqueue_send(parts)
         ensure_io_thread
         @send_queue.push(parts)
         wake_io_thread
       end
 
+
       # --- Recv ---
 
+      # Dequeues up to +max+ received messages, blocking until at least one is available.
+      #
+      # @param max [Integer] maximum number of messages to dequeue
+      # @return [Array<Array<String>>] batch of received multipart messages
       def dequeue_recv_batch(max)
         ensure_io_thread
         msg = wait_for_message
@@ -160,11 +235,16 @@ module OMQ
         batch
       end
 
+
+      # Pushes a nil sentinel into the recv queue to unblock a waiting consumer.
+      #
+      # @return [void]
       def dequeue_recv_sentinel
         @recv_queue.push(nil)
         @recv_signal_w.write_nonblock(".", exception: false) rescue nil
       end
 
+
       # Send a control command to the I/O thread.
       # @api private
       #
@@ -178,6 +258,10 @@ module OMQ
         r
       end
 
+
+      # Wakes the I/O thread via the internal pipe.
+      #
+      # @return [void]
       def wake_io_thread
         @wake_w.write_nonblock(".", exception: false)
       end
@@ -199,11 +283,13 @@ module OMQ
         end
       end
 
+
       def ensure_io_thread
         return if @io_thread
         @io_thread = Thread.new { io_loop }
       end
 
+
       # The I/O loop runs on a dedicated thread. It owns the zmq_socket
       # exclusively and processes commands, sends, and recvs.
       #
@@ -226,6 +312,7 @@ module OMQ
         L.zmq_close(@zmq_socket)
       end
 
+
       def zmq_has_events?
         @events_buf ||= ::FFI::MemoryPointer.new(:int)
         @events_len ||= ::FFI::MemoryPointer.new(:size_t).tap { |p| p.write(:size_t, ::FFI.type_size(:int)) }
@@ -233,6 +320,7 @@ module OMQ
         @events_buf.read_int != 0
       end
 
+
       def drain_cmds
         loop do
           begin
@@ -244,6 +332,7 @@ module OMQ
         end
       end
 
+
       def process_cmd(cmd)
         name, args, result = cmd
         case name
@@ -284,6 +373,7 @@ module OMQ
         true
       end
 
+
       def try_recv
         loop do
           parts = recv_multipart_nonblock
@@ -293,6 +383,7 @@ module OMQ
         end
       end
 
+
       def drain_sends
         @pending_send ||= nil
         loop do
@@ -310,6 +401,7 @@ module OMQ
         end
       end
 
+
       # Returns true if fully sent, false if would block (HWM).
       #
       def send_multipart_nonblock(parts)
@@ -328,6 +420,7 @@ module OMQ
         true
       end
 
+
       def recv_multipart_nonblock
         parts = []
         loop do
@@ -349,6 +442,7 @@ module OMQ
         parts.empty? ? nil : parts
       end
 
+
       def rcvmore?
         buf = ::FFI::MemoryPointer.new(:int)
         len = ::FFI::MemoryPointer.new(:size_t)
@@ -357,6 +451,7 @@ module OMQ
         buf.read_int != 0
       end
 
+
       def get_zmq_fd
         buf = ::FFI::MemoryPointer.new(:int)
         len = ::FFI::MemoryPointer.new(:size_t)
@@ -365,6 +460,7 @@ module OMQ
         buf.read_int
       end
 
+
       # Re-syncs identity to libzmq (user may set it after construction).
       #
       def sync_identity
@@ -374,6 +470,7 @@ module OMQ
         end
       end
 
+
       def apply_options
         set_int_option(L::ZMQ_SNDHWM, @options.send_hwm)
         set_int_option(L::ZMQ_RCVHWM, @options.recv_hwm)
@@ -401,23 +498,27 @@ module OMQ
         set_int_option(L::ZMQ_ROUTER_MANDATORY, 1) if @options.router_mandatory
       end
 
+
       def set_int_option(opt, value)
         buf = ::FFI::MemoryPointer.new(:int)
         buf.write_int(value)
         L.zmq_setsockopt(@zmq_socket, opt, buf, ::FFI.type_size(:int))
       end
 
+
       def set_int64_option(opt, value)
         buf = ::FFI::MemoryPointer.new(:int64)
         buf.write_int64(value)
         L.zmq_setsockopt(@zmq_socket, opt, buf, ::FFI.type_size(:int64))
       end
 
+
       def set_bytes_option(opt, value)
         buf = ::FFI::MemoryPointer.from_string(value)
         L.zmq_setsockopt(@zmq_socket, opt, buf, value.bytesize)
       end
 
+
       def get_string_option(opt)
         buf = ::FFI::MemoryPointer.new(:char, 256)
         len = ::FFI::MemoryPointer.new(:size_t)
@@ -426,6 +527,7 @@ module OMQ
         buf.read_string(len.read(:size_t) - 1)
       end
 
+
       def extract_tcp_port(endpoint)
         return nil unless endpoint
         port = endpoint.split(":").last.to_i
@@ -433,8 +535,10 @@ module OMQ
       end
     end
 
-    # Shared ZMQ context — one per process.
+
+    # Returns the shared ZMQ context (one per process, lazily initialized).
     #
+    # @return [FFI::Pointer] zmq context pointer
     def self.context
       @context ||= Libzmq.zmq_ctx_new.tap do |ctx|
         raise "zmq_ctx_new failed" if ctx.null?

data/lib/omq/ffi/libzmq.rb

@@ -44,6 +44,7 @@ module OMQ
         # libzmq built without ZMQ_BUILD_DRAFT_API
       end
 
+
       # Error
       attach_function :zmq_errno,    [], :int
       attach_function :zmq_strerror, [:int], :string
@@ -69,6 +70,7 @@ module OMQ
       ZMQ_PEER    = 19
       ZMQ_CHANNEL = 20
 
+
       # Socket type name → constant
       SOCKET_TYPES = {
         PAIR: ZMQ_PAIR, PUB: ZMQ_PUB, SUB: ZMQ_SUB,
@@ -86,6 +88,7 @@ module OMQ
       ZMQ_DONTWAIT = 1
       ZMQ_SNDMORE  = 2
 
+
       # Socket options
       ZMQ_IDENTITY     = 5
       ZMQ_SUBSCRIBE    = 6
@@ -105,9 +108,11 @@ module OMQ
       ZMQ_RECONNECT_IVL_MAX = 21
       ZMQ_CONFLATE     = 54
 
+
       # zmq_msg_t is 64 bytes on all platforms
       MSG_T_SIZE = 64
 
+
       # Allocates a zmq_msg_t on the heap.
       #
       # @return [FFI::MemoryPointer]
@@ -116,6 +121,7 @@ module OMQ
         ::FFI::MemoryPointer.new(MSG_T_SIZE)
       end
 
+
       # Raises an error with the current zmq_errno message.
       #
       def self.check!(rc, label = "zmq")

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: omq-ffi
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Patrik Wenger