phronomy 0.17.0 → 0.18.0

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

@@ -28,8 +28,20 @@ module Phronomy
         [remaining, 0.0].max
       end
 
+      # Registers a callback for explicit cancellation.
+      #
+      # 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.
+      #
+      # @return [self]
       # @api public
       def on_cancel(&block)
+        raise ArgumentError, "on_cancel requires a block" unless block
+
         already_cancelled = @mutex.synchronize do
           if @cancelled
             true
@@ -38,19 +50,29 @@ module Phronomy
             false
           end
         end
-        block.call if already_cancelled
+        deliver_cancel_callback(block) if already_cancelled
         self
       end
 
+      # 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
       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
 
@@ -66,6 +88,29 @@ module Phronomy
       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;