farce 0.3.0-arm-linux-gnu → 0.4.0-arm-linux-gnu

data/lib/farce/backports.rb

@@ -0,0 +1,274 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # Backports for Ractor and related functionality to older Ruby versions.
+  #
+  # ## Activating Backports
+  #
+  # There are three ways of using these backports:
+  # * Activating them globally via: {.install}
+  # * Using them within a specific scope via refinements: `using Farce::Backports`
+  # * Calling methods on `Farce::Backports` directly
+  #
+  # Only the first method will also define the global constants `Ractor` and `Ractor::Port`
+  # if they are not natively available.
+  #
+  # @example Activating the backports globally
+  #   Farce::Backports.install
+  #   port = Ractor.current.default_port
+  #
+  # @example Using the backports within a specific namespace via refinements
+  #   # Within a namespace
+  #   module MyNamespace
+  #     using Farce::Backports
+  #
+  #     def self.send_to(ractor_or_port, message)
+  #       port = ractor_or_port.default_port if ractor_or_port.is_a?(Ractor)
+  #       port.send(message)
+  #     end
+  #   end
+  #
+  # @example Activating the backports for a specific file
+  #   # top level of the file
+  #   using Farce::Backports
+  #
+  #   ractor  = Ractor.new { sleep 10 }
+  #   monitor = Ractor.new { puts "exit status: #{receive}" }
+  #
+  #   monitor.monitor(ractor.default_port)
+  #   monitor.join
+  #
+  # @example Activating the backports for a given proc (Ruby 4.1+ only)
+  #   callback = ->(ractor) { ractor.default_port }
+  #   callback.refined(Farce::Backports).call(Ractor.current)
+  #
+  # @example Calling methods on `Farce::Backports` directly
+  #   port = Farce::Backports.default_port(Ractor.current)
+  #
+  # @!method alive?(ractor)
+  #   @scope class
+  #   Backport for {https://docs.ruby-lang.org/en/master/Ractor.html#method-i-alive-3F Ractor#alive?}
+  #   @example
+  #     using Farce::Backports
+  #     ractor = Ractor.new { sleep 10 }
+  #     ractor.alive? # => true
+  #   @param ractor [Ractor] the ractor to check
+  #   @return [Boolean] whether the ractor is alive
+  #
+  # @!method default_port(ractor)
+  #   @scope class
+  #   Backport for {https://docs.ruby-lang.org/en/4.0/Ractor.html#method-i-default_port Ractor.default_port}
+  #   @example
+  #     using Farce::Backports
+  #     ractor = Ractor.new { puts receive }
+  #     port   = ractor.default_port
+  #     port.send("message")
+  #   @param ractor [Ractor] the ractor for which to obtain the default port
+  #   @return [Ractor::Port] the default port of the given ractor
+  #
+  # @!method join(ractor)
+  #   @scope class
+  #   Backport for {https://docs.ruby-lang.org/en/4.0/Ractor.html#method-i-join Ractor#join}
+  #   @example
+  #     using Farce::Backports
+  #     ractor = Ractor.new { sleep 10 }
+  #     ractor.join # blocks until the ractor exits
+  #   @param ractor [Ractor] the ractor to join
+  #   @return [Ractor] the joined ractor
+  #
+  # @!method monitor(ractor, port)
+  #   @scope class
+  #   Backport for {https://docs.ruby-lang.org/en/4.0/Ractor.html#method-i-monitor Ractor#monitor}
+  #   @example
+  #     using Farce::Backports
+  #     ractor = Ractor.new { raise "I'm not happy!" }
+  #     port   = Farce::Ractor::Port.new
+  #     ractor.monitor(port)
+  #     port.receive # => :aborted
+  #   @param ractor [Ractor] the ractor to monitor
+  #   @param port [Ractor::Port] the port to monitor the ractor with
+  #   @return [Boolean] whether the Ractor was still running when the monitor was set up
+  #
+  # @!method unmonitor(ractor, port)
+  #   @scope class
+  #   Backport for {https://docs.ruby-lang.org/en/4.0/Ractor.html#method-i-unmonitor Ractor#unmonitor}
+  #   @example
+  #     using Farce::Backports
+  #     ractor = Ractor.new { sleep 10; raise "I'm not happy!" }
+  #     port   = Farce::Ractor::Port.new
+  #     ractor.monitor(port)
+  #     ractor.unmonitor(port)
+  #     port.receive # blocks forever
+  #   @param ractor [Ractor] the ractor to unmonitor
+  #   @param port [Ractor::Port] the port to unmonitor the ractor with
+  #   @return [Ractor] the unmonitored ractor
+  #
+  # @!method receive(ractor_or_port, timeout: nil)
+  #   @scope class
+  #   Backport for the optional timeout parameter of
+  #   {https://docs.ruby-lang.org/en/master/Ractor.html#method-i-receive Ractor#receive} and
+  #   {https://docs.ruby-lang.org/en/master/Ractor/Port.html#method-i-receive Ractor::Port#receive}
+  #   @example
+  #     using Farce::Backports
+  #     port = Farce::Ractor::Port.new
+  #     port.send("message")
+  #     Farce::Backports.receive(port, timeout: 0.1) # => "message"
+  #   @param ractor_or_port [Ractor, Ractor::Port] the ractor or port to receive from
+  #   @param timeout [Numeric, nil] the timeout for receiving
+  #   @return [Object] the received value
+  #
+  # @!method select(*ractors_and_ports, timeout: nil)
+  #   @scope class
+  #   Backport for the optional timeout parameter of
+  #   {https://docs.ruby-lang.org/en/master/Ractor.html#method-c-select Ractor.select}
+  #
+  # @!method value(ractor)
+  #   @scope class
+  #   Backport for {https://docs.ruby-lang.org/en/4.0/Ractor.html#method-i-value Ractor#value}
+  #   @example
+  #     using Farce::Backports
+  #     ractor = Ractor.new { 42 }
+  #     ractor.value # => 42
+  #   @param ractor [Ractor] the ractor to obtain the value from
+  #   @return [Object] the value of the given ractor
+  module Backports
+    # @!visibility private
+    Extension = Farce::Extension.new
+    private_constant :Extension
+    include Extension
+
+    if Internal.native_ractors?
+      if needs_timeouts = ::Ractor.instance_method(:receive).arity.zero?
+        Extension.define(::Ractor) do
+          def receive(timeout: nil)
+            return super() if timeout.nil?
+            Internal::RactorSelector.current.ractor_receive(self, timeout:)
+          end
+        end
+
+        Extension.define(::Ractor.singleton_class) do
+          def select(*sources, timeout: nil, **)
+            # The selector helper must reach Ruby's native wait without reentering itself.
+            return super(*sources, **) if timeout.nil? && (Internal.native_ports? || sources.all?(::Ractor))
+            Farce::Ractor.select(*sources, timeout:, **)
+          end
+        end
+
+        def self.receive(ractor_or_port, timeout: nil)
+          ractor_or_port = default_port(ractor_or_port) if ractor_or_port.is_a?(Ractor)
+          return ractor_or_port.receive if timeout.nil?
+          return ractor_or_port.receive(timeout:) unless Internal.native_ports?
+          Internal::RactorSelector.current.ractor_receive(ractor_or_port, timeout:)
+        end
+      end
+
+      if Internal.native_ports?
+        unless ::Ractor.method_defined?(:alive?)
+          Extension.define(::Ractor) { def alive? = Backports.alive?(self) }
+
+          def self.alive?(ractor)
+            ractor.monitor(NULL_PORT)
+          ensure
+            ractor.unmonitor(NULL_PORT)
+          end
+        end
+
+        if needs_timeouts
+          Extension.define(::Ractor::Port) do
+            def receive(timeout: nil)
+              return super() if timeout.nil?
+              Internal::RactorSelector.current.ractor_receive(self, timeout:)
+            end
+          end
+        end
+      else
+        Extension.define(::Ractor) do
+          def alive?          = Backports.alive?(self)
+          def default_port    = Backports.default_port(self)
+          def join            = Backports.join(self)
+          def monitor(port)   = Backports.monitor(self, port)
+          def unmonitor(port) = Backports.unmonitor(self, port)
+          def value           = Backports.value(self)
+        end
+
+        def self.alive?(ractor)
+          return true if Ractor.main == ractor
+          state = Internal::RactorState.for(ractor)
+          return state.alive? if state
+          !ractor.inspect.end_with?("terminated>")
+        end
+
+        def self.default_port(ractor) = Farce::Ractor::Port.new(ractor)
+
+        def self.join(ractor)
+          Internal::RactorState.for(ractor)&.join
+          ractor
+        end
+
+        def self.monitor(ractor, port)
+          return true if Ractor.main == ractor
+
+          state = Internal::RactorState.for(ractor)
+          return state.monitor(port) if state
+
+          raise Ractor::Error, "#{ractor.inspect} cannot be monitored" unless ractor.inspect.end_with?("terminated>")
+
+          success = true
+
+          begin
+            ractor.take
+          rescue Ractor::ClosedError
+            # no-op
+          rescue Ractor::RemoteError
+            success = false
+          end
+
+          port.send(success ? :exited : :aborted)
+          false
+        end
+
+        def self.unmonitor(ractor, port)
+          Internal::RactorState.for(ractor)&.unmonitor(port)
+          ractor
+        end
+
+        def self.value(ractor)
+          Internal::RactorState.for(ractor)&.join
+          values = ::Ractor.store_if_absent("Ractor#value") { ObjectSpace::WeakKeyMap.new }
+          entry  = values[ractor] ||= [Mutex.new]
+          entry.first.synchronize { entry << ractor.take if entry.size == 1 }
+          entry[1]
+        end
+      end
+    end
+
+    %i[alive? default_port join monitor unmonitor value].each do |method|
+      next if respond_to?(method)
+      class_eval <<~RUBY, __FILE__, __LINE__ + 1
+        def self.#{method}(ractor, ...) = ractor.#{method}(...)
+      RUBY
+    end
+
+    unless respond_to?(:receive)
+      def self.receive(ractor_or_port, timeout: nil)
+        ractor_or_port = default_port(ractor_or_port) if ractor_or_port.is_a?(Ractor)
+        timeout.nil? ? ractor_or_port.receive : ractor_or_port.receive(timeout:)
+      end
+    end
+
+    def self.select(...) = Farce::Ractor.select(...)
+
+    # Installs the Farce backports for Ractor and Ractor::Port globally.
+    def self.install
+      Extension.install do
+        if Internal.native_ractors?
+          ::Ractor.const_set(:Port, Farce::Ractor::Port) unless Internal.native_ports?
+        else
+          Object.const_set(:Ractor, Farce::Ractor)
+        end
+      end
+    end
+  end
+end

data/lib/farce/engine/jruby/fiber_scheduler.rb

@@ -1,4 +1,6 @@
 # frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
 
 module Farce
   module Internal
@@ -17,6 +19,7 @@ module Farce
     class FiberScheduler
       include SelectScheduler
       prepend SchedulerLifecycle
+      prepend SchedulerSynchronization
 
       def initialize(backend: :auto)
         raise ArgumentError, "unavailable JVM driver: #{backend}" unless %i[auto nio].include?(backend)

data/lib/farce/engine/jruby/scheduler_synchronization.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Internal # :nodoc: all
+    # JRuby can release a mutex and notify its waiter before block is entered.
+    module SchedulerSynchronization
+      class WaitMutex < ::Mutex
+        def synchronize
+          # Registering a wait must never recursively invoke this scheduler.
+          Fiber.blocking { super }
+        end
+      end
+      MutexWait = Struct.new(:blocker, :notification)
+      private_constant :WaitMutex, :MutexWait
+
+      def initialize(...)
+        super
+        @wait_mutex    = WaitMutex.new
+        @mutex_wakeups = {}.compare_by_identity
+      end
+
+      def block(blocker, timeout = nil)
+        return super unless blocker.is_a?(::Mutex)
+        timeout = duration_value(timeout)
+        check_fiber
+        waiting = @wait_mutex.synchronize do
+          @mutex_wakeups.fetch(Fiber.current).tap { it.blocker = blocker }
+        end
+        token = arm_wait
+        early = @wait_mutex.synchronize do
+          waiting.notification.tap { waiting.notification = nil }
+        end
+        resume_wait(token, true) if early.equal?(blocker)
+        wait_with_timeout(token, timeout, false)
+      ensure
+        retire_wait(token) if token
+        @wait_mutex.synchronize { waiting.blocker = waiting.notification = nil } if waiting
+      end
+
+      def unblock(blocker, fiber)
+        return super unless blocker.is_a?(::Mutex)
+        @wait_mutex.synchronize do
+          return false if @closed || @stopping || !(waiting = @mutex_wakeups[fiber])
+          token = @waiting[fiber]
+          if token
+            return false unless waiting.blocker.equal?(blocker)
+            complete_wait(token, true)
+            return true
+          end
+
+          # Keep one early notification per admitted fiber. Matching the blocker
+          # prevents it from waking a different wait, and retirement consumes it.
+          waiting.notification = blocker
+          true
+        end
+      end
+
+      private
+
+      def start_fiber(fiber)
+        @wait_mutex.synchronize { @mutex_wakeups[fiber] = MutexWait.new }
+        super
+      end
+
+      def finish_fiber
+        @wait_mutex.synchronize { @mutex_wakeups.delete(Fiber.current) }
+        super
+      end
+
+      def retire_wait(token)
+        @wait_mutex.synchronize do
+          wait = @waits[token]
+          waiting = @mutex_wakeups[wait.fiber] if wait
+          waiting.blocker = waiting.notification = nil if waiting
+        end
+        super
+      end
+
+      def destroy
+        @wait_mutex&.synchronize { @mutex_wakeups&.clear }
+        super
+      end
+    end
+  end
+end

data/lib/farce/engine/ruby/3.4/null_port.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Internal
+    class NullPort < Internal::Port
+      def self.new         = super(nil)
+      def closed?          = false
+      def inspect          = "Farce::NULL_PORT"
+      def pretty_print(pp) = pp.text(inspect)
+
+      def send(message, move: false)
+        Ractor.new { receive }.send(message, move:) if move && !::Ractor.shareable?(message)
+        self
+      end
+
+      alias << send
+    end
+  end
+end

data/lib/farce/engine/ruby/3.4/patch.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+require "objspace"
+
+module Farce
+  module Internal
+    class RactorState
+      def self.for(ractor) = RACTOR_STATES[ractor.object_id] # rubocop:disable Lint/HashCompareByIdentity
+
+      def initialize
+        @state    = Internal::Atom.new
+        @lock     = Internal::Lock.new
+        @monitors = Internal::Map.new(compare_by_identity: true)
+        freeze
+      end
+
+      def monitor(port)
+        @lock.synchronize do
+          if state = @state.value
+            port.send(state)
+            false
+          else
+            @monitors[port] = true
+          end
+        end
+      end
+
+      def alive?          = @state.value.nil?
+      def join            = @state.wait_until_non_nil
+      def unmonitor(port) = @lock.synchronize { @monitors.delete(port) }
+
+      def set(value)
+        @lock.synchronize do
+          @state.value = value
+          @monitors.each_key { it.send(value) }
+          @monitors.clear
+        end
+      end
+    end
+
+    RACTOR_STATES = Internal::Map.new(compare_by_identity: true)
+
+    module RactorPatch
+      def new(*, **, &callback)
+        raise ArgumentError, "must be called with a block" unless callback
+        callback       = Farce::Ractor.shareable_proc(&callback) unless Ractor.shareable?(callback)
+        ractor         = super(callback, *, **) do |callback, *args|
+          ractor_state = RACTOR_STATES[Ractor.current.object_id] = RactorState.new # rubocop:disable Lint/HashCompareByIdentity
+          result       = instance_exec(*args, &callback)
+          ractor_state.set(:exited)
+          result
+        rescue Exception => e # rubocop:disable Lint/RescueException
+          ractor_state.set(:aborted)
+          raise e
+        end
+
+        RACTOR_STATES.wait_until_non_nil(ractor.object_id)
+        ObjectSpace.define_finalizer(ractor, proc { RACTOR_STATES.delete(it) })
+        ractor
+      end
+    end
+
+    ::Ractor.singleton_class.prepend(RactorPatch)
+  end
+end

data/lib/farce/engine/ruby/3.4/port.rb

@@ -107,32 +107,33 @@ module Farce
 
       def self.new(source = UNDEFINED)
         case source
-        when UNDEFINED then super(QueueReader.new)
-        when ::Ractor  then super(RactorReader.new(source))
+        when UNDEFINED then super(QueueReader.new, ::Ractor.current)
+        when ::Ractor  then super(RactorReader.new(source), source)
+        when nil       then super(nil, false)
         when Port      then source
         else raise ArgumentError, "wrong number of arguments (given 1, expected 0)"
         end
       end
 
-      def initialize(reader)
-        @owner  = ::Ractor.current
+      def initialize(reader, owner)
+        @owner  = owner
         @reader = reader
         Freeze.publish(self)
       end
 
       def ==(other) = other.is_a?(Port) && @reader == other.reader
 
-      def closed? = @reader.closed? || RactorReader.status(@owner) == "terminated"
+      def closed? = @reader&.closed? || RactorReader.status(@owner) == "terminated"
 
       def close
         check_owner!
-        @reader.close
+        @reader&.close
         self
       end
 
       def send(message, move: false)
         raise ::Ractor::ClosedError, "The port was already closed" if closed?
-        @reader.send(message, move:)
+        @reader&.send(message, move:)
         self
       end
 
@@ -140,11 +141,11 @@ module Farce
 
       def receive(timeout: nil)
         check_owner!
-        raise ::Ractor::ClosedError, "The port was already closed" if @reader.closed?
+        raise ::Ractor::ClosedError, "The port was already closed" if @reader&.closed?
         if selector = RactorSelector.for_call(self)
           selector.ractor_receive(self, timeout:)
         else
-          @reader.receive(timeout:)
+          @reader&.receive(timeout:)
         end
       end
 
@@ -153,8 +154,8 @@ module Farce
         @reader.selector_source if @reader.is_a?(RactorReader)
       end
 
-      def selector_watch(...) = @reader.selector_watch(...)
-      def selector_poll(&) = @reader.selector_poll(&)
+      def selector_watch(...) = @reader&.selector_watch(...)
+      def selector_poll(&) = @reader&.selector_poll(&)
 
       def inspect
         class_name = instance_of?(Port) ? "Farce::Ractor::Port" : self.class.name
@@ -177,7 +178,7 @@ module Farce
 
       def check_owner!
         return true if @owner.nil? || ::Ractor.current == @owner
-        raise ::Ractor::Error, "only allowed from the creator ::Ractor of this port"
+        raise ::Ractor::Error, "only allowed from the creator Ractor of this port"
       end
     end
 

data/lib/farce/engine/ruby/3.4/ractor_methods.rb

@@ -17,7 +17,6 @@ module Farce
         selector ? selector.ractor_select(*sources, timeout:, **) : ::Ractor.select(*sources, **)
       end
 
-      # TODO: Wrapper/Extension to add #default_port, etc.
       def new(...) = ::Ractor.new(...)
       def current  = ::Ractor.current
       def main     = ::Ractor.main

data/lib/farce/engine/ruby/4.0/null_port.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Internal
+    class NullPort < ::Ractor::Port
+      class << self
+        alias new! new
+      end
+
+      def self.new
+        retriever = ::Ractor::Port.new
+
+        ::Ractor.new(retriever) do |retriever|
+          null_port = NullPort.new!
+          retriever.send(null_port)
+
+          Thread.current.priority = -15
+          Darwin.set_qos_class(Darwin::BACKGROUND, Darwin::MIN_RELATIVE_PRIORITY) if defined? Darwin.set_qos_class
+          null_port.receive while true
+        end
+
+        retriever.receive
+      ensure
+        retriever&.close
+      end
+
+      def send(_, move: false) = move ? super : self
+      def inspect              = "Farce::NULL_PORT"
+      def pretty_print(pp)     = pp.text(inspect)
+
+      alias << send
+    end
+  end
+end

data/lib/farce/engine/ruby/4.0/port.rb

@@ -10,8 +10,7 @@ module Farce
       include Freeze::Unfreezable
 
       def receive(timeout: nil)
-        selector = RactorSelector.for_call(self)
-        selector ||= RactorSelector.current unless timeout.nil?
+        selector = timeout.nil? ? RactorSelector.for_call(self) : RactorSelector.current
         selector ? selector.ractor_receive(self, timeout:) : super()
       end
     end

data/lib/farce/engine/ruby/4.1/null_port.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+require "farce/engine/ruby/4.0/null_port"

data/lib/farce/engine/ruby.rb

@@ -34,6 +34,12 @@ module Farce
       # simplecov:enable
     end
 
+    begin
+      require "#{ENGINE_PATH}/patch"
+    rescue LoadError => e
+      raise e unless e.path == "#{ENGINE_PATH}/patch"
+    end
+
     unless const_defined?(:NATIVE_WEAK_MAPS, false) && NATIVE_WEAK_MAPS
       autoload :WeakMap,      "farce/engine/ruby/shared/weak_map"
       autoload :WeakKeyMap,   "farce/engine/ruby/shared/weak_map"
@@ -66,6 +72,7 @@ module Farce
 
     autoload :BasePort,       "#{ENGINE_PATH}/port"
     autoload :Port,           "#{ENGINE_PATH}/port"
+    autoload :NullPort,       "#{ENGINE_PATH}/null_port"
     autoload :RactorMethods,  "#{ENGINE_PATH}/ractor_methods"
     autoload :Vault,          "#{ENGINE_PATH}/vault"
 

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

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Internal
+    class NullPort < Internal::Port
+      def initialize       = nil # rubocop:disable Lint/MissingSuper
+      def close            = raise Ractor::Error, "only allowed from the creator Ractor of this port"
+      def closed?          = false
+      def receive(...)     = raise Ractor::Error, "only allowed from the creator Ractor of this port"
+      def send(...)        = self
+      def inspect          = "Farce::NULL_PORT"
+      def pretty_print(pp) = pp.text(inspect)
+      alias << send
+    end
+  end
+end