asterism 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 16a71827f6f79aa024b98f6aa686efa127228644d12f6bef3469dad98d819dac
-  data.tar.gz: b564b747d9cb0dd6d890e86e95cbc04ca75f7d1a55b24490bfd315edfc1cf25a
+  metadata.gz: f03c6be1c5461da008a067c55b609a009b31b7552810836b7272bcdd35443ba7
+  data.tar.gz: df8c8641c8039408dcb3ca803b7fdcfe0a24e3eef3199da0b1277e980977f936
 SHA512:
-  metadata.gz: bff73ce315295e1d2a4426eef3deda857ba8c77db3c789cb48b0ec489c101cd35633fb6d73fbba31d641ad9d467bbaa7db80aefcf4686af1a798a9f4719a66c4
-  data.tar.gz: 594b310948679e9471dab6853846692c0ffc94a670456b9fcccfe44f7c0e4fbc3cf90fde19e401f992e31897b2b385f7a1856c6a8bef5920b1b6cf75c868e7bf
+  metadata.gz: 663fbb3e79d9b824128b541b899028809d899916af70a28fe761581fa2e28285f9841ef78dfafd088c2583f2c9df705328566b1f465ec31886df277c013c90a2
+  data.tar.gz: d447307b7bba1387d35316044c483f974a814ab1b0a4c7f5d32e17e8fc0b954ed2388ee53aaef9bf780bb7ccb98a93669fdf30f0efb7357d007535cae26a33ec

data/README.md

@@ -9,11 +9,11 @@ repository holds the pure Ruby layers, written once for every Ruby:
 |---|---|
 | `mrblib/` | The layers: remote objects (`Asterism`), `Asterism::CDR`, `Asterism::ROS`. The source of truth for both forms below |
 | `mrbgem.rake` | The mrbgem `picoruby-asterism` (mruby / PicoRuby): compiles `mrblib/` |
-| `asterism.gemspec`, `lib/` | The CRuby gem `asterism`: `lib/asterism.rb` loads `mrblib/` as it is, `lib/asterism/cruby.rb` adds what CRuby needs |
+| `asterism.gemspec`, `lib/` | The CRuby gem `asterism`: `lib/asterism.rb` loads `mrblib/` as it is, `lib/asterism/cruby.rb` adds what CRuby needs, `lib/asterism/cruby/` the Ruby-like API (CRuby only) |
 | `data/msgs/` | ROS 2 message types generated from ROS 2 Jazzy's definitions (Apache-2.0, see NOTICE) |
 | `tools/` | The type generator `asterism_msggen.rb`, the Jazzy definitions it reads, `ros2_types.rb` (refreshes them from a ROS 2 image) |
-| `test/` | `test/msgs` (types, CDR; CRuby only), `test_asterism.rb` (objects and ROS between CRuby sessions) |
-| `examples/` | CRuby: `node.rb` (objects with a board), `ros2_talker.rb` (Twist and AddTwoInts with ROS 2) |
+| `test/` | `test/msgs` (types, CDR; CRuby only), `test_asterism.rb` (objects and ROS between CRuby sessions), `test_api_*.rb` (the Ruby-like API) |
+| `examples/` | CRuby: `node.rb` (objects with a board), `node_polled.rb` (the same with the polled API of the boards), `ros2_talker.rb` (topics, a timer, services with ROS 2), `zenoh.rb` (plain Zenoh) |
 
 The Zenoh binding underneath is a separate gem with the same Ruby API on
 each Ruby:
@@ -23,7 +23,15 @@ each Ruby:
 - mruby / PicoRuby: [picoruby-asterism-zenoh](https://github.com/ruby-asterism/picoruby-asterism-zenoh)
   (over zenoh-pico)
 
-Neither gem is on rubygems.org yet (version 0.1.0 builds from these
+Which zenoh-c features the CRuby binding exposes (configuration and TLS,
+scouting, publishers, queriers, the advanced publisher / subscriber,
+events, key expressions, timestamps) and which zenoh-pico could offer is
+in asterism-zenoh's
+[feature coverage](https://github.com/ruby-asterism/asterism-zenoh/blob/main/docs/feature_coverage.md).
+The ones added in 0.3.0 are CRuby only: the shared layer (`mrblib/`) does
+not use them.
+
+Neither gem is on rubygems.org yet (version 0.3.0 builds from these
 repositories with `rake gem`).
 
 ## Using it
@@ -31,7 +39,7 @@ repositories with `rake gem`).
 CRuby (needs CRuby 3.2+ and a C compiler):
 
 ```
-gem install asterism          # also installs asterism-zenoh (~> 0.1.0) and msgpack
+gem install asterism          # also installs asterism-zenoh (~> 0.3.0) and msgpack
 ruby -e 'require "asterism"'
 ```
 
@@ -44,7 +52,7 @@ build but not yet tested. To install from the repositories instead:
 
 ```
 (cd ../asterism-zenoh && rake gem) && rake gem
-gem install --local ../asterism-zenoh/pkg/asterism-zenoh-0.1.0.gem pkg/asterism-0.1.0.gem
+gem install --local ../asterism-zenoh/pkg/asterism-zenoh-0.3.0.gem pkg/asterism-0.3.0.gem
 ```
 
 From the working trees, without installing:
@@ -67,13 +75,14 @@ these repositories.
 ## Tests
 
 ```
-rake                  # both suites
+rake                  # every suite
 rake test:msgs        # generator, type hashes, CDR, bundled types (CRuby only; no Zenoh, no docker)
 rake test:objects     # objects and Asterism::ROS between CRuby sessions over a local peer link
-ASTERISM_TEST_ROUTER=tcp/127.0.0.1:7447 rake test:objects   # the same through a zenohd router
+rake test:api         # the Ruby-like API (blocks, receiving threads, Enumerators)
+ASTERISM_TEST_ROUTER=tcp/127.0.0.1:7447 rake test:objects test:api   # the same through a zenohd router
 ```
 
-`test:objects` needs asterism-zenoh: built next to this repository
+`test:objects` and `test:api` need asterism-zenoh: built next to this repository
 (`../asterism-zenoh`, its `rake compile`), or `ASTERISM_ZENOH_DIR`, or the
 installed gem.
 
@@ -83,11 +92,172 @@ installed gem.
 # objects: join the app "demo" of Family mruby's asterism_demo, call a board,
 # and answer its calls (its keys s / a call screen.say / apu.play here)
 ruby examples/node.rb --router tcp/192.0.2.2:7447 [--peer fmruby-aaaaaa]
+ruby examples/node_polled.rb --router tcp/192.0.2.2:7447    # the same, polled
 
-# ROS 2: geometry_msgs/Twist on /cmd_vel, then AddTwoInts calls
+# ROS 2: /chatter and /cmd_vel from a timer, /chatter_in printed,
+# /cruby/add_two_ints served, AddTwoInts calls
 ruby examples/ros2_talker.rb --router tcp/192.0.2.2:7447 [--service NAME]
+
+# plain Zenoh: run two with different --name
+ruby examples/zenoh.rb --router tcp/192.0.2.2:7447 --name pc1
+```
+
+## The Ruby-like API (CRuby only)
+
+On CRuby, `require "asterism"` also brings a layer with blocks, a receiving
+thread, Enumerators and pattern matching (`lib/asterism/cruby/`). It is
+built on the polled API below, which stays as it is: code written for a
+board still runs unchanged on CRuby, and code using this layer does not run
+on a board.
+
+### Zenoh
+
+```ruby
+Asterism::Zenoh.open("tcp/192.0.2.2:7447") do |s|   # closed when the block ends
+  s.subscribe("home/**") { |sample| puts "#{sample.key} = #{sample.payload}" }
+  s.queryable("home/pc/status") { |q| q.reply("ok") }
+  s.put("home/pc/hello", "hi")
+  s.get("home/**/status").each { |reply| p reply }   # until every answer came or the time ran out
+  sub = s.subscribe("sensor/temp")                    # no block: take from it
+  sub.each.lazy.map { _1.payload.to_f }.first(3)      # waits for the samples
+  s.liveliness_watch("asterism/**") { |key, alive| puts "#{key} #{alive}" }
+  s.run                                               # receive on this thread until Ctrl-C
+end
+
+# asterism-zenoh 0.3.0 (CRuby only)
+Asterism::Zenoh.open("tls/192.0.2.2:7447",
+                     config: { "transport/link/tls/root_ca_certificate" => "ca.pem" }) do |s|
+  pub = s.publisher("home/pc/temp", encoding: "text/plain", priority: :data_high)
+  pub.on_matching { |listening| puts "listened to: #{listening}" }
+  pub.put(21.5)
+  s.delete("home/pc/old")
+  s.subscribe("home/**") { |sm| p [sm.kind, sm.encoding, sm.timestamp&.to_time] }
+  q = s.querier("home/**/status", timeout: 1.0)
+  q.get(errors: true).each { |r| puts r.error? ? "error: #{r.payload}" : r.payload }
+  latched = s.advanced_publisher("home/pc/mode", cache: 1, sample_miss_detection: true)
+  latched.put("eco")                                 # late subscribers with history: get it
+  s.advanced_subscriber("home/**/mode", history: true) { |sm| puts sm.payload }
+  s.on_transport { |ev| puts "#{ev.zid} #{ev.kind}" }
+  s.run
+end
+```
+
+| Call | Notes |
+|---|---|
+| `Asterism::Zenoh.open(locator = nil, mode:, listen:, scouting:, timestamping:, config:, config_file:, interval: 0.002)` | `Session.open` wrapped in a `Connection`. With a block: yields it, closes it after (also on an exception), returns the block's value |
+| `Connection.new(session)` | wraps a session opened with the polled API |
+| `s.put(key, payload, attachment: nil, **opts)` | a payload that is not a String is sent as `to_s`. opts: `encoding:`, `priority:`, `congestion_control:`, `express:`, `reliability:`, `timestamp:`, `allowed_destination:` (asterism-zenoh's `Session#put`) |
+| `s.delete(key, **opts)` | subscribers get a `Sample` of kind `:delete` |
+| `s.publisher(key, **opts)` | a `Publisher`: `put(payload, attachment:, encoding:, timestamp:)`, `delete`, `matching?`, `on_matching { \|listening\| }` (on the receiving thread), `close` |
+| `s.advanced_publisher(key, cache:, sample_miss_detection:, publisher_detection:, **opts)` | the same `Publisher`, keeping the last samples for late subscribers (ROS 2's transient local) |
+| `s.advanced_subscriber(key, depth: 16, history:, recovery:, **opts) { \|sample\| }` | a `Subscription` that also gets the publishers' history; `on_publisher { \|key, alive\| }`, `on_miss { \|miss\| }` |
+| `s.querier(key, timeout: 2.0, **opts)` | a `Querier`: `get(params:, payload:, attachment:, encoding:, errors: false)` like `s.get`, `matching?`, `on_matching`, `close` |
+| `s.on_transport(history: false) { \|ev\| }` / `s.on_link { \|ev\| }` | a `TransportEvent` / `LinkEvent` (`added?` / `removed?`, `zid`, ...) on the receiving thread; returns an `Events` (`close`) |
+| `s.peer_zids`, `router_zids`, `transports`, `links`, `new_timestamp`, `declare_keyexpr(key)` | as in asterism-zenoh |
+| `s.subscribe(key, depth: 16) { \|sample\| }` | the block gets each `Sample` on the receiving thread. Returns a `Subscription` (`close` ends it) |
+| `s.subscribe(key, depth: 16)` | a `Subscription` to take from: `each(timeout: nil)` waits for samples (an Enumerator without a block; Enumerable), `each_pending` gives what is there now as Samples, `pending` / `received` / `dropped` / `closed?` / `close` |
+| `s.queryable(key, depth: 16, complete: false) { \|q\| }` | each query on the receiving thread, finished when the block returns. `q.reply(payload)` answers on the queryable's key (when it has no wildcard), `q.reply(key, payload, attachment:)` as before. Without a block, `each(timeout:)` yields the queries |
+| `s.get(key, timeout: 2.0, params:, payload:, attachment:, target:, consolidation:, errors: false, **opts)` | an Enumerator of `Reply`; each iteration sends the get again. With a block: yields each, returns their number. `errors: true` also yields the error replies (`reply.error?`); opts: `encoding:`, `priority:`, `congestion_control:`, `express:`, `accept_replies:` |
+| `s.liveliness(key)` | a token (`close`) |
+| `s.liveliness_watch(key) { \|key, alive\| }` | on the receiving thread; the tokens alive now come first. Without a block, `each` yields `Liveliness` (`key`, `alive?`) |
+| `s.liveliness_get(key, timeout: 2.0)` | the keys alive now (an Array) |
+| `s.start` / `s.stop` / `s.running?` | receive on a thread of its own |
+| `s.run` | receive on this thread until `stop`, the connection closing, or Ctrl-C (returns nil) |
+| `s.on_error { \|error, where\| }` | what the blocks raise (`StandardError`); without a handler it is printed with `warn`. Receiving goes on |
+| `s.session`, `zid`, `peers`, `poll`, `closed?`, `close` | |
+
+`Sample`, `Reply` (`key`, `payload`, `attachment`, and since 0.3.0 `kind`,
+`encoding`, `timestamp` and the rest; `text` is the payload as UTF-8; both
+are asterism-zenoh's) and `Liveliness` are `Data` values, so they work with pattern
+matching: `case sample in {key: %r{/temp\z}, payload:}`. Times are seconds
+here (the polled API counts milliseconds).
+
+### Objects
+
+```ruby
+Asterism.connect("tcp/192.0.2.2:7447", node: "mypc", app: "demo") do |net|   # closed after
+  net.expose("screen", Screen.new, methods: [:say])
+  net.on_join  { |node| puts "joined #{node}" }
+  net.on_leave { |node| puts "left #{node}" }
+  board = net["fmruby-aaaaaa/demo/screen"]
+  board.say("hello")
+  net.each("*/demo/info").map(&:status)               # Enumerable
+  net.run                                             # answer calls until Ctrl-C
+end
 ```
 
+| Call | Notes |
+|---|---|
+| `Asterism.connect(...) { \|net\| }` | yields an `Asterism::Net`, `Asterism.close` when the block ends; returns the block's value. Without a block, as before |
+| `Asterism.net` | the `Net` of the connection made without a block (nil when not connected) |
+| `net.expose` / `unexpose` / `exposed` | as `Asterism.expose`. The methods run on the receiving thread, in `run`, or in whatever polls |
+| `net[path, timeout: nil]` | a proxy (`timeout` in seconds) |
+| `net.each(pattern = "**")` | the proxies alive now; an Enumerator without a block |
+| `net.on_join { \|node\| }` / `net.on_leave { \|node\| }` | `Asterism.on_join` / `on_leave` of the polled API (the same blocks, told from `Asterism.poll`), here on the receiving thread; what they raise goes to `on_error` |
+| `net.start` / `stop` / `run` / `running?` / `on_error` | as for Zenoh. A method of an exposed object that raises is answered to its caller as a `RemoteError`, as before; `on_error` gets what `on_join` / `on_leave` raise |
+| `net.nodes`, `node_id`, `app`, `connected?`, `lost_reason`, `poll`, `close` | |
+
+### ROS 2
+
+```ruby
+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| puts 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                                            # until Ctrl-C
+end
+```
+
+| Call | Notes |
+|---|---|
+| `Asterism::ROS.connect(locator = nil, domain: 0, type_path: nil, mode:, listen:)` | opens a session; yields an `Asterism::ROS::Connection` and closes it after. `type_path:` adds directories to `TYPE_PATH` |
+| `ros.node(name, namespace: "/", enclave: "/")` | an `Asterism::ROS::Node` (every method of the polled API) with the calls below |
+| `node.subscribe(topic, type) { \|msg, info\| }` | the polled API's (run from `node.poll`), here on the receiving thread; `info` is the `Attachment` or nil. Without a block: a subscription whose `each(timeout: nil)` waits for `[msg, info]` (Enumerable) |
+| `node.topic(topic, type).each` | subscribes for the iteration and withdraws after it (`first(n)`, `break`, the time running out) |
+| `node.every(seconds) { }` | the polled API's timer (run from `node.poll`), here on the receiving thread; returns a `Timer` (`cancel`, `fired`) |
+| `node.service(name, type) { \|req\| response }` | answered while the connection spins (or from `node.poll`). What the block raises goes to `on_error`, and that request gets no answer |
+| `node.call(name, type, request = nil, timeout: 2.0, **fields)` | waits for the response |
+| `ros.spin` (`run`) / `start` / `stop` / `running?` / `on_error` / `close` | |
+| `ros.zenoh` | the `Asterism::Zenoh::Connection` underneath (same receiving thread) |
+
+`type` is a generated type or its name (`"geometry_msgs/msg/Twist"`).
+Messages and `Attachment` take part in pattern matching (`deconstruct_keys`,
+on the boards too): `case msg in {linear: {x:}, angular: {z:}}`. A type
+that is not bundled: generate it with `tools/asterism_msggen.rb -o DIR`
+(see [Message types](#message-types)) and give the directory, as
+`Asterism::ROS.connect(..., type_path: "DIR")` or
+`Asterism::ROS::TYPE_PATH << "DIR"`; then pass its name like any other.
+
+### Threads
+
+- Each connection has at most one receiving thread, and only when the
+  application asks for it (`start`), or the application's own thread
+  inside `run` / `spin`. The blocks (subscriptions, queryables, timers,
+  services, exposed objects, `on_join`) run there, one after another. **A
+  block that takes long delays everything else that connection receives**:
+  hand long work to a thread or a Queue of your own.
+- zenoh-c never calls Ruby: it fills the queues, and the receiving thread
+  empties them every 2 ms (`interval:`) with the polled API.
+- A tick of the receiving thread holds the connection's lock (a `Monitor`;
+  for the object layer, which is one connection per process,
+  `Asterism::LOCK`). The application's calls into the same layer take it
+  too, so the layers written for one thread are never entered by two at
+  once.
+- A call that waits for an answer (`proxy.method`, `node.call`) from another
+  thread while the receiving thread runs does not poll by itself: it waits
+  until a tick brings the answer. On the receiving thread itself (a block
+  that calls), or while nothing receives, it polls as on the boards.
+- `stop`, `close` and the end of the block wait for the receiving thread to
+  end; no thread is left behind. When the connection is lost the receiving
+  thread ends by itself, and waiting calls raise as before.
+- Enumerators (`each`, `get`, `topic`) wait on the thread that iterates
+  them.
+
 ## License
 
 MIT (LICENSE) for Asterism's code. The ROS 2 definitions in
@@ -108,7 +278,8 @@ RubyGems, and on mruby / PicoRuby the Zenoh binding is the separate mrbgem
 
 # The API
 
-The same on every Ruby. The examples use PicoRuby's `sleep_ms`; on CRuby
+The same on every Ruby (the polled API; CRuby adds the layer described in
+[The Ruby-like API](#the-ruby-like-api-cruby-only)). The examples use PicoRuby's `sleep_ms`; on CRuby
 write `sleep`. When PicoRuby's `Machine` is there it is used for the clock
 and the short pauses while waiting; otherwise `Time` and `sleep`. Besides
 `Asterism::Zenoh`, the layers need a `MessagePack` module with `pack` /
@@ -138,7 +309,8 @@ Asterism.nodes                            # => ["linux", "fmruby-bbbbbb"]
 | `Asterism.connect(locator, node:, app:, mode: nil, listen: nil)` | `Asterism` | `locator`, `mode:`, `listen:` go to `Asterism::Zenoh::Session.open` (client of a router by default; `mode: :peer` with or without `listen:` without one). `node:` is this machine's ID, `app:` the application's name (one key chunk each: no `/ * $ ? #`, not starting with `@`; else `ArgumentError`). `Disconnected` when it cannot connect; `Error` when objects of the same `<node>/<app>` are already alive (a second copy of the application), or when already connected. Waits up to about 1.5 s for that check (a router answers at once). |
 | `Asterism.expose(name, obj, methods:)` | `"<node>/<app>/<name>"` | `methods:` is an Array of names, or a Hash `name => number of arguments` (checked before the call; `-1` or the Array form: any). `ArgumentError` when `obj` has no such public method. Exposing a name again replaces it. |
 | `Asterism.unexpose(name)` | true / false | |
-| `Asterism.poll` | true / false | Call from the update loop: polls Zenoh, answers the calls that came in, follows who is alive. `false` once the connection is closed or lost. |
+| `Asterism.poll` | true / false | Call from the update loop: polls Zenoh, answers the calls that came in, follows who is alive and calls the `on_join` / `on_leave` blocks. `false` once the connection is closed or lost. |
+| `Asterism.on_join { \|node\| }` / `Asterism.on_leave { \|node\| }` | `Asterism` | Another node appeared (its node token or one of its objects) / is gone (no token and no object left). The nodes there already join on the first polls after connecting; when the connection is lost, every node known until then leaves (on the next `Asterism.poll`). The blocks run from `Asterism.poll` only, never from the polling inside a waiting call; what they raise comes out of `Asterism.poll`. `Asterism.close` forgets them (a lost connection does not). |
 | `Asterism[path, timeout_ms = 2000]` | `Proxy` | `path` is `<node>/<app>/<object>` without wildcards (`ArgumentError`). Nothing is sent until a method is called. |
 | `proxy.<method>(*args, **kw)` | the remote return value | Waits for the answer (`timeout_ms`). `RemoteError` when it raised there or could not be called (not exposed: `NoMethodError`; wrong number of arguments: `ArgumentError`; no such object: `NameError`), `Timeout` when no answer came in time (also at once when nobody answers that key), `Disconnected`, `EncodeError` (before anything is sent) for a value MessagePack cannot carry. A block cannot be sent (`ArgumentError`). |
 | `proxy.async.<method>(...)` | `Future` | Sends and returns at once. `EncodeError` / `Disconnected` are raised here. |
@@ -214,6 +386,22 @@ took zenoh replies through blocks and fetched the meta from inside
 `respond_to_missing?`, overflowed the stack there. Make waiting calls from
 the update loop, or use `async`.
 
+The blocks the layers call (`Asterism.on_join` / `on_leave`, the ROS
+`node.subscribe` and `node.every` blocks) run from `Asterism.poll` /
+`node.poll`, that is on the update loop's stack, one Ruby block call deeper.
+The layers walk their lists with `while` loops so that nothing else stands
+between the update loop and the block. **Do not wait inside these blocks**
+(no proxy call, no `node.call` / `client.call`): note what came, and make
+the call from the update loop, or start a `call_async` / `async` call and
+look at it later.
+
+Measured on the P4 (Family mruby, 16 KB): an application with
+`on_join` / `on_leave` blocks, relaying calls with another machine in both
+directions at once, keeps 5.8 KB free (as before the blocks); a ROS node
+publishing from `node.every` and receiving through a `node.subscribe` block
+keeps 6.9 KB free, the same as polling `each_pending` by hand. Loading a
+nested type (`geometry_msgs/msg/Twist`) at start-up took 0.6 KB more.
+
 ## Limits
 
 - Objects cannot be passed by reference (a return value is a copy), blocks
@@ -222,6 +410,14 @@ the update loop, or use `async`.
   node; when one of them closes, the others still list the node through
   their objects, but a watcher may see the node token go away.
 - No authentication: a trusted LAN is assumed.
+- Pattern matching on the boards: PicoRuby's compiler (checked on Family
+  mruby's application VM) runs `case/in` with `deconstruct_keys`, nested
+  hash patterns, array patterns, guards, alternatives, ranges, pins and
+  `**rest`, but not two forms: a class as the value in a hash pattern
+  (`in {x: Float}` does not match) and, inside a block, binding a variable
+  of the enclosing method (`v = nil; list.each { |m| case m in {a: v} ... }`
+  leaves it nil). Put the `case` in a method of its own, as in the example
+  above.
 
 ## ROS 2 (rmw_zenoh): `Asterism::ROS` and `Asterism::CDR`
 
@@ -244,6 +440,17 @@ loop do
   pub << { data: "hello" }                               # or pub.publish(str.new(data: "hello"))
   sub.each_pending { |msg, info| puts "#{info && info.sequence}: #{msg.data}" }
 end
+
+# or with blocks, run from node.poll (in the update loop):
+node.every(1) { pub << { data: "tick" } }
+node.subscribe("/cmd_vel", "geometry_msgs/msg/Twist") { |msg, _info| drive(msg) }
+loop { node.poll }
+
+def drive(msg)
+  case msg                                               # deconstruct_keys
+  in { linear: { x: }, angular: { z: } } then move(x, z)
+  end
+end
 node.close                                               # or let the session close
 ```
 
@@ -271,7 +478,9 @@ end
 | `node.subscription(topic, type, qos: DEFAULT_QOS, depth: 16)` | `Subscription` | Subscribes and declares the subscription token. |
 | `sub.each_pending { \|msg, info\| }` | count | `info` is an `Attachment` (`sequence`, `stamp_ns`, `gid`) or nil. Samples that are not valid CDR are skipped and counted in `sub.errors`. |
 | `node.service(name, type, qos: DEFAULT_QOS, depth: 8) { \|req\| response }` | `Service` | Serves `name` (`ros2 service list`). The block gets a `type::Request` and returns a `type::Response` or a Hash of its fields. It runs from `node.poll` (or `service.handle_pending`), never behind the application. A request without rmw_zenoh's attachment, or that does not decode, is counted in `service.errors` and gets no answer. An exception from the block ends that request without an answer and is raised from `node.poll`. `service.handled`: answered so far. |
-| `node.poll(steps = 8)` | true / false | `session.poll(steps)`, then answers the requests waiting for this node's services. Returns what `session.poll` returns. |
+| `node.poll(steps = 8)` | true / false | `session.poll(steps)`, then answers the requests waiting for this node's services, then gives what came to the `subscribe` blocks and fires the `every` timers that are due. Returns what `session.poll` returns. A waiting `client.call` polls only the session and the services (`node.pump`), not the blocks. |
+| `node.subscribe(topic, type, qos: DEFAULT_QOS, depth: 16) { \|msg, info\| }` | `Subscription` | `node.subscription` whose messages (decoded, with their `Attachment` or nil) go to the block, from `node.poll`. `sub.close` ends it. Do not wait in the block (see [Stack](#stack)). |
+| `node.every(seconds) { }` | `Timer` | Calls the block every `seconds` (a Float works), the first time one period from now, from `node.poll` (so no more often than the update loop polls). It keeps the period; after a long stall it starts again from now instead of firing the missed times at once. `timer.cancel`, `timer.fired` (count), `timer.period`. Do not wait in the block. |
 | `node.client(name, type, qos: DEFAULT_QOS)` | `Client` | Declares the client token. |
 | `client.call(request = nil, timeout_ms: 2000, **fields)` | `type::Response` | Sends the request (a `type::Request`, a Hash, or the fields as keywords) and waits, polling the node (its services keep answering). `Asterism::ROS::Timeout` when no response came in time, at once when nobody serves the name; `Asterism::Zenoh::Error` when the session closed. |
 | `client.call_async(request = nil, timeout_ms: 2000, **fields)` | `Call` | Sends and returns at once. `call.done?` never waits (`node.poll` moves it on); `call.value` waits and returns the response or raises like `call`; `call.response` (nil until it came), `call.took_ms`, `call.sequence`. |

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