farce 0.0.1.alpha2-x86-linux-musl

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

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # @!visibility private
+  module Internal # :nodoc: all
+    # Fallback for Ruby implementations supporting Ractor but not Ractor::Port (CRuby 3.x)
+    class Port
+      include MarshalSupport::Reject
+      include Freeze::Unfreezable
+
+      class QueueReader
+        include Freeze::Unfreezable
+
+        FROM_RACTOR = Object.new.freeze
+
+        def initialize
+          @queue    = Queue.new(capacity: nil)
+          @atom     = Atom.new
+          @selector = Atom.new
+          Freeze.publish(self)
+        end
+
+        def send(message, move: false)
+          return @queue.push(message) if ::Ractor.shareable?(message)
+          ractor = @atom.store_if_absent { ::Ractor.new { loop { ::Ractor.yield(::Ractor.receive) } } }
+          ractor.send(message, move:)
+          @queue.push(FROM_RACTOR)
+        rescue ClosedQueueError
+          raise ::Ractor::ClosedError, "The port was already closed"
+        ensure
+          wake_selector
+        end
+
+        def closed? = @queue.closed?
+
+        def close
+          @queue.close
+          wake_selector
+        end
+
+        # Senders may be in another Ractor. Publish only the selectable control
+        # endpoint and shared wake flag, leaving requests and replies local.
+        def selector_watch(control, wakeup) = @selector.value = [control, wakeup].freeze
+
+        def selector_poll
+          # The empty-queue callback distinguishes no message from a nil payload.
+          result = @queue.try_pop { return }
+          result = @atom.value.take if FROM_RACTOR.equal?(result)
+          yield result
+        rescue ClosedQueueError
+          raise ::Ractor::ClosedError, "The port was already closed"
+        end
+
+        def wake_selector
+          return unless target = @selector.value
+          control, wakeup = target
+          Thread.handle_interrupt(INTERRUPT_MASK) do
+            control.send(nil) if wakeup.compare_and_set(false, true)
+          end
+        rescue ::Ractor::ClosedError
+          nil
+        end
+
+        def receive(timeout: nil)
+          result = @queue.pop(timeout:)
+          return result unless FROM_RACTOR.equal?(result)
+          @atom.value.take
+        rescue ClosedQueueError
+          raise ::Ractor::ClosedError, "The port was already closed"
+        end
+      end
+
+      class RactorReader
+        include Freeze::Unfreezable
+
+        PATTERN = /\A#<Ractor:#(?<id>\d+) (?:.+ )?(?<status>\w+)>\z/
+
+        def self.info(ractor, key)
+          raise "unexpected Ractor#inspect format: #{ractor.inspect}" unless match = PATTERN.match(ractor.inspect)
+          match[key]
+        end
+
+        def self.status(ractor) = info(ractor, :status)
+        def self.id(ractor)     = info(ractor, :id)
+
+        def initialize(ractor)
+          @closed = Atom.new(false)
+          @ractor = ractor
+          Freeze.publish(self)
+        end
+
+        def receive(timeout: nil)
+          return ::Ractor.receive if timeout.nil?
+          RactorSelector.current.ractor_receive(::Ractor.current, timeout:)
+        end
+
+        def selector_source = ::Ractor.current
+
+        def closed?   = @closed.value
+        def close     = @closed.value = true
+        def send(...) = @ractor.send(...)
+      end
+
+      private_constant :QueueReader, :RactorReader
+
+      def self.new(source = UNDEFINED)
+        case source
+        when UNDEFINED then super(QueueReader.new)
+        when ::Ractor  then super(RactorReader.new(source))
+        when Port      then source
+        else raise ArgumentError, "wrong number of arguments (given 1, expected 0)"
+        end
+      end
+
+      def initialize(reader)
+        @owner  = ::Ractor.current
+        @reader = reader
+        Freeze.publish(self)
+      end
+
+      def ==(other) = other.is_a?(Port) && @reader == other.reader
+
+      def closed? = @reader.closed? || RactorReader.status(@owner) == "terminated"
+
+      def close
+        check_owner!
+        @reader.close
+        self
+      end
+
+      def send(message, move: false)
+        raise ::Ractor::ClosedError, "The port was already closed" if closed?
+        @reader.send(message, move:)
+        self
+      end
+
+      alias << send
+
+      def receive(timeout: nil)
+        check_owner!
+        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:)
+        end
+      end
+
+      def selector_source
+        check_owner!
+        @reader.selector_source if @reader.is_a?(RactorReader)
+      end
+
+      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
+        "#<#{class_name} to:##{RactorReader.id(@owner)} id:#{object_id}>"
+      rescue StandardError
+        super
+      end
+
+      alias receive! receive
+      private :receive!
+
+      undef dup
+      undef clone
+
+      protected
+
+      attr_reader :reader
+
+      private
+
+      def check_owner!
+        return true if @owner.nil? || ::Ractor.current == @owner
+        raise ::Ractor::Error, "only allowed from the creator ::Ractor of this port"
+      end
+    end
+
+    BasePort = Port
+  end
+end

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

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+require "farce/engine/ruby/shared/ractor_methods"
+
+module Farce
+  # @!visibility private
+  module Internal # :nodoc: all
+    module RactorMethods
+      def shareable_proc(**, &)   = ::Ractor.make_shareable(Farce.rebind(**, &))
+      def shareable_lambda(**, &) = ::Ractor.make_shareable(Farce.rebind(**, lambda: true, &))
+
+      def select(*sources, timeout: nil, **)
+        selector = RactorSelector.for_call(sources)
+        selector ||= RactorSelector.current unless timeout.nil? && sources.all?(::Ractor)
+        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
+    end
+  end
+end

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

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+require "farce/engine/ruby/shared/ractor_selector"
+
+module Farce
+  module Internal
+    class RactorSelector
+      # Ruby 3.4's M:N scheduler can strand the helper during Ractor teardown.
+      # Keep this helper on a dedicated native thread.
+      module DedicatedNativeThread
+        private
+
+        def run
+          Internal.lock_native_thread
+          super
+        end
+      end
+      private_constant :DedicatedNativeThread
+      prepend DedicatedNativeThread
+
+      # Native timeout: must retain Ruby's own error even with a scheduler hook.
+      # Only Farce's APIs backport that keyword.
+      def self.install_hooks(patch)
+        patch[::Ractor.singleton_class, :select, signature: "*sources, **options",
+          schedule: "*sources, **options", before: "return select!(*sources, **options) if options.key?(:timeout)"]
+        patch[::Ractor.singleton_class, :receive, signature: "",
+          schedule: "::Ractor.current"]
+        patch[::Ractor, :receive, :take, signature: "", schedule: "self"]
+      end
+
+      def ractor_receive(source, timeout: nil) = wait([source], timeout)&.at(1)
+      alias ractor_take ractor_receive
+
+      def ractor_select(*sources, timeout: nil, yield_value: UNDEFINED, move: false)
+        options = { yield_value: yield_value, move: move } unless yield_value.equal?(UNDEFINED)
+        raise ArgumentError, "specify at least one Ractor or port" if sources.empty? && !options
+        result    = wait(sources, timeout, options)
+        result[0] = :receive if result && result[0].equal?(@owner)
+        result
+      end
+      alias select ractor_select
+
+      private
+
+      def receive_source(source) = source
+
+      def fallback_port?(source)
+        !source.is_a?(::Ractor) && !source.is_a?(Request) && source.is_a?(Internal::Port)
+      end
+
+      def receive_control = @control.take
+
+      def close_control
+        @control.close_outgoing
+        @control.close_incoming
+      end
+      alias cleanup_control close_control
+
+      def check_closed(_source); end
+
+      def validate_source(source)
+        return if source.is_a?(::Ractor) || source.is_a?(Internal::Port)
+        raise ArgumentError, "expected a Ractor or port"
+      end
+
+      # A private yielding Ractor makes wakeups selectable on Ruby 3.4.
+      # Control traffic stays out of the receiving Ractor's application inbox.
+      def build_control
+        Fiber.blocking do
+          control = ::Ractor.new do
+            ::Ractor.yield(nil)
+            loop do
+              ::Ractor.receive
+              ::Ractor.yield(nil)
+            end
+          rescue ::Ractor::ClosedError
+            nil
+          ensure
+            # No final value is consumed. Close before Ruby publishes it so
+            # publication cannot race with the selector closing this port.
+            ::Ractor.current.close_outgoing
+          end
+          # Complete startup before the first command can send a wakeup.
+          control.take
+          control
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+require "farce/engine/ruby/shared/vault"
+
+module Farce
+  # @!visibility private
+  module Internal # :nodoc: all
+    class Vault
+      class Manager
+        private
+
+        def receive_request
+          message = ::Ractor.receive
+          return message if message.first.is_a?(Symbol)
+
+          ticket, action, arguments = message
+          [action, *arguments, ticket]
+        end
+
+        def respond(port, message, move: false)
+          return port.store(::Ractor.make_shareable(message)) if port.is_a?(Atom)
+          ::Ractor.yield([port, message].freeze, move:)
+        end
+      end
+
+      def initialize
+        @lock     = Lock.new
+        @sequence = Counter.new
+        @ractor   = ::Ractor.new { Manager.new.run }
+        Freeze.publish(self)
+      end
+
+      private
+
+      def execute(action, key, value = nil, move: false)
+        raise Ractor::IsolationError, "key must be shareable" unless ::Ractor.shareable?(key)
+        raise ThreadError, "deadlock; recursive access from the Vault Ractor" if ::Ractor.current.equal?(@ractor)
+        ticket = @sequence.add
+        @lock.synchronize do
+          # Short nested arrays avoid the 3.4 move bug affecting later array elements.
+          @ractor.send([ticket, action, [key, value].freeze].freeze, move:)
+          loop do
+            reply_ticket, response = @ractor.take
+            # A canceled request can leave an older reply in the outgoing queue.
+            next unless reply_ticket == ticket
+
+            success, payload = response
+            return success ? payload : raise(payload)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # @!visibility private
+  module Internal # :nodoc: all
+    BasePort = ::Ractor::Port
+    class Port < BasePort
+      include Freeze::Unfreezable
+
+      def receive(timeout: nil)
+        selector = RactorSelector.for_call(self)
+        selector ||= RactorSelector.current unless timeout.nil?
+        selector ? selector.ractor_receive(self, timeout:) : super()
+      end
+    end
+  end
+end

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+require "farce/engine/ruby/shared/ractor_methods"
+
+module Farce
+  # @!visibility private
+  module Internal # :nodoc: all
+    module RactorMethods
+      def select(*sources, timeout: nil)
+        selector = RactorSelector.for_call(sources)
+        selector ||= RactorSelector.current unless timeout.nil?
+        selector ? selector.ractor_select(*sources, timeout:) : ::Ractor.select(*sources)
+      end
+
+      Internal.delegate(self, ::Ractor, :shareable_proc, :shareable_lambda, :current, :main, :new)
+    end
+  end
+end

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

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+require "farce/engine/ruby/shared/ractor_selector"
+
+module Farce
+  module Internal
+    class RactorSelector
+      def self.install_hooks(patch)
+        if ::Ractor::Port.instance_method(:receive).parameters.include?(%i[key timeout])
+          patch[::Ractor.singleton_class, :select, signature: "*sources, **options", schedule: "*sources, **options"]
+          patch[::Ractor.singleton_class, :receive, schedule: "::Ractor.current, ..."]
+          patch[::Ractor, :receive]
+          patch[::Ractor::Port, :receive]
+        else
+          # Ruby 4.0 treats unsupported keywords as a positional Hash. Preserve
+          # its native argument error before consulting a cooperative scheduler.
+          patch[::Ractor.singleton_class, :select, signature: "*sources", schedule: "*sources",
+            before: "return select!(*sources) if sources.last.is_a?(Hash)"]
+          patch[::Ractor.singleton_class, :receive, signature: "", schedule: "::Ractor.current"]
+          patch[::Ractor, :receive, signature: "", schedule: "self"]
+          patch[::Ractor::Port, :receive, signature: "", schedule: "self"]
+        end
+        patch[::Ractor, :join, :value, signature: "", schedule: "self"]
+      end
+
+      def ractor_receive(source, timeout: nil) = wait([receive_source(source)], timeout)&.at(1)
+
+      def ractor_select(*sources, timeout: nil)
+        raise ArgumentError, "specify at least one Ractor or port" if sources.empty?
+        # Monitor termination without consuming the Ractor's result. Only the
+        # selected caller retrieves that result, so a timeout leaves it available.
+        monitors = {}.compare_by_identity
+        ports    = sources.map do |source|
+          if source.is_a?(::Ractor)
+            port = ::Ractor::Port.new
+            monitors[port] = source
+            source.monitor(port)
+            port
+          else
+            source
+          end
+        end
+        return unless result = wait(ports, timeout)
+        source, value = result
+        ractor        = monitors[source]
+        ractor ? [ractor, native { ractor.value }] : [source, value]
+      ensure
+        monitors&.each do |port, ractor|
+          ractor.unmonitor(port)
+          port.close
+          forget(port)
+        end
+      end
+      alias select ractor_select
+
+      def ractor_join(ractor, timeout: nil)
+        terminated(ractor, timeout) { native { ractor.join } }
+      end
+
+      def ractor_value(ractor, timeout: nil)
+        terminated(ractor, timeout) { native { ractor.value } }
+      end
+
+      private
+
+      def receive_source(source)  = source.is_a?(::Ractor) ? source.default_port : source
+      def fallback_port?(_source) = false
+      def build_control           = ::Ractor::Port.new
+      def receive_control         = @control.receive
+      def close_control           = @control.close
+
+      # Native ports are closed by CRuby during Ractor teardown. Closing them
+      # again from the dying helper can crash the VM.
+      def cleanup_control; end
+
+      def check_closed(source)
+        raise ::Ractor::ClosedError, "The port was already closed" if source.closed?
+      end
+
+      def validate_source(source)
+        return if source.is_a?(::Ractor)
+        raise ArgumentError, "expected a Ractor or port" unless source.is_a?(::Ractor::Port)
+        inspect_port = ::Ractor::Port.instance_method(:inspect)
+        # Native ports expose their owner only through the built-in inspect.
+        owner = inspect_port.bind_call(@owner.default_port)[/to:#\d+/]
+        return if inspect_port.bind_call(source)[/to:#\d+/] == owner
+        raise ::Ractor::Error, "only allowed from the creator Ractor of this port"
+      end
+
+      # Readiness is separate from result retrieval. In particular, join must
+      # wait for termination without taking the value another caller may need.
+      def terminated(ractor, timeout)
+        port = ::Ractor::Port.new
+        ractor.monitor(port)
+        return unless wait([port], timeout)
+        yield
+      ensure
+        if port
+          ractor.unmonitor(port)
+          port.close
+          forget(port)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+require "farce/engine/ruby/shared/vault"
+
+module Farce
+  # @!visibility private
+  module Internal # :nodoc: all
+    class Vault
+      if System.windows?
+        # A Windows Port receiver can remain asleep after its reply was sent.
+        # Wait for a native Atom notification before consuming the queued reply.
+        class ReplyPort
+          include Freeze::Unfreezable
+
+          def initialize
+            @port = ::Ractor::Port.new
+            @ready = Atom.new
+            Freeze.publish(self)
+          end
+
+          def send(message, move: false)
+            @port.send(message, move:)
+            @ready.store(true)
+          end
+
+          def receive
+            @ready.wait_until_non_nil
+            @port.receive
+          end
+
+          def close = @port.close
+          def closed? = @port.closed?
+        end
+      else
+        ReplyPort = ::Ractor::Port
+      end
+      private_constant :ReplyPort
+
+      class Manager
+        private
+
+        def receive_request = ::Ractor.receive
+
+        def respond(port, message, move: false)
+          return port.store(::Ractor.make_shareable(message)) if port.is_a?(Atom)
+          port.send(message, move:)
+        rescue ::Ractor::ClosedError
+          # An interrupted caller closes its private reply port.
+          raise unless port.is_a?(ReplyPort) && port.closed?
+        end
+      end
+
+      def initialize
+        @ractor = ::Ractor.new { Manager.new.run }
+        Freeze.publish(self)
+      end
+
+      private
+
+      def execute(action, key, value = nil, move: false)
+        raise Ractor::IsolationError, "key must be shareable" unless ::Ractor.shareable?(key)
+        raise ThreadError, "deadlock; recursive access from the Vault Ractor" if ::Ractor.current.equal?(@ractor)
+        port = ReplyPort.new
+        @ractor.send([action, key, value, port].freeze, move:)
+        success, payload = port.receive
+        success ? payload : raise(payload)
+      ensure
+        port&.close
+      end
+    end
+  end
+end

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

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # @!visibility private
+  module Internal # :nodoc: all
+    BasePort = ::Ractor::Port
+    class Port < BasePort
+      include Freeze::Unfreezable
+
+      def receive(timeout: nil)
+        if selector = RactorSelector.for_call(self)
+          selector.ractor_receive(self, timeout:)
+        else
+          timeout.nil? ? super() : super
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+require "farce/engine/ruby/shared/ractor_methods"
+
+module Farce
+  # @!visibility private
+  module Internal # :nodoc: all
+    module RactorMethods
+      def select(*sources, timeout: nil)
+        if selector = RactorSelector.for_call(sources)
+          selector.ractor_select(*sources, timeout:)
+        else
+          timeout.nil? ? ::Ractor.select(*sources) : ::Ractor.select(*sources, timeout:)
+        end
+      end
+
+      Internal.delegate(self, ::Ractor, :shareable_proc, :shareable_lambda, :current, :main, :new)
+    end
+  end
+end

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

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+require "farce/engine/ruby/4.0/ractor_selector"
+
+module Farce
+  module Internal
+    class RactorSelector
+      # Ruby 4.1 can crash while formatting a dying helper's exception after
+      # Ractor teardown has freed its ports. Callers and close observe failures.
+      # See https://bugs.ruby-lang.org/issues/22386
+      module ExplicitFailureReporting
+        private
+
+        def run
+          Thread.current.report_on_exception = false
+          super
+        end
+      end
+      private_constant :ExplicitFailureReporting
+      prepend ExplicitFailureReporting
+    end
+  end
+end

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

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