phronomy 0.16.0 → 0.18.0

data/lib/phronomy/engine/concurrency/async_queue.rb

@@ -2,219 +2,36 @@
 
 module Phronomy
   module Concurrency
-    # A thread-safe FIFO queue for passing values between concurrent tasks.
+    # Thread-safe FIFO queue used at explicit thread boundaries.
     #
-    # Wraps +Thread::Queue+ so that callers do not need to reference the Ruby
-    # standard-library type directly.  A future implementation may replace the
-    # backing primitive without changing call sites.
-    #
-    # @example Producer / consumer
-    #   queue = Phronomy::Concurrency::AsyncQueue.new
-    #   Runtime.instance.spawn { queue.push(expensive_io()) }
-    #   value = queue.pop   # blocks until the producer pushes
-    # @api private
+    # It intentionally contains no scheduler/Fiber semantics. Cooperative
+    # application execution is represented by FSMSession state and EventLoop events.
     class AsyncQueue
-      # @param max_size [Integer, nil] optional upper bound on queue depth.
-      #   When set, {#push} blocks the caller until a slot is available.
-      # @api private
       def initialize(max_size: nil)
         @queue = max_size ? SizedQueue.new(max_size) : Thread::Queue.new
-        @max_size = max_size
-        @waiter_mutex = Mutex.new
-        @cross_thread_waiter = nil    # [fiber, scheduler] set by _pop_cooperative; consumed by push
-        @cross_thread_scheduler = nil # set by expect_cross_thread_push
       end
 
-      # Enqueues +item+.
-      # In a cooperative scheduler context with a bounded queue (max_size:), suspends
-      # the current Fiber via a scheduler signal when the queue is full rather than
-      # blocking the OS thread.  Without a scheduler, falls back to the standard
-      # SizedQueue blocking behaviour.
-      # @param item [Object] value to enqueue
-      # @return [self]
-      # @api private
       def push(item)
-        scheduler = Phronomy::Runtime::Scheduler.current
-        if scheduler && @max_size
-          _push_cooperative(scheduler, item)
-        else
-          @queue.push(item)
-          scheduler.raise_signal(@coop_signal) if scheduler && @coop_signal
-          # Wake a cross-thread waiter if one is registered.
-          # Handles the case where a DeterministicScheduler Fiber is suspended
-          # in _pop_cooperative waiting for a push from a non-scheduler thread
-          # (e.g. EventLoop thread where Scheduler.current is nil).
-          # enqueue_fiber is thread-safe; complete_blocking_await decrements
-          # @pending_awaits so run_until_idle can eventually exit.
-          if @cross_thread_scheduler
-            waiter = @waiter_mutex.synchronize do
-              w = @cross_thread_waiter
-              @cross_thread_waiter = nil
-              w
-            end
-            if waiter
-              fiber, sched = waiter
-              sched.complete_blocking_await
-              sched.enqueue_fiber(-> { fiber.resume })
-            end
-          end
-        end
+        @queue.push(item)
         self
       end
 
-      # Dequeues and returns the next item.
-      # In a cooperative scheduler context, suspends the current Fiber (yielding
-      # control back to the scheduler) rather than blocking the OS thread.
-      #
-      # When +timeout+ is given the semantics depend on the active backend:
-      #
-      # * **Thread backend** (`:thread`) — uses real wall-clock time via
-      #   +Thread::Queue#pop(timeout:)+.  Requires Ruby 3.2+.
-      #   Returns +nil+ if no item arrives within the specified number of real seconds.
-      # * **DeterministicScheduler / `:fiber` backend** — uses the scheduler's
-      #   *virtual time* (+scheduler.virtual_time+).  The timeout elapses only when
-      #   the virtual clock is advanced (e.g. via {Phronomy::Testing::FakeClock#advance}).
-      #   In tests this means the timeout is fully deterministic and does not depend on
-      #   actual elapsed wall time.  However, in production `:fiber` mode the timeout
-      #   may never expire unless the scheduler explicitly advances virtual time.
-      #
-      # @note The `:fiber` backend is **EXPERIMENTAL**.  Real-time timeout behaviour
-      #   in production workloads is not guaranteed and may differ from wall-clock
-      #   expectations.
-      # @note **Cooperative timeout limitation**: on the cooperative path, the
-      #   deadline is re-checked *after* a wake-up signal arrives.  If virtual time
-      #   has already passed the deadline when the consumer is woken by a producer
-      #   push, the consumer returns +nil+ rather than the pushed item.  Without any
-      #   wake-up signal the waiting Fiber remains suspended even after
-      #   +scheduler.advance+ — the timeout does not self-fire.
-      # @param timeout [Numeric, nil] seconds to wait before returning +nil+.
-      #   Semantics are wall-clock on `:thread` and virtual-time on `:fiber`.
-      # @return [Object, nil] the next item, or +nil+ when timeout expires
-      # @api private
       def pop(timeout: nil)
-        scheduler = Phronomy::Runtime::Scheduler.current
-        if scheduler
-          _pop_cooperative(scheduler, timeout: timeout)
-        elsif timeout
-          @queue.pop(timeout: timeout)
-        else
-          @queue.pop
-        end
+        timeout ? @queue.pop(timeout: timeout) : @queue.pop
       end
 
-      # Returns the current number of items in the queue.
-      # @return [Integer]
-      # @api private
       def size
         @queue.size
       end
 
-      # Returns +true+ when the queue contains no items.
-      # @return [Boolean]
-      # @api private
       def empty?
         @queue.empty?
       end
 
-      # Closes the queue.  Subsequent {#pop} calls raise +ClosedQueueError+.
-      # @return [self]
-      # @api private
       def close
         @queue.close
         self
       end
-
-      # Marks this queue as expecting pushes from a non-scheduler OS thread.
-      # When set, {#pop} in cooperative mode uses +track_blocking_await+ so that
-      # {Runtime::DeterministicScheduler#run_until_idle} does not exit while
-      # waiting for the cross-thread push.  Called by {EventLoop#register} when
-      # a cooperative scheduler is active on the calling thread.
-      # @param scheduler [Runtime::Scheduler]
-      # @return [self]
-      # @api private
-      def expect_cross_thread_push(scheduler)
-        @cross_thread_scheduler = scheduler
-        self
-      end
-
-      private
-
-      # Cooperative pop for DeterministicScheduler context.
-      # Suspends the current Fiber via the scheduler's signal mechanism rather than
-      # blocking the OS thread.
-      #
-      # Two suspension paths:
-      # * **Same-scheduler** (default): uses {CoopSignal} — the producer is another
-      #   Fiber on the same DeterministicScheduler.  run_until_idle is allowed to
-      #   exit; the producer's push will enqueue the consumer Fiber.
-      # * **Cross-thread** ({#expect_cross_thread_push} was called): uses
-      #   +track_blocking_await+ so that run_until_idle does not exit while waiting
-      #   for a push from a non-scheduler OS thread (e.g. EventLoop).  The push
-      #   side calls +complete_blocking_await+ + +enqueue_fiber+ to resume.
-      #
-      # The empty?/register pair for the cross-thread path is wrapped in
-      # @waiter_mutex to eliminate the race between the empty check and the
-      # registration of the waker.
-      # @api private
-      # @param scheduler [Runtime::Scheduler]
-      # @param timeout [Numeric, nil]
-      # @return [Object, nil]
-      def _pop_cooperative(scheduler, timeout:)
-        @coop_signal ||= scheduler.new_signal
-        deadline = timeout ? (scheduler.virtual_time + timeout) : nil
-
-        loop do
-          unless @queue.empty?
-            item = @queue.pop(timeout: 0)
-            # Notify a push-waiter (bounded queue) that a slot opened up.
-            scheduler.raise_signal(@push_signal) if @push_signal
-            return item
-          end
-          return nil if deadline && scheduler.virtual_time >= deadline
-
-          if @cross_thread_scheduler
-            # Cross-thread path: atomically check the queue and register a waker
-            # so that a concurrent push cannot slip between the empty? check above
-            # and the registration below.
-            will_yield = false
-            @waiter_mutex.synchronize do
-              if @queue.empty?
-                @cross_thread_waiter = [Fiber.current, scheduler]
-                scheduler.track_blocking_await
-                will_yield = true
-              end
-              # else: push arrived between the loop's empty? check and here;
-              # will_yield stays false and the next loop iteration dequeues it.
-            end
-            Fiber.yield(:cooperative_suspend) if will_yield
-          else
-            scheduler.wait_for_signal(@coop_signal)
-          end
-
-          return nil if deadline && scheduler.virtual_time >= deadline
-        end
-      end
-
-      # Cooperative push for DeterministicScheduler context with a bounded queue.
-      # Suspends the current Fiber via a scheduler signal when the queue is full,
-      # rather than blocking the OS thread.
-      # @api private
-      # @param scheduler [Runtime::Scheduler]
-      # @param item [Object]
-      # @return [void]
-      def _push_cooperative(scheduler, item)
-        @push_signal ||= scheduler.new_signal
-
-        loop do
-          unless @queue.size >= @max_size
-            @queue.push(item)
-            # Notify any pop-waiter that an item is now available.
-            scheduler.raise_signal(@coop_signal) if @coop_signal
-            return
-          end
-          scheduler.wait_for_signal(@push_signal)
-        end
-      end
     end
   end
 end

data/lib/phronomy/engine/concurrency/cancellation_scope.rb

@@ -6,7 +6,7 @@ module Phronomy
     # optionally a {Deadline}.
     #
     # +CancellationScope+ replaces ad-hoc +Timeout.timeout+ calls in agent and
-    # tool code.  All work performed within a scope should observe the scope's
+    # tool code. All work performed within a scope should observe the scope's
     # token; when the scope is cancelled (explicitly or by deadline expiry) the
     # token is cancelled and all child tasks that check it will stop.
     #
@@ -18,10 +18,9 @@ module Phronomy
     #
     # @example Explicit cancellation
     #   scope = Phronomy::Concurrency::CancellationScope.new
-    #   Phronomy::Runtime.instance.spawn(name: "worker") do
-    #     scope.token.raise_if_cancelled!
-    #     # ... do work ...
-    #   end
+    #   operation = Phronomy::Runtime.instance.offload.submit(
+    #     cancellation_token: scope.token
+    #   ) { synchronous_operation }
     #   scope.cancel! if some_condition
     class CancellationScope
       # @return [CancellationToken] the token owned by this scope
@@ -33,7 +32,7 @@ module Phronomy
       # @param parent_token [CancellationToken, nil] when provided, cancellation of
       #   the parent token is propagated to this scope's token via a callback
       #   (for explicit cancel) and/or the Runtime timer queue (for monotonic
-      #   deadline expiry).  No polling thread is spawned.
+      #   deadline expiry). No polling thread is spawned.
       # @api private
       def initialize(parent_token: nil)
         @token = Phronomy::Concurrency::CancellationToken.new
@@ -92,7 +91,7 @@ module Phronomy
       end
 
       # Pops from +queue+ with a timeout derived from the attached deadline (or
-      # +fallback_timeout+ seconds when no deadline is set).  If the pop times out,
+      # +fallback_timeout+ seconds when no deadline is set). If the pop times out,
       # the scope is cancelled and the block is called (or a {TimeoutError} raised).
       #
       # @param queue [Phronomy::Concurrency::AsyncQueue] the queue to pop from

data/lib/phronomy/engine/concurrency/cancellation_token.rb

@@ -2,91 +2,46 @@
 
 module Phronomy
   module Concurrency
-    # Provides cooperative cancellation for agent invocations.
-    #
-    # Pass a token to an agent via +config: { cancellation_token: token }+.
-    # The agent checks the token before each LLM call and raises
-    # {Phronomy::CancellationError} when the token is cancelled or the
-    # optional deadline has passed.
-    #
-    # A token may be shared across multiple agent invocations and across threads;
-    # all access to internal state is protected by a Mutex.
-    #
-    # @example Explicit cancel from another thread
-    #   token = Phronomy::Concurrency::CancellationToken.new
-    #   Thread.new { sleep 5; token.cancel! }
-    #   result = agent.invoke("...", config: { cancellation_token: token })
-    #
-    # @example Hard deadline via monotonic clock (recommended)
-    #   token = Phronomy::Concurrency::CancellationToken.timeout_after(30)
-    #   result = agent.invoke("...", config: { cancellation_token: token })
-    #
-    # @example Hard deadline via wall-clock (legacy)
-    #   token = Phronomy::Concurrency::CancellationToken.new(deadline: Time.now + 30)
-    #   result = agent.invoke("...", config: { cancellation_token: token })
-    #
-    # @example Propagate to parallel workers
-    #   token = Phronomy::Concurrency::CancellationToken.new
-    #   orchestrator.dispatch_parallel(task1, task2, cancellation_token: token)
+    # Cooperative cancellation token for Agent/Tool work.
     class CancellationToken
-      # Returns a new token that will expire after +seconds+ seconds, measured
-      # with the monotonic clock (+Process::CLOCK_MONOTONIC+). Unlike constructing
-      # a token with +deadline: Time.now + seconds+, this factory is immune to NTP
-      # adjustments and DST transitions.
-      #
-      # @param seconds [Numeric] duration in seconds until the token expires.
-      # @return [CancellationToken]
+      # Creates a token that expires after +seconds+ measured with the monotonic clock.
       # @api public
       def self.timeout_after(seconds)
         monotonic_deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + seconds
         new(monotonic_deadline: monotonic_deadline)
       end
 
-      # @param deadline [Time, nil] optional wall-clock deadline; the token reports
-      #   +cancelled?+ as +true+ once +Time.now >= deadline+.  Prefer
-      #   {.timeout_after} for duration-based cancellation.
-      # @param monotonic_deadline [Float, nil] internal monotonic timestamp set by
-      #   {.timeout_after}; prefer that factory method over passing this directly.
+      # @param monotonic_deadline [Float, nil] internal monotonic timestamp.
       # @api public
-      # mutant:disable - removing @cancelled = false is equivalent because nil is falsey
-      def initialize(deadline: nil, monotonic_deadline: nil)
+      def initialize(monotonic_deadline: nil)
         @cancelled = false
-        @deadline = deadline
         @monotonic_deadline = monotonic_deadline
         @mutex = Mutex.new
         @cancel_callbacks = []
       end
 
-      # @return [Time, nil] the wall-clock deadline passed to {#initialize}, or +nil+.
-      attr_reader :deadline
-
-      # Returns the remaining seconds until the monotonic deadline fires, or +nil+
-      # when no monotonic deadline is set.  Returns 0.0 if already past.
-      # @return [Float, nil]
       # @api public
       def remaining_monotonic_seconds
         return nil if @monotonic_deadline.nil?
+
         remaining = @monotonic_deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
         [remaining, 0.0].max
       end
 
-      # Registers a one-shot callback invoked when this token is explicitly
-      # cancelled via {#cancel!}.  If the token is already cancelled, the block
-      # is called immediately (still within the caller's thread).
+      # Registers a callback for explicit cancellation.
       #
-      # Callbacks are NOT fired for deadline-based cancellation (i.e. when
-      # {#cancelled?} returns +true+ due to +@monotonic_deadline+ expiry).  Use
-      # {Phronomy::Concurrency::CancellationScope#deadline_in}, which registers
-      # a timer via {Runtime#timer_queue} and calls {#cancel!} on expiry — this
-      # fires all +on_cancel+ callbacks automatically.  {.timeout_after} is a
-      # lightweight alternative that uses lazy clock comparison only and does
-      # NOT trigger callbacks on expiry.
+      # Deadline expiry by itself only changes {#cancelled?}. Components that need
+      # callback delivery for a monotonic deadline must promote that deadline to
+      # +cancel!+ through the Runtime timer queue.
+      #
+      # Cancellation callbacks are independent notifications. Failure of one
+      # callback is logged and does not suppress delivery to other callbacks.
       #
-      # @yield called with no arguments when (or if) the token is cancelled
       # @return [self]
       # @api public
-      # mutant:disable - mutex removal mutation is GVL-safe equivalent under MRI
       def on_cancel(&block)
+        raise ArgumentError, "on_cancel requires a block" unless block
+
         already_cancelled = @mutex.synchronize do
           if @cancelled
             true
@@ -95,50 +50,67 @@ module Phronomy
             false
           end
         end
-        block.call if already_cancelled
+        deliver_cancel_callback(block) if already_cancelled
         self
       end
 
-      # Mark the token as cancelled and fire any registered {#on_cancel} callbacks.
-      # Thread-safe; idempotent — calling multiple times has no additional effect.
+      # Explicitly cancels the token and invokes each currently registered callback
+      # once. The callback registry is cleared before callbacks run so completed
+      # registrations are not retained for the lifetime of a long-lived token.
+      #
+      # Cancellation callbacks are isolated from one another: a StandardError raised
+      # by one callback is logged and the remaining callbacks are still delivered.
+      #
       # @return [self]
       # @api public
-      # mutant:disable - mutex removal and dup-vs-ref mutations are GVL-safe equivalents
       def cancel!
         callbacks = @mutex.synchronize do
           return self if @cancelled
+
           @cancelled = true
-          @cancel_callbacks.dup
+          callbacks = @cancel_callbacks
+          @cancel_callbacks = []
+          callbacks
         end
-        callbacks.each(&:call)
+        callbacks.each { |callback| deliver_cancel_callback(callback) }
         self
       end
 
-      # Returns +true+ when the token has been explicitly cancelled via {#cancel!},
-      # when the wall-clock deadline has passed, or when the monotonic deadline
-      # (set by {.timeout_after}) has elapsed. Thread-safe.
-      # @return [Boolean]
       # @api public
-      # mutant:disable - mutex removal on @cancelled read is GVL-safe equivalent under MRI
       def cancelled?
         return true if @mutex.synchronize { @cancelled }
-        return true if !@deadline.nil? && Time.now >= @deadline
+
         !@monotonic_deadline.nil? &&
           Process.clock_gettime(Process::CLOCK_MONOTONIC) >= @monotonic_deadline
       end
 
-      # Raises {Phronomy::CancellationError} if the token is cancelled.
-      # A convenience method for cooperative cancellation checks inside tools,
-      # RAG loaders, and hooks, replacing the +if cancelled? then raise+ pattern.
-      #
-      # @param message [String] optional error message
-      # @return [nil] when the token is not cancelled
-      # @raise [Phronomy::CancellationError] when the token is cancelled
       # @api public
-      # mutant:disable - raise(CancellationError) resolves to raise(Phronomy::CancellationError) in this namespace
       def raise_if_cancelled!(message = "invocation cancelled")
         raise Phronomy::CancellationError, message if cancelled?
       end
+
+      private
+
+      def deliver_cancel_callback(callback)
+        callback.call
+      rescue => error
+        Phronomy.configuration.logger&.error do
+          "[CancellationToken] on_cancel callback raised #{error.class}: #{error.message}"
+        end
+      end
+
+      # Removes an explicit-cancellation callback that is no longer needed.
+      #
+      # This exists so framework operation registrations do not keep their captured
+      # state alive when the operation completes before the token is cancelled. It is
+      # intentionally not part of the public cancellation API.
+      #
+      # A concurrent +cancel!+ may already have taken the callback for delivery;
+      # callers must therefore make their callback idempotent.
+      def unregister_cancel_callback(callback)
+        @mutex.synchronize { @cancel_callbacks.delete(callback) }
+        self
+      end
     end
   end
 end

data/lib/phronomy/engine/concurrency/deadline.rb

@@ -44,9 +44,8 @@ module Phronomy
       end
 
       # Attaches this deadline to a {CancellationToken} by cancelling the token
-      # when the deadline expires.  Uses the Runtime timer queue (a single
-      # background thread shared by all deadlines) instead of spawning one thread
-      # per deadline.
+      # when the deadline expires. The Runtime timer queue is driven by EventLoop;
+      # no timer-specific OS thread is created.
       #
       # @param token [CancellationToken]
       # @param timer_queue [Runtime::TimerQueue, nil] queue to register with;