asterism 0.2.0 → 0.4.0

data/lib/asterism/cruby/zenoh.rb

@@ -1,5 +1,5 @@
 # Asterism::Zenoh with blocks, threads and Enumerators (CRuby only). The
-# polled API of asterism-zenoh (Session, each_pending, each_reply) is the
+# portable API of asterism-zenoh (Session, each_pending, each_reply) is the
 # same on the boards and stays as it is; this is a layer on top of it.
 #
 #   Asterism::Zenoh.open("tcp/192.0.2.2:7447") do |s|
@@ -8,6 +8,9 @@
 #     s.put("home/pc/hello", "hi")
 #     s.get("home/**/status").each { |reply| p reply }
 #     s.subscribe("sensor/temp").each.lazy.map { _1.payload.to_f }.first(3)
+#     pub = s.publisher("home/pc/temp", encoding: "text/plain")
+#     pub.on_matching { |listening| puts "someone listens: #{listening}" }
+#     s.on_transport { |ev| puts "#{ev.zid} #{ev.kind}" }
 #     s.run                              # until Ctrl-C (or s.start / s.stop)
 #   end
 #
@@ -19,28 +22,8 @@ module Asterism
     # Pause between looks while an Enumerator waits for data (seconds).
     ENUM_STEP = 0.002
 
-    # A received sample. payload and attachment are binary Strings (the
-    # attachment nil when there was none); text is the payload as UTF-8.
-    Sample = Data.define(:key, :payload, :attachment) do
-      def text
-        payload.dup.force_encoding(Encoding::UTF_8)
-      end
-
-      def to_s
-        "#{key}: #{payload}"
-      end
-    end
-
-    # A reply to a get: the key it was sent with, payload and attachment.
-    Reply = Data.define(:key, :payload, :attachment) do
-      def text
-        payload.dup.force_encoding(Encoding::UTF_8)
-      end
-
-      def to_s
-        "#{key}: #{payload}"
-      end
-    end
+    # Sample and Reply (the received values, with kind, encoding,
+    # timestamp and the rest) are asterism-zenoh's (asterism/zenoh/values).
 
     # A liveliness change: key of the token, and whether it appeared.
     Liveliness = Data.define(:key, :alive) do
@@ -57,6 +40,20 @@ module Asterism
         args.unshift(@asterism_key) if args.size == 1 && @asterism_key
         super(*args, **kw)
       end
+
+      # reply_del without a key: the queryable's own key, as reply.
+      def reply_del(key = nil, **kw)
+        super(key || @asterism_key, **kw)
+      end
+
+      def reply_err(payload, **kw)
+        super(payload.is_a?(String) ? payload : payload.to_s, **kw)
+      end
+    end
+
+    # A payload as a String (anything else is sent as to_s).
+    def self.bytes(payload)
+      payload.is_a?(String) ? payload : payload.to_s
     end
 
     # The queryable's key when it names one key (no wildcard).
@@ -83,19 +80,72 @@ module Asterism
       end
     end
 
-    # Seconds (Float) or nil -> milliseconds for the polled API.
+    # Seconds (Float) or nil -> milliseconds for the portable API.
+    # @api private
     def self.ms(seconds, default_ms)
-      return default_ms if seconds.nil?
-      (seconds * 1000).round
+      ::Asterism.time_ms("timeout:", seconds, nil, nil, default_ms)
+    end
+
+    # Warns once for owner (a wrapper, or a Get) when raw (what it wraps)
+    # dropped something. Only for queues whose depth the application left
+    # at the default: one that chose depth: reads dropped itself.
+    # @api private
+    def self.note_dropped(owner, raw, what, unit)
+      d = raw.dropped
+      return false if d == 0
+      ::Asterism.warn_once(owner, "asterism: #{what}: #{d} #{unit} dropped, the queue was full " \
+                                  "(pass a larger depth:, or read dropped)")
+    end
+
+    # The keys liveliness_get returns: an Array, with the counts of the get
+    # behind it.
+    class KeyList < Array
+      # Replies that did not fit the get's queue (oldest first), and all
+      # that came.
+      attr_reader :dropped, :received
+
+      # @api private
+      def finish(get)
+        @dropped = get.dropped
+        @received = get.received
+        self
+      end
+    end
+
+    # What Connection#get and Querier#get return without a block: an
+    # Enumerator (each iteration sends the get again) that also has the
+    # counts of the last get it sent: dropped, received, errors (nil before
+    # the first).
+    class GetEnumerator < Enumerator
+      attr_reader :dropped, :received, :errors
+
+      # @api private
+      def finish(get)
+        @dropped = get.dropped
+        @received = get.received
+        @errors = get.errors
+        self
+      end
+    end
+
+    # Yields obj and closes it after the block (the block's value), or
+    # returns obj without a block. @api private
+    def self.scoped(obj)
+      return obj unless block_given?
+      begin
+        yield obj
+      ensure
+        obj.close
+      end
     end
 
     # Waits on the calling thread until a sample comes into sub (an
     # Asterism::Zenoh::Subscriber or LivelinessWatch), yielding each.
     # Ends when sub or the session closes, or after timeout seconds.
-    def self.drain(sub, session, timeout)
+    def self.drain(sub, session, timeout, take: :each_pending)
       deadline = timeout && (Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout)
       loop do
-        got = sub.each_pending
+        got = sub.public_send(take)
         got.each { |e| yield e }
         break if sub.closed? || session.closed?
         break if deadline && Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
@@ -115,16 +165,75 @@ module Asterism
         @runner.add { @session.poll ? 0 : false }
       end
 
-      def put(key, payload, attachment: nil)
-        @session.put(key, payload.is_a?(String) ? payload : payload.to_s, attachment: attachment)
+      # opts: those of Session#put (attachment:, encoding:, priority:,
+      # congestion_control:, express:, reliability:, timestamp:,
+      # allowed_destination:). A payload that is not a String is sent as
+      # to_s.
+      def put(key, payload, **opts)
+        @session.put(key, Zenoh.bytes(payload), **opts)
+        nil
+      end
+
+      # Deletes key (subscribers get a Sample of kind :delete). opts: those
+      # of Session#delete.
+      def delete(key, **opts)
+        @session.delete(key, **opts)
         nil
       end
 
+      # A declared publisher (Connection::Publisher): put / delete,
+      # matching?, on_matching { |listening| }. opts: those of
+      # Session#publisher (encoding:, priority:, ...). With a block: yields
+      # it and closes it after the block (returns the block's value).
+      def publisher(key, **opts, &blk)
+        Zenoh.scoped(Publisher.new(self, @session.publisher(key, **opts), key), &blk)
+      end
+
+      # An advanced publisher (cache:, sample_miss_detection:,
+      # publisher_detection: and the publisher options): late subscribers
+      # with history get what it kept. Same object as publisher (and the
+      # same block form).
+      def advanced_publisher(key, **opts, &blk)
+        Zenoh.scoped(Publisher.new(self, @session.advanced_publisher(key, **opts), key), &blk)
+      end
+
+      # An advanced subscriber (history:, recovery:, subscriber_detection:,
+      # query_timeout: in seconds or query_timeout_ms:): like subscribe,
+      # plus on_publisher and on_miss.
+      def advanced_subscriber(key, depth: 16, **opts, &blk)
+        sub = AdvancedSubscription.new(self, @session.advanced_subscriber(key, depth: depth, **opts), key)
+        sub.handle(&blk) if blk
+        sub
+      end
+
+      # A declared get (Connection::Querier): get { |reply| }, matching?,
+      # on_matching. timeout: in seconds (2.0) or timeout_ms:; the rest as
+      # Session#querier.
+      def querier(key, timeout: nil, **opts)
+        Querier.new(self, @session.querier(key, timeout: timeout, **opts), key)
+      end
+
+      # on_transport(history: false) { |event| }: a TransportEvent (kind
+      # :added / :removed, zid, whatami) on the receiving thread each time a
+      # peer or router connects or goes. Returns an Events (close it).
+      def on_transport(history: false, depth: 16, &blk)
+        raise ArgumentError, "a block is needed" unless blk
+        Events.new(self, @session.transport_events(depth: depth, history: history), "on_transport", blk)
+      end
+
+      # on_link(history: false) { |event| }: a LinkEvent each time a link
+      # opens or closes.
+      def on_link(history: false, depth: 16, &blk)
+        raise ArgumentError, "a block is needed" unless blk
+        Events.new(self, @session.link_events(depth: depth, history: history), "on_link", blk)
+      end
+
       # With a block: every sample is given to it (as a Sample) on the
       # receiving thread; returns the Subscription (close it to stop).
-      # Without: a Subscription to take from (each, each_pending).
-      def subscribe(key, depth: 16, &blk)
-        sub = Subscription.new(self, @session.subscribe(key, depth), key)
+      # Without: a Subscription to take from (each, each_sample).
+      def subscribe(key, depth: nil, &blk)
+        d = depth.nil? ? DEFAULT_DEPTH : depth
+        sub = Subscription.new(self, @session.subscribe(key, depth: d), key, warn: depth.nil?)
         sub.handle(&blk) if blk
         sub
       end
@@ -133,47 +242,65 @@ module Asterism
       # finished when it returns (reply in the block with q.reply). Without:
       # a Queryable whose each yields the queries (finished after each).
       def queryable(key, depth: 16, complete: false, &blk)
-        qa = Queryable.new(self, @session.queryable(key, depth, complete: complete), key)
+        qa = Queryable.new(self, @session.queryable(key, depth: depth, complete: complete), key)
         qa.handle(&blk) if blk
         qa
       end
 
       # The replies to a get: yields each Reply until every answer came or
-      # timeout (seconds) ran out, and returns their number. Without a
-      # block, an Enumerator (each iteration sends the get again).
-      def get(key, timeout: 2.0, params: nil, payload: nil, attachment: nil, target: :all,
-              consolidation: :none, &blk)
-        args = [key, timeout, params, payload, attachment, target, consolidation]
-        return enum_for(:get_each, *args) unless blk
-        get_each(*args, &blk)
+      # timeout (seconds; or timeout_ms:) ran out, and returns their number
+      # (not named each, so the count stays). Without a block, a
+      # GetEnumerator (each iteration sends the get again; dropped /
+      # received / errors of the last one). errors: true also yields the
+      # error replies (Reply#error?). depth: the replies kept until taken
+      # (DEFAULT_GET_DEPTH, 1024); replies past it are dropped, which warns
+      # once unless depth: was given. opts: encoding:, priority:,
+      # congestion_control:, express:, accept_replies: (Session#get).
+      def get(key, timeout: nil, timeout_ms: nil, params: nil, payload: nil, attachment: nil, target: :all,
+              consolidation: :none, errors: false, depth: nil, **opts, &blk)
+        ms = ::Asterism.time_ms("Connection#get", timeout, timeout_ms, nil, 2000)
+        opts[:depth] = depth unless depth.nil?
+        start = lambda do
+          @session.get(key, timeout_ms: ms, params: params, payload: payload,
+                       attachment: attachment, target: target, consolidation: consolidation, **opts)
+        end
+        get_run(start, errors, "get #{key}", depth.nil?, &blk)
       end
 
-      # A liveliness token (close it to withdraw).
-      def liveliness(key)
-        @session.liveliness(key)
+      # A liveliness token (close it to withdraw). With a block: the token
+      # is withdrawn after the block (returns the block's value).
+      def liveliness(key, &blk)
+        Zenoh.scoped(@session.liveliness(key), &blk)
       end
 
       # With a block: yields key and alive (true when the token appeared) on
       # the receiving thread for each change; the tokens alive now come
-      # first. Without: a Watch whose each yields Liveliness values.
-      def liveliness_watch(key, depth: 16, &blk)
-        w = Watch.new(self, @session.liveliness_watch(key, depth), key)
+      # first, in one burst. Without: a Watch whose each yields Liveliness
+      # values. depth: DEFAULT_WATCH_DEPTH (1024); changes past it are
+      # dropped (Watch#dropped), which warns once unless depth: was given.
+      def liveliness_watch(key, depth: nil, &blk)
+        d = depth.nil? ? DEFAULT_WATCH_DEPTH : depth
+        w = Watch.new(self, @session.liveliness_watch(key, depth: d), key, warn: depth.nil?)
         w.handle(&blk) if blk
         w
       end
 
-      # The keys of the liveliness tokens alive now (an Array; waits for
-      # the answers, at most timeout seconds).
-      def liveliness_get(key, timeout: 2.0)
-        g = @session.liveliness_get(key, Zenoh.ms(timeout, 2000))
-        keys = []
+      # The keys of the liveliness tokens alive now (a KeyList, an Array
+      # with dropped and received; waits for the answers, at most timeout
+      # seconds, or timeout_ms:). depth: DEFAULT_GET_DEPTH (1024); keys
+      # past it are dropped, which warns once unless depth: was given.
+      def liveliness_get(key, timeout: nil, timeout_ms: nil, depth: nil)
+        ms = ::Asterism.time_ms("Connection#liveliness_get", timeout, timeout_ms, nil, 2000)
+        g = @session.liveliness_get(key, timeout_ms: ms, depth: depth)
+        keys = KeyList.new
         loop do
+          ended = g.done? # before taking the replies (see get_each)
           g.each_reply.each { |r| keys << r[0] }
-          break if g.done?
+          break if ended && g.pending == 0
           sleep(ENUM_STEP)
         end
-        g.each_reply.each { |r| keys << r[0] }
-        keys
+        Zenoh.note_dropped(g, g, "liveliness_get #{key}", "keys") if depth.nil?
+        keys.finish(g)
       end
 
       # Receives on a thread of its own (blocks run there). Returns self.
@@ -217,10 +344,31 @@ module Asterism
         @session.zid
       end
 
+      # The routers (client) or peers (peer mode) connected now.
+      def connection_count
+        @session.connection_count
+      end
+
+      # Deprecated: connection_count.
       def peers
-        @session.peers
+        ::Asterism.deprecated("Connection#peers", "Connection#connection_count")
+        @session.connection_count
       end
 
+      # The Zenoh IDs of the peers / routers connected now.
+      def peer_zids = @session.peer_zids
+      def router_zids = @session.router_zids
+
+      # What is connected now: Arrays of Transport / Link.
+      def transports = @session.transports
+      def links = @session.links
+
+      # A new Timestamp from the session's clock (put(timestamp:)).
+      def new_timestamp = @session.new_timestamp
+
+      # A KeyExpr declared on the session (use it as the key afterwards).
+      def declare_keyexpr(key) = @session.declare_keyexpr(key)
+
       # Stops receiving and closes the session (with everything declared on
       # it). Idempotent.
       def close
@@ -235,36 +383,54 @@ module Asterism
 
       private
 
-      def get_each(key, timeout, params, payload, attachment, target, consolidation)
-        g = @session.get(key, Zenoh.ms(timeout, 2000), params, payload,
-                         attachment: attachment, target: target, consolidation: consolidation)
+      # The block form (get_each, the count) or a GetEnumerator over it.
+      def get_run(start, errors, what, warn, &blk)
+        return get_each(start, errors, what, warn, nil, &blk) if blk
+        e = nil
+        e = GetEnumerator.new { |y| get_each(start, errors, what, warn, e) { |r| y << r } }
+      end
+
+      # Sends the get (start) and yields each Reply; error replies only
+      # with errors. The done? before taking the replies: once the get is
+      # done, every reply it had is already in the queue. Warns once when
+      # replies were dropped (warn: depth left at the default); stats (a
+      # GetEnumerator or nil) gets the counts.
+      def get_each(start, errors, what = "get", warn = true, stats = nil)
+        g = start.call
         n = 0
         loop do
-          got = g.each_reply
+          done = g.done?
+          got = g.each_result
           got.each do |r|
+            next if r.error? && !errors
             n += 1
-            yield Reply.new(r[0], r[1], r[2])
+            yield r
           end
-          break if g.done? && g.pending == 0
+          break if done && g.pending == 0
           sleep(ENUM_STEP) if got.empty?
         end
+        Zenoh.note_dropped(g, g, what, "replies") if warn
+        stats&.finish(g)
         n
       end
 
       # A subscription of a Connection. Either its block gets the samples
       # (on the receiving thread), or the application takes them: each (an
       # Enumerator that waits for samples) or each_pending (what is there
-      # now, as the polled API).
+      # now, as the portable API).
       class Subscription
         include Enumerable
 
         attr_reader :key, :subscriber
 
-        def initialize(conn, subscriber, key)
+        # warn: say once when samples were dropped (the depth was left at
+        # the default).
+        def initialize(conn, subscriber, key, warn: false)
           @conn = conn
           @subscriber = subscriber
           @key = key
           @task = nil
+          @warn = warn
         end
 
         def handle(&blk)
@@ -272,31 +438,50 @@ module Asterism
           where = "subscribe #{@key}"
           r = @conn.runner
           @task = r.add do
-            got = @subscriber.each_pending
-            got.each { |e| r.guard(where) { blk.call(Sample.new(e[0], e[1], e[2])) } }
+            got = @subscriber.each_sample
+            got.each { |s| r.guard(where) { blk.call(s) } }
+            note_dropped unless got.empty?
             got.size
           end
           self
         end
 
+        # @api private
+        def note_dropped
+          @warn && Zenoh.note_dropped(self, @subscriber, "subscribe #{@key}", "samples")
+        end
+
         # Yields each Sample as it comes, waiting for the next; ends when the
         # subscription or the session closes, or after timeout seconds.
         # Without a block, an Enumerator (each.lazy.map { ... }.first(3)).
         def each(timeout: nil, &blk)
           return enum_for(:each, timeout: timeout) unless blk
           raise ::Asterism::Error, "this subscription has a block; its samples go there" if @task
-          Zenoh.drain(@subscriber, @conn.session, timeout) { |e| blk.call(Sample.new(e[0], e[1], e[2])) }
+          Zenoh.drain(@subscriber, @conn.session, timeout, take: :each_sample) do |s|
+            note_dropped
+            blk.call(s)
+          end
           self
         end
 
-        # The samples there now as Samples (an Array), or yields them.
-        def each_pending
-          got = @subscriber.each_pending.map { |e| Sample.new(e[0], e[1], e[2]) }
+        # The samples there now as Samples (an Array), or yields them and
+        # returns their number. (The portable API's each_sample.)
+        def each_sample
+          got = @subscriber.each_sample
+          note_dropped unless got.empty?
           return got unless block_given?
           got.each { |s| yield s }
           got.size
         end
 
+        # Deprecated: each_sample. In the portable API each_pending gives
+        # [key, payload, attachment] Arrays; here it gave Samples, so one
+        # name had two shapes.
+        def each_pending(&blk)
+          ::Asterism.deprecated("Connection::Subscription#each_pending", "each_sample")
+          each_sample(&blk)
+        end
+
         def pending = @subscriber.pending
         def received = @subscriber.received
         def dropped = @subscriber.dropped
@@ -380,11 +565,14 @@ module Asterism
 
         attr_reader :key, :watch
 
-        def initialize(conn, watch, key)
+        # warn: say once when changes were dropped (the depth was left at
+        # the default).
+        def initialize(conn, watch, key, warn: false)
           @conn = conn
           @watch = watch
           @key = key
           @task = nil
+          @warn = warn
         end
 
         def handle(&blk)
@@ -394,6 +582,7 @@ module Asterism
           @task = r.add do
             got = @watch.each_pending
             got.each { |e| r.guard(where) { blk.call(e[0], e[1]) } }
+            note_dropped unless got.empty?
             got.size
           end
           self
@@ -404,10 +593,24 @@ module Asterism
         def each(timeout: nil, &blk)
           return enum_for(:each, timeout: timeout) unless blk
           raise ::Asterism::Error, "this watch has a block; its changes go there" if @task
-          Zenoh.drain(@watch, @conn.session, timeout) { |e| blk.call(Liveliness.new(e[0], e[1])) }
+          Zenoh.drain(@watch, @conn.session, timeout) do |e|
+            note_dropped
+            blk.call(Liveliness.new(e[0], e[1]))
+          end
           self
         end
 
+        # @api private
+        def note_dropped
+          @warn && Zenoh.note_dropped(self, @watch, "liveliness_watch #{@key}", "changes")
+        end
+
+        # Changes waiting / received so far / dropped because the queue was
+        # full (the oldest go; the watch no longer knows which tokens are
+        # alive, so declare it again).
+        def pending = @watch.pending
+        def received = @watch.received
+        def dropped = @watch.dropped
         def closed? = @watch.closed?
 
         def close
@@ -417,6 +620,159 @@ module Asterism
           nil
         end
       end
+
+      # A publisher (or advanced publisher) of a Connection.
+      class Publisher
+        attr_reader :key, :publisher
+
+        def initialize(conn, publisher, key)
+          @conn = conn
+          @publisher = publisher
+          @key = key.to_s
+          @tasks = []
+        end
+
+        # opts: attachment:, encoding:, timestamp:. A payload that is not a
+        # String is sent as to_s.
+        def put(payload, **opts)
+          @publisher.put(Zenoh.bytes(payload), **opts)
+          nil
+        end
+
+        def delete(**opts)
+          @publisher.delete(**opts)
+          nil
+        end
+
+        # True when a subscriber matches the key now.
+        def matching? = @publisher.matching?
+
+        # on_matching { |listening| }: true when the first subscriber
+        # appears, false when the last one goes, on the receiving thread.
+        def on_matching(depth: 16, &blk)
+          raise ArgumentError, "a block is needed" unless blk
+          @tasks << Events.new(@conn, @publisher.matching_listener(depth), "on_matching #{@key}", blk)
+          self
+        end
+
+        def closed? = @publisher.closed?
+
+        def close
+          @tasks.each(&:close)
+          @tasks.clear
+          @publisher.close
+          nil
+        end
+
+        def inspect
+          "#<Asterism::Zenoh::Connection::Publisher #{@key}>"
+        end
+      end
+
+      # A querier of a Connection: the same get, sent again and again.
+      class Querier
+        attr_reader :key, :querier
+
+        def initialize(conn, querier, key)
+          @conn = conn
+          @querier = querier
+          @key = key.to_s
+          @tasks = []
+        end
+
+        # Yields each Reply until every answer came or the querier's time
+        # ran out; returns their number. errors: true also yields the error
+        # replies. depth: as Connection#get. Without a block, a
+        # GetEnumerator.
+        def get(params: nil, payload: nil, attachment: nil, encoding: nil, errors: false, depth: nil, &blk)
+          opts = { attachment: attachment, encoding: encoding }
+          opts[:depth] = depth unless depth.nil?
+          start = -> { @querier.get(params, payload, **opts) }
+          @conn.send(:get_run, start, errors, "querier get #{@key}", depth.nil?, &blk)
+        end
+
+        def matching? = @querier.matching?
+
+        # on_matching { |answered| }: true when a queryable matches, false
+        # when none does any more.
+        def on_matching(depth: 16, &blk)
+          raise ArgumentError, "a block is needed" unless blk
+          @tasks << Events.new(@conn, @querier.matching_listener(depth), "on_matching #{@key}", blk)
+          self
+        end
+
+        def closed? = @querier.closed?
+
+        def close
+          @tasks.each(&:close)
+          @tasks.clear
+          @querier.close
+          nil
+        end
+      end
+
+      # A subscription with history and recovery (advanced_subscriber).
+      class AdvancedSubscription < Subscription
+        def initialize(conn, subscriber, key)
+          super
+          @extra = []
+        end
+
+        # on_publisher { |key, alive| }: the advanced publishers on the key
+        # that declared publisher_detection, as they come and go (the ones
+        # there now first).
+        def on_publisher(depth: 16, history: true, &blk)
+          raise ArgumentError, "a block is needed" unless blk
+          w = Watch.new(@conn, @subscriber.detect_publishers(depth, history: history), @key)
+          w.handle(&blk)
+          @extra << w
+          self
+        end
+
+        # on_miss { |miss| }: samples that never came (Miss: source_zid,
+        # source_eid, count); needs sample_miss_detection on the publisher.
+        def on_miss(depth: 16, &blk)
+          raise ArgumentError, "a block is needed" unless blk
+          @extra << Events.new(@conn, @subscriber.miss_listener(depth), "on_miss #{@key}", blk)
+          self
+        end
+
+        def close
+          @extra.each(&:close)
+          @extra.clear
+          super
+        end
+
+        def inspect
+          "#<Asterism::Zenoh::Connection::AdvancedSubscription #{@key}#{@task ? ' (block)' : ''}>"
+        end
+      end
+
+      # The values of a listener (MatchingListener or EventListener) given
+      # to a block on the receiving thread. close stops it.
+      class Events
+        attr_reader :listener
+
+        def initialize(conn, listener, where, blk)
+          @conn = conn
+          @listener = listener
+          r = conn.runner
+          @task = r.add do
+            got = @listener.each_pending
+            got.each { |v| r.guard(where) { blk.call(v) } }
+            got.size
+          end
+        end
+
+        def closed? = @listener.closed?
+
+        def close
+          @conn.runner.remove(@task) if @task
+          @task = nil
+          @listener.close
+          nil
+        end
+      end
     end
   end
 end

data/lib/asterism/version.rb

@@ -1,5 +1,5 @@
 module Asterism
   # The gem's version (the CRuby gem asterism; it depends on asterism-zenoh
   # of the same version).
-  VERSION = "0.2.0"
+  VERSION = "0.4.0"
 end