phronomy 0.16.0 → 0.17.0

data/lib/phronomy/engine/runtime.rb

@@ -13,41 +13,7 @@ require_relative "runtime/timer_service"
 
 module Phronomy
   # Central authority for concurrent primitives.
-  #
-  # +Runtime+ is the single place that creates {Task}s, {TaskGroup}s, and
-  # manages the lifecycle of all concurrency in Phronomy.  It owns:
-  #
-  # * a pluggable {Scheduler} (default: {ThreadScheduler})
-  # * a task registry for graceful shutdown
-  # * the shared {BlockingAdapterPool}
-  #
-  # In production, use the process-wide singleton via {.instance}.
-  # In tests, construct a Runtime with a {FakeScheduler} to run tasks
-  # synchronously without spawning additional threads:
-  #
-  # @example Production usage
-  #   group = Phronomy::Runtime.instance.task_group(limit: 4)
-  #   tools.each { |t| group.spawn { t.call } }
-  #   results = group.await_all
-  #
-  # @example Test usage — no extra threads
-  #   runtime = Phronomy::Runtime.new(scheduler: Phronomy::Runtime::FakeScheduler.new)
-  #   task = runtime.spawn { 42 }
-  #   expect(task.wait_result).to eq(42)
   class Runtime
-    # Returns the process-wide default Runtime.
-    #
-    # Auto-creates an instance using the scheduler backend specified by
-    # +Phronomy.configuration.runtime_backend+:
-    # - +:thread+ (default) — {ThreadScheduler} (one OS thread per task)
-    # - +:immediate+ — {FakeScheduler} (synchronous, no extra threads)
-    # - +:fiber+ — {DeterministicScheduler} in autorun mode (EXPERIMENTAL;
-    #   Fiber-based synchronous execution; not yet suitable for production
-    #   because it uses virtual time rather than real wall-clock timers)
-    # - +:cooperative+ — deprecated alias for +:immediate+
-    #
-    # @return [Runtime]
-    # @api private
     @instance_mutex = Mutex.new
 
     class << self
@@ -57,17 +23,10 @@ module Phronomy
         end
       end
 
-      # Compatibility setter retained for existing tests.
-      def instance=(runtime)
-        replace_default_for_test(runtime)
-      end
-
-      # Test-only, non-creating access to the default Runtime.
       def default_if_initialized_for_test
         instance_mutex.synchronize { @instance }
       end
 
-      # Test-only replacement. The caller owns both Runtime lifecycles.
       def replace_default_for_test(runtime)
         instance_mutex.synchronize do
           previous = @instance
@@ -76,7 +35,6 @@ module Phronomy
         end
       end
 
-      # Test-only restoration of a previously captured Runtime.
       def restore_default_for_test(runtime)
         instance_mutex.synchronize { @instance = runtime }
       end
@@ -97,7 +55,6 @@ module Phronomy
         result
       end
 
-      # Does not create a Runtime or EventLoop.
       def in_event_loop_context?
         runtime = instance_mutex.synchronize { @instance }
         runtime&.event_loop_current? || false
@@ -111,13 +68,8 @@ module Phronomy
 
       def build_default_runtime
         scheduler = case Phronomy.configuration.runtime_backend
-        when :cooperative
-          Phronomy.configuration.logger&.warn(
-            "[phronomy] runtime_backend: :cooperative is a deprecated alias for :immediate. " \
-            "Use :immediate for synchronous/test execution. " \
-            ":cooperative will be reassigned when a real cooperative Fiber-based scheduler is available."
-          )
-          FakeScheduler.new
+        when :thread
+          ThreadScheduler.new
         when :immediate
           FakeScheduler.new
         when :fiber
@@ -129,37 +81,17 @@ module Phronomy
           )
           DeterministicScheduler.new(autorun: true)
         else
-          ThreadScheduler.new
+          raise Phronomy::ConfigurationError,
+            "unknown runtime_backend: #{Phronomy.configuration.runtime_backend.inspect}"
         end
         new(scheduler: scheduler)
       end
     end
 
-    # Returns +true+ when the calling thread is executing inside an active
-    # scheduler task (i.e. {Task.current} is non-nil).  Code running inside
-    # a {Runtime#spawn} block is always in a scheduler context.
-    #
-    # Use this to detect potential scheduler-blocking calls:
-    #   if Phronomy::Runtime.in_scheduler_context?
-    #     Phronomy.configuration.logger&.warn("blocking call inside scheduler task")
-    #   end
-    #
-    # @return [Boolean]
-    # @api private
     def self.in_scheduler_context?
       !Task.current.nil?
     end
 
-    # Executes +block+ and returns +[result, elapsed_ms]+ where +elapsed_ms+
-    # is the wall-clock duration in milliseconds (Integer, rounded).
-    #
-    # Isolates all direct references to +Process.clock_gettime+ /
-    # +Process::CLOCK_MONOTONIC+ in one place so that callers stay at the
-    # framework abstraction level.
-    #
-    # @yield block to time
-    # @return [Array(Object, Integer)] +[block_return_value, elapsed_ms]+
-    # @api private
     def self.measure_ms
       t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
       result = yield
@@ -167,18 +99,12 @@ module Phronomy
       [result, elapsed_ms]
     end
 
-    # The scheduler backing this runtime instance.
-    # @return [Scheduler]
     attr_reader :scheduler
 
-    # @return [Symbol] current Runtime lifecycle state
-    # @api private
     def state
       @lifecycle_mutex.synchronize { @state }
     end
 
-    # @param scheduler [Scheduler] execution backend (default: {ThreadScheduler})
-    # @api private
     def initialize(scheduler: ThreadScheduler.new)
       @scheduler = scheduler
       @event_loop_scheduler = ThreadScheduler.new
@@ -196,23 +122,6 @@ module Phronomy
       @shutdown_result = nil
     end
 
-    # Cooperative yield point.
-    #
-    # Signals the scheduler that the current task is willing to give up CPU time
-    # so that other ready tasks can run.  On the default {ThreadScheduler} this
-    # calls +Thread.pass+.  On a future fiber-based scheduler this would switch
-    # to the next runnable fiber.
-    #
-    # When +blocking_detect_threshold_ms+ is configured, checks whether the
-    # current task has exceeded that threshold without yielding; if so, emits a
-    # warning via the configured logger and increments
-    # +non_yield_threshold_violation_count+.
-    #
-    # Call this inside tight loops or CPU-intensive sections of tool +execute+
-    # methods and Workflow actions to keep the scheduler responsive.
-    #
-    # @return [void]
-    # @api private
     def yield
       if (threshold = Phronomy.configuration.blocking_detect_threshold_ms)
         slice_start = Task.current_cpu_slice_start_ms
@@ -232,64 +141,19 @@ module Phronomy
       @scheduler.yield
     end
 
-    # Number of times a task has exceeded the CPU-bound detection threshold
-    # (i.e. ran longer than +blocking_detect_threshold_ms+ without yielding).
-    # Resets to 0 when the Runtime is recreated.
-    # @return [Integer]
-    # @api private
     def non_yield_threshold_violation_count
       @metrics.starvation_count
     end
 
-    # Cooperative yield point with a call-count gate.
-    #
-    # Increments a per-thread counter and calls {#yield} when the counter
-    # reaches a multiple of +every+.  The counter is thread-local so concurrent
-    # tasks each maintain their own independent loop counter without requiring
-    # a mutex.
-    #
-    # @example
-    #   data.each_with_index do |row, i|
-    #     process(row)
-    #     Phronomy::Runtime.instance.yield_if_needed(every: 500)
-    #   end
-    #
-    # @param every [Integer] yield once every N calls (default: 1000)
-    # @return [void]
-    # @api private
     def yield_if_needed(every: 1000)
-      # Delegate Thread.current access to Task so that runtime.rb stays outside
-      # the Thread.current allowlist (Issue #302).
       self.yield if (Task.increment_yield_counter! % every).zero?
     end
 
-    # Creates a new {TaskGroup} with an optional concurrency cap.
-    #
-    # @param limit          [Integer, Float::INFINITY] max simultaneous tasks
-    # @param failure_policy [Symbol] one of :fail_fast, :collect_all, :skip_failed (default :fail_fast)
-    # @return [TaskGroup]
-    # @api private
     def task_group(limit: Float::INFINITY, failure_policy: :fail_fast)
       ensure_accepting_work!
       TaskGroup.new(limit: limit, failure_policy: failure_policy, runtime: self)
     end
 
-    # Spawns a single {Task} using the runtime's scheduler.
-    #
-    # The spawned task is registered in the task registry so {#shutdown}
-    # can wait for it to complete.  The task is automatically deregistered
-    # from the registry when it finishes (success, failure, or cancellation)
-    # so long-lived runtimes do not accumulate stale references.
-    #
-    # Task names beginning with a recognised type prefix are counted in the
-    # task-centric metrics returned by {#task_snapshot}.  Recognised prefixes:
-    # +agent-+, +tool-+, +workflow-+, +rag-+, +llm-+, +vector-+.
-    #
-    # @param name [String, nil] optional label for debugging
-    # @yield block to execute (concurrently or synchronously, depending on
-    #   the configured scheduler)
-    # @return [Task]
-    # @api private
     def spawn(name: nil, &block)
       ensure_accepting_work!
       type = _task_type(name)
@@ -306,9 +170,9 @@ module Phronomy
         rescue CancellationError
           @metrics.record_end(type, :cancelled, run_start)
           raise
-        rescue => e
+        rescue => error
           @metrics.record_end(type, :failed, run_start)
-          raise e
+          raise error
         ensure
           current = Task.current
           @task_registry.deregister(current) if current
@@ -318,93 +182,28 @@ module Phronomy
       task
     end
 
-    # Returns a snapshot of task-centric metrics for the current Runtime.
-    #
-    # | Key | Description |
-    # |-----|-------------|
-    # | `active_agent_tasks`      | currently running agent spawns |
-    # | `active_tool_tasks`       | currently running tool spawns |
-    # | `active_workflow_tasks`   | currently running workflow spawns |
-    # | `active_llm_tasks`        | currently running LLM calls |
-    # | `task_wait_time_p50_ms`   | p50 spawn-to-start latency (ms) |
-    # | `task_wait_time_p95_ms`   | p95 spawn-to-start latency (ms) |
-    # | `task_run_time_p50_ms`    | p50 execution duration (ms) |
-    # | `task_run_time_p95_ms`    | p95 execution duration (ms) |
-    # | `cancelled_tasks`         | total cancelled task count |
-    # | `failed_tasks`            | total failed task count |
-    # | `non_yield_threshold_violation_count` | cumulative count of tasks that ran past `blocking_detect_threshold_ms` without yielding |
-    #
-    # @return [Hash{Symbol => Numeric}]
-    # @api private
     def task_snapshot
       @metrics.snapshot
     end
 
-    # Returns the shared {BlockingAdapterPool} for this Runtime.
-    # All blocking I/O (LLM HTTP, MCP, ActiveRecord, Redis) should be
-    # submitted through this pool.
-    #
-    # Pool settings default to 10 workers / 100-deep queue.  Override by
-    # constructing a Runtime with custom pool options or by replacing the
-    # shared Runtime via {.instance=} in tests.
-    #
-    # @param pool_size  [Integer] worker thread count
-    #   (default: {Phronomy::Configuration#blocking_io_pool_size}, currently 10)
-    # @param queue_size [Integer] max pending operations
-    #   (default: {Phronomy::Configuration#blocking_io_queue_size}, currently 100)
-    # @return [BlockingAdapterPool]
-    # @api private
-    def blocking_io(pool_size: Phronomy.configuration.blocking_io_pool_size,
-      queue_size: Phronomy.configuration.blocking_io_queue_size)
+    def blocking_io(
+      pool_size: Phronomy.configuration.blocking_io_pool_size,
+      queue_size: Phronomy.configuration.blocking_io_queue_size
+    )
       ensure_accepting_work!
       @pool_registry.default_pool(pool_size: pool_size, queue_size: queue_size)
     end
 
-    # Returns (or lazily creates) a named {BlockingAdapterPool}.
-    #
-    # Named pools allow per-subsystem thread-budget control and observability.
-    # Recommended pool names: +:llm+, +:mcp+, +:db+, +:redis+, +:tool+.
-    # Each pool gets its own dedicated worker threads labelled with the pool name.
-    #
-    # @example
-    #   runtime.pool(:llm)            # default size (10 workers)
-    #   runtime.pool(:db, size: 20)   # custom size
-    #
-    # @param name      [Symbol, String] pool identifier
-    # @param size      [Integer] worker thread count (default: 10)
-    # @param queue_size [Integer] max pending operations (default: 100)
-    # @return [BlockingAdapterPool]
-    # @api private
     def pool(name, size: 10, queue_size: 100)
       ensure_accepting_work!
       @pool_registry.named_pool(name, size: size, queue_size: queue_size)
     end
 
-    # Returns the shared timer queue for this Runtime.
-    #
-    # When the scheduler is a {DeterministicScheduler} (e.g. the +:fiber+
-    # runtime backend), returns a {SchedulerTimerAdapter} that integrates with
-    # the scheduler's tick cycle instead of spawning a background OS thread.
-    # This is the first concrete step of the TimerQueue scheduler-tick integration
-    # described in ADR-010 (Issue #331).
-    #
-    # For all other schedulers, returns a {TimerQueue} backed by a single
-    # background thread.
-    #
-    # All deadline-based cancellation should be registered here instead of
-    # spawning one-off sleep threads.  Lazily created on first access.
-    #
-    # @return [TimerQueue, SchedulerTimerAdapter]
-    # @api private
     def timer_queue
       ensure_accepting_work!
       @timer_service.timer_queue
     end
 
-    # Returns the Runtime-owned EventLoop, creating it once on first use.
-    # During draining an existing loop remains available, but an unused loop
-    # is never created after shutdown begins.
-    # @api private
     def event_loop
       @lifecycle_mutex.synchronize do
         case @state
@@ -422,22 +221,15 @@ module Phronomy
       end
     end
 
-    # Does not create an EventLoop.
-    # @api private
     def event_loop_current?
       event_loop = @lifecycle_mutex.synchronize { @event_loop }
       event_loop&.current? || false
     end
 
-    # Internal EventLoop service spawn. Always uses a real OS thread and is
-    # deliberately excluded from the normal TaskRegistry drain.
-    # @api private
     def __spawn_event_loop_service(&block)
       @event_loop_scheduler.spawn(name: "event-loop", parent: nil, &block)
     end
 
-    # Called only for an unexpected dispatcher failure.
-    # @api private
     def __event_loop_failed(error)
       @lifecycle_mutex.synchronize do
         return if @shutdown_result || @state == :terminated
@@ -447,13 +239,6 @@ module Phronomy
       end
     end
 
-    # Synchronous, bounded Runtime shutdown. Must be invoked from an external
-    # management thread, lifecycle hook, or test teardown—not a Phronomy Task.
-    #
-    # +timeout+ bounds TaskRegistry and EventLoop graceful shutdown. Existing
-    # pool and timer shutdown contracts are unchanged by this proposal.
-    # @return [Runtime::ShutdownResult]
-    # @api public
     def shutdown(
       timeout: Phronomy.configuration.event_loop_stop_grace_seconds,
       cancel_grace: timeout
@@ -541,13 +326,13 @@ module Phronomy
       error = nil
       begin
         @pool_registry.shutdown
-      rescue => e
-        error ||= e
+      rescue => caught
+        error ||= caught
       ensure
         begin
           @timer_service.shutdown
-        rescue => e
-          error ||= e
+        rescue => caught
+          error ||= caught
         end
       end
       error
@@ -569,7 +354,7 @@ module Phronomy
     def _task_type(name)
       return :other if name.nil?
 
-      prefix = TASK_TYPE_PREFIXES.find { |p| name.to_s.start_with?("#{p}-") }
+      prefix = TASK_TYPE_PREFIXES.find { |candidate| name.to_s.start_with?("#{candidate}-") }
       prefix ? prefix.to_sym : :other
     end
   end

data/lib/phronomy/engine/task_group.rb

@@ -2,41 +2,20 @@
 
 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.
+    # @param limit [Integer, Float::INFINITY]
+    # @param failure_policy [Symbol]
+    # @param runtime [Runtime] runtime authority used to spawn every child Task
     # @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)
+    def initialize(runtime:, limit: Float::INFINITY, failure_policy: :fail_fast)
+      unless FAILURE_POLICIES.include?(failure_policy)
+        raise ArgumentError, "unknown failure_policy: #{failure_policy}"
+      end
+      unless runtime
+        raise ArgumentError, "runtime is required"
+      end
 
       @limit = limit
       @failure_policy = failure_policy
@@ -47,44 +26,20 @@ module Phronomy
       @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
+      task = @runtime.spawn(name: "task-group-worker") do
+        block.call
+      ensure
+        release_slot!
       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 }
@@ -99,14 +54,6 @@ module Phronomy
 
     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|
@@ -120,34 +67,29 @@ module Phronomy
       fail_fast_error = nil
 
       tasks.length.times do
-        entry = completion_q.pop  # cooperative suspend via scheduler signal
+        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? }
+          tasks.each { |task| task.cancel! unless task.done? }
         end
       end
 
       case @failure_policy
       when :fail_fast
         raise fail_fast_error if fail_fast_error
-        entries.map { |r| r[:value] }
+        entries.map { |entry| entry[:value] }
       when :skip_failed
-        entries.filter_map { |r| r[:value] unless r[:error] }
-      else # :collect_all
-        errors = entries.filter_map { |r| r[:error] }
+        entries.filter_map { |entry| entry[:value] unless entry[:error] }
+      else
+        errors = entries.filter_map { |entry| entry[:error] }
         raise errors.first if errors.any?
-        entries.map { |r| r[:value] }
+        entries.map { |entry| entry[: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|
@@ -158,8 +100,6 @@ module Phronomy
 
       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
@@ -169,45 +109,35 @@ module Phronomy
         if entry[:error] && @failure_policy == :fail_fast && !cancelled
           cancelled = true
           fail_fast_error = entry[:error]
-          tasks.each { |t| t.cancel! unless t.done? }
+          tasks.each { |task| task.cancel! unless task.done? }
         end
       end
 
       case @failure_policy
       when :fail_fast
         raise fail_fast_error if fail_fast_error
-        entries.map { |r| r[:value] }
+        entries.map { |entry| entry[:value] }
       when :skip_failed
-        entries.filter_map { |r| r[:value] unless r[:error] }
-      else # :collect_all
-        errors = entries.filter_map { |r| r[:error] }
+        entries.filter_map { |entry| entry[:value] unless entry[:error] }
+      else
+        errors = entries.filter_map { |entry| entry[:error] }
         raise errors.first if errors.any?
-        entries.map { |r| r[:value] }
+        entries.map { |entry| entry[: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
+      tasks.each do |task|
+        task.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
@@ -221,8 +151,6 @@ module Phronomy
       self
     end
 
-    # Returns the number of currently executing child tasks.
-    # @return [Integer]
     # @api private
     def active_task_count
       @mutex.synchronize { @active }