phronomy 0.17.0 → 0.19.0

data/lib/phronomy/engine/task/fiber_backend.rb

@@ -1,157 +0,0 @@
-# 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 wait_result
-        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/engine/task/immediate_backend.rb

@@ -1,89 +0,0 @@
-# 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 wait_result
-        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/engine/task/mapped_backend.rb

@@ -1,90 +0,0 @@
-# frozen_string_literal: true
-
-require "timeout"
-
-module Phronomy
-  class Task
-    # Backend for Tasks created by {Task#map}.
-    #
-    # A mapped task's lifecycle is driven entirely by the +on_complete+
-    # callback of its source task — it never spawns a thread of its own.
-    # +MappedBackend+ transitions the owning task to +:running+ immediately
-    # on initialization so that +FSMSession+ treats it as an in-progress
-    # async action.  Completion (or failure) is triggered externally via
-    # {Task#transition!} from the +on_complete+ callback registered by
-    # {Task#map}.
-    #
-    # +await+ and +join+ block until {#unblock} is called, which {Task#map}
-    # arranges by registering a second +on_complete+ callback on the *mapped*
-    # task itself after the transform callback has been registered.
-    #
-    # @api private
-    class MappedBackend < Backend
-      def initialize(task:, &)
-        super
-        @done_queue = Queue.new
-        task.transition!(:running)
-      end
-
-      # Unblocks +await+ / +join+.  Called by {Task#map} after the mapped task
-      # reaches a terminal state.
-      # @api private
-      def unblock(value, error)
-        @done_queue.push([value, error])
-      end
-
-      # Blocks until the mapped task reaches a terminal state.
-      # @return [Object] the mapped value
-      # @raise [Exception] if the source task or the map block raised an error
-      # @api private
-      def wait_result
-        scheduler = Thread.current.thread_variable_get(Task::SCHEDULER_KEY)
-        in_managed_fiber = !Fiber.respond_to?(:main) || Fiber.current != Fiber.main
-        if scheduler && in_managed_fiber && !@task.done?
-          scheduler.track_blocking_await
-          waiting_fiber = Fiber.current
-          @task.on_complete do |_value, _error|
-            scheduler.complete_blocking_await
-            scheduler.enqueue_fiber(-> { waiting_fiber.resume })
-          end
-          Fiber.yield(:cooperative_suspend)
-        end
-
-        value, error = @done_queue.pop
-        raise error if error
-
-        value
-      end
-
-      # Returns +false+ — a mapped task has no independent thread to kill.
-      # @return [Boolean]
-      # @api private
-      def alive?
-        false
-      end
-
-      # No-op — mapped tasks carry no independent thread to cancel.
-      # @return [self]
-      # @api private
-      def cancel!
-        self
-      end
-
-      # Blocks until the mapped task completes, with an optional timeout.
-      # @param limit [Numeric, nil]
-      # @return [Object, nil] +nil+ on timeout
-      # @api private
-      def join(limit = nil)
-        if limit.nil?
-          wait_result
-        else
-          begin
-            Timeout.timeout(limit) { wait_result }
-          rescue Timeout::Error
-            nil
-          end
-        end
-      end
-    end
-  end
-end

data/lib/phronomy/engine/task/thread_backend.rb

@@ -1,84 +0,0 @@
-# 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 wait_result
-        @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/engine/task_group.rb

@@ -1,193 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  # Manages a bounded set of concurrent {Task}s with structured concurrency.
-  class TaskGroup
-    FAILURE_POLICIES = %i[fail_fast collect_all skip_failed].freeze
-
-    # @param limit [Integer, Float::INFINITY]
-    # @param failure_policy [Symbol]
-    # @param runtime [Runtime] runtime authority used to spawn every child Task
-    # @api private
-    def initialize(runtime:, limit: Float::INFINITY, failure_policy: :fail_fast)
-      unless FAILURE_POLICIES.include?(failure_policy)
-        raise ArgumentError, "unknown failure_policy: #{failure_policy}"
-      end
-      unless runtime
-        raise ArgumentError, "runtime is required"
-      end
-
-      @limit = limit
-      @failure_policy = failure_policy
-      @runtime = runtime
-      @tasks = []
-      @mutex = Mutex.new
-      @cond = ConditionVariable.new
-      @active = 0
-    end
-
-    # @api private
-    def spawn(&block)
-      wait_for_slot!
-
-      task = @runtime.spawn(name: "task-group-worker") do
-        block.call
-      ensure
-        release_slot!
-      end
-
-      @mutex.synchronize { @tasks << task }
-      task
-    end
-
-    # @api private
-    def await_all
-      tasks = @mutex.synchronize { @tasks.dup }
-      return [] if tasks.empty?
-
-      if Phronomy::Runtime::Scheduler.current
-        _await_all_cooperative(tasks)
-      else
-        _await_all_threaded(tasks)
-      end
-    end
-
-    private
-
-    def _await_all_cooperative(tasks)
-      completion_q = Phronomy::Concurrency::AsyncQueue.new
-      tasks.each_with_index do |task, idx|
-        task.on_complete do |value, error|
-          completion_q.push({index: idx, value: value, error: error})
-        end
-      end
-
-      entries = Array.new(tasks.length)
-      cancelled = false
-      fail_fast_error = nil
-
-      tasks.length.times do
-        entry = completion_q.pop
-        entries[entry[:index]] = entry
-
-        if entry[:error] && @failure_policy == :fail_fast && !cancelled
-          cancelled = true
-          fail_fast_error = entry[:error]
-          tasks.each { |task| task.cancel! unless task.done? }
-        end
-      end
-
-      case @failure_policy
-      when :fail_fast
-        raise fail_fast_error if fail_fast_error
-        entries.map { |entry| entry[:value] }
-      when :skip_failed
-        entries.filter_map { |entry| entry[:value] unless entry[:error] }
-      else
-        errors = entries.filter_map { |entry| entry[:error] }
-        raise errors.first if errors.any?
-        entries.map { |entry| entry[:value] }
-      end
-    end
-
-    def _await_all_threaded(tasks)
-      completion_q = Queue.new
-      tasks.each_with_index do |task, idx|
-        task.on_complete do |value, error|
-          completion_q.push({index: idx, value: value, error: error})
-        end
-      end
-
-      entries = Array.new(tasks.length)
-      cancelled = false
-      fail_fast_error = nil
-
-      tasks.length.times do
-        entry = completion_q.pop
-        entries[entry[:index]] = entry
-
-        if entry[:error] && @failure_policy == :fail_fast && !cancelled
-          cancelled = true
-          fail_fast_error = entry[:error]
-          tasks.each { |task| task.cancel! unless task.done? }
-        end
-      end
-
-      case @failure_policy
-      when :fail_fast
-        raise fail_fast_error if fail_fast_error
-        entries.map { |entry| entry[:value] }
-      when :skip_failed
-        entries.filter_map { |entry| entry[:value] unless entry[:error] }
-      else
-        errors = entries.filter_map { |entry| entry[:error] }
-        raise errors.first if errors.any?
-        entries.map { |entry| entry[:value] }
-      end
-    end
-
-    public
-
-    # @api private
-    def cancel_all!
-      tasks = @mutex.synchronize { @tasks.dup }
-      tasks.each(&:cancel!)
-      tasks.each do |task|
-        task.join
-      rescue
-        nil
-      end
-
-      scheduler = Phronomy::Runtime::Scheduler.current
-      if scheduler && @coop_signal
-        @active = 0
-        scheduler.raise_signal_all(@coop_signal)
-      else
-        @mutex.synchronize do
-          @active = 0
-          @cond.broadcast
-        end
-      end
-      self
-    end
-
-    # @api private
-    def active_task_count
-      @mutex.synchronize { @active }
-    end
-
-    private
-
-    def wait_for_slot!
-      scheduler = Phronomy::Runtime::Scheduler.current
-      if scheduler
-        @coop_signal ||= scheduler.new_signal
-        loop do
-          if @active < @limit
-            @active += 1
-            return
-          end
-          scheduler.wait_for_signal(@coop_signal)
-        end
-      else
-        @mutex.synchronize do
-          @cond.wait(@mutex) while @active >= @limit
-          @active += 1
-        end
-      end
-    end
-
-    def release_slot!
-      scheduler = Phronomy::Runtime::Scheduler.current
-      if scheduler && @coop_signal
-        @active -= 1
-        scheduler.raise_signal(@coop_signal)
-      else
-        @mutex.synchronize do
-          @active -= 1
-          @cond.signal
-        end
-      end
-    end
-  end
-end

data/lib/phronomy/eval/comparison.rb

@@ -1,47 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Eval
-    # Runs the same Dataset against two callables (configuration A and B) and
-    # packages the paired results for side-by-side comparison.
-    #
-    # @example
-    #   cmp     = Comparison.new(scorer: Scorer::ExactMatch.new)
-    #   pairs   = cmp.compare(dataset, callable_a, callable_b)
-    #   pairs.each do |pair|
-    #     puts "A=#{pair.result_a.score} B=#{pair.result_b.score}"
-    #   end
-    #
-    #   # Aggregate each side independently
-    #   Metrics.new(pairs.map(&:result_a)).to_h
-    class Comparison
-      # Holds the two EvalResults for a single EvalCase.
-      ComparisonPair = Data.define(:eval_case, :result_a, :result_b)
-
-      # @param scorer [Scorer::Base]
-      # @api public
-      def initialize(scorer: Scorer::ExactMatch.new)
-        @scorer = scorer
-      end
-
-      # Evaluates both callables on every case in the dataset.
-      #
-      # @param dataset    [Dataset]
-      # @param callable_a [#call]
-      # @param callable_b [#call]
-      # @return [Array<ComparisonPair>]
-      # @api public
-      def compare(dataset, callable_a, callable_b)
-        runner_a = Runner.new(scorer: @scorer)
-        runner_b = Runner.new(scorer: @scorer)
-
-        results_a = runner_a.run(dataset, callable_a)
-        results_b = runner_b.run(dataset, callable_b)
-
-        results_a.zip(results_b).map do |a, b|
-          ComparisonPair.new(eval_case: a.eval_case, result_a: a, result_b: b)
-        end
-      end
-    end
-  end
-end

data/lib/phronomy/eval/dataset.rb

@@ -1,45 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Eval
-    # An ordered collection of EvalCase objects.
-    #
-    # @example Build from a plain array of hashes
-    #   dataset = Dataset.from_array([
-    #     { input: "What is 2+2?", expected: "4" },
-    #     { input: "Capital of France?", expected: "Paris" }
-    #   ])
-    class Dataset
-      include Enumerable
-
-      # @param cases [Array<EvalCase>]
-      # @api public
-      def initialize(cases = [])
-        @cases = cases.freeze
-      end
-
-      # Constructs a Dataset from an Array of Hash-like objects.
-      # Each hash must have at least +:input+ and +:expected+ keys.
-      # An optional +:metadata+ key is forwarded as-is.
-      #
-      # @param pairs [Array<Hash>]
-      # @return [Dataset]
-      # @api public
-      def self.from_array(pairs)
-        new(pairs.map { |h| EvalCase.new(**h) })
-      end
-
-      # @yield [EvalCase]
-      # @api public
-      def each(&block)
-        @cases.each(&block)
-      end
-
-      # @return [Integer]
-      # @api public
-      def size
-        @cases.size
-      end
-    end
-  end
-end