asterism 0.0.0 → 0.2.0

data/lib/asterism/cruby/objects.rb

@@ -0,0 +1,224 @@
+# 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.connect("tcp/192.0.2.2:7447", node: "mypc", app: "demo") do |net|
+#     net.expose("screen", Screen.new, methods: [:say])
+#     net.on_join  { |node| puts "joined #{node}" }
+#     net.on_leave { |node| puts "left #{node}" }
+#     net["fmruby-aaaaaa/demo/screen"].say("hello")
+#     net.each("*/demo/info").map(&:status)
+#     net.run                             # answer calls until Ctrl-C
+#   end
+#
+# Locking: the object layer is one connection per process with its state in
+# the Asterism module, written for one thread. Every entry into it (polling,
+# answering, calling, exposing, listing) holds Asterism::LOCK, so the
+# receiving thread and the application's threads take turns. A call that
+# waits for its answer while the receiving thread runs does not poll; it
+# waits for the receiving thread's ticks (Asterism::Runner#wait_until).
+require "monitor"
+
+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
+  # 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|
+      define_method(m) do |*args, **kw, &blk|
+        ::Asterism::LOCK.synchronize { super(*args, **kw, &blk) }
+      end
+    end
+
+    # 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)
+      ::Asterism::LOCK.synchronize do
+        super(locator, node: node, app: app, mode: mode, listen: listen)
+        # The Net of a connection that was lost (not closed) belongs to the
+        # old session.
+        old = @net
+        @net = nil
+        old&.release
+      end
+      return self unless blk
+      net = ::Asterism.net
+      begin
+        blk.call(net)
+      ensure
+        net.close
+      end
+    end
+
+    # Stops the receiving thread first (outside the lock: it may be inside
+    # a tick), then closes.
+    def close
+      net = @net
+      @net = nil
+      net&.release
+      ::Asterism::LOCK.synchronize { super }
+    end
+
+    # The on_join / on_leave blocks (called from Asterism.poll): with a Net,
+    # what they raise goes to its on_error and the other blocks still run.
+    def tell(where, blk, node)
+      net = @net
+      return super unless net
+      net.runner.guard(where) { super }
+    end
+
+    # Lists under the lock, yields outside it (the block may make calls).
+    def each(pattern = "**", &blk)
+      list = ::Asterism::LOCK.synchronize { super(pattern, &nil) }
+      return list unless blk
+      list.each(&blk)
+      list.size
+    end
+
+    # A call waiting for its answer. On the receiving thread, or when it
+    # does not run: polls, as on the boards. On another thread while it
+    # runs: waits for its ticks to bring the answer.
+    def wait_until(&cond)
+      loop do
+        r = @net&.runner
+        if r && r.running? && !r.current?
+          r.wait_until(&cond)
+          return if ::Asterism::LOCK.synchronize(&cond)
+          # The receiving thread stopped before the answer: poll here.
+        else
+          return ::Asterism::LOCK.synchronize { super(&cond) }
+        end
+      end
+    end
+  end
+  singleton_class.prepend(Locked)
+
+  class Future
+    # Prepended: done? reads the connection state, under the lock.
+    module Locked
+      def done?
+        ::Asterism::LOCK.synchronize { super }
+      end
+    end
+    prepend Locked
+  end
+
+  # The connection of this process (Asterism is one per process) as an
+  # object, with a receiving thread. nil when not connected.
+  def self.net
+    LOCK.synchronize do
+      return nil unless connected?
+      @net ||= Net.new
+    end
+  end
+
+  # The block API of the object layer. Made by Asterism.connect with a
+  # block, or Asterism.net after a connect without one.
+  class Net
+    attr_reader :runner
+
+    def initialize
+      @runner = Runner.new(::Asterism.instance_variable_get(:@session), lock: ::Asterism::LOCK, name: "asterism")
+      # One tick: Asterism.poll (answers the calls, tells on_join /
+      # on_leave); false once the connection is gone.
+      @runner.add { ::Asterism.poll ? 0 : false }
+    end
+
+    def node_id = ::Asterism.node_id
+    def app = ::Asterism.app
+    def connected? = ::Asterism.connected?
+    def lost_reason = ::Asterism.lost_reason
+    def nodes = ::Asterism.nodes
+    def exposed = ::Asterism.exposed
+
+    # Asterism.expose: methods: an Array of names or a Hash name => number
+    # of arguments. The object's methods run on the receiving thread (or in
+    # run, or in whatever polls).
+    def expose(name, obj, methods:)
+      ::Asterism.expose(name, obj, methods: methods)
+    end
+
+    def unexpose(name)
+      ::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)]
+    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)).
+    def each(pattern = "**", &blk)
+      return enum_for(:each, pattern) unless blk
+      ::Asterism.each(pattern, &blk)
+    end
+    include Enumerable
+
+    # on_join { |node| } / on_leave { |node| }: Asterism.on_join /
+    # on_leave, the same as on the boards (called from Asterism.poll), here
+    # on the receiving thread. What they raise goes to on_error.
+    def on_join(&blk)
+      ::Asterism.on_join(&blk)
+      self
+    end
+
+    def on_leave(&blk)
+      ::Asterism.on_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.)
+    def on_error(&blk)
+      @runner.on_error(&blk)
+      self
+    end
+
+    # Answers calls on a thread of its own. Returns self.
+    def start
+      @runner.start
+      self
+    end
+
+    def stop
+      @runner.stop
+      self
+    end
+
+    # Answers calls on this thread until stop, the connection closing, or
+    # Ctrl-C. Returns nil.
+    def run
+      @runner.run
+    end
+
+    def running?
+      @runner.running?
+    end
+
+    def poll
+      ::Asterism.poll
+    end
+
+    # Stops the receiving thread and closes the connection (Asterism.close).
+    def close
+      ::Asterism.close
+      nil
+    end
+
+    # For Asterism.close: stop receiving and forget the session.
+    def release
+      @runner.close
+    end
+
+    def inspect
+      "#<Asterism::Net #{node_id}/#{app}#{running? ? ' running' : ''}>"
+    end
+  end
+end

data/lib/asterism/cruby/ros.rb

@@ -0,0 +1,305 @@
+# Asterism::ROS with a receiving thread and Enumerators (CRuby only).
+# Asterism::ROS::Node, node.poll, the subscribe / every blocks and pattern
+# matching on messages are the shared ones (mrblib/ros.rb), as on the
+# boards; this layer runs node.poll on a receiving thread, routes what the
+# blocks raise to on_error, and adds the Enumerators.
+#
+#   Asterism::ROS.connect("tcp/192.0.2.2:7447", domain: 0) do |ros|
+#     node = ros.node("ruby_talker")
+#     chatter = node.publisher("/chatter", "std_msgs/msg/String")
+#     chatter << { data: "hello from Ruby" }
+#     node.subscribe("/odom", "nav_msgs/msg/Odometry") { |odom| p odom.pose.pose.position.x }
+#     node.every(0.1) { chatter << { data: Time.now.to_s } }
+#     node.service("/add_ruby", "example_interfaces/srv/AddTwoInts") { |req| { sum: req.a + req.b } }
+#     p node.call("/add_two_ints", "example_interfaces/srv/AddTwoInts", a: 1, b: 2).sum
+#     node.topic("/scan", "sensor_msgs/msg/LaserScan").each.lazy.first(1)
+#     ros.spin
+#   end
+#
+# Locking: each connection has one lock (its Runner's). A tick (node.poll:
+# services answered, subscription blocks, timers) holds it; so do the calls
+# that change a node (making publishers, subscriptions, services, clients,
+# timers) and publishing. A service call made on another thread while the connection
+# spins waits for the ticks (Asterism::Runner#wait_until) instead of
+# polling by itself.
+module Asterism
+  module ROS
+    # Opens a Zenoh session and makes a Connection for nodes on it. domain:
+    # the ROS domain of the nodes made by ros.node. type_path: directories
+    # with generated types to add to Asterism::ROS::TYPE_PATH. The other
+    # options go to Asterism::Zenoh::Session.open. With a block: yields the
+    # Connection, closes it when the block ends and returns its value.
+    def self.connect(locator = nil, domain: 0, type_path: nil, interval: Runner::DEFAULT_INTERVAL, **opts)
+      Array(type_path).each { |d| TYPE_PATH << File.expand_path(d) unless TYPE_PATH.include?(File.expand_path(d)) }
+      zconn = ::Asterism::Zenoh.open(locator, interval: interval, **opts)
+      conn = Connection.new(zconn, domain: domain)
+      return conn unless block_given?
+      begin
+        yield conn
+      ensure
+        conn.close
+      end
+    end
+
+    # The ROS side of a Zenoh connection: makes nodes and spins them.
+    class Connection
+      attr_reader :zenoh, :domain
+
+      def initialize(zconn, domain: 0)
+        @zenoh = zconn
+        @domain = domain.to_i
+        @nodes = []
+      end
+
+      def session = @zenoh.session
+      def runner = @zenoh.runner
+
+      # An Asterism::ROS::Node on this connection, with the block API
+      # (subscribe, every, topic; services answered while it spins).
+      def node(name, namespace: "/", enclave: "/")
+        runner.lock.synchronize do
+          n = Node.new(session, name, namespace: namespace, domain: @domain, enclave: enclave)
+          n.extend(Spinning)
+          n.asterism_spin_on(runner)
+          @nodes << n
+          n
+        end
+      end
+
+      def nodes = @nodes.dup
+
+      # Spins on this thread (services, subscription blocks, timers) until
+      # stop, the connection closing, or Ctrl-C. Returns nil.
+      def spin
+        runner.run
+      end
+      alias run spin
+
+      # Spins on a thread of its own. Returns self.
+      def start
+        runner.start
+        self
+      end
+
+      def stop
+        runner.stop
+        self
+      end
+
+      def running? = runner.running?
+
+      # on_error { |error, where| }: what subscription, timer and service
+      # blocks raise (the service request then gets no answer).
+      def on_error(&blk)
+        runner.on_error(&blk)
+        self
+      end
+
+      # Stops spinning, withdraws the nodes and closes the session.
+      def close
+        runner.stop
+        @nodes.each { |n| n.close rescue ::Asterism::Zenoh::Error }
+        @nodes = []
+        @zenoh.close
+        nil
+      end
+
+      def inspect
+        "#<Asterism::ROS::Connection domain #{@domain}#{running? ? ' spinning' : ''}>"
+      end
+    end
+
+    # A service block raised; it was reported through on_error already.
+    class ServiceFailed < ::StandardError; end
+
+    # Added to the nodes a Connection makes (Node#extend). The methods of
+    # Node keep their meaning; these come on top.
+    module Spinning
+      def asterism_spin_on(runner)
+        @asterism_runner = runner
+        node = self
+        @asterism_task = runner.add { node.poll ? 0 : false }
+      end
+
+      # As Node#pump (node.poll and waiting service calls go through it). A
+      # service block that raised was reported (on_error) and its request
+      # left unanswered; polling goes on.
+      def pump(steps = 8)
+        super
+      rescue ::Asterism::ROS::ServiceFailed
+        !@session.closed?
+      end
+
+      # The subscribe and every blocks (called from node.poll): what they
+      # raise goes to on_error, and the others still run.
+      def handle(sub, msg, info)
+        @asterism_runner.guard("subscribe #{sub.topic_key}") { super }
+      end
+
+      def fire(timer, now)
+        @asterism_runner.guard("every #{timer.period}") { super }
+      end
+
+      def asterism_runner = @asterism_runner
+
+      # The calls that change the node take the connection's lock.
+      %i[subscription client close every cancel_timer].each do |m|
+        define_method(m) do |*args, **kw, &blk|
+          @asterism_runner.lock.synchronize { super(*args, **kw, &blk) }
+        end
+      end
+
+      # As Node#publisher; publishing takes the lock too (a timer on the
+      # receiving thread and the application may publish at once).
+      def publisher(topic, type, qos: DEFAULT_QOS)
+        r = @asterism_runner
+        r.lock.synchronize do
+          pub = super
+          pub.extend(LockedPublisher)
+          pub.instance_variable_set(:@asterism_lock, r.lock)
+          pub
+        end
+      end
+
+      # As Node#service: the block answers while the connection spins (or
+      # from node.poll). What it raises goes to on_error and that request
+      # gets no answer.
+      def service(name, type, qos: DEFAULT_QOS, depth: 8, &handler)
+        raise ArgumentError, "service needs a block" unless handler
+        r = @asterism_runner
+        where = "service #{name}"
+        wrapped = proc do |req|
+          handler.call(req)
+        rescue StandardError => e
+          r.report(e, where)
+          raise ::Asterism::ROS::ServiceFailed, e.message
+        end
+        r.lock.synchronize { super(name, type, qos: qos, depth: depth, &wrapped) }
+      end
+
+      # With a block: as on the boards (Node#subscribe), the block gets each
+      # message (and its Attachment, or nil) from node.poll, here while the
+      # connection spins; returns the Subscription. Without: a Subscription
+      # whose each waits for messages (an Enumerator).
+      def subscribe(topic, type, qos: DEFAULT_QOS, depth: 16, &blk)
+        r = @asterism_runner
+        r.lock.synchronize do
+          sub = blk ? super : subscription(topic, type, qos: qos, depth: depth)
+          sub.extend(Stream)
+          sub.asterism_stream_on(session)
+          sub
+        end
+      end
+
+      # A topic to iterate: each subscribes for the iteration and withdraws
+      # after it (node.topic("/scan", "sensor_msgs/msg/LaserScan").each.lazy.first(1)).
+      def topic(topic, type, qos: DEFAULT_QOS, depth: 16)
+        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)
+        c = @asterism_runner.lock.synchronize do
+          @clients ||= {}
+          cl = @clients[service]
+          if cl.nil? || cl.closed?
+            cl = client(service, type)
+            @clients[service] = cl
+          end
+          cl
+        end
+        c.call(request, timeout_ms: ms, **fields)
+      end
+    end
+
+    module LockedPublisher
+      def publish(msg)
+        @asterism_lock.synchronize { super }
+      end
+    end
+
+    # Added to the subscriptions node.subscribe makes.
+    module Stream
+      include Enumerable
+
+      def asterism_stream_on(session)
+        @asterism_session = session
+      end
+
+      # Yields each message (and its Attachment) as it comes, waiting for
+      # the next; ends when the subscription or the session closes, or after
+      # timeout seconds. Without a block, an Enumerator.
+      def each(timeout: nil, &blk)
+        return enum_for(:each, timeout: timeout) unless blk
+        raise ::Asterism::Error, "this subscription has a block; its messages go there" if handler
+        deadline = timeout && (Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout)
+        loop do
+          got = each_pending
+          got.each { |m| blk.call(m[0], m[1]) }
+          break if closed? || @asterism_session.closed?
+          break if deadline && Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+          sleep(::Asterism::Zenoh::ENUM_STEP) if got.empty?
+        end
+        self
+      end
+
+    end
+
+    # node.topic: subscribes while it is iterated.
+    class Topic
+      include Enumerable
+
+      attr_reader :name, :type
+
+      def initialize(node, name, type, qos, depth)
+        @node = node
+        @name = name
+        @type = type
+        @qos = qos
+        @depth = depth
+      end
+
+      # Yields each message and its Attachment, from a subscription made
+      # for this iteration (withdrawn when it ends: break, first(n), the
+      # time running out). Without a block, an Enumerator.
+      def each(timeout: nil, &blk)
+        return enum_for(:each, timeout: timeout) unless blk
+        sub = @node.subscribe(@name, @type, qos: @qos, depth: @depth)
+        begin
+          sub.each(timeout: timeout, &blk)
+        ensure
+          sub.close
+        end
+        self
+      end
+
+      def inspect
+        "#<Asterism::ROS::Topic #{@name}>"
+      end
+    end
+
+    class Client
+      # Prepended: a call made on another thread while the connection
+      # spins waits for the ticks instead of polling the node by itself.
+      # (Calls from a board's update loop are on one thread; here the
+      # application may call from several.)
+      # (The sequence number is read once in the shared call_async, so
+      # several threads may call through one client without a lock.)
+      module Waiting
+        def wait_for(c)
+          loop do
+            r = ::Asterism::Runner.for(@session)
+            if r && r.running? && !r.current?
+              r.wait_until { c.done? }
+              return if c.done?
+            else
+              return r ? r.lock.synchronize { super } : super
+            end
+          end
+        end
+      end
+      prepend Waiting
+    end
+  end
+end