asterism 0.3.0 → 0.4.0

data/lib/asterism/cruby/objects.rb

@@ -1,6 +1,6 @@
 # The object layer (Asterism.connect / expose / []) with blocks and a
 # receiving thread (CRuby only). Asterism.connect without a block,
-# Asterism.poll and the rest of the polled API work as on the boards.
+# Asterism.poll and the rest of the portable API work as on the boards.
 #
 #   Asterism.connect("tcp/192.0.2.2:7447", node: "mypc", app: "demo") do |net|
 #     net.expose("screen", Screen.new, methods: [:say])
@@ -23,10 +23,10 @@ module Asterism
   # Held by every entry into the object layer (reentrant).
   LOCK = Monitor.new
 
-  # The polled API, entered under LOCK. Prepended to the Asterism module's
+  # The portable API, entered under LOCK. Prepended to the Asterism module's
   # singleton class, so the shared methods themselves are not changed.
   module Locked
-    %i[expose unexpose poll nodes [] call_async meta connected? exposed on_join on_leave].each do |m|
+    %i[expose unexpose poll nodes [] call_async meta connected? exposed on_join on_leave off_join off_leave].each do |m|
       define_method(m) do |*args, **kw, &blk|
         ::Asterism::LOCK.synchronize { super(*args, **kw, &blk) }
       end
@@ -35,9 +35,11 @@ module Asterism
     # With a block: yields an Asterism::Net and closes when the block ends
     # (also on an exception); returns the block's value. Without a block,
     # as before (returns Asterism).
-    def connect(locator, node:, app:, mode: nil, listen: nil, &blk)
+    def connect(locator, node:, app:, mode: nil, listen: nil, config: nil, connect_timeout: nil, check_timeout: nil,
+                &blk)
       ::Asterism::LOCK.synchronize do
-        super(locator, node: node, app: app, mode: mode, listen: listen)
+        super(locator, node: node, app: app, mode: mode, listen: listen, config: config,
+                       connect_timeout: connect_timeout, check_timeout: check_timeout)
         # The Net of a connection that was lost (not closed) belongs to the
         # old session.
         old = @net
@@ -145,15 +147,17 @@ module Asterism
       ::Asterism.unexpose(name)
     end
 
-    # A proxy for <node>/<app>/<object>; timeout in seconds.
-    def [](path, timeout: nil)
-      ::Asterism[path, Zenoh.ms(timeout, ::Asterism::DEFAULT_TIMEOUT_MS)]
+    # A proxy for <node>/<app>/<object>; timeout: in seconds (or
+    # timeout_ms:).
+    def [](path, timeout: nil, timeout_ms: nil)
+      ::Asterism[path, timeout: timeout, timeout_ms: timeout_ms]
     end
     alias proxy []
 
     # The exposed objects alive now matching the pattern, as proxies. With
-    # a block, yields each and returns their number; without, an
-    # Enumerator (net.each("*/demo/info").map(&:status)).
+    # a block, yields each and returns their number (1.0: returns self, as
+    # Ruby's each does; net.count is the number); without, an Enumerator
+    # (net.each("*/demo/info").map(&:status)).
     def each(pattern = "**", &blk)
       return enum_for(:each, pattern) unless blk
       ::Asterism.each(pattern, &blk)
@@ -173,6 +177,17 @@ module Asterism
       self
     end
 
+    # Removes a block given to on_join / on_leave (keep the Proc).
+    def off_join(blk)
+      ::Asterism.off_join(blk)
+      self
+    end
+
+    def off_leave(blk)
+      ::Asterism.off_leave(blk)
+      self
+    end
+
     # on_error { |error, where| }: what on_join / on_leave blocks raise.
     # (An exposed method that raises is answered to its caller as a
     # RemoteError, as before; it does not come here.)

data/lib/asterism/cruby/ros.rb

@@ -197,9 +197,11 @@ module Asterism
         Topic.new(self, topic, type, qos, depth)
       end
 
-      # Node#call with the time limit in seconds as well: timeout: 2.0.
-      def call(service, type, request = nil, timeout: nil, timeout_ms: nil, **fields)
-        ms = timeout_ms || ::Asterism::Zenoh.ms(timeout, Client::DEFAULT_TIMEOUT_MS)
+      # Node#call; here timeout: is always the time limit, also for a
+      # request type with a field named timeout (give such a request as
+      # request: { ... }).
+      def call(service, type, req = nil, request: nil, timeout: nil, timeout_ms: nil, **fields)
+        ms = ::Asterism.time_ms("Node#call", timeout, timeout_ms, nil, nil)
         c = @asterism_runner.lock.synchronize do
           @clients ||= {}
           cl = @clients[service]
@@ -209,7 +211,7 @@ module Asterism
           end
           cl
         end
-        c.call(request, timeout_ms: ms, **fields)
+        c.call(req, request: request, timeout_ms: ms, **fields)
       end
     end
 

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|
@@ -80,10 +80,63 @@ 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
@@ -130,30 +183,34 @@ module Asterism
 
       # A declared publisher (Connection::Publisher): put / delete,
       # matching?, on_matching { |listening| }. opts: those of
-      # Session#publisher (encoding:, priority:, ...).
-      def publisher(key, **opts)
-        Publisher.new(self, @session.publisher(key, **opts), key)
+      # 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.
-      def advanced_publisher(key, **opts)
-        Publisher.new(self, @session.advanced_publisher(key, **opts), key)
+      # 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_ms:): like subscribe, plus on_publisher and on_miss.
+      # 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, **opts), key)
+        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; the rest as Session#querier.
-      def querier(key, timeout: 2.0, **opts)
-        Querier.new(self, @session.querier(key, timeout_ms: Zenoh.ms(timeout, 2000), **opts), key)
+      # 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
@@ -161,21 +218,22 @@ module Asterism
       # 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, history: history), "on_transport", 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, history: history), "on_link", 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
@@ -184,53 +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).
-      # errors: true also yields the error replies (Reply#error?); opts:
-      # encoding:, priority:, congestion_control:, express:,
-      # accept_replies: (Session#get).
-      def get(key, timeout: 2.0, params: nil, payload: nil, attachment: nil, target: :all,
-              consolidation: :none, errors: false, **opts, &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, Zenoh.ms(timeout, 2000), params, payload,
+          @session.get(key, timeout_ms: ms, params: params, payload: payload,
                        attachment: attachment, target: target, consolidation: consolidation, **opts)
         end
-        return enum_for(:get_each, start, errors) unless blk
-        get_each(start, errors, &blk)
+        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.
@@ -274,8 +344,15 @@ 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.
@@ -306,10 +383,19 @@ module Asterism
 
       private
 
+      # 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.
-      def get_each(start, errors)
+      # 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
@@ -323,23 +409,28 @@ module Asterism
           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)
@@ -349,29 +440,48 @@ module Asterism
           @task = r.add do
             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, take: :each_sample) { |s| blk.call(s) }
+          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
+        # 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
@@ -455,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)
@@ -469,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
@@ -479,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
@@ -554,11 +682,13 @@ module Asterism
 
         # Yields each Reply until every answer came or the querier's time
         # ran out; returns their number. errors: true also yields the error
-        # replies. Without a block, an Enumerator.
-        def get(params: nil, payload: nil, attachment: nil, encoding: nil, errors: false, &blk)
-          start = -> { @querier.get(params, payload, attachment: attachment, encoding: encoding) }
-          return @conn.send(:enum_for, :get_each, start, errors) unless blk
-          @conn.send(:get_each, start, errors, &blk)
+        # 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?

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.3.0"
+  VERSION = "0.4.0"
 end

data/lib/asterism.rb

@@ -16,8 +16,8 @@ require_relative "asterism/version"
   require_relative "../mrblib/#{f}"
 end
 require_relative "asterism/cruby"
-# The Ruby-like API on top (blocks, a receiving thread, Enumerators,
-# pattern matching): CRuby only, see README "The Ruby-like API".
+# The CRuby API on top (blocks, a receiving thread, Enumerators,
+# pattern matching): CRuby only, see README "The CRuby API".
 %w[runner zenoh objects ros].each do |f|
   require_relative "asterism/cruby/#{f}"
 end