farce 0.2.0-x86-linux-gnu → 0.4.0-x86-linux-gnu

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/port.rb

@@ -10,11 +10,19 @@ module Farce
       include MarshalSupport::Reject
       include Freeze::Unfreezable
 
-      def initialize = @queue = Thread::Queue.new
-      def closed?    = @queue.closed?
+      def initialize
+        @queue          = Thread::Queue.new
+        @select_mutex   = Mutex.new
+        @select_waiters = []
+      end
+
+      def closed? = @queue.closed?
 
       def close
-        @queue.close
+        @select_mutex.synchronize do
+          @queue.close
+          @select_waiters.each(&:broadcast)
+        end
         self
       end
 
@@ -29,14 +37,44 @@ module Farce
           raise Ractor::Error, "can not move #{value.class} object" unless value.is_a?(Unshareable::Movable)
         end
         @queue.push(value)
+        notify_selectors
         self
       rescue ::ClosedQueueError
         raise Ractor::ClosedError, "The port was already closed"
       end
 
+      # @api private
+      def register_selector(waiter)
+        @select_mutex.synchronize { @select_waiters << waiter }
+      end
+
+      # @api private
+      def unregister_selector(waiter)
+        @select_mutex.synchronize { @select_waiters.delete(waiter) }
+      end
+
+      # @api private
+      def select_receive
+        @select_mutex.synchronize do
+          raise Ractor::ClosedError, "The port was already closed" if closed?
+          begin
+            value = @queue.pop(true)
+          rescue ThreadError
+            return
+          end
+          [self, value]
+        end
+      end
+
       alias << send
 
       def inspect = "#<#{self.class.name} to:#1 id:#{object_id}>"
+
+      private
+
+      def notify_selectors
+        @select_mutex.synchronize { @select_waiters.each(&:broadcast) }
+      end
     end
 
     BasePort = Port

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/queue.rb

@@ -12,10 +12,10 @@ module Farce
       attr_reader :capacity
 
       def initialize(capacity: 1024, track_age: false)
-        @queue    = capacity ? Thread::SizedQueue.new(capacity) : Thread::Queue.new
-        @capacity = capacity
-        @signal   = Signal.new
-        @tracking = track_age ? { lock: Mutex.new, timestamps: [], generation: 0 } : nil
+        @queue     = capacity ? Thread::SizedQueue.new(capacity) : Thread::Queue.new
+        @capacity  = capacity
+        @signal    = Signal.new
+        @tracking  = track_age ? { lock: Mutex.new, timestamps: [], generation: 0 } : nil
         @lifecycle = { lock: Mutex.new, hard_closed: false }
         Freeze.publish(self)
       end

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

@@ -63,8 +63,8 @@ module Farce
         with_storage(name) { _1[_2] = value }
       end
 
-      def select(...)
-        raise "TODO: not implemented"
+      def select(*sources, timeout: nil)
+        RactorSelector.new.select(*sources, timeout:)
       end
 
       alias recv receive

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

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # @!visibility private
+  module Internal # :nodoc: all
+    # Wait for shim port readiness without consuming messages from losing ports.
+    class RactorSelector
+      def select(*sources, timeout: nil)
+        raise ArgumentError, "specify at least one Ractor::Port or Ractor" if sources.empty?
+        sources.each do |source|
+          next if source.is_a?(Ractor) || source.is_a?(Port)
+          raise ArgumentError, "should be Ractor::Port or Ractor"
+        end
+
+        timeout  = duration(timeout)
+        deadline = Clock.now + timeout if timeout
+        monitors = {}.compare_by_identity
+        ports    = sources.uniq.map do |source|
+          next source unless source.is_a?(Ractor)
+
+          port           = BasePort.new
+          monitors[port] = source
+          source.monitor(port)
+          port
+        end
+
+        result = wait(ports, deadline)
+        return unless result
+
+        port, value = result
+        ractor      = monitors[port]
+        ractor ? [ractor, ractor.value] : [port, value]
+      ensure
+        monitors&.each do |port, ractor|
+          ractor.unmonitor(port)
+          port.close
+        end
+      end
+
+      private
+
+      def duration(value)
+        return if value.nil?
+        raise TypeError, "cannot convert String into time interval" if value.is_a?(String)
+        value = Float(value)
+        raise RangeError, "timeout out of range" unless value.finite?
+        raise ArgumentError, "time interval must not be negative" if value.negative?
+        value
+      end
+
+      def wait(ports, deadline)
+        wakeup = Signal.new
+        ports.each { it.register_selector(wakeup) }
+        while true
+          # Observe before checking readiness so a send during that check
+          # changes the generation and prevents the following wait from parking.
+          generation = wakeup.generation
+          ports.each do |port|
+            result = port.select_receive
+            return result if result
+          end
+          remaining = deadline - Clock.now if deadline
+          return if remaining && !remaining.positive?
+          return unless ReservationWaiting.wait(wakeup, generation, deadline)
+        end
+      ensure
+        ports.each { it.unregister_selector(wakeup) }
+      end
+    end
+  end
+end

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/extension.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # Defines a reusable extension for adding methods to target classes.
+  # These methods can either be activated as refinements, or installed globally to extend the target classes.
+  #
+  # ```ruby
+  # DoubleSize = Farce::Extension.define(String) do
+  #   def double_size = size * 2
+  # end
+  #
+  # module Namespace
+  #   using DoubleSize
+  #   "hello".double_size # => 10
+  # end
+  #
+  # "hello".respond_to?(:double_size) # => false
+  #
+  # DoubleSize.install
+  # "hello".respond_to?(:double_size) # => true
+  # ```
+  #
+  # ## Extending multiple classes
+  #
+  # An extension can also modify multiple target classes simultaneously:
+  #
+  # ```ruby
+  # DoubleSize = Farce::Extension.new do
+  #   define(String) { def double_size = size * 2 }
+  #   define(Array) { def double_size = sum(&:double_size) }
+  # end
+  #
+  # using DoubleSize
+  # ["hello", "foo"].double_size # => 16
+  # ```
+  class Extension < Module
+    # @api private
+    class Mixin < Module # :nodoc:
+      attr_reader :extension, :target
+
+      def initialize(extension, target, &)
+        @extension = extension
+        @target    = target
+        super(&)
+      end
+
+      def name = -"#{@extension.name}[#{@target.inspect}]"
+
+      def install
+        return if @target.ancestors.include?(self)
+        @target.prepend(self)
+      end
+    end
+    private_constant :Mixin
+
+    # @overload define(*targets)
+    #   Defines an extension for the given target classes.
+    #   @param targets [Array<Class>] the target classes to define methods for
+    #   @yield the block containing method definitions
+    #   @yieldreceiver [Module, Refinement] the module/refinement used for extending the target class.
+    #   @return [Extension] the newly created extension instance
+    #   @see Extension#define
+    def self.define(...) = new { define(...) }
+
+    # Creates a new extension.
+    # @yield Optional block for `define` calls or adding methods to the extension itself.
+    # @yieldreceiver [Extension] the extension instance itself.
+    def initialize
+      check_state!
+      @definitions = Internal::StrictMap.new
+      @lock        = Lock.new
+      @installed   = Flag.new
+      super
+    end
+
+    # @api private
+    def [](target) = @definitions[target]
+
+    # Defines additional methods for a given target class.
+    #
+    # The given block will be invoked at least twice. Once in the context of a refinement for the target class,
+    # and once in the context of the mixin module that will be prepended to the target class.
+    #
+    # @example
+    #   extension = Farce::Extension.new
+    #   extension.define(String) { def double_size = size * 2 }
+    #
+    #   module Namespace
+    #     using extension
+    #     String.method_defined?(:double_size) # => true
+    #   end
+    #
+    #   String.method_defined?(:double_size) # => false
+    #   extension.install
+    #   String.method_defined?(:double_size) # => true
+    #
+    # @param targets [Array<Class>] the target classes to define methods for
+    # @yield the block containing method definitions
+    # @yieldreceiver [Module, Refinement] the module/refinement used for extending the target class.
+    # @return [self] the extension instance
+    def define(*targets, &)
+      @lock.synchronize do
+        check_state!
+        targets.each do |target|
+          refine(target, &)
+          mixin = @definitions.store_if_absent(target) { Mixin.new(self, target) }
+          mixin.module_eval(&)
+          mixin.install if installed?
+        end
+      end
+      self
+    end
+
+    # Installs the extension globally.
+    # @return [void]
+    def install
+      @lock.synchronize do
+        return false if installed?
+        check_state!(allow_frozen: true)
+        @definitions.each_value(&:install)
+        yield if block_given?
+        @installed.set
+      end
+    end
+
+    # @return [Boolean] whether the extension has been installed
+    def installed? = @installed.set?
+
+    # Freezes the extension.
+    #
+    # No {#define definitions} can be added after freezing the extension.
+    # @return [self] the frozen extension
+    def freeze
+      return self if frozen?
+      @lock.synchronize do
+        @definitions.freeze
+        super
+      end
+    end
+
+    private
+
+    def check_state!(allow_frozen: false)
+      raise Ractor::IsolationError, "must be called from main Ractor" if Internal.native_ractors? && !Ractor.main?
+      Internal::Freeze.check(self) unless allow_frozen
+    end
+  end
+end

data/lib/farce/integrations/ractor_tmvar.rb

@@ -13,7 +13,10 @@ module Farce
     # Take, put, and swap operate on the value staged in this attempt.
     # An empty read, take, or swap, or a put into a full TMVar fails the
     # attempt. Farce.transaction retries these conditions within its retry limit.
-    # The try_* methods return nil or false without failing the attempt.
+    # The try_* methods return nil or false when unavailable without failing
+    # the attempt. Blocks passed to try_read and try_take run only when full,
+    # including for stored nil, and return the block's result.
+    # Create an empty TMVar with Ractor::TMVar.new and a full nil with .new(nil).
     # Assigned values are made shareable, matching Ractor::TVar's setter.
     #
     # Run outside Ractor.atomically, as required by {RactorTVar}.

data/lib/farce/internal/fake_ractor.rb

@@ -21,6 +21,7 @@ module Farce
         INSTANCE     = Freeze.publish(new)
         DEFAULT_PORT = BasePort.new
 
+        def alive?       = true
         def default_port = DEFAULT_PORT
         def inspect      = "#<Farce::Ractor#1 running>"
         def join         = sleep
@@ -78,7 +79,7 @@ module Farce
           ensure
             state.mutex.synchronize do
               state.monitors.each do |monitor|
-                monitor << state.status
+                FakeRactor.send_status(monitor, self, state.status)
               end
               state.monitors = nil
             end
@@ -97,6 +98,8 @@ module Farce
           Farce::Ractor[key] = value
         end
 
+        def alive? = STATES[self].status == :running
+
         def monitor(port) # rubocop:disable Naming/PredicateMethod
           state = STATES[self]
 
@@ -108,7 +111,7 @@ module Farce
             end
           end
 
-          port << state.status
+          FakeRactor.send_status(port, self, state.status)
           false
         end
 
@@ -148,6 +151,11 @@ module Farce
         undef clone
       end
 
+      def self.send_status(port, ractor, status)
+        payload = System.ruby_version >= "4.1" ? [ractor, status].freeze : status
+        port << payload
+      end
+
       def self.current
         # JRuby fibers expose a backing thread with a different thread group.
         thread   = Internal.storage_thread(Thread.current)

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/scheduler_lifecycle.rb

@@ -82,15 +82,13 @@ module Farce
 
       def unblock(_blocker, fiber) # rubocop:disable Naming/PredicateMethod
         return false if @closed || !(token = current_wait(fiber))
-        @mailbox << Completion.new(token, true, nil).freeze
-        wakeup
+        complete_wait(token, true)
         true
       end
 
       def fiber_interrupt(fiber, exception) # rubocop:disable Naming/PredicateMethod
         return false if @closed || !(token = current_wait(fiber))
-        @mailbox << Completion.new(token, nil, exception).freeze
-        wakeup
+        complete_wait(token, nil, exception)
         true
       end
 
@@ -202,6 +200,11 @@ module Farce
 
       private
 
+      def complete_wait(token, value, error = nil)
+        @mailbox << Completion.new(token, value, error).freeze
+        wakeup
+      end
+
       def finish_close
         return if @closed
         shutdown

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|