libtmux-async 0.1.0.alpha.1

data/lib/libtmux/async/process.rb

@@ -0,0 +1,310 @@
+# frozen_string_literal: true
+
+require "async/notification"
+require "libtmux/child"
+
+module LibTmux
+  module Async
+    class ProcessDriver
+      CHUNK = 16_384
+      private_constant :CHUNK
+
+      attr_reader :pid, :result
+
+      def initialize(scope, ticket, argv, input, deadline, cancel, limits)
+        @scope, @ticket, @argv, @input = scope, ticket, argv, input
+        @deadline, @cancel, @limits = deadline, cancel, limits
+        @started = clock
+        @changed = ::Async::Notification.new
+        @tasks, @streams = [], []
+        @buffers = {stdout: +"".b, stderr: +"".b}
+        @finished_reads = 0
+      end
+
+      def call
+        failure = nil
+        begin
+          watch_cancellation
+          @scope.__send__(:acquire, @ticket, @deadline, method(:check_cancel))
+          check_budget(:spawn)
+          check_cancel(:spawn)
+          spawn
+          start_io
+          drive
+        rescue ::Async::Cancel
+          if observed?
+            begin
+              drive
+            rescue Exception => error
+              failure = error
+            end
+          else
+            failure = Cancelled.new("command task was cancelled", **details(:read))
+          end
+        rescue Exception => error
+          failure = error
+        ensure
+          errors = cleanup
+          @scope.__send__(:release_active, @ticket) if retired?
+          if failure
+            Async.__send__(:attach_cleanup, failure, errors)
+          elsif !failure && !errors.empty?
+            failure = TransportError.new("Async command cleanup failed", **details(:retire), cleanup_errors: errors)
+          end
+        end
+        raise failure if failure
+
+        @result
+      end
+
+      def retired?
+        (!@child || @child_joined) && @tasks.all?(&:finished?)
+      end
+
+      def cleanup
+        @retiring = true
+        deadline = @cleanup_deadline ||= clock + @limits.fetch(:cleanup_timeout)
+        errors = []
+        @tasks.each do |task|
+          task.cancel unless task.finished?
+        rescue ::Async::Cancel
+          retry if clock < deadline
+          errors << "I/O task cancellation remains pending"
+        rescue Exception => error
+          errors << "I/O task cancellation failed (#{error.class})"
+        end
+        @streams.each do |stream|
+          stream.close unless stream.closed?
+        rescue IOError, SystemCallError => error
+          errors << "command descriptor close failed (#{error.class})"
+        end
+        if @child
+          begin
+            if @pid && !@child.observed? && !@child.observation_error.is_a?(Errno::ECHILD)
+              @child.signal("TERM")
+              # Reserve the cleanup budget for reaping; timer grace can overrun it.
+              @child.signal("KILL") unless @child.observed?
+            end
+          rescue SystemCallError => error
+            errors << "owned client termination failed (#{error.class})"
+          ensure
+            @child.finish_signalling
+          end
+          cleanup_wait(deadline) { @child.complete? }
+          if @child.complete?
+            begin
+              joined = @child.join([deadline - clock, 0].max)
+              @child_joined = !!joined
+              errors << "native child observer join remains pending" unless joined
+            rescue ::Async::Cancel
+              retry if clock < deadline
+              errors << "native child observer join was interrupted"
+            end
+          else
+            errors << "owned client reaping remains pending after cleanup deadline"
+          end
+          errors << "child observation failed (#{@child.observation_error.class})" if @child.observation_error
+          errors << "child reaping failed (#{@child.retirement_error.class})" if @child.retirement_error
+          @child.close
+        end
+        @tasks.each do |task|
+          begin
+            task.wait(timeout: [deadline - clock, 0].max) unless task.finished?
+          rescue ::Async::Cancel
+            retry if clock < deadline
+            errors << "I/O task join was interrupted"
+          rescue Exception => error
+            errors << "I/O task join failed (#{error.class})"
+          end
+        end
+        errors
+      end
+
+      def details(phase)
+        {delivery: @result || @status ? :observed : (@pid ? :possibly_sent : :not_sent), phase: phase, pid: @pid}
+      end
+
+      private
+
+      def clock
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+
+      def observed?
+        !!(@child&.observed? && !@child.observation_error)
+      end
+
+      def watch_cancellation
+        return unless @cancel
+
+        start_task do
+          until @cancel.cancelled?
+            Fiber.scheduler.io_wait(@cancel.reader, IO::READABLE)
+          end
+          @cancelled = true
+          @scope.__send__(:notify)
+        end
+      end
+
+      def check_cancel(phase)
+        raise @failure if @failure
+
+        if (@cancelled || @cancel&.cancelled?) && !observed?
+          raise Cancelled.new("command was cancelled", **details(phase))
+        end
+      end
+
+      def check_budget(phase)
+        if clock >= [@deadline, @drain_deadline || @deadline].min
+          raise DeadlineExceeded.new("command deadline exceeded", **details(phase))
+        end
+      end
+
+      def pipe
+        IO.pipe.tap { |pair| pair.each(&:binmode); @streams.concat(pair) }
+      end
+
+      def spawn
+        Thread.handle_interrupt(Exception => :never) do
+          input, @writer = pipe
+          @stdout, output = pipe
+          @stderr, error = pipe
+          @child = Internal::OwnedChild.new
+          begin
+            @pid = Process.spawn({"TMUX" => nil, "TMUX_PANE" => nil}, [@argv.first, @argv.first], *@argv.drop(1),
+              in: input, out: output, err: error, close_others: true)
+          ensure
+            @child.spawned(@pid)
+          end
+          [input, output, error].each(&:close)
+        end
+      rescue IOError, SystemCallError => error
+        raise TransportError.new("could not start command (#{error.class})", **details(:spawn)), cause: nil
+      end
+
+      def start_task(&block)
+        task = ::Async::Task.new(::Async::Task.current) do
+          begin
+            block.call
+          rescue ::Async::Cancel
+            @failure ||= Cancelled.new("command I/O task was cancelled", **details(:read)) unless @retiring
+          rescue IOError, SystemCallError => error
+            @failure ||= TransportError.new("command I/O failed (#{error.class})", **details(:read)) unless @retiring
+          rescue Exception => error
+            @failure ||= error unless @retiring
+          ensure
+            @changed.signal
+            @scope.__send__(:notify)
+          end
+        end
+        @tasks << task
+        task.run
+        task
+      end
+
+      def start_io
+        start_task { read_stream(@stdout, :stdout) }
+        start_task { read_stream(@stderr, :stderr) }
+        start_task { write_input }
+        start_task do
+          until @child.complete?
+            @child.reader.read_nonblock(CHUNK, exception: false)
+            update_exit
+            Fiber.scheduler.io_wait(@child.reader, IO::READABLE) unless @child.complete?
+          end
+          update_exit
+        end
+      end
+
+      def read_stream(io, stream)
+        buffer = @buffers.fetch(stream)
+        loop do
+          remaining = @limits.fetch(stream) - buffer.bytesize
+          bytes = io.read_nonblock([CHUNK, remaining + 1].min, exception: false)
+          case bytes
+          when nil then break
+          when :wait_readable then Fiber.scheduler.io_wait(io, IO::READABLE)
+          when String
+            raise CapacityError.new("command #{stream} exceeded its byte limit", **details(:read)) if bytes.bytesize > remaining
+
+            @scope.__send__(:retain_output, @ticket, bytes.bytesize)
+            buffer << bytes
+          end
+        end
+        @finished_reads += 1
+      ensure
+        io.close unless io.closed?
+      end
+
+      def write_input
+        offset = 0
+        while offset < @input.bytesize && !@writer.closed?
+          written = @writer.write_nonblock(@input.byteslice(offset, CHUNK), exception: false)
+          if written == :wait_writable
+            Fiber.scheduler.io_wait(@writer, IO::WRITABLE)
+          else
+            offset += written
+          end
+        end
+      rescue Errno::EPIPE
+        nil
+      ensure
+        @writer.close unless @writer.closed?
+      end
+
+      def update_exit
+        if @child.observation_error
+          raise TransportError.new("command exit observation failed (#{@child.observation_error.class})", **details(:wait))
+        end
+        if @child.observed?
+          @drain_deadline ||= clock + @limits.fetch(:drain_timeout)
+          @child.finish_signalling
+        end
+        raise TransportError.new("command reaping failed", **details(:wait)) if @child.retirement_error
+
+        @status = @child.status
+        @changed.signal
+      end
+
+      def drive
+        loop do
+          begin
+            update_exit
+            raise @failure if @failure
+            if @status && @finished_reads == 2
+              check_budget(:publish)
+              @result = CommandResult.new(**@buffers, status: @status, pid: @pid, argv: @argv, elapsed_seconds: clock - @started)
+              return
+            end
+            phase = observed? ? :drain : :read
+            check_budget(phase)
+            check_cancel(phase)
+            remaining = [@deadline, @drain_deadline || @deadline].min - clock
+            ::Async::Task.current.with_timeout(remaining) { @changed.wait }
+          rescue ::Async::TimeoutError
+            raise DeadlineExceeded.new("command deadline exceeded", **details(phase))
+          rescue ::Async::Cancel
+            raise unless observed?
+          end
+        end
+      end
+
+      def cleanup_wait(deadline)
+        until yield
+          remaining = deadline - clock
+          return unless remaining.positive?
+
+          begin
+            @child.reader.read_nonblock(CHUNK, exception: false)
+            Fiber.scheduler.io_wait(@child.reader, IO::READABLE, remaining) unless yield
+          rescue ::Async::Cancel
+            next
+          rescue IOError, SystemCallError
+            return
+          end
+        end
+      end
+    end
+    private_constant :ProcessDriver
+  end
+end

data/lib/libtmux/async/scope.rb

@@ -0,0 +1,390 @@
+# frozen_string_literal: true
+
+require "libtmux/async/process"
+
+module LibTmux
+  module Async
+    class Scope
+      Request = Struct.new(:bytes, :task, :execution, :result, :error, :active, :output_bytes, keyword_init: true)
+      private_constant :Request
+
+      attr_reader :server
+
+      def initialize(parent:, server:, concurrency: 4, max_requests: 32, max_controls: 4, max_queue_bytes: 1 << 22,
+        max_output_bytes: 1 << 23, stdout_limit: 1 << 20, stderr_limit: 1 << 18,
+        input_limit: 1 << 20, argv_limit: 1 << 18, cleanup_timeout: 0.5, drain_timeout: 0.5)
+        unless ::Async::Task.current? && parent.is_a?(::Async::Task) && !parent.finished? && parent.root.equal?(Fiber.scheduler)
+          raise ArgumentError, "parent must be a live task on the current Async scheduler"
+        end
+        [concurrency, max_requests, max_controls, max_queue_bytes, max_output_bytes, stdout_limit, stderr_limit, input_limit, argv_limit].each do |value|
+          raise ArgumentError, "scope limits must be positive Integers" unless value.is_a?(Integer) && value.positive?
+        end
+        [cleanup_timeout, drain_timeout].each do |value|
+          raise ArgumentError, "cleanup deadlines must be positive and finite" unless value.is_a?(Numeric) && value.finite? && value.positive?
+        end
+        @parent, @thread, @pid, @scheduler = parent, Thread.current, Process.pid, Fiber.scheduler
+        @concurrency, @max_requests, @max_queue, @max_output = concurrency, max_requests, max_queue_bytes, max_output_bytes
+        @controls, @max_controls = [], max_controls
+        @limits = {stdout: stdout_limit, stderr: stderr_limit, input: input_limit, argv: argv_limit,
+          cleanup_timeout: cleanup_timeout, drain_timeout: drain_timeout}.freeze
+        @requests, @waiting, @maps = [], [], []
+        @active = @queued_bytes = @output_bytes = 0
+        @changed = ::Async::Notification.new
+        @server = Server.new(self, server)
+      end
+
+      def close
+        ensure_owner
+        if @maps.flatten.include?(::Async::Task.current?)
+          raise ClosedError.new("cannot close an Async scope from its active map worker", phase: :retire)
+        end
+        @closed = true
+        deadline = clock + @limits.fetch(:cleanup_timeout) * 2
+        errors = []
+        @controls.each { |control| control.__send__(:request_close) }
+        @maps.flatten.each { |task| cancel_task(task, deadline, errors) }
+        @requests.dup.each { |request| cancel_task(request.task, deadline, errors) }
+        @maps.flatten.each { |task| join_task(task, deadline, errors) }
+        @controls.dup.each do |control|
+          begin
+            control.close(timeout: (deadline - clock).clamp(0, 0.5))
+            @controls.delete(control)
+          rescue Exception => error
+            errors << "control close failed (#{error.class})"
+            errors.concat(error.cleanup_errors) if error.is_a?(Error)
+          end
+        end
+        @requests.dup.each do |request|
+          begin
+            request.task.wait(timeout: [deadline - clock, 0].max) unless request.task.finished?
+          rescue ::Async::Cancel
+            retry if clock < deadline
+          rescue Exception => error
+            errors << "request join failed (#{error.class})"
+          end
+          if request.execution && !request.execution.retired?
+            errors.concat(request.execution.cleanup)
+            release_active(request) if request.execution.retired?
+          end
+          errors.concat(request.error.cleanup_errors) if request.error.is_a?(Error)
+          if !request.execution || request.execution.retired?
+            release(request)
+          else
+            errors << "request ownership remains pending"
+          end
+        end
+        raise TransportError.new("Async scope cleanup failed", phase: :retire, cleanup_errors: errors) unless errors.empty?
+
+        nil
+      end
+
+      def closed?
+        ensure_owner
+        !!@closed
+      end
+
+      # Frozen counters and limits from this scope, without I/O or payloads.
+      # Process slots remain occupied until retirement; they are not a live PID count.
+      # Valid after close on the owning thread, process and scheduler.
+      def diagnostics
+        ensure_owner
+        {transport: :async_process, closed: !!@closed, admitted_requests: @requests.length,
+          reserved_process_slots: @requests.length,
+          waiting_requests: @waiting.length, active_process_slots: @active,
+          reserved_request_bytes: @queued_bytes, retained_output_bytes: @output_bytes,
+          control_connections: @controls.count { |control| !control.__send__(:retired?) }, maps: @maps.length,
+          limits: {concurrency: @concurrency, max_requests: @max_requests, max_controls: @max_controls,
+            max_queue_bytes: @max_queue, max_output_bytes: @max_output,
+            stdout_limit: @limits.fetch(:stdout), stderr_limit: @limits.fetch(:stderr),
+            input_limit: @limits.fetch(:input), argv_limit: @limits.fetch(:argv),
+            cleanup_timeout: @limits.fetch(:cleanup_timeout), drain_timeout: @limits.fetch(:drain_timeout),
+            close_timeout: @limits.fetch(:cleanup_timeout) * 2}.freeze}.freeze
+      end
+
+      def map(values, concurrency: @concurrency, max_items: 1024, max_bytes: @max_output, result_bytes: nil)
+        ensure_open
+        unless concurrency.is_a?(Integer) && concurrency.positive? && concurrency <= @max_requests
+          raise ArgumentError, "map concurrency must fit scope admission capacity"
+        end
+        unless [max_items, max_bytes].all? { |value| value.is_a?(Integer) && value.positive? }
+          raise ArgumentError, "map limits must be positive Integers"
+        end
+        raise ArgumentError, "map requires a block" unless block_given?
+        raise ArgumentError, "result_bytes must be callable" if result_bytes && !result_bytes.respond_to?(:call)
+
+        source = values.to_enum
+        tasks, results = [], []
+        @maps << tasks
+        next_index = retained = 0
+        failure = nil
+        begin
+          concurrency.times do
+            task = ::Async::Task.new(@parent) do
+              begin
+                loop do
+                  break if failure
+                  value = begin
+                    source.next
+                  rescue StopIteration
+                    break
+                  end
+                  index = next_index
+                  raise CapacityError.new("ordered map item limit reached", phase: :admission) if index >= max_items
+
+                  next_index += 1
+                  result = yield value
+                  bytes = result_bytes ? result_bytes.call(result) : retained_bytes(result)
+                  unless bytes.is_a?(Integer) && bytes >= 0
+                    raise ArgumentError, "result_bytes must return a nonnegative Integer"
+                  end
+                  if retained + bytes > max_bytes || @output_bytes + bytes > @max_output
+                    raise CapacityError.new("ordered map retained output limit reached", phase: :read, delivery: :observed)
+                  end
+                  retained += bytes
+                  @output_bytes += bytes
+                  results[index] = result
+                end
+              rescue Exception => error
+                if failure && error.is_a?(Error)
+                  Async.__send__(:attach_cleanup, failure, error.cleanup_errors)
+                end
+                failure ||= error
+              ensure
+                notify
+              end
+            end
+            tasks << task
+            task.run
+          end
+          until tasks.all?(&:finished?)
+            break if failure
+            @changed.wait
+          end
+        rescue Exception => error
+          failure ||= error
+        ensure
+          deadline = clock + @limits.fetch(:cleanup_timeout) * 2
+          errors = []
+          tasks.each { |task| cancel_task(task, deadline, errors) }
+          tasks.each { |task| join_task(task, deadline, errors) }
+          @maps.delete(tasks) if tasks.all?(&:finished?)
+          @output_bytes -= retained
+          if failure
+            Async.__send__(:attach_cleanup, failure, errors)
+          elsif !failure && !errors.empty?
+            failure = TransportError.new("ordered map cleanup failed", phase: :retire, cleanup_errors: errors)
+          end
+        end
+        raise failure if failure
+
+        results.freeze
+      end
+
+      private
+
+      attr_reader :parent
+
+      def open_control(binding:, session_id:, **options)
+        ensure_open
+        @controls.reject!(&:closed?)
+        raise CapacityError.new("Async control capacity is exhausted", phase: :admission) if @controls.length >= @max_controls
+
+        control = ControlConnection.allocate
+        @controls << control
+        begin
+          control.__send__(:initialize, scope: self, binding: binding, session_id: session_id, **options)
+          control.__send__(:start)
+        rescue Exception
+          @controls.delete(control) if control.__send__(:retired?)
+          raise
+        end
+        control
+      end
+
+      def clock
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+
+      def join_task(task, deadline, errors)
+        until task.finished?
+          remaining = deadline - clock
+          unless remaining.positive?
+            errors << "owned task join remains pending"
+            break
+          end
+          begin
+            task.wait(timeout: remaining)
+          rescue ::Async::Cancel
+            next
+          rescue Exception => error
+            errors << "owned task join failed (#{error.class})"
+            break
+          end
+        end
+      end
+
+      def cancel_task(task, deadline, errors)
+        task.cancel unless task.finished?
+      rescue ::Async::Cancel
+        retry if clock < deadline
+        errors << "owned task cancellation remains pending"
+      rescue Exception => error
+        errors << "owned task cancellation failed (#{error.class})"
+      end
+
+      def retained_bytes(value)
+        nodes = 0
+        visiting = {}
+        measure = lambda do |item, depth|
+          nodes += 1
+          if nodes > 2048 || depth > 32
+            raise CapacityError.new("ordered map result structure limit reached", phase: :read, delivery: :observed)
+          end
+          case item
+          when nil, true, false, Float then 8
+          when Integer then [8, (item.bit_length + 7) / 8].max
+          when Symbol then item.to_s.bytesize
+          when String then item.bytesize
+          when CommandResult then measure.call([item.stdout, item.stderr, item.argv], depth + 1)
+          when Array, Hash
+            if visiting[item.object_id]
+              raise CapacityError.new("ordered map result contains a cycle", phase: :read, delivery: :observed)
+            end
+            visiting[item.object_id] = true
+            begin
+              if item.is_a?(Array)
+                8 + item.sum { |child| measure.call(child, depth + 1) }
+              else
+                8 + item.sum { |key, child| measure.call(key, depth + 1) + measure.call(child, depth + 1) }
+              end
+            ensure
+              visiting.delete(item.object_id)
+            end
+          else
+            raise UnsupportedFeatureError.new("ordered map application results require a result_bytes estimator", phase: :read, delivery: :observed)
+          end
+        end
+        measure.call(value, 0)
+      end
+
+      def ensure_owner
+        unless Process.pid == @pid && Thread.current.equal?(@thread) && Fiber.scheduler.equal?(@scheduler)
+          raise ClosedError.new("Async scope belongs to another thread, process or scheduler", phase: :admission)
+        end
+      end
+
+      def ensure_open
+        ensure_owner
+        raise ClosedError.new("Async scope is closed", phase: :admission) if @closed || @parent.finished?
+      end
+
+      def execute(argv, input: "".b, timeout: 5.0, cancel: nil)
+        ensure_open
+        deadline = clock + timeout if timeout.is_a?(Numeric) && timeout.finite?
+        raise ArgumentError, "timeout must be finite" unless deadline
+        unless argv.is_a?(Array) && !argv.empty? && argv.all? { |arg| arg.is_a?(String) && !arg.include?("\0") }
+          raise ArgumentError, "argv must be a nonempty Array of Strings without NUL"
+        end
+        raise ArgumentError, "input must be a String" unless input.is_a?(String)
+        if cancel && (!cancel.respond_to?(:reader) || !cancel.respond_to?(:cancelled?))
+          raise ArgumentError, "cancel must provide a reader and cancellation state"
+        end
+        raise Cancelled.new("command cancelled before admission", phase: :admission) if cancel&.cancelled?
+        raise DeadlineExceeded.new("command deadline elapsed before admission", phase: :admission) if clock >= deadline
+
+        argv_bytes = argv.sum { |arg| arg.bytesize + 1 }
+        bytes = input.bytesize + argv_bytes
+        if input.bytesize > @limits.fetch(:input) || argv_bytes > @limits.fetch(:argv) ||
+            @requests.length >= @max_requests || @queued_bytes + bytes > @max_queue
+          raise CapacityError.new("Async request admission limit reached", phase: :admission)
+        end
+        ticket = Request.new(bytes: bytes, output_bytes: 0)
+        @requests << ticket
+        @waiting << ticket
+        @queued_bytes += bytes
+        ticket.execution = ProcessDriver.new(self, ticket, argv.map { |arg| arg.dup.freeze }.freeze,
+          input.b.freeze, deadline, cancel, @limits)
+        ticket.task = ::Async::Task.new(@parent) do
+          begin
+            ticket.result = ticket.execution.call
+          rescue Exception => error
+            ticket.error = error
+          ensure
+            notify
+          end
+        end
+        begin
+          ticket.task.run
+          ticket.task.wait
+        rescue Exception => error
+          unless ticket.result && error.is_a?(::Async::Cancel)
+            errors = []
+            failure = error unless error.is_a?(::Async::Cancel)
+            deadline = clock + @limits.fetch(:cleanup_timeout) * 2
+            cancel_task(ticket.task, deadline, errors)
+            join_task(ticket.task, deadline, errors)
+            ticket.error = failure || ticket.error || Cancelled.new("command caller was cancelled", **ticket.execution.details(:read))
+            Async.__send__(:attach_cleanup, ticket.error, errors)
+          end
+        end
+        raise ticket.error if ticket.error
+
+        ticket.result
+      ensure
+        if ticket && (!ticket.task || (ticket.task.finished? && ticket.execution.retired?))
+          release(ticket)
+        end
+      end
+
+      def acquire(ticket, deadline, check_cancel)
+        loop do
+          check_cancel.call(:admission)
+          raise ClosedError.new("Async scope is closed", phase: :admission) if @closed
+          raise DeadlineExceeded.new("command deadline elapsed in admission", phase: :admission) if clock >= deadline
+
+          if @waiting.first.equal?(ticket) && @active < @concurrency
+            @waiting.shift
+            @active += 1
+            ticket.active = true
+            notify
+            return
+          end
+          begin
+            ::Async::Task.current.with_timeout(deadline - clock) { @changed.wait }
+          rescue ::Async::TimeoutError
+            raise DeadlineExceeded.new("command deadline elapsed in admission", phase: :admission)
+          end
+        end
+      end
+
+      def release_active(ticket)
+        return unless ticket.active
+
+        ticket.active = false
+        @active -= 1
+        notify
+      end
+
+      def retain_output(ticket, bytes)
+        if @output_bytes + bytes > @max_output
+          raise CapacityError.new("Async retained output limit reached", **ticket.execution.details(:read))
+        end
+        @output_bytes += bytes
+        ticket.output_bytes += bytes
+      end
+
+      def release(ticket)
+        return unless @requests.delete(ticket)
+
+        @waiting.delete(ticket)
+        @queued_bytes -= ticket.bytes
+        @output_bytes -= ticket.output_bytes
+        notify
+      end
+
+      def notify
+        @changed.signal
+      end
+    end
+  end
+end