phronomy 0.6.0 → 0.7.1

data/lib/phronomy/task/fiber_backend.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+module Phronomy
+  class Task
+    # Cooperative task backend using Ruby Fibers.
+    #
+    # Unlike {ImmediateBackend} (which runs the block to completion on the
+    # calling thread) or {ThreadBackend} (which runs the block on a new OS
+    # thread), +FiberBackend+ wraps the block in a +Fiber+ that is NOT started
+    # immediately.  The owning scheduler calls {#step} to advance execution one
+    # cooperative step at a time.
+    #
+    # This backend is used exclusively by {Runtime::DeterministicScheduler} to
+    # enable deterministic, wall-clock-free testing of concurrent logic.
+    #
+    # Thread-local key under which the currently active {DeterministicScheduler}
+    # is stored so that {#await} can suspend cooperatively.
+    SCHEDULER_KEY = :phronomy_deterministic_scheduler
+
+    # @api private
+    class FiberBackend < Backend
+      def initialize(task:, &block)
+        super
+        @value = nil
+        @error = nil
+        @cancel_error = nil
+        @cancel_requested = false
+        @started = false
+        @cooperative_suspend = false
+
+        # Capture `self` (the FiberBackend instance) in the closure so that
+        # instance-variable writes from inside the Fiber update this object.
+        @fiber = Fiber.new do
+          task.transition!(:running)
+          begin
+            # If cancel! was called before the first step, raise immediately.
+            raise @cancel_error if @cancel_error
+
+            @value = block.call
+            task.transition!(:completed, value: @value)
+          rescue CancellationError => e
+            task.transition!(:cancelled, error: e)
+            @error = e
+          rescue => e
+            task.transition!(:failed, error: e)
+            @error = e
+          ensure
+            task.transition!(:cancelled) unless task.done?
+          end
+        end
+      end
+
+      # Advances execution by one scheduler step.
+      # Resumes the Fiber until it yields (via +Fiber.yield+) or finishes.
+      # Cooperative cancellation is checked at the start of each step: if
+      # +cancel!+ has been called, +CancellationError+ is raised inside the
+      # Fiber at this controlled checkpoint rather than injected at an
+      # arbitrary suspension point via +Fiber#raise+.
+      # @return [self]
+      # @api private
+      def step
+        return self unless @fiber.alive?
+
+        @started = true
+        # Deliver pending cancellation at this scheduler checkpoint rather than
+        # injecting it mid-Fiber via Fiber#raise (which would be preemptive).
+        if @cancel_requested && @cancel_error
+          begin
+            @fiber.raise(@cancel_error)
+          rescue FiberError
+            nil  # Fiber completed between the check and raise — safe to ignore.
+          end
+          @cancel_requested = false
+          return self
+        end
+        yield_value = @fiber.resume
+        # A yield value of :cooperative_suspend signals that the Fiber deliberately
+        # suspended itself (e.g. inside CoopSignal#wait) and must NOT be
+        # re-enqueued by step_callable — it will be resumed by an explicit signal.
+        @cooperative_suspend = (yield_value == :cooperative_suspend)
+        self
+      end
+
+      # Returns +true+ if the Fiber yielded cooperatively (via a signal wait)
+      # and should not be automatically re-enqueued by the scheduler.
+      # @return [Boolean]
+      # @api private
+      def cooperative_suspend?
+        @cooperative_suspend
+      end
+
+      # Blocks until the task completes.
+      #
+      # When called from within a {DeterministicScheduler}-managed Fiber,
+      # suspends the current Fiber cooperatively and schedules it to resume
+      # when this task completes.  When called from outside a managed Fiber
+      # (e.g. the main fiber or a regular thread), drives execution by calling
+      # {#step} in a loop.
+      #
+      # @return [Object]
+      # @raise [Exception]
+      # @api private
+      def await
+        unless @fiber.alive?
+          raise @error if @error
+          return @value
+        end
+
+        scheduler = Thread.current.thread_variable_get(SCHEDULER_KEY)
+        # Fiber.main was added in Ruby 3.2.4+; fall back to true (assume we are
+        # inside a managed Fiber whenever a scheduler is active).
+        in_managed_fiber = !Fiber.respond_to?(:main) || Fiber.current != Fiber.main
+        if scheduler && in_managed_fiber
+          # Cooperative context: suspend current Fiber until task is done.
+          waiting_fiber = Fiber.current
+          @task.on_complete { scheduler.enqueue_fiber(-> { waiting_fiber.resume }) }
+          Fiber.yield(:cooperative_suspend)
+        else
+          # Non-cooperative context: drive the fiber to completion.
+          step while @fiber.alive?
+        end
+
+        raise @error if @error
+        @value
+      end
+
+      # @return [Boolean] +true+ while the Fiber has not yet finished
+      # @api private
+      def alive?
+        @fiber.alive?
+      end
+
+      # Requests cancellation using a cooperative checkpoint mechanism.
+      # Sets a cancellation flag; the error is raised inside the Fiber at the
+      # next +step+ call (i.e. when the scheduler next dispatches this task),
+      # not injected at an arbitrary suspension point via +Fiber#raise+.
+      # If the Fiber has not yet started, the error is recorded so it is raised
+      # on the first {#step}.
+      # @return [self]
+      # @api private
+      def cancel!
+        @cancel_error = CancellationError.new("Task cancelled")
+        @cancel_requested = true
+        self
+      end
+
+      # Joins execution by stepping until the Fiber is no longer alive.
+      # @param limit [Numeric, nil] ignored
+      # @return [self]
+      # @api private
+      def join(_limit = nil)
+        step while @fiber.alive?
+        self
+      end
+    end
+  end
+end

data/lib/phronomy/task/immediate_backend.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Phronomy
+  class Task
+    # Synchronous task backend that executes the block on the calling thread.
+    #
+    # Used by {Runtime::FakeScheduler} to allow tests to verify cooperative
+    # scheduling behaviour without spawning additional Threads.  The block
+    # runs to completion before {#initialize} returns, so {#await} and {#join}
+    # always return immediately.
+    #
+    # Thread count invariant: +ImmediateBackend+ never creates a new Thread.
+    class ImmediateBackend < Backend
+      # Executes +block+ synchronously on the calling thread.
+      # Saves and restores +Task.current+ so nested ImmediateBackend tasks
+      # compose correctly.
+      #
+      # @param task  [Task]
+      # @yieldreturn [Object]
+      # @api private
+      def initialize(task:, &block)
+        super
+        @value = nil
+        @error = nil
+        previous_task = Thread.current[:phronomy_current_task]
+        Thread.current[:phronomy_current_task] = task
+        task.transition!(:running)
+        begin
+          @value = block.call
+          task.transition!(:completed, value: @value)
+        rescue CancellationError => e
+          task.transition!(:cancelled, error: e)
+          @error = e
+        rescue => e
+          task.transition!(:failed, error: e)
+          @error = e
+        ensure
+          task.transition!(:cancelled) unless task.done?
+          Thread.current[:phronomy_current_task] = previous_task
+        end
+      end
+
+      # Returns the block's return value, or re-raises its exception.
+      # @return [Object]
+      # @raise [Exception]
+      # @api private
+      def await
+        raise @error if @error
+
+        @value
+      end
+
+      # @return [Object, nil]
+      # @api private
+      def completed_value
+        @value
+      end
+
+      # @return [Exception, nil]
+      # @api private
+      def completed_error
+        @error
+      end
+
+      # Always +false+ — block has already completed by the time the task
+      # is visible to callers.
+      # @return [Boolean]
+      # @api private
+      def alive?
+        false
+      end
+
+      # No-op: the block has already completed.
+      # @return [self]
+      # @api private
+      def cancel!
+        self
+      end
+
+      # Returns immediately — nothing to wait for.
+      # @param limit [Numeric, nil] ignored
+      # @return [self]
+      # @api private
+      def join(_limit = nil)
+        self
+      end
+    end
+  end
+end

data/lib/phronomy/task/thread_backend.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Phronomy
+  class Task
+    # Thread-based Task backend (default).
+    #
+    # Each task runs on its own OS thread.  Cancellation is delivered via
+    # +Thread#raise(CancellationError)+, which cooperates with +rescue+ clauses
+    # inside the block.  This backend is always available and requires no
+    # external dependencies.
+    #
+    # When the cooperative scheduler backend is introduced, this backend will
+    # remain available as the fallback for blocking I/O operations that must
+    # run outside the scheduler (e.g. inside {BlockingAdapterPool}).
+    class ThreadBackend < Backend
+      def initialize(task:, &block)
+        super
+        @value = nil
+        @error = nil
+        @thread = Thread.new do
+          Thread.current.name = task.name if task.name
+          Thread.current[:phronomy_current_task] = task
+          Thread.current[:phronomy_task_cpu_slice_start_ms] =
+            Process.clock_gettime(Process::CLOCK_MONOTONIC, :millisecond)
+          task.transition!(:running)
+          @value = block.call
+          task.transition!(:completed, value: @value)
+        rescue CancellationError => e
+          task.transition!(:cancelled, error: e)
+          @error = e
+        rescue => e
+          task.transition!(:failed, error: e)
+          @error = e
+        ensure
+          # Guard against Thread#raise firing before the rescue handler has a
+          # chance to run (e.g. when cancel! is called immediately after spawn).
+          task.transition!(:cancelled) unless task.done?
+        end
+      end
+
+      # @return [Object]
+      # @raise [Exception]
+      # @api private
+      def await
+        @thread.join
+        raise @error if @error
+
+        @value
+      end
+
+      # @return [Boolean]
+      # @api private
+      def alive?
+        @thread.alive?
+      end
+
+      # @return [self]
+      # @api private
+      def cancel!
+        @thread.raise(CancellationError, "Task cancelled") if @thread.alive?
+        self
+      end
+
+      # @param limit [Numeric, nil]
+      # @return [Thread, nil]
+      # @api private
+      def join(limit = nil)
+        @thread.join(limit)
+      end
+
+      # @return [Object, nil]
+      # @api private
+      def completed_value
+        @value
+      end
+
+      # @return [Exception, nil]
+      # @api private
+      def completed_error
+        @error
+      end
+    end
+  end
+end

data/lib/phronomy/task.rb

@@ -0,0 +1,275 @@
+# frozen_string_literal: true
+
+require_relative "task/backend"
+require_relative "task/thread_backend"
+require_relative "task/immediate_backend"
+require_relative "task/fiber_backend"
+
+module Phronomy
+  # A single unit of concurrent work.
+  #
+  # Decouples task semantics from the underlying execution primitive via a
+  # pluggable {Backend}.  The default backend is {ThreadBackend}; a cooperative
+  # or test-double backend can be substituted via {.default_backend_class=} or
+  # by passing +backend_class:+ to {.spawn}.
+  #
+  # +Task.spawn+ is an **internal API** used by schedulers and the framework
+  # itself.  Application code and framework components should use
+  # +Runtime.instance.spawn+ instead, which routes through the configured
+  # scheduler and respects the concurrency model.
+  #
+  # @example Basic usage (framework/test code only — prefer Runtime.instance.spawn in app code)
+  #   task = Phronomy::Task.spawn { expensive_io() }
+  #   result = task.await   # blocks until done, re-raises errors
+  #
+  # @example Cancel a running task
+  #   task = Phronomy::Task.spawn { loop { Phronomy::Task.checkpoint! } }
+  #   task.cancel!
+  #
+  # @example Task tree — cancel parent cancels children
+  #   parent = Phronomy::Task.spawn { sleep 10 }
+  #   child  = Phronomy::Task.spawn(parent: parent) { sleep 10 }
+  #   parent.cancel!   # child is also cancelled
+  class Task
+    # Valid task lifecycle states.
+    STATES = %i[pending running completed failed cancelled].freeze
+
+    # Returns the process-wide default backend class.
+    # Defaults to {ThreadBackend}.
+    # Override in tests or to enable a cooperative scheduler backend.
+    # @return [Class<Backend>]
+    # @api private
+    def self.default_backend_class
+      @default_backend_class || ThreadBackend
+    end
+
+    # Sets the process-wide default backend class.
+    # @param klass [Class<Backend>]
+    # @api private
+    def self.default_backend_class=(klass)
+      @default_backend_class = klass
+    end
+
+    # Returns the {Task} currently executing on this thread, or +nil+.
+    # Returns +nil+ when called from outside a task-managed execution context.
+    # @return [Task, nil]
+    # @api private
+    def self.current
+      Thread.current[:phronomy_current_task]
+    end
+
+    # Returns the monotonic clock value (ms) when the current task last recorded
+    # a yield (or when the task started), or +nil+ when not inside a task context.
+    # Used by {Runtime#yield} for CPU-bound detection without placing
+    # +Thread.current+ in files outside the allowlist.
+    # @return [Integer, nil]
+    # @api private
+    def self.current_cpu_slice_start_ms
+      Thread.current[:phronomy_task_cpu_slice_start_ms]
+    end
+
+    # Resets the CPU slice start clock for the current task to +now+.
+    # Call this immediately after the cooperative yield has been performed so
+    # that the next yield correctly measures only the time since the last yield.
+    # @api private
+    def self.record_yield!
+      Thread.current[:phronomy_task_cpu_slice_start_ms] =
+        Process.clock_gettime(Process::CLOCK_MONOTONIC, :millisecond)
+    end
+
+    # Returns and increments a per-thread yield-if-needed counter.
+    # Used by {Runtime#yield_if_needed} so that the counter is thread-local
+    # without putting +Thread.current+ in runtime.rb (which is outside the
+    # Thread.current allowlist).
+    # @return [Integer] the new counter value
+    # @api private
+    def self.increment_yield_counter!
+      count = (Thread.current[:phronomy_yield_if_needed_counter] || 0) + 1
+      Thread.current[:phronomy_yield_if_needed_counter] = count
+      count
+    end
+
+    # Cooperative cancellation checkpoint.
+    #
+    # Raises {CancellationError} if the current task's status is +:cancelled+.
+    # On {ThreadBackend}, cancellation is delivered via +Thread#raise+ so this
+    # is a no-op in practice; on future cooperative backends this will be the
+    # primary cancellation mechanism.
+    #
+    # Safe to call from outside a task context (no-op when no current task).
+    # @return [void]
+    # @raise [CancellationError] if the current task has been cancelled
+    # @api private
+    def self.checkpoint!
+      ct = current
+      return unless ct
+
+      raise CancellationError, "Task cancelled" if ct.status == :cancelled
+    end
+
+    # Spawns a new task executing +block+ concurrently.
+    #
+    # @param name          [String, nil]    optional human-readable label
+    # @param parent        [Task, nil]      parent task; cancelling the parent
+    #   also cancels this task (default: currently running task)
+    # @param backend_class [Class<Backend>] backend to use
+    # @yieldreturn [Object] the task result
+    # @return [Task]
+    # @api private
+    def self.spawn(name: nil, parent: current, backend_class: default_backend_class, &block)
+      new(name: name, parent: parent, backend_class: backend_class, &block)
+    end
+
+    # @return [String, nil] optional human-readable label
+    attr_reader :name
+
+    # @return [Task, nil] parent task in the task tree, if any
+    attr_reader :parent
+
+    # @return [Backend] the execution backend for this task
+    # @api private
+    attr_reader :backend
+
+    # @param name          [String, nil]
+    # @param parent        [Task, nil]
+    # @param backend_class [Class<Backend>]
+    # @api private use {.spawn} instead
+    def initialize(name: nil, parent: nil, backend_class: self.class.default_backend_class, &block)
+      @name = name
+      @parent = parent
+      @status = :pending
+      @mutex = Mutex.new
+      @children = []
+      @on_complete_callbacks = []
+      @completed_value = nil
+      @completed_error = nil
+      parent&.register_child(self)
+      @backend = backend_class.new(task: self, &block)
+    end
+
+    # Returns the current lifecycle state.
+    # @return [Symbol] one of {STATES}
+    # @api private
+    def status
+      @mutex.synchronize { @status }
+    end
+
+    # Blocks until the task completes and returns its value.
+    # Re-raises any exception raised inside the block.
+    #
+    # @return [Object] the result produced by the block
+    # @raise [Exception] if the block raised an error
+    # @api private
+    def await
+      @backend.await
+    end
+
+    # Registers a callback to be invoked when the task reaches a terminal state
+    # (+:completed+, +:failed+, or +:cancelled+).
+    #
+    # The callback receives two arguments: +value+ (the task's return value,
+    # or +nil+) and +error+ (the exception, or +nil+).  These are provided
+    # directly so the callback does not need to call +task.await+, which would
+    # risk a self-join error when the callback runs inside the task's own thread.
+    #
+    # If the task is already done when this method is called, the callback is
+    # invoked immediately (synchronously, on the calling thread).
+    #
+    # @yield [value, error] called when the task finishes
+    # @return [self]
+    # @api private
+    def on_complete(&callback)
+      fire_now = false
+      fire_args = nil
+      @mutex.synchronize do
+        # Check @status directly to avoid re-entering the mutex (done? calls
+        # status, which also takes @mutex).
+        if %i[completed failed cancelled].include?(@status)
+          fire_now = true
+          fire_args = [@completed_value, @completed_error]
+        else
+          @on_complete_callbacks << callback
+        end
+      end
+      callback.call(*fire_args) if fire_now
+      self
+    end
+
+    # Returns +true+ once the task has finished (success, error, or cancellation).
+    # @return [Boolean]
+    # @api private
+    def done?
+      %i[completed failed cancelled].include?(status)
+    end
+
+    # Requests cancellation.  Propagates to all registered child tasks.
+    # Sets status to :cancelled immediately so that even tasks that have not
+    # started executing yet are correctly marked as cancelled after join.
+    # Passes a CancellationError to on_complete callbacks so callers do not
+    # need to call await to discover the error.
+    # @return [self]
+    # @api private
+    def cancel!
+      transition!(:cancelled, error: CancellationError.new("Task cancelled"))
+      # @backend may be nil if cancel! is called while ImmediateBackend is still
+      # initializing (the block runs synchronously inside .new, so register_child
+      # fires before @backend is assigned).  Safe-navigate to avoid NoMethodError.
+      @backend&.cancel!
+      children = @mutex.synchronize { @children.dup }
+      children.each(&:cancel!)
+      self
+    end
+
+    # Joins the underlying execution context, optionally with a timeout.
+    # Returns +nil+ when the timeout expires before completion.
+    #
+    # @param limit [Numeric, nil] seconds to wait; nil waits indefinitely
+    # @return [Object, nil]
+    # @api private
+    def join(limit = nil)
+      @backend.join(limit)
+    end
+
+    # Returns +true+ while the task's block is still executing.
+    # @return [Boolean]
+    # @api private
+    def alive?
+      @backend.alive?
+    end
+
+    # Updates the task lifecycle state.
+    # Called by backends during execution transitions.
+    # Terminal states (completed/failed/cancelled) are never overwritten.
+    # When a terminal state is reached, fires on_complete callbacks (outside
+    # the mutex) passing the result value and error directly.
+    #
+    # @param new_status [Symbol]
+    # @param value      [Object, nil]    task return value (terminal states only)
+    # @param error      [Exception, nil] exception raised by the block, if any
+    # @api private
+    def transition!(new_status, value: nil, error: nil)
+      callbacks = nil
+      @mutex.synchronize do
+        # Check @status directly (not via #done?) to avoid re-entering the mutex.
+        return if %i[completed failed cancelled].include?(@status)
+
+        @status = new_status
+        if %i[completed failed cancelled].include?(new_status)
+          @completed_value = value
+          @completed_error = error
+          callbacks = @on_complete_callbacks.dup
+          @on_complete_callbacks.clear
+        end
+      end
+      callbacks&.each { |cb| cb.call(value, error) }
+    end
+
+    # Registers +child+ as a child task for cancellation propagation.
+    # Called automatically during child task initialization.
+    # @param child [Task]
+    # @api private
+    def register_child(child)
+      @mutex.synchronize { @children << child }
+    end
+  end
+end