phronomy 0.7.0 → 0.8.0

data/lib/phronomy/task/immediate_backend.rb

@@ -0,0 +1,89 @@
+# 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 await
+        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/task/thread_backend.rb

@@ -0,0 +1,84 @@
+# 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 await
+        @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/task.rb

@@ -0,0 +1,275 @@
+# frozen_string_literal: true
+
+require_relative "task/backend"
+require_relative "task/thread_backend"
+require_relative "task/immediate_backend"
+require_relative "task/fiber_backend"
+
+module Phronomy
+  # A single unit of concurrent work.
+  #
+  # Decouples task semantics from the underlying execution primitive via a
+  # pluggable {Backend}.  The default backend is {ThreadBackend}; a cooperative
+  # or test-double backend can be substituted via {.default_backend_class=} or
+  # by passing +backend_class:+ to {.spawn}.
+  #
+  # +Task.spawn+ is an **internal API** used by schedulers and the framework
+  # itself.  Application code and framework components should use
+  # +Runtime.instance.spawn+ instead, which routes through the configured
+  # scheduler and respects the concurrency model.
+  #
+  # @example Basic usage (framework/test code only — prefer Runtime.instance.spawn in app code)
+  #   task = Phronomy::Task.spawn { expensive_io() }
+  #   result = task.await   # blocks until done, re-raises errors
+  #
+  # @example Cancel a running task
+  #   task = Phronomy::Task.spawn { loop { Phronomy::Task.checkpoint! } }
+  #   task.cancel!
+  #
+  # @example Task tree — cancel parent cancels children
+  #   parent = Phronomy::Task.spawn { sleep 10 }
+  #   child  = Phronomy::Task.spawn(parent: parent) { sleep 10 }
+  #   parent.cancel!   # child is also cancelled
+  class Task
+    # Valid task lifecycle states.
+    STATES = %i[pending running completed failed cancelled].freeze
+
+    # Returns the process-wide default backend class.
+    # Defaults to {ThreadBackend}.
+    # Override in tests or to enable a cooperative scheduler backend.
+    # @return [Class<Backend>]
+    # @api private
+    def self.default_backend_class
+      @default_backend_class || ThreadBackend
+    end
+
+    # Sets the process-wide default backend class.
+    # @param klass [Class<Backend>]
+    # @api private
+    def self.default_backend_class=(klass)
+      @default_backend_class = klass
+    end
+
+    # Returns the {Task} currently executing on this thread, or +nil+.
+    # Returns +nil+ when called from outside a task-managed execution context.
+    # @return [Task, nil]
+    # @api private
+    def self.current
+      Thread.current[:phronomy_current_task]
+    end
+
+    # Returns the monotonic clock value (ms) when the current task last recorded
+    # a yield (or when the task started), or +nil+ when not inside a task context.
+    # Used by {Runtime#yield} for CPU-bound detection without placing
+    # +Thread.current+ in files outside the allowlist.
+    # @return [Integer, nil]
+    # @api private
+    def self.current_cpu_slice_start_ms
+      Thread.current[:phronomy_task_cpu_slice_start_ms]
+    end
+
+    # Resets the CPU slice start clock for the current task to +now+.
+    # Call this immediately after the cooperative yield has been performed so
+    # that the next yield correctly measures only the time since the last yield.
+    # @api private
+    def self.record_yield!
+      Thread.current[:phronomy_task_cpu_slice_start_ms] =
+        Process.clock_gettime(Process::CLOCK_MONOTONIC, :millisecond)
+    end
+
+    # Returns and increments a per-thread yield-if-needed counter.
+    # Used by {Runtime#yield_if_needed} so that the counter is thread-local
+    # without putting +Thread.current+ in runtime.rb (which is outside the
+    # Thread.current allowlist).
+    # @return [Integer] the new counter value
+    # @api private
+    def self.increment_yield_counter!
+      count = (Thread.current[:phronomy_yield_if_needed_counter] || 0) + 1
+      Thread.current[:phronomy_yield_if_needed_counter] = count
+      count
+    end
+
+    # Cooperative cancellation checkpoint.
+    #
+    # Raises {CancellationError} if the current task's status is +:cancelled+.
+    # On {ThreadBackend}, cancellation is delivered via +Thread#raise+ so this
+    # is a no-op in practice; on future cooperative backends this will be the
+    # primary cancellation mechanism.
+    #
+    # Safe to call from outside a task context (no-op when no current task).
+    # @return [void]
+    # @raise [CancellationError] if the current task has been cancelled
+    # @api private
+    def self.checkpoint!
+      ct = current
+      return unless ct
+
+      raise CancellationError, "Task cancelled" if ct.status == :cancelled
+    end
+
+    # Spawns a new task executing +block+ concurrently.
+    #
+    # @param name          [String, nil]    optional human-readable label
+    # @param parent        [Task, nil]      parent task; cancelling the parent
+    #   also cancels this task (default: currently running task)
+    # @param backend_class [Class<Backend>] backend to use
+    # @yieldreturn [Object] the task result
+    # @return [Task]
+    # @api private
+    def self.spawn(name: nil, parent: current, backend_class: default_backend_class, &block)
+      new(name: name, parent: parent, backend_class: backend_class, &block)
+    end
+
+    # @return [String, nil] optional human-readable label
+    attr_reader :name
+
+    # @return [Task, nil] parent task in the task tree, if any
+    attr_reader :parent
+
+    # @return [Backend] the execution backend for this task
+    # @api private
+    attr_reader :backend
+
+    # @param name          [String, nil]
+    # @param parent        [Task, nil]
+    # @param backend_class [Class<Backend>]
+    # @api private use {.spawn} instead
+    def initialize(name: nil, parent: nil, backend_class: self.class.default_backend_class, &block)
+      @name = name
+      @parent = parent
+      @status = :pending
+      @mutex = Mutex.new
+      @children = []
+      @on_complete_callbacks = []
+      @completed_value = nil
+      @completed_error = nil
+      parent&.register_child(self)
+      @backend = backend_class.new(task: self, &block)
+    end
+
+    # Returns the current lifecycle state.
+    # @return [Symbol] one of {STATES}
+    # @api private
+    def status
+      @mutex.synchronize { @status }
+    end
+
+    # Blocks until the task completes and returns its value.
+    # Re-raises any exception raised inside the block.
+    #
+    # @return [Object] the result produced by the block
+    # @raise [Exception] if the block raised an error
+    # @api private
+    def await
+      @backend.await
+    end
+
+    # Registers a callback to be invoked when the task reaches a terminal state
+    # (+:completed+, +:failed+, or +:cancelled+).
+    #
+    # The callback receives two arguments: +value+ (the task's return value,
+    # or +nil+) and +error+ (the exception, or +nil+).  These are provided
+    # directly so the callback does not need to call +task.await+, which would
+    # risk a self-join error when the callback runs inside the task's own thread.
+    #
+    # If the task is already done when this method is called, the callback is
+    # invoked immediately (synchronously, on the calling thread).
+    #
+    # @yield [value, error] called when the task finishes
+    # @return [self]
+    # @api private
+    def on_complete(&callback)
+      fire_now = false
+      fire_args = nil
+      @mutex.synchronize do
+        # Check @status directly to avoid re-entering the mutex (done? calls
+        # status, which also takes @mutex).
+        if %i[completed failed cancelled].include?(@status)
+          fire_now = true
+          fire_args = [@completed_value, @completed_error]
+        else
+          @on_complete_callbacks << callback
+        end
+      end
+      callback.call(*fire_args) if fire_now
+      self
+    end
+
+    # Returns +true+ once the task has finished (success, error, or cancellation).
+    # @return [Boolean]
+    # @api private
+    def done?
+      %i[completed failed cancelled].include?(status)
+    end
+
+    # Requests cancellation.  Propagates to all registered child tasks.
+    # Sets status to :cancelled immediately so that even tasks that have not
+    # started executing yet are correctly marked as cancelled after join.
+    # Passes a CancellationError to on_complete callbacks so callers do not
+    # need to call await to discover the error.
+    # @return [self]
+    # @api private
+    def cancel!
+      transition!(:cancelled, error: CancellationError.new("Task cancelled"))
+      # @backend may be nil if cancel! is called while ImmediateBackend is still
+      # initializing (the block runs synchronously inside .new, so register_child
+      # fires before @backend is assigned).  Safe-navigate to avoid NoMethodError.
+      @backend&.cancel!
+      children = @mutex.synchronize { @children.dup }
+      children.each(&:cancel!)
+      self
+    end
+
+    # Joins the underlying execution context, optionally with a timeout.
+    # Returns +nil+ when the timeout expires before completion.
+    #
+    # @param limit [Numeric, nil] seconds to wait; nil waits indefinitely
+    # @return [Object, nil]
+    # @api private
+    def join(limit = nil)
+      @backend.join(limit)
+    end
+
+    # Returns +true+ while the task's block is still executing.
+    # @return [Boolean]
+    # @api private
+    def alive?
+      @backend.alive?
+    end
+
+    # Updates the task lifecycle state.
+    # Called by backends during execution transitions.
+    # Terminal states (completed/failed/cancelled) are never overwritten.
+    # When a terminal state is reached, fires on_complete callbacks (outside
+    # the mutex) passing the result value and error directly.
+    #
+    # @param new_status [Symbol]
+    # @param value      [Object, nil]    task return value (terminal states only)
+    # @param error      [Exception, nil] exception raised by the block, if any
+    # @api private
+    def transition!(new_status, value: nil, error: nil)
+      callbacks = nil
+      @mutex.synchronize do
+        # Check @status directly (not via #done?) to avoid re-entering the mutex.
+        return if %i[completed failed cancelled].include?(@status)
+
+        @status = new_status
+        if %i[completed failed cancelled].include?(new_status)
+          @completed_value = value
+          @completed_error = error
+          callbacks = @on_complete_callbacks.dup
+          @on_complete_callbacks.clear
+        end
+      end
+      callbacks&.each { |cb| cb.call(value, error) }
+    end
+
+    # Registers +child+ as a child task for cancellation propagation.
+    # Called automatically during child task initialization.
+    # @param child [Task]
+    # @api private
+    def register_child(child)
+      @mutex.synchronize { @children << child }
+    end
+  end
+end

data/lib/phronomy/task_group.rb

@@ -0,0 +1,265 @@
+# 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