nl 0.2.4 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 125daafb96b4c4e1147421c6482219e9158ad31d0827859a61c86d97f506c62a
-  data.tar.gz: ed544d00ae8fa14525e75e913bf3e6e36931c520d9dbdc86d79a10dcbf859310
+  metadata.gz: 06d7f10231a9e4b6ce47149f17099f6c72eaad8c72101ac768d3413ee1a8b12b
+  data.tar.gz: 9ecf3d32020db7cebc41de402a6e47b524aa3146db8d935cdba467d31faeda6d
 SHA512:
-  metadata.gz: d9af220cb3e60bb8a30124c50304a8916679ca5f2b559ecc17828312a522ad73244e5ab9ff22b337641be93a9907f86790b0c6a9e2118533abd853e687d77349
-  data.tar.gz: d35efcdb26611ca0eba7d422280c96caafee84b39e988a453dd3c3ef23a05294a5d767e1b9f0cd515e0d3224ba04ff8a345b7edd759348dbd095d20d47cc2506
+  metadata.gz: 4ec97708c16968c722830441a0755419ebb38e5740c11a996d4ea7e6f9f07dec1803877159eb248096b069c4c1808398777fd13aff5c6aa92a8dafc47d901bf7
+  data.tar.gz: 112cfdc2829d1e6f135995315cf1fa3ef3b3aa81e1ba5ac47da3011e029113bb04a6a6c2e4a369346a38cb08a8735bb021d52b1eba0a0d540d31559f6337e71c

data/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## Unreleased
 
+## v0.3.0 (2026-09-01)
+
+- Fix encoding of nested attributes and mark them with `NLA_F_NESTED`.
+- Support encoding and decoding of nested type-value attributes.
+- Support multiplexing requests via `Family.async`
+- Support receiving notifications (unsolicited messages).
+- Rename `Genl::Connection#open` to `Genl::Connection#family`.
+
 ## v0.2.4 (2026-08-22)
 
 ## v0.2.3 (2026-03-24)

data/lib/nl/async/dispatcher.rb

@@ -0,0 +1,199 @@
+# rbs_inline: enabled
+
+require_relative '../datagram'
+require_relative '../error'
+require_relative '../exchange'
+require_relative '../notification_router'
+require_relative '../sequence_allocator'
+
+module Nl
+  module Async
+    # Owns the single receive loop for a socket and routes replies by sequence.
+    class Dispatcher
+      Pending = Data.define(:exchange, :protocol, :reply_class, :sink)
+      private_constant :Pending
+
+      def initialize(socket, executor: :thread, notifications:)
+        @socket = socket
+        @sequences = SequenceAllocator.new
+        @notifications = notifications
+        @driver = executor.respond_to?(:start) ? executor : Async.driver(executor)
+        @mutex = Mutex.new
+        @send_mutex = Mutex.new
+        @pending = {}
+        @closed = false
+        @task = @driver.start { receive_loop }
+      end
+
+      def exchange(protocol, kind, request_class, reply_class, args, &block)
+        operation = exchange_async(protocol, kind, request_class, reply_class, args)
+        if kind == :dump
+          if block
+            operation.each(&block)
+            nil
+          else
+            operation.to_a
+          end
+        else
+          operation.await
+        end
+      end
+
+      def exchange_async(protocol, kind, request_class, reply_class, args, stream_capacity: nil)
+        request = protocol.build_request(kind, request_class, args)
+
+        key = nil
+        seq = pid = nil
+        operation = sink = nil
+        @send_mutex.synchronize do
+          @mutex.synchronize do
+            raise ClosedError, 'dispatcher is closed' if @closed
+
+            pid = @socket.local_port_id
+            seq = @sequences.next { @pending.key?([it, pid]) }
+            key = [seq, pid]
+            mailbox = Mailbox.new(capacity: stream_capacity)
+            operation, sink = if kind == :dump
+              Stream.build(mailbox:, on_close: -> { discard(key) })
+            else
+              Future.build(mailbox:, on_close: -> { discard(key) })
+            end
+            exchange = Exchange.new(kind:, expects_reply: !reply_class.nil?)
+            @pending[key] = Pending.new(exchange:, protocol:, reply_class:, sink:)
+          end
+
+          begin
+            protocol.send_message(@socket, request, seq:, pid:)
+          rescue Exception => error
+            fail_pending(key, error)
+            raise
+          end
+        end
+        operation
+      end
+
+      def async_capable? #: true
+        true
+      end
+
+      def receive_notification(protocol, timeout: nil)
+        @notifications.channel(protocol).pop(timeout:)
+      end
+
+      def close
+        task = @mutex.synchronize do
+          next if @closed
+
+          @closed = true
+          @socket.close unless @socket.closed?
+          @task
+        end
+        fail_all(ClosedError.new('dispatcher is closed'))
+        @driver.stop(task) if task && !task.equal?(::Thread.current)
+        nil
+      end
+
+      private def receive_loop
+        loop do
+          break if @mutex.synchronize { @closed }
+
+          @socket.wait_readable
+          data = @socket.recvmsg_nonblock(exception: false)
+          next if data == :wait_readable
+
+          dispatch_datagram(IO::Buffer.for(data.first))
+        rescue Errno::ENOBUFS => e
+          @notifications.lose_all(NotificationLossError.new('kernel receive buffer overflowed'))
+          fail_all(e)
+        end
+      rescue Exception => e
+        fail_receive_loop(e)
+      end
+
+      private def fail_receive_loop(error)
+        failed = @mutex.synchronize do
+          next false if @closed
+
+          @closed = true
+          @socket.close unless @socket.closed?
+          true
+        end
+        return unless failed
+
+        fail_all(error)
+        @notifications.close
+      end
+
+      private def dispatch_datagram(buffer)
+        Datagram.each_frame(buffer) do |header, payload|
+          key = [header.seq, header.pid]
+          pending = @mutex.synchronize { @pending[key] }
+          unless pending
+            @notifications.route(header, payload) if header.seq.zero?
+            next
+          end
+
+          begin
+            message = pending.protocol.decode_frame(header, payload, pending.reply_class)
+            dispatch_outcome(key, pending, pending.exchange.accept(message))
+          rescue Exception => error
+            fail_pending(key, error) if pending
+          end
+        end
+      end
+
+      private def dispatch_outcome(key, pending, outcome)
+        return unless outcome
+
+        case outcome
+        when Exchange::Item
+          begin
+            pending.sink.push(outcome.value)
+          rescue Mailbox::FullError
+            fail_pending(key, StreamOverflowError.new("reply buffer exceeded for sequence #{key.first}"))
+          end
+        when Exchange::Complete
+          complete_pending(key, pending, pending.exchange.result)
+        when Exchange::Failure
+          fail_pending(key, outcome.exception)
+        end
+      end
+
+      private def complete_pending(key, pending, value)
+        removed = @mutex.synchronize { @pending.delete(key) }
+        return unless removed
+        return if pending.exchange.cancelled?
+
+        if pending.exchange.kind == :dump
+          pending.sink.finish
+        elsif pending.exchange.expects_reply?
+          pending.sink.succeed(value)
+        else
+          pending.sink.finish
+        end
+      end
+
+      private def discard(key)
+        @mutex.synchronize do
+          if pending = @pending[key]
+            pending.exchange.cancel
+          end
+        end
+      end
+
+      private def fail_pending(key, error)
+        pending = @mutex.synchronize { @pending.delete(key) }
+        pending&.sink&.fail(error) unless pending&.exchange&.cancelled?
+      end
+
+      private def fail_all(error)
+        pending = @mutex.synchronize do
+          old = @pending.values
+          @pending.clear
+          old
+        end
+        pending.each { it.sink.fail(error) unless it.exchange.cancelled? }
+      end
+    end
+  end
+end

data/lib/nl/async/driver.rb

@@ -0,0 +1,39 @@
+# rbs_inline: enabled
+
+module Nl
+  module Async
+    module Drivers
+      class Thread
+        def start(&block)
+          ::Thread.new(&block)
+        end
+
+        def stop(task)
+          task.join
+        end
+      end
+
+      class Fiber
+        def start(&block)
+          raise ArgumentError, 'Fiber.scheduler is not installed' unless ::Fiber.scheduler
+
+          ::Fiber.schedule(&block)
+        end
+
+        def stop(_task)
+          # Scheduled fibers have no general join operation. Closing the socket
+          # makes the receive loop terminate at its next scheduling point.
+        end
+      end
+    end
+
+    def self.driver(name)
+      case name
+      when :thread then Drivers::Thread.new
+      when :fiber then Drivers::Fiber.new
+      else
+        raise ArgumentError, "unknown async executor: #{name.inspect}"
+      end
+    end
+  end
+end

data/lib/nl/async/mailbox.rb

@@ -0,0 +1,83 @@
+# rbs_inline: enabled
+
+require_relative '../error'
+
+module Nl
+  module Async
+    # A thread-safe, scheduler-aware, single-consumer mailbox.
+    class Mailbox
+      class FullError < StandardError; end
+
+      def initialize(capacity: nil)
+        raise ArgumentError, 'capacity must be positive' if capacity && capacity <= 0
+
+        @mutex = Mutex.new
+        @condition = ConditionVariable.new
+        @queue = []
+        @closed = false
+        @capacity = capacity
+      end
+
+      # Adds a value without executing consumer code.
+      # @rbs (untyped) -> bool
+      def push(value)
+        push_value(value, enforce_capacity: true)
+      end
+
+      # Adds a completion/error event even when the value capacity is full.
+      def push_terminal(value)
+        push_value(value, enforce_capacity: false)
+      end
+
+      private def push_value(value, enforce_capacity:)
+        @mutex.synchronize do
+          return false if @closed
+          if enforce_capacity && @capacity && @queue.length >= @capacity
+            raise FullError, 'mailbox capacity exceeded'
+          end
+
+          wake = @queue.empty?
+          @queue << value
+          @condition.signal if wake
+        end
+        true
+      end
+
+      # Removes the next value, suspending through the current thread or Fiber scheduler if empty.
+      # @rbs (?timeout: Numeric?) -> untyped
+      def pop(timeout: nil)
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout if timeout
+
+        @mutex.synchronize do
+          loop do
+            return @queue.shift unless @queue.empty?
+            raise ClosedError if @closed
+
+            remaining = deadline && deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            raise TimeoutError if remaining && remaining <= 0
+
+            @condition.wait(@mutex, remaining)
+          end
+        end
+      end
+
+      def close
+        @mutex.synchronize do
+          return nil if @closed
+
+          @closed = true
+          @condition.broadcast
+        end
+        nil
+      end
+
+      def closed?
+        @mutex.synchronize { @closed }
+      end
+
+      def empty?
+        @mutex.synchronize { @queue.empty? }
+      end
+    end
+  end
+end

data/lib/nl/async/operation.rb

@@ -0,0 +1,279 @@
+# rbs_inline: enabled
+
+require_relative '../error'
+
+module Nl
+  module Async
+    module Events
+      Item = Data.define(:value)
+      Done = Data.define
+      Error = Data.define(:exception)
+    end
+    private_constant :Events
+
+    class ConcurrentConsumptionError < StandardError; end
+    class StreamOverflowError < StandardError; end
+
+    # Future for the result of an already-started, single-reply operation.
+    # @rbs generic out Result
+    class Future
+      def self.build(mailbox: Mailbox.new, on_close: nil)
+        operation = new(mailbox:, on_close:)
+        [operation, Sink.new(mailbox)]
+      end
+
+      def initialize(mailbox:, on_close:)
+        @mailbox = mailbox
+        @on_close = on_close
+        @mutex = Mutex.new
+        @state = :open
+        @value = nil
+        @error = nil
+      end
+
+      # @rbs (?timeout: Numeric?) -> Result
+      def await(timeout: nil)
+        return terminal_result unless @mutex.synchronize { @state == :open }
+
+        event = @mailbox.pop(timeout:)
+        case event
+        when Events::Item
+          settle_done(event.value)
+        when Events::Done
+          settle_done(nil)
+        when Events::Error
+          settle_failed(event.exception)
+        end
+        @mailbox.close
+        terminal_result
+      rescue ClosedError
+        terminal_result
+      end
+      alias value await
+
+      def ready? #: bool
+        @mutex.synchronize { @state != :open } || !@mailbox.empty?
+      end
+
+      # Stops local delivery. The dispatcher still drains the Netlink exchange.
+      def close #: nil
+        closed, callback = @mutex.synchronize do
+          next [false, nil] if @state != :open
+
+          @state = :closed
+          [true, @on_close]
+        end
+        if closed
+          callback&.call
+          @mailbox.close
+        end
+        nil
+      end
+
+      private def settle_done(value)
+        @mutex.synchronize do
+          if @state == :open
+            @state = :done
+            @value = value
+          end
+        end
+      end
+
+      private def settle_failed(error)
+        @mutex.synchronize do
+          if @state == :open
+            @state = :failed
+            @error = error
+          end
+        end
+      end
+
+      private def terminal_result
+        state, value, error = @mutex.synchronize { [@state, @value, @error] }
+        case state
+        when :done then value
+        when :failed then raise error
+        else raise ClosedError, 'future is closed'
+        end
+      end
+
+      class Sink
+        def initialize(mailbox)
+          @mailbox = mailbox
+        end
+
+        def succeed(value) = @mailbox.push(Events::Item.new(value))
+        def finish = @mailbox.push_terminal(Events::Done.new)
+        def fail(exception) = @mailbox.push_terminal(Events::Error.new(exception))
+      end
+    end
+
+    # Single-pass consumer handle for a multipart Netlink operation.
+    # @rbs generic out Item
+    class Stream
+      include Enumerable #[Item]
+
+      def self.build(mailbox: Mailbox.new, on_close: nil)
+        operation = new(mailbox:, on_close:)
+        [operation, Sink.new(mailbox)]
+      end
+
+      def initialize(mailbox:, on_close:)
+        @mailbox = mailbox
+        @on_close = on_close
+        @mutex = Mutex.new
+        @owner = nil
+        @state = :open
+        @error = nil
+      end
+
+      # @rbs () { (Item) -> void } -> self
+      #    | () -> Enumerator[Item, self]
+      def each
+        return enum_for(__method__) unless block_given?
+
+        state, error = current_state
+        case state
+        when :completed then return self
+        when :closed then raise ClosedError, 'stream is closed'
+        when :failed then raise error
+        end
+
+        claim_consumer!
+        begin
+          loop do
+            case event = @mailbox.pop
+            when Events::Item
+              yield event.value
+            when Events::Done
+              completed = mark_completed
+              @mailbox.close
+              terminal_result unless completed
+              break
+            when Events::Error
+              failed = mark_failed(event.exception)
+              @mailbox.close
+              raise event.exception if failed
+
+              terminal_result
+            end
+          end
+          self
+        rescue ClosedError
+          terminal_result
+        ensure
+          close if open?
+        end
+      end
+
+      # @rbs (?timeout: Numeric?) -> Item
+      def next(timeout: nil)
+        state, error = current_state
+        case state
+        when :completed then raise StopIteration
+        when :closed then raise ClosedError, 'stream is closed'
+        when :failed then raise error
+        end
+
+        claim_consumer!
+        case event = @mailbox.pop(timeout:)
+        when Events::Item
+          event.value
+        when Events::Done
+          completed = mark_completed
+          @mailbox.close
+          raise StopIteration if completed
+
+          terminal_result(next_item: true)
+        when Events::Error
+          failed = mark_failed(event.exception)
+          @mailbox.close
+          raise event.exception if failed
+
+          terminal_result(next_item: true)
+        end
+      rescue ClosedError
+        terminal_result(next_item: true)
+      end
+
+      # Stops local delivery. The dispatcher still drains the Netlink exchange.
+      def close #: nil
+        closed, callback = @mutex.synchronize do
+          next [false, nil] if @state != :open
+
+          @state = :closed
+          [true, @on_close]
+        end
+        if closed
+          callback&.call
+          @mailbox.close
+        end
+        nil
+      end
+
+      def closed? #: bool
+        @mutex.synchronize { @state != :open }
+      end
+
+      private def current_state
+        @mutex.synchronize { [@state, @error] }
+      end
+
+      private def open?
+        @mutex.synchronize { @state == :open }
+      end
+
+      private def claim_consumer!
+        owner = Fiber.current
+        @mutex.synchronize do
+          @owner ||= owner
+          unless @owner.equal?(owner)
+            raise ConcurrentConsumptionError, 'a stream can only be consumed by one fiber'
+          end
+        end
+      end
+
+      private def mark_completed
+        @mutex.synchronize do
+          next false unless @state == :open
+
+          @state = :completed
+          true
+        end
+      end
+
+      private def mark_failed(error)
+        @mutex.synchronize do
+          next false unless @state == :open
+
+          @state = :failed
+          @error = error
+          true
+        end
+      end
+
+      private def terminal_result(next_item: false)
+        state, error = current_state
+        case state
+        when :completed
+          raise StopIteration if next_item
+          self
+        when :failed
+          raise error
+        else
+          raise ClosedError, 'stream is closed'
+        end
+      end
+
+      class Sink
+        def initialize(mailbox)
+          @mailbox = mailbox
+        end
+
+        def push(value) = @mailbox.push(Events::Item.new(value))
+        def finish = @mailbox.push_terminal(Events::Done.new)
+        def fail(exception) = @mailbox.push_terminal(Events::Error.new(exception))
+      end
+    end
+  end
+end

data/lib/nl/async.rb

@@ -0,0 +1,15 @@
+# rbs_inline: enabled
+
+require_relative 'error'
+
+module Nl
+  # Asynchronous request handling support.
+  module Async
+    class UnavailableError < StandardError; end
+  end
+end
+
+require_relative 'async/mailbox'
+require_relative 'async/operation'
+require_relative 'async/driver'
+require_relative 'async/dispatcher'