phronomy 0.16.0 → 0.18.0

data/lib/phronomy/engine/task/fiber_backend.rb

@@ -1,157 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  class Task
-    # Cooperative task backend using Ruby Fibers.
-    #
-    # Unlike {ImmediateBackend} (which runs the block to completion on the
-    # calling thread) or {ThreadBackend} (which runs the block on a new OS
-    # thread), +FiberBackend+ wraps the block in a +Fiber+ that is NOT started
-    # immediately.  The owning scheduler calls {#step} to advance execution one
-    # cooperative step at a time.
-    #
-    # This backend is used exclusively by {Runtime::DeterministicScheduler} to
-    # enable deterministic, wall-clock-free testing of concurrent logic.
-    #
-    # Thread-local key under which the currently active {DeterministicScheduler}
-    # is stored so that {#await} can suspend cooperatively.
-    SCHEDULER_KEY = :phronomy_deterministic_scheduler
-
-    # @api private
-    class FiberBackend < Backend
-      def initialize(task:, &block)
-        super
-        @value = nil
-        @error = nil
-        @cancel_error = nil
-        @cancel_requested = false
-        @started = false
-        @cooperative_suspend = false
-
-        # Capture `self` (the FiberBackend instance) in the closure so that
-        # instance-variable writes from inside the Fiber update this object.
-        @fiber = Fiber.new do
-          task.transition!(:running)
-          begin
-            # If cancel! was called before the first step, raise immediately.
-            raise @cancel_error if @cancel_error
-
-            @value = block.call
-            task.transition!(:completed, value: @value)
-          rescue CancellationError => e
-            task.transition!(:cancelled, error: e)
-            @error = e
-          rescue => e
-            task.transition!(:failed, error: e)
-            @error = e
-          ensure
-            task.transition!(:cancelled) unless task.done?
-          end
-        end
-      end
-
-      # Advances execution by one scheduler step.
-      # Resumes the Fiber until it yields (via +Fiber.yield+) or finishes.
-      # Cooperative cancellation is checked at the start of each step: if
-      # +cancel!+ has been called, +CancellationError+ is raised inside the
-      # Fiber at this controlled checkpoint rather than injected at an
-      # arbitrary suspension point via +Fiber#raise+.
-      # @return [self]
-      # @api private
-      def step
-        return self unless @fiber.alive?
-
-        @started = true
-        # Deliver pending cancellation at this scheduler checkpoint rather than
-        # injecting it mid-Fiber via Fiber#raise (which would be preemptive).
-        if @cancel_requested && @cancel_error
-          begin
-            @fiber.raise(@cancel_error)
-          rescue FiberError
-            nil  # Fiber completed between the check and raise — safe to ignore.
-          end
-          @cancel_requested = false
-          return self
-        end
-        yield_value = @fiber.resume
-        # A yield value of :cooperative_suspend signals that the Fiber deliberately
-        # suspended itself (e.g. inside CoopSignal#wait) and must NOT be
-        # re-enqueued by step_callable — it will be resumed by an explicit signal.
-        @cooperative_suspend = (yield_value == :cooperative_suspend)
-        self
-      end
-
-      # Returns +true+ if the Fiber yielded cooperatively (via a signal wait)
-      # and should not be automatically re-enqueued by the scheduler.
-      # @return [Boolean]
-      # @api private
-      def cooperative_suspend?
-        @cooperative_suspend
-      end
-
-      # Blocks until the task completes.
-      #
-      # When called from within a {DeterministicScheduler}-managed Fiber,
-      # suspends the current Fiber cooperatively and schedules it to resume
-      # when this task completes.  When called from outside a managed Fiber
-      # (e.g. the main fiber or a regular thread), drives execution by calling
-      # {#step} in a loop.
-      #
-      # @return [Object]
-      # @raise [Exception]
-      # @api private
-      def wait_result
-        unless @fiber.alive?
-          raise @error if @error
-          return @value
-        end
-
-        scheduler = Thread.current.thread_variable_get(SCHEDULER_KEY)
-        # Fiber.main was added in Ruby 3.2.4+; fall back to true (assume we are
-        # inside a managed Fiber whenever a scheduler is active).
-        in_managed_fiber = !Fiber.respond_to?(:main) || Fiber.current != Fiber.main
-        if scheduler && in_managed_fiber
-          # Cooperative context: suspend current Fiber until task is done.
-          waiting_fiber = Fiber.current
-          @task.on_complete { scheduler.enqueue_fiber(-> { waiting_fiber.resume }) }
-          Fiber.yield(:cooperative_suspend)
-        else
-          # Non-cooperative context: drive the fiber to completion.
-          step while @fiber.alive?
-        end
-
-        raise @error if @error
-        @value
-      end
-
-      # @return [Boolean] +true+ while the Fiber has not yet finished
-      # @api private
-      def alive?
-        @fiber.alive?
-      end
-
-      # Requests cancellation using a cooperative checkpoint mechanism.
-      # Sets a cancellation flag; the error is raised inside the Fiber at the
-      # next +step+ call (i.e. when the scheduler next dispatches this task),
-      # not injected at an arbitrary suspension point via +Fiber#raise+.
-      # If the Fiber has not yet started, the error is recorded so it is raised
-      # on the first {#step}.
-      # @return [self]
-      # @api private
-      def cancel!
-        @cancel_error = CancellationError.new("Task cancelled")
-        @cancel_requested = true
-        self
-      end
-
-      # Joins execution by stepping until the Fiber is no longer alive.
-      # @param limit [Numeric, nil] ignored
-      # @return [self]
-      # @api private
-      def join(_limit = nil)
-        step while @fiber.alive?
-        self
-      end
-    end
-  end
-end

data/lib/phronomy/engine/task/immediate_backend.rb

@@ -1,89 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  class Task
-    # Synchronous task backend that executes the block on the calling thread.
-    #
-    # Used by {Runtime::FakeScheduler} to allow tests to verify cooperative
-    # scheduling behaviour without spawning additional Threads.  The block
-    # runs to completion before {#initialize} returns, so {#await} and {#join}
-    # always return immediately.
-    #
-    # Thread count invariant: +ImmediateBackend+ never creates a new Thread.
-    class ImmediateBackend < Backend
-      # Executes +block+ synchronously on the calling thread.
-      # Saves and restores +Task.current+ so nested ImmediateBackend tasks
-      # compose correctly.
-      #
-      # @param task  [Task]
-      # @yieldreturn [Object]
-      # @api private
-      def initialize(task:, &block)
-        super
-        @value = nil
-        @error = nil
-        previous_task = Thread.current[:phronomy_current_task]
-        Thread.current[:phronomy_current_task] = task
-        task.transition!(:running)
-        begin
-          @value = block.call
-          task.transition!(:completed, value: @value)
-        rescue CancellationError => e
-          task.transition!(:cancelled, error: e)
-          @error = e
-        rescue => e
-          task.transition!(:failed, error: e)
-          @error = e
-        ensure
-          task.transition!(:cancelled) unless task.done?
-          Thread.current[:phronomy_current_task] = previous_task
-        end
-      end
-
-      # Returns the block's return value, or re-raises its exception.
-      # @return [Object]
-      # @raise [Exception]
-      # @api private
-      def wait_result
-        raise @error if @error
-
-        @value
-      end
-
-      # @return [Object, nil]
-      # @api private
-      def completed_value
-        @value
-      end
-
-      # @return [Exception, nil]
-      # @api private
-      def completed_error
-        @error
-      end
-
-      # Always +false+ — block has already completed by the time the task
-      # is visible to callers.
-      # @return [Boolean]
-      # @api private
-      def alive?
-        false
-      end
-
-      # No-op: the block has already completed.
-      # @return [self]
-      # @api private
-      def cancel!
-        self
-      end
-
-      # Returns immediately — nothing to wait for.
-      # @param limit [Numeric, nil] ignored
-      # @return [self]
-      # @api private
-      def join(_limit = nil)
-        self
-      end
-    end
-  end
-end

data/lib/phronomy/engine/task/mapped_backend.rb

@@ -1,90 +0,0 @@
-# frozen_string_literal: true
-
-require "timeout"
-
-module Phronomy
-  class Task
-    # Backend for Tasks created by {Task#map}.
-    #
-    # A mapped task's lifecycle is driven entirely by the +on_complete+
-    # callback of its source task — it never spawns a thread of its own.
-    # +MappedBackend+ transitions the owning task to +:running+ immediately
-    # on initialization so that +FSMSession+ treats it as an in-progress
-    # async action.  Completion (or failure) is triggered externally via
-    # {Task#transition!} from the +on_complete+ callback registered by
-    # {Task#map}.
-    #
-    # +await+ and +join+ block until {#unblock} is called, which {Task#map}
-    # arranges by registering a second +on_complete+ callback on the *mapped*
-    # task itself after the transform callback has been registered.
-    #
-    # @api private
-    class MappedBackend < Backend
-      def initialize(task:, &)
-        super
-        @done_queue = Queue.new
-        task.transition!(:running)
-      end
-
-      # Unblocks +await+ / +join+.  Called by {Task#map} after the mapped task
-      # reaches a terminal state.
-      # @api private
-      def unblock(value, error)
-        @done_queue.push([value, error])
-      end
-
-      # Blocks until the mapped task reaches a terminal state.
-      # @return [Object] the mapped value
-      # @raise [Exception] if the source task or the map block raised an error
-      # @api private
-      def wait_result
-        scheduler = Thread.current.thread_variable_get(Task::SCHEDULER_KEY)
-        in_managed_fiber = !Fiber.respond_to?(:main) || Fiber.current != Fiber.main
-        if scheduler && in_managed_fiber && !@task.done?
-          scheduler.track_blocking_await
-          waiting_fiber = Fiber.current
-          @task.on_complete do |_value, _error|
-            scheduler.complete_blocking_await
-            scheduler.enqueue_fiber(-> { waiting_fiber.resume })
-          end
-          Fiber.yield(:cooperative_suspend)
-        end
-
-        value, error = @done_queue.pop
-        raise error if error
-
-        value
-      end
-
-      # Returns +false+ — a mapped task has no independent thread to kill.
-      # @return [Boolean]
-      # @api private
-      def alive?
-        false
-      end
-
-      # No-op — mapped tasks carry no independent thread to cancel.
-      # @return [self]
-      # @api private
-      def cancel!
-        self
-      end
-
-      # Blocks until the mapped task completes, with an optional timeout.
-      # @param limit [Numeric, nil]
-      # @return [Object, nil] +nil+ on timeout
-      # @api private
-      def join(limit = nil)
-        if limit.nil?
-          wait_result
-        else
-          begin
-            Timeout.timeout(limit) { wait_result }
-          rescue Timeout::Error
-            nil
-          end
-        end
-      end
-    end
-  end
-end

data/lib/phronomy/engine/task/thread_backend.rb

@@ -1,84 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  class Task
-    # Thread-based Task backend (default).
-    #
-    # Each task runs on its own OS thread.  Cancellation is delivered via
-    # +Thread#raise(CancellationError)+, which cooperates with +rescue+ clauses
-    # inside the block.  This backend is always available and requires no
-    # external dependencies.
-    #
-    # When the cooperative scheduler backend is introduced, this backend will
-    # remain available as the fallback for blocking I/O operations that must
-    # run outside the scheduler (e.g. inside {BlockingAdapterPool}).
-    class ThreadBackend < Backend
-      def initialize(task:, &block)
-        super
-        @value = nil
-        @error = nil
-        @thread = Thread.new do
-          Thread.current.name = task.name if task.name
-          Thread.current[:phronomy_current_task] = task
-          Thread.current[:phronomy_task_cpu_slice_start_ms] =
-            Process.clock_gettime(Process::CLOCK_MONOTONIC, :millisecond)
-          task.transition!(:running)
-          @value = block.call
-          task.transition!(:completed, value: @value)
-        rescue CancellationError => e
-          task.transition!(:cancelled, error: e)
-          @error = e
-        rescue => e
-          task.transition!(:failed, error: e)
-          @error = e
-        ensure
-          # Guard against Thread#raise firing before the rescue handler has a
-          # chance to run (e.g. when cancel! is called immediately after spawn).
-          task.transition!(:cancelled) unless task.done?
-        end
-      end
-
-      # @return [Object]
-      # @raise [Exception]
-      # @api private
-      def wait_result
-        @thread.join
-        raise @error if @error
-
-        @value
-      end
-
-      # @return [Boolean]
-      # @api private
-      def alive?
-        @thread.alive?
-      end
-
-      # @return [self]
-      # @api private
-      def cancel!
-        @thread.raise(CancellationError, "Task cancelled") if @thread.alive?
-        self
-      end
-
-      # @param limit [Numeric, nil]
-      # @return [Thread, nil]
-      # @api private
-      def join(limit = nil)
-        @thread.join(limit)
-      end
-
-      # @return [Object, nil]
-      # @api private
-      def completed_value
-        @value
-      end
-
-      # @return [Exception, nil]
-      # @api private
-      def completed_error
-        @error
-      end
-    end
-  end
-end

data/lib/phronomy/engine/task_group.rb

@@ -1,265 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  # Manages a bounded set of concurrent {Task}s with structured concurrency.
-  #
-  # Enforces an upper bound on simultaneously running tasks (+limit+).
-  # When the limit is reached, {#spawn} blocks the caller until a slot
-  # becomes available.  Results are always returned in the order tasks
-  # were spawned, regardless of completion order.
-  #
-  # A configurable +failure_policy+ controls how errors propagate:
-  # - +:fail_fast+ (default) — cancels all remaining tasks on the first error
-  # - +:collect_all+ — waits for every task to complete, then raises the first error
-  # - +:skip_failed+ — ignores failed tasks and returns only successful results
-  #
-  # {#cancel_all!} cancels every task in the group and joins them, guaranteeing
-  # that the active child task count reaches zero before returning.
-  #
-  # @example Parallel tool calls with a concurrency cap
-  #   group = Phronomy::TaskGroup.new(limit: 5)
-  #   tasks = items.map { |item| group.spawn { process(item) } }
-  #   results = group.await_all   # Array in spawn order
-  #
-  # @example Collect-all failure policy
-  #   group = Phronomy::TaskGroup.new(failure_policy: :collect_all)
-  #   …
-  class TaskGroup
-    # Valid failure policies.
-    FAILURE_POLICIES = %i[fail_fast collect_all skip_failed].freeze
-
-    # @param limit          [Integer, Float::INFINITY] maximum simultaneous active tasks
-    # @param failure_policy [Symbol] one of {FAILURE_POLICIES} (default +:fail_fast+)
-    # @param runtime        [Runtime, nil] runtime used to spawn tasks via {Runtime#spawn};
-    #   when +nil+, tasks are created directly via +Task.new+ (backward-compatible mode).
-    #   Pass +runtime: self+ from {Runtime#task_group} to keep task execution consistent
-    #   with the configured scheduler backend.
-    # @api private
-    def initialize(limit: Float::INFINITY, failure_policy: :fail_fast, runtime: nil)
-      raise ArgumentError, "unknown failure_policy: #{failure_policy}" unless FAILURE_POLICIES.include?(failure_policy)
-
-      @limit = limit
-      @failure_policy = failure_policy
-      @runtime = runtime
-      @tasks = []
-      @mutex = Mutex.new
-      @cond = ConditionVariable.new
-      @active = 0
-    end
-
-    # Spawns a new task within the group.
-    # Blocks if the number of currently active tasks equals +limit+.
-    #
-    # @yield block to execute concurrently
-    # @return [Task] the spawned task
-    # @api private
-    def spawn(&block)
-      wait_for_slot!
-
-      task = if @runtime
-        @runtime.spawn(name: "task-group-worker") do
-          block.call
-        ensure
-          release_slot!
-        end
-      else
-        Task.new do
-          block.call
-        ensure
-          release_slot!
-        end
-      end
-
-      @mutex.synchronize { @tasks << task }
-      task
-    end
-
-    # Waits for all spawned tasks to complete.
-    # Returns results in spawn order.
-    #
-    # Failure behaviour is controlled by the +failure_policy+ set at
-    # construction time:
-    # - +:fail_fast+    — raises the first error after cancelling unfinished tasks
-    # - +:collect_all+  — waits for all tasks, then raises the first error
-    # - +:skip_failed+  — returns only the values of successful tasks
-    #
-    # @return [Array] results in spawn order (or successful-only for :skip_failed)
-    # @raise [Exception] when any task failed (except :skip_failed)
-    # @api private
-    def await_all
-      tasks = @mutex.synchronize { @tasks.dup }
-      return [] if tasks.empty?
-
-      if Phronomy::Runtime::Scheduler.current
-        _await_all_cooperative(tasks)
-      else
-        _await_all_threaded(tasks)
-      end
-    end
-
-    private
-
-    # Cooperative await_all for DeterministicScheduler context.
-    # Uses on_complete callbacks + AsyncQueue to observe task completions in
-    # arrival order (not spawn order), matching the fail-fast semantics of the
-    # threaded path.  AsyncQueue#pop suspends the current Fiber cooperatively
-    # rather than blocking the OS thread.
-    # @api private
-    # @param tasks [Array<Task>]
-    # @return [Array]
-    def _await_all_cooperative(tasks)
-      completion_q = Phronomy::Concurrency::AsyncQueue.new
-      tasks.each_with_index do |task, idx|
-        task.on_complete do |value, error|
-          completion_q.push({index: idx, value: value, error: error})
-        end
-      end
-
-      entries = Array.new(tasks.length)
-      cancelled = false
-      fail_fast_error = nil
-
-      tasks.length.times do
-        entry = completion_q.pop  # cooperative suspend via scheduler signal
-        entries[entry[:index]] = entry
-
-        if entry[:error] && @failure_policy == :fail_fast && !cancelled
-          cancelled = true
-          fail_fast_error = entry[:error]
-          tasks.each { |t| t.cancel! unless t.done? }
-        end
-      end
-
-      case @failure_policy
-      when :fail_fast
-        raise fail_fast_error if fail_fast_error
-        entries.map { |r| r[:value] }
-      when :skip_failed
-        entries.filter_map { |r| r[:value] unless r[:error] }
-      else # :collect_all
-        errors = entries.filter_map { |r| r[:error] }
-        raise errors.first if errors.any?
-        entries.map { |r| r[:value] }
-      end
-    end
-
-    # Thread-blocking await_all for ThreadBackend / ImmediateBackend context.
-    # Uses Task#on_complete callbacks instead of spawning N additional watcher
-    # tasks (Issue #328).  on_complete receives the task's value and error
-    # directly — no await call is needed, eliminating the risk of a self-join
-    # when the callback fires inside the task's own execution thread.
-    def _await_all_threaded(tasks)
-      completion_q = Queue.new
-      tasks.each_with_index do |task, idx|
-        task.on_complete do |value, error|
-          completion_q.push({index: idx, value: value, error: error})
-        end
-      end
-
-      entries = Array.new(tasks.length)
-      cancelled = false
-      # The error that triggered fail_fast cancellation (tracked separately so
-      # we raise it rather than a secondary CancellationError from cancelled tasks).
-      fail_fast_error = nil
-
-      tasks.length.times do
-        entry = completion_q.pop
-        entries[entry[:index]] = entry
-
-        if entry[:error] && @failure_policy == :fail_fast && !cancelled
-          cancelled = true
-          fail_fast_error = entry[:error]
-          tasks.each { |t| t.cancel! unless t.done? }
-        end
-      end
-
-      case @failure_policy
-      when :fail_fast
-        raise fail_fast_error if fail_fast_error
-        entries.map { |r| r[:value] }
-      when :skip_failed
-        entries.filter_map { |r| r[:value] unless r[:error] }
-      else # :collect_all
-        errors = entries.filter_map { |r| r[:error] }
-        raise errors.first if errors.any?
-        entries.map { |r| r[:value] }
-      end
-    end
-
-    public
-
-    # Cancels all tasks currently in the group and waits for each to finish.
-    # After this method returns, the active child task count is guaranteed to
-    # be zero.
-    #
-    # Note: if a task is cancelled before its block has started executing, the
-    # internal +ensure+ clause inside the block may not run, so @active is
-    # reset explicitly after all tasks are joined.
-    #
-    # @return [self]
-    # @api private
-    def cancel_all!
-      tasks = @mutex.synchronize { @tasks.dup }
-      tasks.each(&:cancel!)
-      tasks.each do |t|
-        t.join
-      rescue
-        nil
-      end
-      # Force @active to zero: tasks cancelled before block execution starts
-      # may not decrement @active via their ensure clause.
-      scheduler = Phronomy::Runtime::Scheduler.current
-      if scheduler && @coop_signal
-        @active = 0
-        scheduler.raise_signal_all(@coop_signal)
-      else
-        @mutex.synchronize do
-          @active = 0
-          @cond.broadcast
-        end
-      end
-      self
-    end
-
-    # Returns the number of currently executing child tasks.
-    # @return [Integer]
-    # @api private
-    def active_task_count
-      @mutex.synchronize { @active }
-    end
-
-    private
-
-    def wait_for_slot!
-      scheduler = Phronomy::Runtime::Scheduler.current
-      if scheduler
-        @coop_signal ||= scheduler.new_signal
-        loop do
-          if @active < @limit
-            @active += 1
-            return
-          end
-          scheduler.wait_for_signal(@coop_signal)
-        end
-      else
-        @mutex.synchronize do
-          @cond.wait(@mutex) while @active >= @limit
-          @active += 1
-        end
-      end
-    end
-
-    def release_slot!
-      scheduler = Phronomy::Runtime::Scheduler.current
-      if scheduler && @coop_signal
-        @active -= 1
-        scheduler.raise_signal(@coop_signal)
-      else
-        @mutex.synchronize do
-          @active -= 1
-          @cond.signal
-        end
-      end
-    end
-  end
-end