farce 0.2.0 → 0.3.0

data/lib/farce/engine/shared/main_scheduler.rb

@@ -4,13 +4,13 @@
 
 module Farce
   module Internal # :nodoc: all
-    class MainThreadScheduler < ThreadScheduler
+    class MainThreadExecutor < ThreadExecutor
       # Enter the main emulated Ractor without starting another thread.
       def execute(...) = FakeRactor.with_current(Ractor.main) { super }
       def local?(wait: true) = Ractor.main? # rubocop:disable Lint/UnusedMethodArgument
     end
 
-    MainScheduler = MainThreadScheduler.new do |*args, &block|
+    MainScheduler = MainThreadExecutor.new do |*args, &block|
       Thread.new do
         ThreadGroup::Default.add(Thread.current)
         block.call(*args)

data/lib/farce/engine/shared/parallel_scheduler.rb

@@ -4,6 +4,6 @@
 
 module Farce
   module Internal # :nodoc: all
-    ParallelScheduler = ThreadScheduler.new(&Ractor.method(:new))
+    ParallelScheduler = ThreadExecutor.new(&Ractor.method(:new))
   end
 end

data/lib/farce/engine/shared/proxy_owner.rb

@@ -7,7 +7,7 @@ module Farce
     class ProxyOwner
       include ProxyOwnerNotifications
 
-      class OwnerScheduler < Farce::ThreadScheduler
+      class OwnerScheduler < Farce::ThreadExecutor
         def initialize
           @threads = Thread::Queue.new
           super

data/lib/farce/engine/shared/unshared_atom.rb

@@ -17,7 +17,7 @@ module Farce
         @value               = value
         @compare_by_identity = compare_by_identity
         @mutex               = Mutex.new
-        @signal              = ConditionVariable.new
+        @signal              = Signal.new
         @updating            = false
         @updating_fiber      = nil
         @updating_thread     = nil
@@ -224,13 +224,14 @@ module Farce
       end
 
       def wait_for_signal(deadline)
-        return @signal.wait(@mutex) unless deadline
-
-        remaining = deadline - Clock.now
-        return false unless remaining.positive?
-
-        @signal.wait(@mutex, remaining)
-        true
+        # Snapshot while holding the state lock so a change during registration is not missed.
+        generation = @signal.generation
+        begin
+          @mutex.unlock
+          ReservationWaiting.wait(@signal, generation, deadline)
+        ensure
+          @mutex.lock unless @mutex.owned?
+        end
       end
 
       def reject_update_wait!

data/lib/farce/engine/shared.rb

@@ -13,6 +13,15 @@ module Farce
   module Internal # :nodoc: all
     include Autoloads["#{__dir__}/shared"]
 
+    # Keep thread-only scheduler workers and their tasks in their emulated Ractor.
+    def with_scheduler_thread_group
+      group = ThreadGroup.new
+      FakeRactor::GROUPS[group] = Ractor.current
+      yield group
+    ensure
+      FakeRactor::GROUPS.delete(group)
+    end
+
     # @api private
     # The shim's shareable? can delegate to a lazy or weak value and change its state.
     # Snapshot metadata uses only structural properties on engines without Ractors.

data/lib/farce/internal/lease_initialization.rb

@@ -5,7 +5,7 @@
 module Farce
   # @!visibility private
   module Internal # :nodoc: all
-    # Coordinates lazy Lease construction without running user code under a storage lock.
+    # Coordinates lazy construction without running user code under a storage lock.
     class LeaseInitialization
       def initialize
         @mutex        = Mutex.new

data/lib/farce/internal/local_executor_methods.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Internal # :nodoc: all
+    # The local scheduling and execution interface for Ractor-local executors.
+    module LocalExecutorMethods
+      LOCAL_MODES = %i[local smart smart_raise smart_move smart_copy].freeze
+      private_constant :LOCAL_MODES
+
+      # @param wait [Boolean] Accepted for compatibility with {Abstract::Executor#local?}.
+      # @return [true] Workers run in the calling Ractor.
+      def local?(wait: true) = true # rubocop:disable Lint/UnusedMethodArgument
+
+      # Run a task directly, preserving its block, arguments, and calling fiber.
+      # `mode` and `auto_local` follow the same validation as {#schedule}.
+      # @param (see Abstract::Executor#execute)
+      # @return [self]
+      def execute(*, mode: :smart, auto_local: true, &)
+        validate_local_mode(mode, auto_local)
+        super(*, mode: :local, auto_local: true, &)
+      end
+
+      private
+
+      def validate_local_mode(mode, auto_local)
+        return if auto_local || LOCAL_MODES.include?(mode)
+        raise ArgumentError, "only local or smart modes are supported"
+      end
+    end
+  end
+end

data/lib/farce/internal/local_scheduled_task.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Internal # :nodoc: all
+    # A Ractor-local task that retains its block and argument references.
+    class LocalScheduledTask
+      include Noncopyable
+      include Farce::Unshareable
+
+      def initialize(args, block)
+        @args  = args
+        @block = block
+        super()
+      end
+
+      def to_proc(completion = nil)
+        lambda do
+          @block.call(*@args)
+        ensure
+          completion&.task_finished
+        end
+      end
+    end
+  end
+end

data/lib/farce/internal/scheduled_task.rb

@@ -12,7 +12,7 @@ module Farce
       MANAGER = ModeManager.new
 
       def initialize(args, block, mode)
-        @block  = Ractor.shareable_proc(&block)
+        @block  = Ractor.shareable?(block) ? block : Ractor.shareable_proc(&block)
         @unwrap = false
         @args   = args.map! do |arg|
           wrapped = MANAGER.wrap(arg, mode:)

data/lib/farce/internal/thread_pool_supervisor.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Internal # :nodoc: all
+    # A Ractor-local service for delayed pool growth and executor shutdown requests.
+    class ThreadPoolSupervisor
+      include Farce::Unshareable
+
+      def self.current = Storage.store_if_absent(self) { new }
+
+      def initialize
+        @queue  = TimerQueue.new(mode: :raise)
+        @closed = Atom.new(false)
+        @worker = Thread.new do
+          loop do
+            entry = @queue.pop
+            break if entry == :stop
+            pool, token = entry
+            pool = pool.value
+            token == :close ? pool.close : pool.scale_if_needed(token)
+          end
+        end
+        super
+      end
+
+      def close_handle(pool) = [@queue, Envelope::Local.new(pool)].freeze
+
+      def schedule(pool, token, delay)
+        raise ::Farce::ClosedQueueError, "pool supervisor is closed" if @closed.value
+        @queue.push([Envelope::Local.new(pool), token].freeze, delay:)
+      end
+
+      def close
+        return unless @closed.compare_and_set(false, true)
+        @queue.push(:stop, clock: 0)
+        @worker.join
+        @queue.close
+      end
+    end
+
+    at_exit { Storage[ThreadPoolSupervisor]&.close }
+  end
+end

data/lib/farce/internal/unshared_pool_worker.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Internal # :nodoc: all
+    # A worker coordinator pinned to its pool's Ractor.
+    class UnsharedPoolWorker < PoolWorker
+      include Farce::Unshareable
+
+      private def publish_shareable = pin_unshareable
+    end
+  end
+end

data/lib/farce/internal.rb

@@ -54,6 +54,19 @@ module Farce
       new_self
     end
 
+    # @api private
+    # @return [Abstract::Executor, Fiber::Scheduler, nil]
+    def local_scheduler(create: false)
+      if Fiber.respond_to?(:scheduler) && fiber_scheduler = Fiber.scheduler
+        return fiber_scheduler
+      end
+      return Internal::MainScheduler if Ractor.main?
+      return Internal::Storage[:local_scheduler] unless create
+      Internal::Storage.store_if_absent(:local_scheduler) do
+        Internal.native_ractors? ? Scheduler.create(Thread) : ThreadExecutor.new
+      end
+    end
+
     def timeout_deadline(timeout)
       return if timeout.nil?
 
@@ -101,6 +114,7 @@ module Farce
     def prepare_mutable_numeric(_)        = nil
     def prepare_map_access(_klass, _kind) = nil
     def finalize_engine                   = nil
+    def with_scheduler_thread_group       = yield(ThreadGroup.new)
 
     def delegate(from, to, *methods)
       methods.each do |method|

data/lib/farce/local/pool.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Local
+    # A shareable handle with an independent thread pool in each scope.
+    #
+    # Each pool uses the scaling settings and fiber scheduler configured at
+    # construction. Tasks always keep their block and argument references. Only
+    # local and smart modes are accepted when `auto_local` is false. A scheduler
+    # constructor must be convertible to a shareable proc for use in each Ractor.
+    # {#close} drains only the current scope's pool. {#close_all} drains every pool
+    # across all scopes and Ractors, and prevents new pools from starting.
+    #
+    # @example Keep task state within each Ractor
+    #   pool    = Farce::Local::Pool.new(max_size: 2)
+    #   results = Farce::Unshared::Queue.new
+    #   pool.schedule { results.push(:done) }
+    #   results.pop # => :done
+    #   pool.close_all
+    class Pool < Abstract::Pool
+      include Shareable::Unfreezable
+      include Scoped
+      include Internal::LocalExecutorMethods
+
+      # (see Farce::Abstract::Pool#initialize)
+      # @!macro scopes
+      # @param scope [Symbol] The scope of the pool. Defaults to `:ractor`.
+      def initialize(min_size: 0, max_size: 4, max_inflight: 64,
+                     grow_after: 0.005, shrink_after: 30, capacity: 1024, scope: :ractor,
+                     backend: Internal::FROZEN_CONFIG.io_backend, &constructor)
+        initialize_configuration(min_size:, max_size:, max_inflight:, grow_after:, shrink_after:, backend:)
+        @constructor = prepare_constructor(constructor || Internal::FROZEN_CONFIG.fiber_scheduler_constructor)
+        @pools       = Strict::Map.new
+        @closed_all  = Internal::Flag.new(false)
+        @initialization_key = Object.new.freeze
+        super(scope:, min_size: @min_size, max_size: @max_size, max_inflight: @max_inflight,
+              grow_after: @grow_after, shrink_after: @shrink_after, capacity:, backend:)
+      end
+
+      # Stop accepting work in this scope and drain its queued tasks.
+      # @return [self]
+      def close
+        pool = @closed_all.value ? Internal::Storage[self, scope:] : scoped_value
+        pool&.close
+        self
+      end
+
+      # Stop accepting work in every scope and Ractor and request draining.
+      # Future scopes also reject submissions. Does not wait for running tasks.
+      # @return [self]
+      def close_all
+        return self unless @closed_all.compare_and_set(false, true)
+        @pools.each_pair do |pool, queue|
+          queue.push([pool, :close].freeze, clock: 0)
+        rescue ClosedQueueError
+          # The owning Ractor may already have shut down its supervisor.
+          nil
+        end
+        close
+      end
+
+      # @return [Integer] Running and starting workers in this scope.
+      def size = current_pool&.size || 0
+
+      # @return [Symbol] The current scope's pool state.
+      def state = current_pool&.state || :closed
+
+      # @return [Exception, nil] The first worker error in this scope.
+      def error = current_pool&.error
+
+      # @return [Boolean] Whether this scope rejects new tasks.
+      def closed? = @closed_all.value || super
+
+      Internal.delegate(self, :scoped_value, :drained?, :admission_generation, :wait_for_admission,
+        :admission_changed, :task_taken, :retire_worker, :worker_stopped, :scale_if_needed)
+
+      private
+
+      def enqueue_task(non_block, ...)
+        raise PoolClosedError, "cannot schedule task on a closed pool" if @closed_all.value
+        pool = scoped_value
+        submitted = non_block ? pool.try_schedule(...) : pool.schedule(...)
+        submitted && self
+      end
+
+      def current_pool
+        @closed_all.value ? Internal::Storage[self, scope:] : scoped_value
+      end
+
+      # Worker setup can yield. Initialize once when fibers share a scope.
+      def scoped_value
+        storage = Internal::Storage.scope(scope)
+        pool    = storage[self]
+        return pool if pool
+
+        initializers = Internal::Storage.store_if_absent(@initialization_key) { Internal::Storage::ThreadSafe.new }
+        initializers.store_if_absent(storage) { Internal::LeaseInitialization.new }.fetch { super }
+      end
+
+      def new_scoped_value(**)
+        pool              = Unshared::Pool.new(**, &@constructor)
+        queue, reference  = Internal::ThreadPoolSupervisor.current.close_handle(pool)
+        @pools[reference] = queue
+        pool.close if @closed_all.value
+        pool
+      end
+    end
+  end
+end

data/lib/farce/local/scheduler.rb

@@ -0,0 +1,219 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Local
+    # A shareable handle with an independent task scheduler in each scope.
+    #
+    # {.new} leaves each scheduler unstarted. Launch it with {#launch_thread}, or
+    # install it with `Fiber.set_scheduler`. {.create} starts a worker thread in
+    # each scope when that scope is first used. The default scope is `:ractor`.
+    #
+    # Tasks retain their blocks and argument references. {#execute} runs directly
+    # in the calling fiber. A fiber scheduler
+    # constructor must be convertible to a shareable proc for use in each Ractor.
+    # {#close} closes the current scope. {#close_all} closes all scopes and prevents
+    # new schedulers from starting. {.current} returns an {Unshared::Scheduler}.
+    #
+    # @example Start one worker in each Ractor
+    #   scheduler = Farce::Local::Scheduler.create
+    #   results = Farce::Unshared::Queue.new
+    #   scheduler.schedule { results.push(:done) }
+    #   results.pop # => :done
+    #   scheduler.close_all
+    class Scheduler < Abstract::Scheduler
+      include Shareable::Unfreezable
+      include Scoped
+      include Internal::LocalExecutorMethods
+
+      # Returns the current thread's unshared scheduler, or nil when none is installed.
+      # @param (see Abstract::Scheduler.current)
+      # @return [Unshared::Scheduler, nil]
+      def self.current(**) = Unshared::Scheduler.current(**)
+
+      # Starts a worker in this scope and retains the launch settings for other scopes.
+      # Additional options and the block are forwarded to {#initialize}.
+      # @param executor [Class, nil] Thread or a custom executor that stays in each Ractor.
+      # @param name [String, nil] Optional worker name.
+      # @param priority [Integer, nil] Optional worker thread priority.
+      # @yieldreturn [Object] Fiber scheduler to install in each worker.
+      # @return [Scheduler]
+      def self.create(executor = Thread, name: nil, priority: nil, **, &)
+        raise ArgumentError, "Local schedulers cannot launch Ractor workers" if executor && executor <= Ractor
+        worker = [executor || Thread, name && -String(name), priority && Integer(priority)].freeze
+        new(**, worker:, &)
+      end
+
+      # Creates a handle whose scoped schedulers remain unstarted.
+      # The constructor block builds the fiber scheduler when a scope is launched or installed.
+      # @!macro scopes
+      # @overload initialize(capacity: 1024, backend: Farce.config.io_backend, scope: :ractor, &constructor)
+      #   @param capacity [Integer, nil] Pending-task capacity, or nil for an unbounded queue in each scope.
+      #   @param backend [Symbol] IO backend for the built-in scheduler.
+      #   @param scope [Symbol] The scheduler scope. Defaults to :ractor.
+      #   @yieldreturn [Object] Fiber scheduler to install in each scope.
+      def initialize(capacity: 1024, backend: Internal::FROZEN_CONFIG.io_backend, scope: :ractor,
+                     worker: nil, &constructor)
+        @constructor        = prepare_constructor(constructor || Internal::FROZEN_CONFIG.fiber_scheduler_constructor)
+        @backend            = backend
+        @worker             = worker
+        @schedulers         = Strict::Map.new
+        @closed_all         = Internal::Flag.new(false)
+        @initialization_key = Object.new.freeze
+        @registration_key   = Object.new.freeze
+        super(scope:, capacity: capacity && Integer(capacity), backend:)
+      end
+
+      # Enqueue a task in the current scope, preserving its block and arguments.
+      # `mode` is ignored when `auto_local` is true. Otherwise, only local and smart modes are accepted.
+      # @overload schedule(*args, mode: :smart, auto_local: true)
+      #   @param (see Farce::Abstract::Executor#schedule)
+      #   @return [self]
+      def schedule(...) = enqueue_task(false, ...)
+
+      # (see Abstract::Scheduler#try_schedule)
+      def try_schedule(...) = enqueue_task(true, ...)
+
+      # Starts a worker for the current scope. Other scopes retain their creation behavior.
+      # @param executor [Class, nil] Thread or a custom executor that stays in this Ractor.
+      # @param name [String, nil] Optional worker name.
+      # @param priority [Integer, nil] Optional worker thread priority.
+      # @return [Thread, Object] The worker.
+      # @raise [ArgumentError] If a Ractor executor is supplied.
+      def launch(executor = Thread, name: nil, priority: nil)
+        raise ArgumentError, "Local schedulers cannot launch Ractor workers" if executor && executor <= Ractor
+        raise "Scheduler may not be reused" if @closed_all.value
+        active_scoped_value.launch(executor, name:, priority:)
+      end
+
+      # Closes the current scope and rejects new submissions there.
+      # @return [self]
+      def close
+        current_scheduler&.close
+        self
+      end
+
+      # Requests shutdown in every scope and Ractor and rejects future scopes.
+      # Does not wait for queued or running tasks to finish.
+      # @return [self]
+      def close_all
+        return self unless @closed_all.compare_and_set(false, true)
+        @schedulers.each_pair do |scheduler, queue|
+          queue.push([scheduler, :close].freeze, clock: 0)
+        rescue ClosedQueueError
+          # The owning Ractor may already have shut down its supervisor.
+          nil
+        end
+        close
+      end
+
+      # @return [Symbol] The current scope's scheduler state.
+      def state = current_scheduler&.state || :closed
+
+      # @return [Exception, nil] The current scope's scheduler error.
+      def error = current_scheduler&.error
+
+      # @return [Boolean] Whether the current scope rejects new tasks.
+      def closed? = @closed_all.value || scoped_value.closed?
+
+      # @return [Boolean] Whether the current scope is dispatching tasks.
+      def alive? = current_scheduler&.alive? || false
+
+      # @return [Ractor] The current scope's owning Ractor.
+      def owner = Ractor.current
+
+      # @param value [Ractor] The current Ractor.
+      # @raise [ArgumentError] If another owner is supplied.
+      def owner=(value)
+        raise ArgumentError, "owner must be the current Ractor" unless value == Ractor.current
+      end
+
+      # @return [Boolean] Whether a fiber scheduler constructor was supplied.
+      def wraps_external? = !@constructor.nil?
+
+      # @return [Object, nil] The fiber scheduler in the current scope, when supplied by a constructor.
+      def external_scheduler = current_scheduler&.external_scheduler
+
+      # @api private
+      def inspect_with(inspector)
+        inspector.object_group(self) do
+          inspector.attribute(:scope, scope)
+          inspector.attribute(:state, state)
+          inspector.attribute(:backend, @backend)
+          yield if block_given?
+        end
+      end
+
+      private
+
+      def enqueue_task(non_block, *, mode: :smart, auto_local: true, &block)
+        raise SchedulerClosedError, "cannot schedule task on a closed scheduler" if @closed_all.value
+        scheduler = scoped_value
+        raise SchedulerClosedError, "cannot schedule task on a closed scheduler" if scheduler.closed?
+        raise LocalJumpError, "Cannot schedule without a block" unless block
+
+        validate_local_mode(mode, auto_local)
+        register_scheduler(scheduler)
+
+        submitted =
+          if non_block
+            scheduler.try_schedule(*, mode:, auto_local:, &block)
+          else
+            scheduler.schedule(*, mode:, auto_local:, &block)
+          end
+
+        submitted && self
+      end
+
+      def current_scheduler
+        return scoped_value unless @closed_all.value
+        scheduler = Internal::Storage[self, scope:]
+        scheduler&.close
+        scheduler
+      end
+
+      # Worker setup can yield. Initialize once when fibers share a scope.
+      def scoped_value
+        storage = Internal::Storage.scope(scope)
+        scheduler = storage[self]
+        return scheduler if scheduler
+
+        initializers = Internal::Storage.store_if_absent(@initialization_key) { Internal::Storage::ThreadSafe.new }
+        initializers.store_if_absent(storage) { Internal::LeaseInitialization.new }.fetch { super }
+      end
+
+      def active_scoped_value
+        scheduler = scoped_value
+        register_scheduler(scheduler)
+        scheduler
+      end
+
+      def register_scheduler(scheduler)
+        registrations = Internal::Storage.store_if_absent(@registration_key) { Internal::Storage::ThreadSafe.new }
+        registrations.store_if_absent(scheduler) do
+          queue, reference = Internal::ThreadPoolSupervisor.current.close_handle(scheduler)
+          @schedulers[reference] = queue
+          true
+        end
+        scheduler.close if @closed_all.value
+      end
+
+      def new_scoped_value(**)
+        scheduler = Unshared::Scheduler.new(**, &@constructor)
+        if @worker && !@closed_all.value
+          register_scheduler(scheduler)
+          executor, name, priority = @worker
+          scheduler.launch(executor, name:, priority:) unless @closed_all.value
+        end
+        scheduler.close if @closed_all.value
+        scheduler
+      end
+
+      def set_scheduler!(...)
+        raise "Scheduler may not be reused" if @closed_all.value
+        active_scoped_value.set_scheduler!(...)
+      end
+    end
+  end
+end