phronomy 0.6.0 → 0.7.1

data/lib/phronomy/runtime/pool_registry.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Phronomy
+  class Runtime
+    # Registry and lifecycle manager for {BlockingAdapterPool} instances.
+    #
+    # Maintains one unnamed "default" pool (accessed via {#default_pool}) and
+    # an arbitrary number of named pools (accessed via {#named_pool}).
+    # All pools are shut down together by {#shutdown}.
+    # @api private
+    class PoolRegistry
+      def initialize
+        @mutex = Mutex.new
+        @pools = {}
+        @default = nil
+      end
+
+      # Returns (or lazily creates) the unnamed default pool.
+      # @param pool_size  [Integer]
+      # @param queue_size [Integer]
+      # @return [BlockingAdapterPool]
+      # @api private
+      def default_pool(pool_size: 10, queue_size: 100)
+        @default ||= BlockingAdapterPool.new(
+          name: :default,
+          pool_size: pool_size,
+          queue_size: queue_size
+        )
+      end
+
+      # Returns (or lazily creates) a named pool.
+      # @param name      [Symbol, String]
+      # @param size      [Integer]
+      # @param queue_size [Integer]
+      # @return [BlockingAdapterPool]
+      # @api private
+      def named_pool(name, size: 10, queue_size: 100)
+        @mutex.synchronize do
+          @pools[name.to_sym] ||= BlockingAdapterPool.new(
+            name: name,
+            pool_size: size,
+            queue_size: queue_size
+          )
+        end
+      end
+
+      # Shuts down the default pool and all named pools.
+      # @return [void]
+      # @api private
+      def shutdown
+        @default&.shutdown
+        pools = @mutex.synchronize { @pools.values.dup }
+        pools.each(&:shutdown)
+      end
+    end
+  end
+end

data/lib/phronomy/runtime/runtime_metrics.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module Phronomy
+  class Runtime
+    # Internal store for task-centric counters and latency samples.
+    #
+    # All access is mutex-protected.  The ring buffers for wait/run times are
+    # bounded to {WINDOW} samples so that long-lived runtimes do not grow
+    # unbounded.
+    # @api private
+    class RuntimeMetrics
+      WINDOW = 1000
+      private_constant :WINDOW
+
+      def initialize
+        @mutex = Mutex.new
+        @active_by_type = Hash.new(0)
+        @wait_ms = []
+        @run_ms = []
+        @cancelled = Hash.new(0)
+        @failed = Hash.new(0)
+        @starvation_count = 0
+      end
+
+      # Records that a new task of +type+ has been spawned.
+      # @param type [Symbol]
+      # @return [void]
+      # @api private
+      def record_start(type)
+        @mutex.synchronize { @active_by_type[type] += 1 }
+      end
+
+      # Appends a wait-time sample (milliseconds from spawn to start).
+      # @param wait_ms [Float]
+      # @return [void]
+      # @api private
+      def record_wait(wait_ms)
+        @mutex.synchronize do
+          @wait_ms << wait_ms
+          @wait_ms.shift if @wait_ms.size > WINDOW
+        end
+      end
+
+      # Records completion of a task (decrements active count, appends run time).
+      # @param type    [Symbol]
+      # @param outcome [:completed, :cancelled, :failed]
+      # @param run_start_ms [Integer] monotonic millisecond timestamp from task start
+      # @return [void]
+      # @api private
+      def record_end(type, outcome, run_start_ms)
+        run_ms = Process.clock_gettime(Process::CLOCK_MONOTONIC, :millisecond) - run_start_ms
+        @mutex.synchronize do
+          @active_by_type[type] = [@active_by_type[type] - 1, 0].max
+          @run_ms << run_ms
+          @run_ms.shift if @run_ms.size > WINDOW
+          case outcome
+          when :cancelled then @cancelled[type] += 1
+          when :failed then @failed[type] += 1
+          end
+        end
+      end
+
+      # Increments the CPU-starvation counter (task ran without yielding over
+      # the configured +blocking_detect_threshold_ms+ threshold).
+      # @return [void]
+      # @api private
+      def increment_starvation
+        @mutex.synchronize { @starvation_count += 1 }
+      end
+
+      # Returns the current starvation counter value.
+      # @return [Integer]
+      # @api private
+      def starvation_count
+        @mutex.synchronize { @starvation_count }
+      end
+
+      # Returns the full task-centric metrics hash (see {Runtime#task_snapshot}).
+      # @return [Hash{Symbol => Numeric}]
+      # @api private
+      def snapshot
+        @mutex.synchronize do
+          active = @active_by_type.dup
+          wait = @wait_ms.dup
+          run = @run_ms.dup
+          cancelled = @cancelled.values.sum
+          failed = @failed.values.sum
+          starvation = @starvation_count
+          {
+            active_agent_tasks: active[:agent].to_i,
+            active_tool_tasks: active[:tool].to_i,
+            active_workflow_tasks: active[:workflow].to_i,
+            active_rag_tasks: active[:rag].to_i,
+            active_llm_tasks: active[:llm].to_i,
+            task_wait_time_p50_ms: _percentile(wait, 50),
+            task_wait_time_p95_ms: _percentile(wait, 95),
+            task_run_time_p50_ms: _percentile(run, 50),
+            task_run_time_p95_ms: _percentile(run, 95),
+            cancelled_tasks: cancelled,
+            failed_tasks: failed,
+            non_yield_threshold_violation_count: starvation
+          }
+        end
+      end
+
+      private
+
+      def _percentile(samples, pct)
+        return 0.0 if samples.empty?
+
+        sorted = samples.sort
+        idx = ((pct / 100.0) * (sorted.size - 1)).round
+        sorted[idx].round(3)
+      end
+    end
+  end
+end

data/lib/phronomy/runtime/scheduler.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Phronomy
+  class Runtime
+    # Abstract base class for Runtime scheduler backends.
+    #
+    # A scheduler is responsible for turning +Runtime#spawn+ calls into
+    # runnable {Task} objects.  Concrete subclasses decide whether tasks
+    # execute on threads, Fibers, or some other execution primitive.
+    #
+    # The interface is intentionally minimal: callers only see {Task}
+    # objects and never interact with the scheduler directly.
+    class Scheduler
+      # Thread-local key under which the active scheduler is stored.
+      # Shared with {Task::FiberBackend} (same symbol).
+      # @api private
+      SCHEDULER_KEY = :phronomy_deterministic_scheduler
+
+      # Returns the scheduler currently dispatching on this OS thread, or +nil+
+      # when running outside a cooperative (Fiber-based) scheduler context.
+      #
+      # Uses +Thread#thread_variable_get+ (not +Thread#[]+) so that the value is
+      # visible across all Fibers running on the same OS thread.
+      #
+      # @return [Scheduler, nil]
+      # @api private
+      def self.current
+        Thread.current.thread_variable_get(SCHEDULER_KEY)
+      end
+
+      # Creates a new scheduler-aware signal object for this scheduler.
+      # Signalling primitives use this instead of +ConditionVariable+ when a
+      # cooperative scheduler is active.
+      #
+      # Default implementation raises +NotImplementedError+.  Subclasses that
+      # support cooperative suspension (e.g. {DeterministicScheduler}) must
+      # override this.
+      #
+      # @return [Object] an opaque signal handle understood by {#wait_for_signal}
+      #   and {#raise_signal}
+      # @api private
+      def new_signal
+        raise NotImplementedError, "#{self.class}#new_signal is not implemented"
+      end
+
+      # Suspends the current execution unit (Fiber or Thread) until +signal+ is
+      # raised via {#raise_signal}.
+      #
+      # @param signal [Object] signal handle returned by {#new_signal}
+      # @return [void]
+      # @api private
+      def wait_for_signal(signal)
+        raise NotImplementedError, "#{self.class}#wait_for_signal is not implemented"
+      end
+
+      # Wakes up one waiter suspended on +signal+.
+      #
+      # @param signal [Object] signal handle returned by {#new_signal}
+      # @return [void]
+      # @api private
+      def raise_signal(signal)
+        raise NotImplementedError, "#{self.class}#raise_signal is not implemented"
+      end
+
+      # Wakes up all waiters suspended on +signal+.
+      #
+      # @param signal [Object] signal handle returned by {#new_signal}
+      # @return [void]
+      # @api private
+      def raise_signal_all(signal)
+        raise NotImplementedError, "#{self.class}#raise_signal_all is not implemented"
+      end
+
+      # Spawns a new task.
+      #
+      # @param name   [String, nil] optional human-readable label
+      # @param parent [Task, nil]   parent task for cancellation propagation
+      # @yield block to execute concurrently (or synchronously, depending on
+      #   the concrete scheduler)
+      # @return [Task]
+      # @api private
+      def spawn(name:, parent:, &block)
+        raise NotImplementedError, "#{self.class}#spawn is not implemented"
+      end
+
+      # Cooperative yield point.
+      #
+      # Default implementation is a no-op.  Thread-based subclasses should
+      # override with +Thread.pass+; fiber-based subclasses should switch to the
+      # next runnable fiber.
+      # @return [void]
+      # @api private
+      def yield
+        # no-op by default; subclasses override
+      end
+    end
+  end
+end

data/lib/phronomy/runtime/scheduler_timer_adapter.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Phronomy
+  class Runtime
+    # A drop-in replacement for {TimerQueue} that delegates timer scheduling to
+    # a {DeterministicScheduler} instead of spawning a dedicated background OS thread.
+    #
+    # When a {Runtime} is backed by {DeterministicScheduler} (e.g. the +:fiber+
+    # runtime backend), {Runtime#timer_queue} returns an instance of this adapter
+    # rather than a {TimerQueue}.  This eliminates the +phronomy-timer-queue+
+    # background thread for Fiber-based runtimes.
+    #
+    # Timer callbacks are fired during {DeterministicScheduler#run_until_idle}
+    # when {DeterministicScheduler#autorun?} is +true+ (i.e. the +:fiber+ backend).
+    # They can also be fired explicitly by calling
+    # {DeterministicScheduler#fire_real_timers}.
+    #
+    # == Known Limitation (Issue #331)
+    #
+    # Timers that require an actual wall-clock sleep (e.g. a deadline of 10 s
+    # from now that will not be reached until real time elapses) will not fire
+    # automatically: +run_until_idle+ does not block waiting for future deadlines.
+    # This is an accepted limitation of the current stepping-stone implementation.
+    # Full resolution requires integrating the cooperative scheduler with the
+    # {EventLoop} tick cycle so that a single event-loop iteration checks both
+    # ready Fibers and expired wall-clock timers.
+    #
+    # Use the +:thread+ runtime backend (default) for production workloads that
+    # depend on real-time deadline enforcement.
+    #
+    # @see DeterministicScheduler#schedule_real_after
+    # @see DeterministicScheduler#fire_real_timers
+    # Bridges wall-clock timers to the cooperative {DeterministicScheduler}.
+    #
+    # Registers a recurring timer callback with the scheduler's {TimerQueue}
+    # so that Fiber-based tasks can await real time without blocking OS threads.
+    # @api private
+    class SchedulerTimerAdapter
+      # @param scheduler [DeterministicScheduler]
+      # @api private
+      def initialize(scheduler)
+        @scheduler = scheduler
+      end
+
+      # Schedules a one-shot callback to fire after +seconds+ from now.
+      # Delegates to {DeterministicScheduler#schedule_real_after}.
+      #
+      # Raises {PoolShutdownError} after {#shutdown} has been called, matching
+      # the behaviour of {TimerQueue#schedule}.
+      #
+      # @param seconds [Numeric] delay before the callback fires
+      # @yield called when the deadline is reached
+      # @return [self]
+      # @api private
+      def schedule(seconds:, &callback)
+        raise Phronomy::PoolShutdownError, "SchedulerTimerAdapter has been shut down" if @stopped
+
+        @scheduler.schedule_real_after(seconds, &callback)
+        self
+      end
+
+      # No-op: there is no background thread to stop.
+      # Present for API compatibility with {TimerQueue}.
+      # @return [self]
+      # @api private
+      def shutdown
+        @stopped = true
+        self
+      end
+
+      # Returns the number of pending (not yet fired) callbacks.
+      # @return [Integer]
+      # @api private
+      def pending_count
+        @scheduler.pending_real_timer_count
+      end
+    end
+  end
+end

data/lib/phronomy/runtime/task_registry.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Phronomy
+  class Runtime
+    # Internal registry of active {Task} instances for a {Runtime}.
+    #
+    # Tracks every task that has been spawned but not yet completed so that
+    # {Runtime#shutdown} can drain them.  Tasks that complete synchronously
+    # (e.g. under {FakeScheduler} / {ImmediateBackend}) deregister themselves
+    # before the caller returns from {Runtime#spawn}, so they are never added
+    # to the registry in the first place.
+    # @api private
+    class TaskRegistry
+      def initialize
+        @mutex = Mutex.new
+        @tasks = []
+      end
+
+      # Adds +task+ to the registry unless it already completed synchronously.
+      # @param task [Task]
+      # @return [void]
+      # @api private
+      def register(task)
+        @mutex.synchronize { @tasks << task unless task.done? }
+      end
+
+      # Removes +task+ from the registry (called from the task's ensure block).
+      # @param task [Task]
+      # @return [void]
+      # @api private
+      def deregister(task)
+        @mutex.synchronize { @tasks.delete(task) }
+      end
+
+      # Waits for all registered tasks to finish (used by {Runtime#shutdown}).
+      # @return [void]
+      # @api private
+      def drain
+        tasks = @mutex.synchronize { @tasks.dup }
+        tasks.each do |t|
+          t.join
+        rescue
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/runtime/thread_scheduler.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Phronomy
+  class Runtime
+    # Thread-based scheduler: spawns each task in a new OS thread.
+    #
+    # This is the default scheduler used by {Runtime} in production.
+    # It delegates directly to {Task.spawn} with the default
+    # {Task::ThreadBackend}, preserving the pre-282 behaviour exactly.
+    # @api private
+    class ThreadScheduler < Scheduler
+      # Spawns +block+ as a new {Task} backed by a Thread.
+      #
+      # @param name   [String, nil]
+      # @param parent [Task, nil]
+      # @return [Task]
+      # @api private
+      def spawn(name:, parent:, &block)
+        Task.spawn(name: name, parent: parent, &block)
+      end
+
+      # Yields the current thread's time slice to other runnable threads.
+      # @return [void]
+      # @api private
+      def yield
+        Thread.pass
+      end
+    end
+  end
+end

data/lib/phronomy/runtime/timer_queue.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module Phronomy
+  class Runtime
+    # A thread-safe timer queue backed by a single background thread.
+    #
+    # Replaces the pattern of spawning one +Thread.new { sleep(t); callback }+
+    # per deadline.  Any number of timers share a single background thread that
+    # sleeps until the earliest pending deadline.
+    #
+    # Use {#schedule} to register a one-shot callback; call {#shutdown} when the
+    # queue is no longer needed (e.g. on process exit) to stop the background
+    # thread cleanly.
+    class TimerQueue
+      # @param clock [#call] zero-argument callable that returns the current
+      #   monotonic time in seconds (defaults to +Process::CLOCK_MONOTONIC+).
+      #   Override in tests to inject a fake clock.
+      # @api private
+      def initialize(clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) })
+        @clock = clock
+        @heap = [] # [[fire_at, callback], ...]
+        @mutex = Mutex.new
+        @cond = ConditionVariable.new
+        @stopped = false
+        @thread = Thread.new { run_loop }
+        @thread.name = "phronomy-timer-queue"
+      end
+
+      # Schedule a one-shot callback to fire after +seconds+ from now.
+      #
+      # @param seconds [Numeric] delay before the callback fires
+      # @yield called (in the timer thread) when the deadline is reached
+      # @return [self]
+      # @api private
+      def schedule(seconds:, &callback)
+        fire_at = @clock.call + seconds.to_f
+        @mutex.synchronize do
+          raise Phronomy::PoolShutdownError, "TimerQueue has been shut down" if @stopped
+          insert_sorted(fire_at, callback)
+          @cond.signal
+        end
+        self
+      end
+
+      # Stop the background thread.  Pending (un-fired) callbacks are discarded.
+      #
+      # @return [self]
+      # @api private
+      def shutdown
+        @mutex.synchronize do
+          @stopped = true
+          @cond.signal
+        end
+        @thread.join
+        self
+      end
+
+      # Number of pending (not yet fired) callbacks.  Primarily for testing.
+      # @return [Integer]
+      # @api private
+      def pending_count
+        @mutex.synchronize { @heap.size }
+      end
+
+      private
+
+      def insert_sorted(fire_at, callback)
+        @heap << [fire_at, callback]
+        @heap.sort_by! { |(t, _)| t }
+      end
+
+      def run_loop
+        loop do
+          callback = next_callback
+          break if callback == :stopped
+          begin
+            callback&.call
+          rescue => e
+            Phronomy.configuration.logger&.error { "[TimerQueue] callback raised #{e.class}: #{e.message}" }
+          end
+        end
+      end
+
+      def next_callback
+        @mutex.synchronize do
+          loop do
+            return :stopped if @stopped
+
+            if @heap.empty?
+              @cond.wait(@mutex)
+            else
+              now = @clock.call
+              fire_at, = @heap.first
+              if fire_at <= now
+                return @heap.shift[1]
+              else
+                remaining = fire_at - now
+                @cond.wait(@mutex, remaining)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/runtime/timer_service.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Phronomy
+  class Runtime
+    # Lazy-initialised timer service for a {Runtime} instance.
+    #
+    # Returns a {SchedulerTimerAdapter} when the backing scheduler is a
+    # {DeterministicScheduler} (enabling virtual-time integration for the
+    # `:fiber` backend), or a standard {TimerQueue} (OS-thread backed) for all
+    # other schedulers.
+    # @api private
+    class TimerService
+      # @param scheduler [Scheduler]
+      # @api private
+      def initialize(scheduler)
+        @scheduler = scheduler
+        @mutex = Mutex.new
+        @timer = nil
+      end
+
+      # Returns (or lazily creates) the timer queue for this runtime.
+      # @return [TimerQueue, SchedulerTimerAdapter]
+      # @api private
+      def timer_queue
+        @mutex.synchronize do
+          @timer ||= if @scheduler.is_a?(DeterministicScheduler)
+            SchedulerTimerAdapter.new(@scheduler)
+          else
+            TimerQueue.new
+          end
+        end
+      end
+
+      # Shuts down the timer queue if it was started.
+      # @return [void]
+      # @api private
+      def shutdown
+        @mutex.synchronize { @timer&.shutdown }
+      end
+    end
+  end
+end