libtmux-async 0.1.0.alpha.2 → 0.1.0.alpha.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1ea540b90e8bd302c36602c0d1b3db74136a60773deb92bb5358b3c7bc48e3f0
-  data.tar.gz: cf67c1667785062c2c29a6c27732e3bf6012d4edd17ff62a4679e55429aeda91
+  metadata.gz: e64f6117feba9404d8cd8fabcdacbdf1ef098f3b1bdc6226c4f03c66a2581fbc
+  data.tar.gz: 9ff7ca35a31683ccdf6ba76562ec4ff156aaf2eb75e9e13e1e1a197abefbdbc4
 SHA512:
-  metadata.gz: e99804e99791d37c02fb54b374f9a29fcad90b5296da46bc5f333e5d20fedd3796a9796e2103a52c690b76981b806826ea18c0c2da7916b4fa72100e8496c541
-  data.tar.gz: 93ddf5982950f17a2afd0199186fde93ecf590006dc4fbaf84e76458405cb0092d28b4378914e481ac710b55012d056867a03b9b436e99e74f2e4f88444f1172
+  metadata.gz: cb9f3e5f40e3ad10061c168a68728d33a19a6917071bf4853f63a83f122427c7b9caa43312a120aa2d30fa4abaeb83bfd36457717099a06a484479b135f015f7
+  data.tar.gz: df18e0b035473957c327faf618798fd1dbd2e12e4e19aa5fc423ce5426442d5842d2637e6246ea345f9a9b833b387ae2805c35e2cba04b8cc2e373f280f01567

data/README.md

@@ -11,68 +11,135 @@
 
 # libtmux-async
 
-Run libtmux operations inside an application-owned Async task. This
-gem provides a subprocess facade, ordered mapping, control replies and event
-subscriptions. Imports start no scheduler, tmux server or background task.
+Run libtmux operations inside an application-owned Async task: a
+[subprocess facade][async-server], [ordered mapping][async-scope-map],
+[control replies][guardedreply] and
+[event subscriptions][async-controlsubscription].
+
+[API reference](https://libtmux.org/en/ruby/latest/reference/libtmux-async/) ·
+[Guide](https://libtmux.org/en/ruby/latest/guides/async/) ·
+[RubyGems](https://rubygems.org/gems/libtmux-async)
 
 </div>
 
-Requires tmux 3.3a or newer. The Async facade dispatches through a
-version-checked core server and carries the same daemon release check.
+Part of [libtmux for Ruby](https://github.com/libtmux/libtmux-ruby#readme).
+Built on [libtmux](https://github.com/libtmux/libtmux-ruby/tree/master/gems/libtmux).
+
+Imports start no scheduler, tmux server or background task. A scope borrows a
+core [`Server`][server] and leaves its daemon running when the scope exits.
 
-Install the alpha with `gem install libtmux-async --pre`.
+**Contents** — [Quick start](#quick-start) ·
+[Cancel](#cancel-a-request-without-stalling-the-others) ·
+[Map](#keep-results-ordered-and-bounded) ·
+[Control](#read-control-events-in-a-scope) ·
+[Leaves out](#what-it-leaves-out) · [Support](#support-and-status) ·
+[Documentation](#documentation)
 
-The [complete program](../../examples/async_cancel.rb) owns an isolated server
-and its cleanup. This excerpt uses that server and creates the Async root:
+## Quick start
 
-<!-- example: async_cancel/main -->
+Install the alpha. It needs Ruby 3.3 or newer and tmux 3.3a or newer on
+`PATH`:
+
+```console
+$ gem install libtmux-async --pre
+```
+
+Open a scope over a core server with [`LibTmux::Async.open`][async-open], then
+capture every pane concurrently with [`Scope#map`][async-scope-map]. The outer
+[`Server.start`][server-start] block only supplies a server for the scope to
+borrow:
+
+<!-- example: api_async_scope/main -->
 ```ruby
-Async do |parent|
-  LibTmux::Async.open(parent: parent, server: server) do |scope|
-    waiting = parent.async do
-      scope.server.run(["wait-for", "-S", "ready", ";", "wait-for", "held"], timeout: 0.5)
-    rescue LibTmux::Cancelled => error
-      error
+require "libtmux"
+require "libtmux/async"
+
+LibTmux::Server.start do |server|
+  server.new_session(name: "work", command: ["/bin/cat"])
+  server.new_session(name: "logs", command: ["/bin/cat"])
+  Async do |parent|
+    LibTmux::Async.open(parent: parent, server: server) do |scope|
+      refs = scope.server.list_panes.map(&:ref)
+      screens = scope.map(refs, concurrency: 2) { |ref| scope.server.pane(ref).capture }
+      puts "captured panes: #{screens.length}"
+      puts "all succeeded: #{screens.all?(&:success?)}"
     end
-    scope.server.wait_for("ready", timeout: 0.5)
-    Example.check(scope.diagnostics.fetch(:active_process_slots) == 1, "waiting client lost its slot")
-    captures = scope.map(scope.server.list_panes.map(&:ref), concurrency: 2) do |ref|
-      scope.server.pane(ref).capture
+  end.wait
+end
+```
+<!-- /example -->
+
+It prints:
+
+```text
+captured panes: 2
+all succeeded: true
+```
+
+- Leave out `parent:` to use the current Async task.
+- A scope rejects use from another thread, process or scheduler, so create one
+  scope for each scheduler thread.
+- Scope exit retires its clients and joins its owned tasks.
+
+## Cancel a request without stalling the others
+
+### [`Async::Server#run`][async-server-run]: cancel a request that is waiting
+
+`scope.server.run` waits for a tmux command in a task. Cancel that task and
+the scope retires its client, while sibling requests keep running.
+
+[`wait_for`][async-server-wait_for] returns once the request has signalled
+that it is running, so the cancel arrives while it waits:
+
+<!-- example: api_async_run/main -->
+```ruby
+require "libtmux"
+require "libtmux/async"
+
+LibTmux::Server.start do |server|
+  server.new_session(name: "work", command: ["/bin/cat"])
+  Async do |parent|
+    LibTmux::Async.open(parent: parent, server: server) do |scope|
+      waiting = parent.async do
+        scope.server.run(["wait-for", "-S", "ready", ";", "wait-for", "held"], timeout: 5)
+      rescue LibTmux::Cancelled => error
+        error
+      end
+      scope.server.wait_for("ready", timeout: 5)
+      waiting.cancel
+      failure = waiting.wait
+      puts "request: #{failure.class}"
+      puts "delivery: #{failure.delivery}"
     end
-    Example.check(captures.all?(&:success?), "sibling captures stalled")
-    waiting.cancel
-    failure = waiting.wait
-    Example.check(failure.is_a?(LibTmux::Cancelled), "cancellation lost")
-    Example.check(failure.delivery == :possibly_sent, "cancelled dispatch claimed no effects")
-    Example.raises(Errno::ECHILD) { Process.waitpid(failure.pid, Process::WNOHANG) }
-    Example.check(scope.server.diagnostics.fetch(:admitted_requests).zero?, "cancelled client remains admitted")
-  end
-end.wait
+  end.wait
+end
 ```
 <!-- /example -->
 
-Omitting `parent:` uses the existing current Async task. The source server must
-outlive the scope. References keep their source binding identity. Scope exit
-retires its clients and joins its owned tasks; it leaves the borrowed daemon
-alive. A scope rejects use from another thread, process or scheduler. Create a
-separate scope for each scheduler thread. Interactive terminal attachment stays
-on the blocking core facade and raises `UnsupportedFeatureError` on this facade.
-
-`scope.server.run` returns the same binary `CommandResult` as core. Its stdin,
-stdout and stderr are owned by scheduler tasks. A bounded native helper observes
-and reaps each child only after its final signalling handoff. Cancelling the
-calling task retires its client and raises `Cancelled` with `:not_sent` or
-`:possibly_sent` delivery. An already observed exit completes its bounded drain.
-Repeated cancellation does not restart cleanup deadlines or replace an earlier
-operation failure. Deadlines cannot undo tmux effects.
-
-`scope.map` returns a frozen Array in input order; independent requests may
-complete out of order. It caps retained items at 1024 and accounts payload bytes
-in strings, primitive values, `CommandResult`, Arrays and Hashes. Cycles and
-excessive nesting are refused. Application-defined results require an explicit
-`result_bytes:` callable returning a nonnegative Integer. Keep measured values
-unchanged until the map returns. These payload limits complement item counts;
-they are not exact Ruby heap measurements.
+It prints:
+
+```text
+request: LibTmux::Cancelled
+delivery: possibly_sent
+```
+
+- `run` returns the same binary [`CommandResult`][commandresult] as the core.
+- [`Cancelled`][cancelled] carries `delivery` as `:not_sent` or
+  `:possibly_sent`. A deadline cannot undo tmux effects.
+- Interactive terminal attachment stays on the blocking core and raises
+  [`UnsupportedFeatureError`][unsupportedfeatureerror] here.
+
+The [complete program](../../examples/async_cancel.rb) also keeps capturing
+while the request waits, and checks that the cancelled client is reaped. The
+contract is in [Async scope][behavior-async-scope].
+
+## Keep results ordered and bounded
+
+### [`Scope#map`][async-scope-map]: input order, capped payloads
+
+`map` runs a block for each item, up to `concurrency:` at a time, and returns a
+frozen Array in input order. The quick start is a `map`. These limits apply to
+every scope:
 
 | Scope limit | Default |
 | --- | --- |
@@ -84,23 +151,134 @@ they are not exact Ruby heap measurements.
 | Control connections | 4 |
 | Ordinary command deadline | 5 seconds |
 
-Control connections use their own request, reply and subscriber limits. Obtain
-one with `scope.server.open_control(session: ref)`. `exchange` returns guarded
-`GuardedReply` blocks with `:boundary_window` attribution. It makes no claim of
-final command completion. Outside-block events arrive through `events.next` or
-an explicit `subscribe`; consumer callbacks run outside the parser. Reliable
-subscriptions raise on overflow. Tail subscriptions report dropped ranges.
-Cancelling a dispatched, undrained exchange closes that connection.
-
-`pause_output(pane_id:)` and `resume_output(pane_id:)` retain guarded evidence
-and report possible output loss through gap events. A requested-action gap
-does not prove that the action took effect. Close a connection before passing
-it as `reconnect:` to `scope.server.open_control`; the replacement stays owned
-by that scope and reports a new generation plus a gap with unknown loss.
-Subscriptions expose their `generation`; prior subscriptions stay closed.
-Reconnect and resume never replay requests or missed output.
-
-The development bundle pins Async 2.46 and io-event 1.22. The
-[compatibility workflow](https://github.com/libtmux/libtmux-ruby/actions/workflows/compatibility.yml)
-exercises the selected Ruby/tmux versions on Linux and macOS and retains
-per-revision results. Package builds and tests do not publish this gem.
+- Independent requests may complete out of order, and the result is still in
+  input order.
+- `map` caps retained items and counts payload bytes of strings, primitive
+  values, [`CommandResult`][commandresult], Arrays and Hashes. Cycles and deep
+  nesting are refused.
+- An application-defined result needs a `result_bytes:` callable that returns
+  a nonnegative Integer.
+- Keep measured values unchanged until the map returns. The counts cover
+  payload bytes and do not measure the Ruby heap.
+
+The contract is in [Async map][behavior-async-map].
+
+## Read control events in a scope
+
+### [`Async::Server#open_control`][async-server-open_control]: replies and events
+
+A control connection has its own request, reply and subscriber limits.
+[`exchange`][async-controlconnection-exchange] runs one command, and
+[`events`][async-controlconnection-events] yields what tmux reports outside a
+reply:
+
+<!-- example: api_async_control/main -->
+```ruby
+require "libtmux"
+require "libtmux/async"
+
+LibTmux::Server.start do |server|
+  session = server.new_session(name: "work", command: ["/bin/cat"])
+  window = session.list_windows.fetch(0)
+  Async do |parent|
+    LibTmux::Async.open(parent: parent, server: server) do |scope|
+      scope.server.open_control(session: session.ref) do |control|
+        reply = control.exchange("display-message -p ready", timeout: 5)
+        puts "reply: #{reply.blocks.last.body.strip}"
+        events = control.events
+        window.rename("renamed")
+        event = events.next(timeout: 5) until event&.raw&.start_with?("%window-renamed")
+        puts "event: #{event.raw.strip}"
+      end
+    end
+  end.wait
+end
+```
+<!-- /example -->
+
+It prints:
+
+```text
+reply: ready
+event: %window-renamed @0 renamed
+```
+
+- `exchange` answers a [`GuardedReply`][guardedreply] with `:boundary_window`
+  attribution. It makes no claim that the command finished.
+- Events arrive through `events.next` or an explicit
+  [`subscribe`][async-controlconnection-subscribe]. Consumer callbacks run
+  outside the parser.
+- A reliable subscription raises on overflow, and a tail subscription reports
+  the dropped range.
+- Cancelling a dispatched exchange that is not drained closes the connection.
+- [`pause_output`][async-controlconnection-pause_output] and
+  [`resume_output`][async-controlconnection-resume_output] report possible
+  loss through gap events. A gap does not show that the action took effect.
+- To reconnect, close the connection and pass it as `reconnect:`. The
+  replacement stays owned by the scope, has a new generation, and starts with
+  a gap of unknown loss. Nothing is replayed.
+
+The contract is in [Control connections][behavior-control].
+
+## What it leaves out
+
+- **Terminal attachment.** `attach` stays on the blocking core and raises
+  [`UnsupportedFeatureError`][unsupportedfeatureerror] on this facade.
+- **Replay.** Reconnect and resume never replay requests or missed output. See
+  [Control connections][behavior-control].
+- **A scheduler.** Imports start no scheduler or background task, and your
+  application owns the Async root task. See [Execution modes][doc-modes].
+- **Cross-thread scopes.** A scope belongs to the thread, process and
+  scheduler that opened it. See [Async scope][behavior-async-scope].
+
+## Support and status
+
+**Alpha.** APIs may change between releases.
+
+- **Ruby 3.3 or newer** and **tmux 3.3a or newer.** The facade dispatches
+  through a version-checked core server, so it carries the same daemon release
+  check.
+- **Control connections need tmux 3.7 or newer.**
+  [`open_control`][async-server-open_control] refuses an older daemon before a
+  control client attaches.
+- **Async 2.46.** The gem depends on `async` ~> 2.46.0 and the same version of
+  `libtmux`.
+- **Linux, including WSL, and macOS.** The [compatibility workflow][compat]
+  runs Ruby 3.3, 3.4 and 4.0 with tmux 3.3a through 3.8 on Ubuntu 24.04 and retains
+  per-revision results. macOS is supported on a best-effort basis, and CI
+  coverage for it is highly limited.
+
+## Documentation
+
+| | |
+| --- | --- |
+| [Reference](https://libtmux.org/en/ruby/latest/reference/libtmux-async/) | The Async classes, one page each |
+| [Async guide](https://libtmux.org/en/ruby/latest/guides/async/) | Running concurrent commands within an owned scope |
+| [Execution modes][doc-modes] | Blocking calls, Async tasks and control subscriptions |
+| [Recipes][doc-recipes] | Complete programs with checked excerpts |
+| [Public behavior][behavior-async-scope] | Scheduling, ownership and limits of a scope |
+
+[async-controlconnection-events]: https://libtmux.org/en/ruby/latest/reference/libtmux-async-controlconnection-events/
+[async-controlconnection-exchange]: https://libtmux.org/en/ruby/latest/reference/libtmux-async-controlconnection-exchange/
+[async-controlconnection-pause_output]: https://libtmux.org/en/ruby/latest/reference/libtmux-async-controlconnection-pause_output/
+[async-controlconnection-resume_output]: https://libtmux.org/en/ruby/latest/reference/libtmux-async-controlconnection-resume_output/
+[async-controlconnection-subscribe]: https://libtmux.org/en/ruby/latest/reference/libtmux-async-controlconnection-subscribe/
+[async-controlsubscription]: https://libtmux.org/en/ruby/latest/reference/libtmux-async-controlsubscription/
+[async-open]: https://libtmux.org/en/ruby/latest/reference/libtmux-async-open/
+[async-scope-map]: https://libtmux.org/en/ruby/latest/reference/libtmux-async-scope-map/
+[async-server]: https://libtmux.org/en/ruby/latest/reference/libtmux-async-server/
+[async-server-open_control]: https://libtmux.org/en/ruby/latest/reference/libtmux-async-server-open_control/
+[async-server-run]: https://libtmux.org/en/ruby/latest/reference/libtmux-async-server-run/
+[async-server-wait_for]: https://libtmux.org/en/ruby/latest/reference/libtmux-async-server-wait_for/
+[behavior-async-map]: ../../docs/reference/behavior.md#async-map
+[behavior-async-scope]: ../../docs/reference/behavior.md#async-scope
+[behavior-control]: ../../docs/reference/behavior.md#control-connections
+[cancelled]: https://libtmux.org/en/ruby/latest/reference/libtmux-cancelled/
+[commandresult]: https://libtmux.org/en/ruby/latest/reference/libtmux-commandresult/
+[compat]: https://github.com/libtmux/libtmux-ruby/actions/workflows/compatibility.yml
+[doc-modes]: ../../docs/modes.md
+[doc-recipes]: ../../docs/recipes.md
+[guardedreply]: https://libtmux.org/en/ruby/latest/reference/libtmux-guardedreply/
+[server]: https://libtmux.org/en/ruby/latest/reference/libtmux-server/
+[server-start]: https://libtmux.org/en/ruby/latest/reference/libtmux-server-start/
+[unsupportedfeatureerror]: https://libtmux.org/en/ruby/latest/reference/libtmux-unsupportedfeatureerror/

data/lib/libtmux/async/control.rb

@@ -23,30 +23,34 @@ module LibTmux
           raise ArgumentError, "timeout must be finite and nonnegative"
         end
         deadline = timeout && clock + timeout
-        loop do
-          @mutex.synchronize do
-            if @gap
-              gap, @gap = @gap, nil
-              return gap
-            end
-            unless @queue.empty?
-              event = @queue.shift
-              @bytes -= event.bytesize
-              return event
+        # Kernel#loop would swallow the StopIteration that ends the stream and
+        # return nil from next.
+        while true
+          begin
+            @mutex.synchronize do
+              if @gap
+                gap, @gap = @gap, nil
+                return gap
+              end
+              unless @queue.empty?
+                event = @queue.shift
+                @bytes -= event.bytesize
+                return event
+              end
+              raise @failure if @failure
+              raise StopIteration if @closed
             end
-            raise @failure if @failure
-            raise StopIteration if @closed
-          end
-          remaining = deadline && deadline - clock
-          raise DeadlineExceeded.new("control event deadline elapsed", phase: :subscription) if remaining && remaining <= 0
+            remaining = deadline && deadline - clock
+            raise DeadlineExceeded.new("control event deadline elapsed", phase: :subscription) if remaining && remaining <= 0
 
-          if remaining
-            ::Async::Task.current.with_timeout(remaining) { @changed.wait }
-          else
-            @changed.wait
+            if remaining
+              ::Async::Task.current.with_timeout(remaining) { @changed.wait }
+            else
+              @changed.wait
+            end
+          rescue ::Async::TimeoutError
+            raise DeadlineExceeded.new("control event deadline elapsed", phase: :subscription)
           end
-        rescue ::Async::TimeoutError
-          raise DeadlineExceeded.new("control event deadline elapsed", phase: :subscription)
         end
       end
 
@@ -60,6 +64,7 @@ module LibTmux
     class ControlConnection < LibTmux::ControlConnection
       def initialize(scope:, binding:, session_id:, reconnect: nil, **limits)
         @scope = scope
+        @release = binding.release
         @writer_changed = ::Async::Notification.new
         @startup_changed = ::Async::Notification.new
         @exchanges, @exchange_changed = {}, ::Async::Notification.new
@@ -81,6 +86,7 @@ module LibTmux
         end
         raise CapacityError.new("control command exceeds its byte limit", phase: :admission) if line.bytesize > @max_command
 
+        Internal::NativeGuard.check_line(line, @release)
         deadline = clock + timeout
         request = admit(line, cancel, flow: flow)
         @exchanges[request.id] = true

data/lib/libtmux/async/scope.rb

@@ -186,6 +186,7 @@ module LibTmux
 
       def open_control(binding:, session_id:, **options)
         ensure_open
+        Internal::TmuxVersion.require_control(binding.release)
         @controls.reject!(&:closed?)
         raise CapacityError.new("Async control capacity is exhausted", phase: :admission) if @controls.length >= @max_controls
 

data/lib/libtmux/async/server.rb

@@ -12,14 +12,7 @@ module LibTmux
       end
 
       def run(argv, input: "".b, timeout: 5.0, cancel: nil)
-        ensure_owner
-        ensure_open
-        validate_argv(argv)
-        raise ArgumentError, "raw commands cannot override endpoint flags" if argv.first.start_with?("-")
-
-        fence, marker = Internal::TmuxVersion.fence(@release)
-        result = @scope.__send__(:execute, @pin.command_prefix + fence + argv, input: input, timeout: timeout, cancel: cancel)
-        Internal::TmuxVersion.check_fence(result, marker, @release)
+        dispatch(argv, input: input, timeout: timeout, cancel: cancel)
       end
 
       def close
@@ -66,6 +59,18 @@ module LibTmux
 
       private
 
+      def dispatch(argv, input: "".b, timeout: 5.0, cancel: nil, repaired_break: false)
+        ensure_owner
+        ensure_open
+        validate_argv(argv)
+        raise ArgumentError, "raw commands cannot override endpoint flags" if argv.first.start_with?("-")
+
+        Internal::NativeGuard.check(argv, @release, repaired_break: repaired_break)
+        fence, marker = Internal::TmuxVersion.fence(@release)
+        result = @scope.__send__(:execute, @pin.command_prefix + fence + argv, input: input, timeout: timeout, cancel: cancel)
+        Internal::TmuxVersion.check_fence(result, marker, @release)
+      end
+
       def ensure_owner
         @scope.__send__(:ensure_owner)
       end

data/lib/libtmux/async/version.rb

@@ -2,6 +2,6 @@
 
 module LibTmux
   module Async
-    VERSION = "0.1.0.alpha.2"
+    VERSION = "0.1.0.alpha.3"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: libtmux-async
 version: !ruby/object:Gem::Version
-  version: 0.1.0.alpha.2
+  version: 0.1.0.alpha.3
 platform: ruby
 authors:
 - libtmux contributors
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.1.0.alpha.2
+        version: 0.1.0.alpha.3
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.1.0.alpha.2
+        version: 0.1.0.alpha.3
 - !ruby/object:Gem::Dependency
   name: async
   requirement: !ruby/object:Gem::Requirement
@@ -59,7 +59,7 @@ licenses:
 - MIT
 metadata:
   source_code_uri: https://github.com/libtmux/libtmux-ruby
-  documentation_uri: https://libtmux.org/en/ruby/v0.1.0.alpha.2/reference/
+  documentation_uri: https://libtmux.org/en/ruby/v0.1.0.alpha.3/reference/
 rdoc_options: []
 require_paths:
 - lib