phronomy 0.17.0 → 0.18.0

data/lib/phronomy/engine/runtime/timer_queue.rb

@@ -2,104 +2,81 @@
 
 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.
+    # Threadless monotonic timer heap driven by EventLoop.
     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], ...]
+        @heap = []
         @mutex = Mutex.new
-        @cond = ConditionVariable.new
         @stopped = false
-        @thread = Thread.new { run_loop }
-        @thread.name = "phronomy-timer-queue"
+        @wake = nil
+      end
+
+      # Installs a lightweight wake callback used when a newly scheduled timer
+      # may change EventLoop's current wait deadline.
+      def wake_with(&block)
+        @mutex.synchronize { @wake = block }
+        self
       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)
+        raise ArgumentError, "schedule requires a block" unless callback
+
         fire_at = @clock.call + seconds.to_f
+        wake = nil
         @mutex.synchronize do
           raise Phronomy::PoolShutdownError, "TimerQueue has been shut down" if @stopped
-          insert_sorted(fire_at, callback)
-          @cond.signal
+
+          previous_first = @heap.first&.first
+          @heap << [fire_at, callback]
+          @heap.sort_by!(&:first)
+          wake = @wake if previous_first.nil? || fire_at < previous_first
         end
+        wake&.call
         self
       end
 
-      # Stop the background thread.  Pending (un-fired) callbacks are discarded.
-      #
-      # @return [self]
-      # @api private
-      def shutdown
+      # Seconds until the next timer is due, nil when no timers are pending.
+      def seconds_until_next
         @mutex.synchronize do
-          @stopped = true
-          @cond.signal
+          return nil if @stopped || @heap.empty?
+          [@heap.first.first - @clock.call, 0.0].max
         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
+      # Executes all callbacks whose deadline is due. Must be called by EventLoop.
+      def fire_due
+        callbacks = @mutex.synchronize do
+          return 0 if @stopped
 
-      def insert_sorted(fire_at, callback)
-        @heap << [fire_at, callback]
-        @heap.sort_by! { |(t, _)| t }
-      end
+          now = @clock.call
+          due_count = @heap.bsearch_index { |(fire_at, _)| fire_at > now } || @heap.length
+          @heap.shift(due_count).map(&:last)
+        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}" }
+        callbacks.each do |callback|
+          callback.call
+        rescue => error
+          Phronomy.configuration.logger&.error do
+            "[TimerQueue] callback raised #{error.class}: #{error.message}"
           end
         end
+        callbacks.length
       end
 
-      def next_callback
-        @mutex.synchronize do
-          loop do
-            return :stopped if @stopped
+      def pending_count
+        @mutex.synchronize { @heap.size }
+      end
 
-            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
+      def shutdown
+        wake = @mutex.synchronize do
+          return self if @stopped
+          @stopped = true
+          @heap.clear
+          @wake
         end
+        wake&.call
+        self
       end
     end
   end

data/lib/phronomy/engine/runtime/timer_service.rb

@@ -2,38 +2,30 @@
 
 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
+    # Lazy owner of the Runtime's threadless timer queue.
     class TimerService
-      # @param scheduler [Scheduler]
-      # @api private
-      def initialize(scheduler)
-        @scheduler = scheduler
+      def initialize
         @mutex = Mutex.new
         @timer = nil
+        @waker = 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
+          @timer ||= TimerQueue.new.tap do |timer|
+            timer.wake_with(&@waker) if @waker
           end
         end
       end
 
-      # Shuts down the timer queue if it was started.
-      # @return [void]
-      # @api private
+      def wake_with(&block)
+        @mutex.synchronize do
+          @waker = block
+          @timer&.wake_with(&block)
+        end
+        self
+      end
+
       def shutdown
         @mutex.synchronize { @timer&.shutdown }
       end

data/lib/phronomy/engine/runtime.rb

@@ -1,25 +1,22 @@
 # frozen_string_literal: true
 
-require_relative "runtime/scheduler"
-require_relative "runtime/thread_scheduler"
-require_relative "runtime/fake_scheduler"
-require_relative "runtime/deterministic_scheduler"
 require_relative "runtime/timer_queue"
-require_relative "runtime/scheduler_timer_adapter"
-require_relative "runtime/task_registry"
-require_relative "runtime/runtime_metrics"
 require_relative "runtime/shutdown_result"
 require_relative "runtime/timer_service"
 
 module Phronomy
-  # Central authority for concurrent primitives.
+  # Owns the EventLoop, offloaded synchronous work, timers and shutdown lifecycle.
+  #
+  # Runtime no longer schedules arbitrary Tasks. Framework control flow belongs
+  # to EventLoop/FSMSession; synchronous work that must not run on the EventLoop
+  # belongs to OffloadPool.
   class Runtime
     @instance_mutex = Mutex.new
 
     class << self
       def instance
         instance_mutex.synchronize do
-          @instance ||= build_default_runtime
+          @instance ||= new
         end
       end
 
@@ -65,54 +62,12 @@ module Phronomy
       def instance_mutex
         @instance_mutex ||= Mutex.new
       end
-
-      def build_default_runtime
-        scheduler = case Phronomy.configuration.runtime_backend
-        when :thread
-          ThreadScheduler.new
-        when :immediate
-          FakeScheduler.new
-        when :fiber
-          Phronomy.configuration.logger&.warn(
-            "[phronomy] runtime_backend: :fiber uses DeterministicScheduler in autorun mode. " \
-            "This is an EXPERIMENTAL Fiber-based cooperative scheduler. " \
-            "Wall-clock timer integration is available via SchedulerTimerAdapter (Issues #331, #337). " \
-            "Not recommended for production use."
-          )
-          DeterministicScheduler.new(autorun: true)
-        else
-          raise Phronomy::ConfigurationError,
-            "unknown runtime_backend: #{Phronomy.configuration.runtime_backend.inspect}"
-        end
-        new(scheduler: scheduler)
-      end
-    end
-
-    def self.in_scheduler_context?
-      !Task.current.nil?
-    end
-
-    def self.measure_ms
-      t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-      result = yield
-      elapsed_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - t0) * 1000).round
-      [result, elapsed_ms]
-    end
-
-    attr_reader :scheduler
-
-    def state
-      @lifecycle_mutex.synchronize { @state }
     end
 
-    def initialize(scheduler: ThreadScheduler.new)
-      @scheduler = scheduler
-      @event_loop_scheduler = ThreadScheduler.new
-      @task_registry = TaskRegistry.new
-      @metrics = RuntimeMetrics.new
-      @timer_service = TimerService.new(scheduler)
+    def initialize
+      @timer_service = TimerService.new
       @pool_registry = Phronomy::Concurrency::PoolRegistry.new(
-        timer_queue_provider: -> { @timer_service.timer_queue }
+        timer_queue_provider: -> { timer_queue }
       )
       @lifecycle_mutex = Mutex.new
       @shutdown_mutex = Mutex.new
@@ -122,73 +77,13 @@ module Phronomy
       @shutdown_result = nil
     end
 
-    def yield
-      if (threshold = Phronomy.configuration.blocking_detect_threshold_ms)
-        slice_start = Task.current_cpu_slice_start_ms
-        if slice_start
-          elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC, :millisecond) - slice_start
-          if elapsed > threshold
-            name = Task.current&.name || "unknown"
-            Phronomy.configuration.logger&.warn(
-              "[Phronomy] CPU-bound task detected: '#{name}' ran #{elapsed.round}ms " \
-              "without yielding (threshold: #{threshold}ms)"
-            )
-            @metrics.increment_starvation
-          end
-        end
-      end
-      Task.record_yield!
-      @scheduler.yield
-    end
-
-    def non_yield_threshold_violation_count
-      @metrics.starvation_count
-    end
-
-    def yield_if_needed(every: 1000)
-      self.yield if (Task.increment_yield_counter! % every).zero?
-    end
-
-    def task_group(limit: Float::INFINITY, failure_policy: :fail_fast)
-      ensure_accepting_work!
-      TaskGroup.new(limit: limit, failure_policy: failure_policy, runtime: self)
-    end
-
-    def spawn(name: nil, &block)
-      ensure_accepting_work!
-      type = _task_type(name)
-      spawn_at = Process.clock_gettime(Process::CLOCK_MONOTONIC, :millisecond)
-      @metrics.record_start(type)
-
-      task = @scheduler.spawn(name: name, parent: Task.current) do
-        run_start = Process.clock_gettime(Process::CLOCK_MONOTONIC, :millisecond)
-        @metrics.record_wait(run_start - spawn_at)
-        begin
-          result = block.call
-          @metrics.record_end(type, :completed, run_start)
-          result
-        rescue CancellationError
-          @metrics.record_end(type, :cancelled, run_start)
-          raise
-        rescue => error
-          @metrics.record_end(type, :failed, run_start)
-          raise error
-        ensure
-          current = Task.current
-          @task_registry.deregister(current) if current
-        end
-      end
-      @task_registry.register(task)
-      task
-    end
-
-    def task_snapshot
-      @metrics.snapshot
+    def state
+      @lifecycle_mutex.synchronize { @state }
     end
 
-    def blocking_io(
-      pool_size: Phronomy.configuration.blocking_io_pool_size,
-      queue_size: Phronomy.configuration.blocking_io_queue_size
+    def offload(
+      pool_size: Phronomy.configuration.offload_pool_size,
+      queue_size: Phronomy.configuration.offload_queue_size
     )
       ensure_accepting_work!
       @pool_registry.default_pool(pool_size: pool_size, queue_size: queue_size)
@@ -199,8 +94,16 @@ module Phronomy
       @pool_registry.named_pool(name, size: size, queue_size: queue_size)
     end
 
+    # Public timer access also ensures that the EventLoop that drives timers is alive.
     def timer_queue
       ensure_accepting_work!
+      timer = @timer_service.timer_queue
+      event_loop
+      timer
+    end
+
+    # Internal EventLoop access that does not recursively initialise EventLoop.
+    def __timer_queue
       @timer_service.timer_queue
     end
 
@@ -208,7 +111,11 @@ module Phronomy
       @lifecycle_mutex.synchronize do
         case @state
         when :running
-          @event_loop ||= EventLoop.new(runtime: self)
+          unless @event_loop
+            @event_loop = EventLoop.new(runtime: self)
+            @timer_service.wake_with { @event_loop&.wake }
+          end
+          @event_loop
         when :draining
           return @event_loop if @event_loop
 
@@ -222,12 +129,8 @@ module Phronomy
     end
 
     def event_loop_current?
-      event_loop = @lifecycle_mutex.synchronize { @event_loop }
-      event_loop&.current? || false
-    end
-
-    def __spawn_event_loop_service(&block)
-      @event_loop_scheduler.spawn(name: "event-loop", parent: nil, &block)
+      loop_instance = @lifecycle_mutex.synchronize { @event_loop }
+      loop_instance&.current? || false
     end
 
     def __event_loop_failed(error)
@@ -243,7 +146,7 @@ module Phronomy
       timeout: Phronomy.configuration.event_loop_stop_grace_seconds,
       cancel_grace: timeout
     )
-      if Phronomy::Task.current
+      if event_loop_current?
         raise Phronomy::RuntimeShutdownReentrancyError,
           "Runtime#shutdown must be called from an external management thread"
       end
@@ -253,29 +156,33 @@ module Phronomy
       @shutdown_mutex.synchronize do
         return @shutdown_result if @shutdown_result
 
-        deadline = monotonic_now + timeout
-        event_loop = @lifecycle_mutex.synchronize do
+        # Phase 1 — drain sessions with the full configured grace.
+        drain_deadline = monotonic_now + timeout
+        loop_instance = @lifecycle_mutex.synchronize do
           @state = :draining unless @state == :failed
           @event_loop
         end
-        event_loop&.begin_draining
+        loop_instance&.begin_draining
 
-        task_status = drain_runtime_work(event_loop, deadline)
+        loop_idle = !loop_instance || loop_instance.wait_until_idle(drain_deadline)
 
         @lifecycle_mutex.synchronize do
           @state = :stopping unless @state == :failed
         end
 
-        event_loop_status = if event_loop
-          event_loop.shutdown(deadline: deadline, cancel_grace: cancel_grace)
+        # Phase 2 — stop the EventLoop thread with a short independent budget.
+        # An idle EventLoop processes STOP and exits in < 1ms normally; the 0.2s
+        # budget here is only a safety net for OS scheduling jitter.
+        stop_deadline = monotonic_now + [cancel_grace.to_f, 0.2].max
+        event_loop_status = if loop_instance
+          loop_instance.stop_and_join(deadline: stop_deadline)
         else
           :not_started
         end
 
         subsystem_error = shutdown_pools_and_timer
-        final_task_status = @task_registry.empty? ? :empty : task_status
-        cleanup_complete = final_task_status == :empty &&
-          (!event_loop || !event_loop.task_alive?) &&
+        cleanup_complete = loop_idle &&
+          (!loop_instance || !loop_instance.thread_alive?) &&
           event_loop_status != :cancel_timeout &&
           subsystem_error.nil?
 
@@ -285,11 +192,12 @@ module Phronomy
         else
           :terminated
         end
+
         result = ShutdownResult.new(
           runtime_outcome: runtime_outcome,
           cleanup_status: cleanup_complete ? :complete : :incomplete,
           event_loop_status: event_loop_status,
-          task_registry_status: final_task_status,
+          task_registry_status: :empty,
           error: failure
         )
 
@@ -311,17 +219,6 @@ module Phronomy
         "Runtime is #{current_state}; new work is not accepted"
     end
 
-    def drain_runtime_work(event_loop, deadline)
-      loop do
-        task_status = @task_registry.drain_until(deadline)
-        return :timeout if task_status == :timeout
-
-        event_loop_idle = !event_loop || event_loop.wait_until_idle(deadline)
-        return :timeout unless event_loop_idle
-        return :empty if @task_registry.empty?
-      end
-    end
-
     def shutdown_pools_and_timer
       error = nil
       begin
@@ -347,15 +244,5 @@ module Phronomy
     def monotonic_now
       Process.clock_gettime(Process::CLOCK_MONOTONIC)
     end
-
-    TASK_TYPE_PREFIXES = %w[agent tool workflow rag llm vector].freeze
-    private_constant :TASK_TYPE_PREFIXES
-
-    def _task_type(name)
-      return :other if name.nil?
-
-      prefix = TASK_TYPE_PREFIXES.find { |candidate| name.to_s.start_with?("#{candidate}-") }
-      prefix ? prefix.to_sym : :other
-    end
   end
 end