farce 0.0.1.alpha2-x86_64-linux-gnu

data/lib/farce/priority_queue.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # A shareable priority queue with transfer modes for unshareable values.
+  class PriorityQueue < Farce::Abstract::PriorityQueue
+    include Internal::ManagedQueue
+    include Shareable::Unfreezable
+
+    # (see Farce::Abstract::PriorityQueue#initialize)
+    # @!macro modes
+    # @param mode [Symbol] the default mode for sending unshareable values
+    def initialize(capacity: nil, default_priority: 0, order: :ascending, mode: :copy, track_age: false)
+      @manager = ModeManager.new(mode:)
+      super(capacity:, default_priority:, order:, track_age:)
+    end
+
+    # (see Farce::Abstract::PriorityQueue#push)
+    # @!macro modes
+    # @param mode [Symbol] the default mode for sending unshareable values
+    def push(value, non_block = false, priority: default_priority, timeout: nil, mode: nil) # rubocop:disable Style/OptionalBooleanParameter
+      push_to_storage(priority, non_block, @manager.wrap(value, mode:), timeout:)
+    end
+
+    # (see Farce::Abstract::PriorityQueue#try_push)
+    # @!macro modes
+    # @param mode [Symbol] the default mode for sending unshareable values
+    def try_push(value, priority: default_priority, mode: nil)
+      return true if @queue.push(priority, @manager.wrap(value, mode:))
+
+      block_given? ? yield : false
+    end
+
+    # (see Farce::Abstract::PriorityQueue#pop)
+    def pop(non_block = false, timeout: nil) # rubocop:disable Style/OptionalBooleanParameter
+      return try_pop { raise ThreadError, "queue empty" } if non_block
+      deadline = timeout_at(timeout) unless timeout.nil?
+
+      while true
+        empty  = false
+        result = @reverse_order ? @queue.pop_last { empty = true } : @queue.pop { empty = true }
+
+        return @manager.unwrap(result) unless empty
+        remaining = remaining_timeout(deadline)
+        return block_given? ? yield : nil unless wait_pop(timeout: remaining)
+      end
+    end
+
+    # (see Farce::Abstract::PriorityQueue#try_pop)
+    def try_pop
+      empty  = false
+      result = @reverse_order ? @queue.pop_last { empty = true } : @queue.pop { empty = true }
+      return @manager.unwrap(result) unless empty
+      yield if block_given?
+    end
+
+    # (see Farce::Abstract::PriorityQueue#peek)
+    # @note Peeking at a moved value claims it for this Ractor while leaving it queued.
+    def peek
+      empty  = false
+      result = if @reverse_order
+                 @queue.peek_last { empty = true }
+               else
+                 @queue.peek { empty = true }
+               end
+      empty ? (block_given? ? yield : nil) : @manager.unwrap(result)
+    end
+  end
+end

data/lib/farce/proxy/register.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  class Proxy < BasicObject
+    # Creates a new register for defining wrapper methods for proxy classes.
+    # Helpful to isolate proxy definitions that shouldn't be activated globally.
+    #
+    # @example
+    #   register = Farce::Proxy::Register.new
+    #
+    #   register.define(Hash) do
+    #     # Don't send the fetch block to the proxied object
+    #     # Allows blocks that aren't ractor-safe
+    #     def fetch(*args)
+    #       return super unless block_given?
+    #       undefined = Object.new.freeze
+    #       result    = super(args.first, undefined)
+    #       undefined.equal?(result) ? yield(args.first) : result
+    #     end
+    #   end
+    #
+    #   default_proxy = Farce::Proxy.new({})
+    #   custom_proxy  = Farce::Proxy.new({}, register:)
+    #
+    #   Ractor.new(default_proxy, custom_proxy) do |default_proxy, custom_proxy|
+    #     default_proxy.fetch(:key) { Ractor.main? } # => true
+    #     custom_proxy.fetch(:key) { Ractor.main? } # => false
+    #   end
+    class Register
+      include Internal::MarshalSupport::Reject
+
+      # Mixin extending the modules created by {Register#define}
+      module Definition
+        # Same as `Module#define_method`, but makes Proc definitions shareable across Ractors.
+        #
+        # @overload define_method(name)
+        #   @param name [Symbol, String] the name of the method to define
+        #   @yield block to define the method body
+        #
+        # @overload define_method(name, definition)
+        #   @param name [Symbol, String] the name of the method to define
+        #   @param definition [Proc, Method, UnboundMethod] the method body
+        def define_method(name, definition = UNDEFINED, &block)
+          if UNDEFINED.equal?(definition)
+            return super(name) unless block
+            definition = block
+          end
+
+          definition = Ractor.shareable_lambda(&definition) if definition.is_a?(Proc) && !Ractor.shareable?(definition)
+
+          super(name, definition)
+        end
+      end
+
+      include Farce::Shareable::Tracked
+
+      # @api private
+      attr_reader :inner_mirror, :outer_mirror
+
+      def initialize
+        @inner_mirror = ClassMirror.new(Wrapper::Inner)
+        @outer_mirror = ClassMirror.new(Wrapper::Outer)
+        super
+      end
+
+      # Created a new module that will be included in the proxy for the specified class and layer.
+      # You can define methods using `def` within the block.
+      # These methods may call `super` (which will ultimately delegate to the proxied object).
+      #
+      # The inner layer is invoked inside the Ractor the proxy resides in, while the outer layer is
+      # invoked in the caller's Ractor.
+      #
+      # The wrapper objects do not have to be Ractor-shareable, so you may use instance variables for memoization.
+      #
+      # @param klass [Class] the class to define wrapper methods for
+      # @param layer [Symbol] the layer of the proxy to define methods for (:inner or :outer)
+      # @yield block to define wrapper methods for the proxied object
+      # @yieldreceiver [Module] the module representing the wrapper layer, extended by {Definition}
+      def define(klass, layer: :outer, &)
+        check_frozen!
+        mirror_for(layer).define(klass) do
+          extend Definition
+
+          module_eval(&)
+        end
+      end
+
+      private
+
+      def mirror_for(layer)
+        case layer
+        when :inner then @inner_mirror
+        when :outer then @outer_mirror
+        else raise ArgumentError, "Unknown layer: #{layer}"
+        end
+      end
+    end
+  end
+end

data/lib/farce/proxy/supervisor.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+require "farce/envelope"
+
+module Farce
+  class Proxy < BasicObject
+    # Creates a new register for defining wrapper methods for proxy classes.
+    # @api private
+    class Supervisor # :nodoc: all
+      NilValue = Object.new.freeze
+      Request  = Data.define(:success, :result, :args, :kwargs, :block)
+
+      attr_reader :mode_manager, :register
+
+      def initialize(register, scheduler, reference)
+        @mode_manager = ModeManager.new(register:)
+        @queue        = Strict::Queue.new(capacity: 1)
+        @pending      = Strict::Map.new(compare_by_identity: true)
+        @register     = register
+        @scheduler    = scheduler
+        @reference    = reference
+      end
+
+      def run(object)
+        @owner         = Internal::ProxyOwner.current
+        @wrapper_class = @register.outer_mirror[::Kernel.instance_method(:class).bind_call(object)]
+        Ractor.make_shareable(self)
+        @owner.register(self)
+        @scheduler.schedule(mode: :local) { run!(object) }
+      end
+
+      # Sends a method to the outer wrapper, which then will most likely trigger {#dispatch},
+      # which will send it over the queue to the inner wrapper.
+      def send(...)
+        check_owner!
+        wrapper.__send__(...)
+      end
+
+      # Dispatches the method call to the inner wrapper via the queue and waits for the result.
+      # Called by Wrapper::Outer#method_missing
+      def dispatch(*args, **kwargs, &)
+        args.map! { @mode_manager.wrap(it) }
+        kwargs.transform_values! { @mode_manager.wrap(it) }
+
+        Ractor.make_shareable(kwargs)
+        Ractor.make_shareable(args)
+
+        block   = Ractor.shareable_proc(&) if block_given?
+        request = Request.new(Internal::Flag.new, Strict::Queue.new(capacity: 1), args, kwargs, block)
+
+        begin
+          @pending[request.result] = true
+          # Register before checking closure so shutdown cannot miss this reply.
+          check_owner!
+          @queue.push(request)
+          result = request.result.pop
+        rescue ClosedQueueError
+          raise Ractor::RemoteError, "proxy owner has stopped"
+        ensure
+          @pending.delete(request.result)
+        end
+
+        value = @mode_manager.unwrap(result)
+        value = nil if NilValue.equal?(value)
+
+        return value if request.success.value
+        value = Ractor::RemoteError.new(value) if value.is_a?(String)
+        raise value
+      end
+
+      def method_defined?(...)
+        check_owner!
+        wrapper.respond_to?(...)
+      end
+
+      def stop
+        @queue.close
+        @pending.each_key(&:close)
+        @owner.unregister(self)
+      end
+
+      private
+
+      def check_owner!
+        return if @owner.alive? && !@queue.closed?
+        raise Ractor::RemoteError, "proxy owner has stopped"
+      end
+
+      def wrapper
+        token = @reference.value
+        Internal::Storage.store_if_absent(token) { @wrapper_class.new(self) }
+      end
+
+      def deliver(request, result)
+        request.result.push(result)
+      rescue ClosedQueueError
+        # The owner may have stopped while the target method was running.
+        nil
+      end
+
+      def run!(object)
+        inner_wrapper = @register.inner_mirror[::Kernel.instance_method(:class).bind_call(object)].new(object, self)
+        until @queue.closed?
+          @queue.seal unless @reference.alive?
+          begin
+            request = @queue.pop(timeout: 0.1)
+          rescue ClosedQueueError
+            break
+          end
+          next unless request
+          begin
+            args                  = request.args.map { @mode_manager.unwrap(it) }
+            kwargs                = request.kwargs.transform_values { @mode_manager.unwrap(it) }
+            result                = inner_wrapper.__send__(*args, **kwargs, &request.block)
+            request.success.value = true
+            result                = SELF if object.equal?(result)
+            result = nil.equal?(result) ? NilValue : @mode_manager.wrap(result)
+          rescue Exception => e # rubocop:disable Lint/RescueException
+            request.success.value = false
+            begin
+              result = @mode_manager.wrap(e)
+            rescue StandardError
+              result = -"#{e.class}: #{e.message}"
+            end
+          end
+          deliver(request, result)
+        end
+      ensure
+        stop
+      end
+    end
+
+    private_constant :Supervisor
+  end
+end

data/lib/farce/proxy/wrapper.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  class Proxy < BasicObject
+    # @api private
+    class Wrapper < ::BasicObject # :nodoc: all
+      include ::Farce.const_get(:Internal)::Delegation
+
+      class Inner < self
+        def initialize(object, ...)
+          @__object__ = object
+          super(...)
+        end
+
+        private
+
+        # Dispatches method calls to @__object__
+        def method_missing(...)      = @__object__.__send__(...)
+        def respond_to_missing?(...) = @__object__.respond_to?(...)
+      end
+
+      class Outer < self
+        private
+
+        # Dispatches method calls to be processed by the Ractor the proxied object resides in.
+        def method_missing(...)      = @__supervisor__.dispatch(...)
+        def respond_to_missing?(...) = @__supervisor__.dispatch(:respond_to?, ...)
+      end
+
+      define_method(:respond_to?, ::Kernel.instance_method(:respond_to?))
+      def initialize(supervisor) = @__supervisor__ = supervisor
+
+      private
+
+      def __wrap__(...)   = @__supervisor__.mode_manager.wrap(...)
+      def __unwrap__(...) = @__supervisor__.mode_manager.unwrap(...)
+
+      ::Farce::MODES.each do |mode|
+        class_eval <<~RUBY, __FILE__, __LINE__ + 1
+          private def __#{mode}__(object) = __wrap__(object, mode: :#{mode})
+        RUBY
+      end
+    end
+
+    private_constant :Wrapper
+  end
+end

data/lib/farce/proxy.rb

@@ -0,0 +1,291 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # A proxy mimics the API of another object, executing method calls within the Ractor that created it.
+  # This is an easy way to have drop-in replacements for objects that cannot be shared across Ractors.
+  # Delegated calls raise Ractor::RemoteError after the owner exits.
+  #
+  # ```ruby
+  # # Mutable arrays aren't Ractor-shareable
+  # array   = []
+  # proxied = []
+  # proxy   = Farce::Proxy.new(proxied)
+  #
+  # Farce::Ractor.new(array, proxy) do |*list|
+  #   list.each { it << 42 }
+  # end.join
+  #
+  # # The array got copied instead of being modified in place
+  # array # => []
+  #
+  # # The proxy didn't get copied
+  # proxied # => [42]
+  # ```
+  #
+  # ## Customizing Proxy Behavior
+  #
+  # Imagine we have an unshareable class:
+  #
+  # ```ruby
+  # class MyClass
+  #   include Farce::Unshareable
+  #   attr_reader :record
+  #
+  #   def initialize = @record = []
+  #   def <<(value) = @record << value
+  # end
+  # ```
+  #
+  # We can use a proxy to still allow cross-ractor access:
+  #
+  # ```ruby
+  # my_instance = MyClass.new
+  # my_proxy    = Farce::Proxy.create(my_instance)
+  #
+  # Ractor.new(my_proxy) { it << 42 }.join
+  #
+  # my_instance.record # => [42]
+  # ```
+  #
+  # The above example has one issue:
+  # We cannot chain the calls, because `<<` returns an array, which actually gets copied.
+  #
+  # ```ruby
+  # my_instance = MyClass.new
+  # my_proxy    = Farce::Proxy.create(my_instance)
+  #
+  # Ractor.new(my_proxy) { it << 42 << 43 }.join
+  #
+  # my_instance.record # => [42]
+  # ```
+  #
+  # We could easily fix this inside `MyClass` by returning `self` from `<<`, but maybe we don't actually control
+  # `MyClass`? In that case, we can add a proxy definition:
+  #
+  # ```ruby
+  # # The "inner" layer runs in the same ractor that the proxied object lives in.
+  # Farce::Proxy.define(MyClass, layer: :inner) do
+  #   # Also proxy the value returned by `<<`
+  #   def <<(...) = __proxy__(super)
+  # end
+  #
+  # my_instance = MyClass.new
+  # my_proxy    = Farce::Proxy.create(my_instance)
+  #
+  # Ractor.new(my_proxy) { it << 42 << 43 }.join
+  #
+  # my_instance.record # => [42, 43]
+  # ```
+  #
+  # ### Advanced customization
+  #
+  # The proxy wrappers define methods for all supported {file:docs/modes.md modes}. Use the outer wrapper for argument
+  # handling and memoization, use the inner wrapper for handling return values:
+  #
+  # ```ruby
+  # # This class cannot easily be shared across Ractors, as it uses a Mutex and a mutable array.
+  # class MyClass
+  #   attr_reader :capacity
+  #
+  #   def initialize(capacity = 100)
+  #     @capacity = Integer(capacity)
+  #     @record   = []
+  #     @mutex    = Mutex.new
+  #   end
+  #
+  #   def add(value)
+  #     @mutex.synchronize do
+  #       return false if @record.size >= @capacity
+  #       @record << value
+  #       true
+  #     end
+  #   end
+  #
+  #   def to_a = @record.dup
+  # end
+  #
+  # # Lets define some rules
+  #
+  # Farce::Proxy.define(MyClass, layer: :outer) do
+  #   # Capacity doesn't change, so we can memoize it.
+  #   def capacity = @capacity ||= super
+  #
+  #   # Maybe a common use-case is adding MyClass instances to MyClass instances?
+  #   # If so, maybe we want to proxy these as well? Make everything else shareable.
+  #   def add(value)
+  #     value = __proxy__(value) if value.is_a? MyClass
+  #     super __make_shareable__(value)
+  #   end
+  # end
+  #
+  # Farce::Proxy.define(MyClass, layer: :inner) do
+  #   # to_a already creates a new array every time, we don't have to copy it again
+  #   def to_a = __move__(super)
+  # end
+  # ```
+  #
+  # Proxies should mimic the original object's interface as closely as possible, but nothing keeps you from adding
+  # custom methods:
+  #
+  # ```ruby
+  # class MyClass
+  #   def is_proxy? = false
+  # end
+  #
+  # Farce::Proxy.define(MyClass) do
+  #   def is_proxy? = true
+  #   def proxy_method = "Hi from the proxy!!!"
+  # end
+  #
+  # my_instance = MyClass.new
+  # my_proxy    = Farce::Proxy.create(my_instance)
+  #
+  # my_instance.is_proxy? # => false
+  # my_proxy.is_proxy?    # => true
+  #
+  # my_proxy.proxy_method if my_proxy.is_proxy? # => "Hi from the proxy!!!"
+  # ```
+  class Proxy < BasicObject
+    include ::Farce.const_get(:Internal)::Autoloads
+    include ::Farce.const_get(:Internal)::Delegation
+
+    REGISTER   = Register.new
+    SELF       = ::Object.new.freeze
+    UNDEFINED  = ::Farce.const_get(:UNDEFINED)
+    ProxyOwner = ::Farce.const_get(:Internal)::ProxyOwner
+
+    private_constant :Supervisor, :Wrapper, :REGISTER, :SELF, :UNDEFINED, :ProxyOwner
+
+    define_method(:respond_to?, ::Kernel.instance_method(:respond_to?))
+    define_method(:__freeze__,  ::Kernel.instance_method(:freeze))
+    private :__freeze__
+
+    # @return [Farce::Proxy::Register] the default register used by the proxy class
+    def self.default_register = REGISTER
+
+    # @overload define(klass, layer: :outer)
+    #   (see Farce::Proxy::Register#define)
+    #   @see .default_register
+    #   @see Farce::Proxy::Register#define
+    def self.define(...) = REGISTER.define(...)
+
+    # @overload create(object, register: nil, scheduler: nil)
+    #   Creates a new proxy for the given object if it is not Ractor-shareable.
+    #   Returns the given object otherwise.
+    #   @param (see Farce::Proxy#initialize)
+    #
+    # @overload create(register: nil)
+    #   Creates a new Ractor, runs the given block within it, and returns the result.
+    #   If the result is not Ractor-shareable, it will be proxied.
+    #   The new Ractor stops after its proxies are collected.
+    #
+    #   @yield The block to be executed within the new Ractor.
+    #   @yieldreceiver [nil]
+    #
+    # @overload create(scheduler:, register: nil)
+    #   Schedules the given block to be executed by the specified scheduler.
+    #   Returns its result. If the result is not Ractor-shareable, it will be proxied.
+    #
+    #   @yield The block to be executed by the scheduler.
+    #   @yieldreceiver [nil]
+    #
+    # @return [BasicObject, Farce::Proxy] the proxied object or the original object if it is Ractor-shareable
+    def self.create(object = UNDEFINED, register: nil, scheduler: nil, &)
+      if UNDEFINED.equal?(object)
+        initializer = ::Farce::Strict::Atom.new(::Farce::Ractor.shareable_proc(&))
+        success     = ::Farce::Strict::Atom.new
+        result      = ::Farce::Strict::Atom.new
+        owned       = scheduler.nil?
+        scheduler ||= owner_scheduler
+
+        schedule_initializer(scheduler, initializer, register, success, result, owned)
+
+        success.wait_until_non_nil
+        return result.swap(nil) if success.value
+        raise ::Farce::Ractor::RemoteError, result.swap(nil)
+      end
+
+      return object if Ractor.shareable?(object)
+      new(object, register:, scheduler:)
+    end
+
+    def self.owner_scheduler = ::Farce::ThreadScheduler.new { |*args, &block| ::Farce::Ractor.new(*args, &block) }
+    private_class_method :owner_scheduler
+
+    def self.schedule_initializer(scheduler, *)
+      scheduler.schedule(*) do |initializer, register, success, result, owned|
+        local_scheduler = ::Farce::Proxy.__send__(:initialize_proxy, initializer, register, success, result, owned)
+        result = nil
+        ProxyOwner.drain_scheduler(local_scheduler) if local_scheduler
+      rescue ::StandardError => e
+        raise unless result
+        result.value  = -"#{e.class}: #{e.message}"
+        success.value = false
+      ensure
+        local_scheduler&.close
+      end
+    end
+    private_class_method :schedule_initializer
+
+    # Keep initializer and proxy temporaries out of the frame that drains the owner.
+    def self.initialize_proxy(initializer, register, success, result, owned)
+      initialized = initializer.swap(nil).call
+      local_scheduler = nil
+      local_scheduler = ProxyOwner.create_scheduler if owned && !::Farce::Ractor.shareable?(initialized)
+      created         = ::Farce::Proxy.create(initialized, register:, scheduler: local_scheduler)
+      # Resolve shareability before the atom setter. Its native traversal scratch
+      # state can otherwise retain the proxy while the owner drains its scheduler.
+      ::Farce::Ractor.make_shareable(created)
+      result.value  = created
+      success.value = true
+      local_scheduler
+    rescue ::Exception # rubocop:disable Lint/RescueException -- Close the owned scheduler before propagating initialization failures.
+      local_scheduler&.close
+      raise
+    end
+    private_class_method :initialize_proxy
+
+    # @param object [BasicObject] the object to be managed by the proxy
+    # @param register [Farce::Proxy::Register, nil] the register to use
+    # @param scheduler [Farce::Abstract::Scheduler, nil] the scheduler to use
+    def initialize(object, register: nil, scheduler: nil)
+      @token        = ::Object.new.freeze # cross-ractor finalizers don't work reliably across Ruby versions
+      @supervisor   = Supervisor.new(register || REGISTER, scheduler || ::Farce, ::Farce::WeakValue.new(@token))
+      @proxy_class  = ::Kernel.instance_method(:class).bind_call(self)
+      @object_class = ::Kernel.instance_method(:class).bind_call(object)
+      @object_id    = ::BasicObject.instance_method(:__id__).bind_call(object)
+      __freeze__
+      @supervisor.run(object)
+    end
+
+    # @return [true] proxies can be shared even when their targets cannot
+    def ractor_shareable? = true
+
+    # @note Does not call `#inspect` on the proxied object itself, to avoid Ractor round-trips
+    # @return [String] a string representation of the proxy object
+    def inspect = "#<#{@proxy_class.inspect} object=#<#{@object_class.inspect}:0x#{@object_id.to_s(16)}>>"
+
+    # @api private
+    def pretty_print(pp)
+      pp.group(1, "#<#{@proxy_class.inspect} ", ">") do
+        pp.text "object="
+        pp.text "#<#{@object_class.inspect}:0x#{@object_id.to_s(16)}>"
+      end
+    end
+
+    private
+
+    # @api private
+    def marshal_dump = ::Kernel.raise(::TypeError, "Farce::Proxy cannot be marshaled")
+
+    # Dispatches method calls to be processed by the Ractor the proxied object resides in.
+    def method_missing(...)
+      result = @supervisor.send(...)
+      SELF.equal?(result) ? self : result
+    end
+
+    def respond_to_missing?(...) = @supervisor.method_defined?(...)
+  end
+end