farce 0.0.1.alpha2-x86_64-linux-gnu

data/lib/farce/envelope.rb

@@ -0,0 +1,335 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # An envelope can be used to wrap an unshareable value in a shareable object.
+  #
+  # Once created, the envelope can be shared between Ractors without any objects being moved or copied until the
+  # envelope is opened.
+  #
+  # When a Ractor attempts to open an envelope, it attempts "claim" it. Some envelopes may only be claimed by a single
+  # Ractor, others can be claimed by any Ractor. Claims cannot be taken back.
+  #
+  # @!method claim
+  #   Attempts to claim the envelope for the current Ractor.
+  #   @return [Envelope, nil]
+  #     The envelope if the claim was successful, or `nil` if the envelope has already been claimed by another Ractor.
+  #
+  # @!method claimed?
+  #   @return [Boolean] `true` if the envelope has been claimed by any Ractor, `false` otherwise.
+  #
+  # @!method owned?
+  #   @return [Boolean] `true` if the envelope has been claimed by the current Ractor, `false` otherwise.
+  class Envelope
+    include Internal::Noncopyable
+    include Internal::Inspect
+
+    VAULT_ATOM = Internal::Atom.new
+    private_constant :VAULT_ATOM
+
+    include Shareable
+    include Abstract::Value
+
+    # Raised when trying to claim an envelope that has already been claimed by another Ractor.
+    AlreadyClaimed = Class.new(Ractor::IsolationError)
+
+    module Copyable
+      include Internal::Copyable
+
+      define_method(:dup, Object.instance_method(:dup))
+      define_method(:clone, Object.instance_method(:clone))
+
+      private
+
+      def initialize_copy(other)
+        Object.instance_method(:initialize_copy).bind_call(self, other)
+      end
+    end
+    private_constant :Copyable
+
+    # An envelope that copies its contents. Can be opened by multiple Ractors.
+    # The value will be copied once when the envelope is created, and then once per Ractor that opens the envelope.
+    #
+    # @!method new(value)
+    #   @!scope class
+    #   @param (see Farce::Envelope#initialize)
+    #   @return [Copy, Share] A new envelope wrapping the given value.
+    class Copy < Farce::Envelope
+      include Copyable
+
+      # @overload initialize(value)
+      #   @param [Object] value The value to wrap in the envelope.
+      def initialize(value, auto_unwrap = nil)
+        @vault = VAULT_ATOM.store_if_absent { Internal::Vault.new }
+        super
+        @vault.copy_in(self, value)
+      end
+
+      # @api private
+      def marshal_dump
+        storage = Internal::Storage.ractor
+        [1, storage.key?(self) ? storage[self] : retrieve, auto_unwrap]
+      end
+
+      # @api private
+      def marshal_load(data)
+        value, manager = Internal::MarshalSupport.payload(data, 2)
+        initialize(value, manager)
+        Internal::Storage.ractor[self] = value
+      end
+
+      # (see Envelope#claim)
+      def claim = self
+
+      # (see Envelope#claimed?)
+      def claimed? = true
+
+      # (see Envelope#owned?)
+      def owned? = true
+
+      protected
+
+      def retrieve = @vault.copy_out(vault_key)
+
+      private
+
+      def initialize_dup(other)
+        value      = other.retrieve
+        @vault_key = Object.new.freeze
+        super
+        @vault.copy_in(@vault_key, value)
+      end
+
+      def initialize_clone(other, freeze: nil)
+        value      = other.retrieve
+        @vault_key = Object.new.freeze
+        super
+        @vault.copy_in(@vault_key, value)
+      end
+
+      def vault_key = defined?(@vault_key) ? @vault_key : self
+    end
+
+    # An envelope that moves its contents. Can only be opened by a single Ractor.
+    # The value will be moved once when the envelope is created, and then once when the envelope is opened.
+    #
+    # @!method new(value)
+    #   @!scope class
+    #   @param (see Farce::Envelope#initialize)
+    #   @return [Move, Share] A new envelope wrapping the given value.
+    class Move < Farce::Envelope
+      include Internal::MarshalSupport::Reject
+      include Shareable::Unfreezable
+
+      # @overload initialize(value)
+      #   @param [Object] value The value to wrap in the envelope.
+      def initialize(value, auto_unwrap = nil)
+        @vault = VAULT_ATOM.store_if_absent { Internal::Vault.new }
+        @owner = Internal::Atom.new
+        super
+        @vault.move_in(self, value)
+      end
+
+      # (see Envelope#claim)
+      def claim
+        owner = @owner.store_if_absent { Ractor.current }
+        self if owner == Ractor.current
+      end
+
+      # (see Envelope#claimed?)
+      def claimed? = !@owner.value.nil?
+
+      # (see Envelope#owned?)
+      def owned? = @owner.value == Ractor.current
+
+      private def retrieve = @vault.move_out(self)
+    end
+
+    # An envelope that keeps its contents local to the Ractor that created it.
+    # Can only be opened by the Ractor that created it.
+    #
+    # @!method new(value)
+    #   @!scope class
+    #   @param (see Farce::Envelope#initialize)
+    #   @return [Local, Share] A new envelope wrapping the given value.
+    class Local < Farce::Envelope
+      include Copyable
+
+      # @overload initialize(value)
+      #   @param value [Object] The value to wrap in the envelope.
+      def initialize(value, auto_unwrap = nil)
+        @owner = Ractor.current
+        Internal::Storage.ractor[self] = value
+        super
+      end
+
+      # @api private
+      def marshal_dump
+        raise TypeError, "local envelope belongs to another Ractor" unless owned?
+        [1, Internal::Storage.ractor[self], auto_unwrap]
+      end
+
+      # @api private
+      def marshal_load(data)
+        value, manager = Internal::MarshalSupport.payload(data, 2)
+        initialize(value, manager)
+      end
+
+      # (see Envelope#claim)
+      def claim = owned? ? self : nil
+
+      # (see Envelope#claimed?)
+      def claimed? = true
+
+      # (see Envelope#owned?)
+      def owned? = @owner == Ractor.current
+
+      private
+
+      def initialize_copy(other)
+        super
+        other.claim!
+        Internal::Storage.ractor[self] = other.value.dup
+      end
+    end
+
+    # An envelope that wraps a Ractor-shareable value. Can be opened by any Ractor.
+    # Defeats the purpose of an envelope, but is provided for code that expects an envelope.
+    #
+    # @!method new(value)
+    #   @!scope class
+    #   @param (see Farce::Envelope#initialize)
+    #   @return [Share] A new envelope wrapping the given value.
+    class Share < Farce::Envelope
+      include Copyable
+
+      attr_reader :value
+
+      # @overload initialize(value)
+      #   @param value [Object] The value to wrap in the envelope. Must be shareable.
+      def initialize(value, auto_unwrap = nil)
+        raise ArgumentError, "value must be shareable" unless Ractor.shareable?(value)
+        @value = value
+        super
+      end
+
+      # @api private
+      def marshal_dump = [1, value, auto_unwrap]
+
+      # @api private
+      def marshal_load(data)
+        value, manager = Internal::MarshalSupport.payload(data, 2)
+        initialize(Ractor.make_shareable(value), manager)
+      end
+
+      # (see Envelope#claim)
+      def claim = self
+
+      # (see Envelope#claimed?)
+      def claimed? = true
+
+      # (see Envelope#owned?)
+      def owned? = true
+    end
+
+    # @note
+    #   The keyword arguments are only accepted by Envelope itself, not by its subclasses.
+    #   Also, if multiple keyword arguments are provided, `mode` takes precedence over `local`, which takes precedence
+    #   over `move`.
+    #
+    # Creates an envelope wrapping the given value. If the value is Ractor-shareable, a {Share} envelope will be
+    # created. Otherwise, the type of envelope will be determined by the keyword arguments.
+    #
+    # @overload new(value, move: false)
+    #   @param value [BasicObject] The value to wrap in the envelope.
+    #   @param move [Boolean] Whether to create a {Move} envelope. Ignored if `local` or `mode` is provided.
+    #   @return [Envelope] A new envelope wrapping the given value.
+    #
+    # @overload new(value, local: false)
+    #   @param value [BasicObject] The value to wrap in the envelope.
+    #   @param local [Boolean] Whether to create a {Local} envelope. Ignored if `mode` is provided.
+    #   @return [Envelope] A new envelope wrapping the given value.
+    #
+    # @overload new(value, mode:)
+    #   @param value [BasicObject] The value to wrap in the envelope.
+    #   @param mode [Symbol, nil] The type of envelope to create. Can be `:move`, `:copy`, or `:local`.
+    #   @return [Envelope] A new envelope wrapping the given value.
+    #
+    # @return [Envelope] A new envelope wrapping the given value.
+    def self.new(value, *, **)
+      return super if self != Envelope
+      return Share.new(value, *) if Ractor.shareable?(value)
+      subclass_for(**).new(value, *)
+    end
+
+    def self.subclass_for(move: false, local: false, mode: nil)
+      case mode
+      when :move  then Move
+      when :copy  then Copy
+      when :local then Local
+      when nil    then local ? Local : (move ? Move : Copy)
+      else raise ArgumentError, "invalid mode: #{mode.inspect}"
+      end
+    end
+    private_class_method :subclass_for
+
+    # @api private
+    attr_reader :auto_unwrap
+
+    # @overload initialize(value)
+    #   @param value [BasicObject] The value to wrap in the envelope.
+    def initialize(_, auto_unwrap = nil)
+      raise ArgumentError, "auto_unwrap needs to be shareable" unless Ractor.shareable?(auto_unwrap)
+      @auto_unwrap = auto_unwrap
+      super()
+    end
+
+    # Attempts to claim the envelope for the current Ractor.
+    # Raises an exception if it was unable to claim the envelope.
+    # @return [Envelope] The envelope if the claim was successful.
+    # @raise [AlreadyClaimed] If the envelope has already been claimed by another Ractor.
+    def claim! = claim || raise(AlreadyClaimed, "envelope has already been claimed by another Ractor")
+
+    # Attempts to claim the envelope and retrieves the value if successful.
+    # May be called multiple times.
+    # @return [BasicObject] The value wrapped in the envelope.
+    # @raise [AlreadyClaimed] If the envelope has already been claimed by another Ractor.
+    def value = Internal::Storage.ractor.store_if_absent(self) { claim! && retrieve }
+
+    # Compares wrapped values. Compatible envelopes can be compared without
+    # claiming or opening either envelope.
+    # @param other [BasicObject, Envelope] The value or envelope to compare.
+    # @param identity [Boolean] Whether to compare the values by identity instead of equality.
+    # @return [Boolean] Whether the wrapped values match.
+    def same_value?(other, identity: false)
+      if comparison_vault
+        other_vault = other.comparison_vault if Envelope === other
+        if comparison_vault.equal?(other_vault)
+          return comparison_vault.same_value?(comparison_key, other.comparison_key, identity:)
+        elsif !(Envelope === other) && Ractor.shareable?(other)
+          return comparison_vault.same_value?(comparison_key, other, identity:, right_stored: false)
+        end
+      end
+
+      left  = value
+      right = Envelope === other ? other.value : other
+      return BasicObject.instance_method(:equal?).bind_call(left, right) if identity
+
+      left == right
+    end
+
+    # @api private
+    def inspect_with(inspector)
+      super do
+        inspector.breakable
+        inspector.from_envelope(self, "value=")
+      end
+    end
+
+    protected
+
+    def comparison_vault = defined?(@vault) && @vault
+    def comparison_key   = defined?(@vault_key) ? @vault_key : self
+  end
+end

data/lib/farce/error.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+begin
+  require "weakref"
+rescue LoadError => e
+  raise e unless e.path == "weakref"
+end
+
+module Farce
+  # Raised when an operation cannot proceed because a queue is closed.
+  ClosedQueueError = Class.new(::ClosedQueueError)
+
+  # Raised when a push cannot proceed because a queue is sealed.
+  SealedQueueError = Class.new(ClosedQueueError)
+
+  # Raised when attempting to schedule a task on a closed scheduler.
+  SchedulerClosedError = Class.new(StandardError)
+
+  # Raised when attempting to schedule a task on a closed pool.
+  PoolClosedError = Class.new(SchedulerClosedError)
+
+  # Raised when a timed operation does not complete before its timeout.
+  TimeoutError = Class.new(StandardError)
+
+  # Raised when an operation requires ownership by the current Fiber.
+  OwnershipError = Class.new(StandardError)
+
+  # Raised when attempting to use a permanently retired lease.
+  RetiredLeaseError = Class.new(StandardError)
+
+  # Raised when a weak reference is no longer valid because the referenced object has been garbage collected.
+  WeakRefError = Class.new(defined?(::WeakRef::RefError) ? ::WeakRef::RefError : StandardError)
+end

data/lib/farce/exchanger.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # A Ractor-shareable rendezvous with transfer modes for unshareable values.
+  # Values received from a partner are automatically unwrapped.
+  #
+  # @example Exchanging mutable values between Ractors
+  #   exchanger = Farce::Exchanger.new
+  #   worker    = Farce::Ractor.new(exchanger) { |shared| shared.exchange([:worker]) }
+  #   exchanger.exchange([:main]) # => [:worker]
+  class Exchanger < Farce::Abstract::Exchanger
+    include Shareable::Unfreezable
+
+    # @!macro modes
+    # @param mode [Symbol] the default mode used to transfer values between Ractors
+    def initialize(mode: :copy)
+      @manager   = ModeManager.new(mode:)
+      @exchanger = Internal::Exchanger.new
+      super()
+    end
+
+    # The default mode used to transfer values between Ractors.
+    # @return [Symbol]
+    def mode = @manager.mode
+
+    # (see Abstract::Exchanger#exchange)
+    # The offered value is prepared before waiting. A timeout does not undo copying,
+    # moving, or freezing it. The fallback result is returned unchanged.
+    # @!macro modes
+    # @param mode [Symbol, nil] the transfer mode, or nil to use the exchanger's default mode
+    def exchange(offered, timeout: nil, mode: nil)
+      offered   = @manager.wrap(offered, mode:)
+      timed_out = false
+      result    = @exchanger.exchange(offered, timeout:) { timed_out = true }
+      return @manager.unwrap(result) unless timed_out
+      yield if block_given?
+    end
+  end
+end

data/lib/farce/flag.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # A Ractor-shareable atomic boolean for coordinating threads and Ractors.
+  # Only true and false are accepted. Read {#value} when testing the flag's state.
+  # Use {#compare_and_set} to check and change the state in a single atomic operation.
+  #
+  # On CRuby, subclasses must not add Ruby instance variables.
+  #
+  # @example Allowing one caller to claim work
+  #   claimed = Farce::Flag.new
+  #   workers = 4.times.map do
+  #     Thread.new { claimed.compare_and_set(false, true) }
+  #   end
+  #   workers.count { |worker| worker.value } # => 1
+  #   claimed.value # => true
+  #
+  # @!method initialize(value = false)
+  #   @param value [Boolean] the initial value
+  #   @raise [ArgumentError] if the value is not true or false
+  class Flag < Internal::Flag
+    include Abstract::Flag
+    include Shareable::Native
+  end
+end

data/lib/farce/integrations/active_support/blank.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+# @!group ActiveSupport Integration
+require "farce/integrations/active_support"
+
+# ActiveSupport's blank? already checks empty?
+# Therefore Vector/Map/Set implementations do not need additional blank? checks.
+#-
+
+module Farce
+  # @!visibility private
+  module Internal # :nodoc: all
+    # @api private
+    class Vault
+      # rubocop:disable-next Naming/PredicatePrefix
+      if defined?(Manager)
+        class Manager
+          def is_blank(key, _, port) = respond(port, [true, @data[key].blank?].freeze)
+        end
+
+        def is_blank?(key) = execute(:is_blank, key)
+      else
+        def is_blank?(key) = @data[key].blank?
+      end
+    end
+  end
+
+  module Abstract
+    class Atom
+      # @!macro active_support
+      # @return [Boolean] true if the atom's value is blank, false otherwise.
+      def blank? = internal_atom.value.blank?
+    end
+
+    module Value
+      # @!macro active_support
+      # @return [Boolean] true if the value is blank, false otherwise.
+      def blank? = value.blank?
+    end
+  end
+
+  class Atom
+    # @!macro active_support
+    # @return [Boolean] true if the atom's value is blank, false otherwise.
+    def blank?
+      current = internal_atom.value
+      NIL_VALUE.equal?(current) || current.blank?
+    end
+  end
+
+  class Envelope
+    # @!macro active_support
+    # Checks if the envelope's value is blank without claiming it.
+    # @return [Boolean] true if the envelope's value is blank or inaccessible, false otherwise.
+    def blank?
+      if !claimed? && (vault = comparison_vault)
+        result = vault.is_blank?(comparison_key)
+        # A concurrent claim may have removed the value from the vault.
+        return result unless claimed?
+      end
+      return true unless owned?
+
+      value.blank?
+    end
+  end
+end

data/lib/farce/integrations/active_support/clock.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+# @!group ActiveSupport Integration
+require "farce/integrations/active_support"
+
+module Farce
+  module Clock
+    # @!macro active_support
+    # Treat ActiveSupport durations as relative offsets.
+    def self.parse(value)
+      return offset(value) if ActiveSupport::Duration === value
+      super
+    end
+  end
+end

data/lib/farce/integrations/active_support/duplicable.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+# @!group ActiveSupport Integration
+require "farce/integrations/active_support"
+
+module Farce
+  class Config
+    # @!macro active_support
+    # @return [Boolean] true
+    def duplicable? = true
+  end
+
+  class WeakValue
+    # @!macro active_support
+    # @return [Boolean] true
+    def duplicable? = true
+  end
+
+  class WeakRef
+    # @!macro active_support
+    # @return [Boolean] true
+    def duplicable? = true
+  end
+
+  class Reference
+    # @!macro active_support
+    # @return [Boolean] true
+    def duplicable? = true
+  end
+
+  module Abstract
+    class Queue
+      # @!macro active_support
+      # @return [Boolean] false
+      def duplicable? = false
+    end
+
+    class Set
+      # @!macro active_support
+      # @return [Boolean] true
+      def duplicable? = true
+    end
+
+    class LeaseMap
+      # @!macro active_support
+      # @return [Boolean] false
+      def duplicable? = false
+    end
+
+    module DuplicableMap
+      # @!macro active_support
+      # @return [Boolean] true
+      def duplicable? = true
+    end
+  end
+
+  module Internal
+    module Copyable
+      # @!macro active_support
+      # @return [Boolean] true
+      def duplicable? = true
+    end
+
+    module Noncopyable
+      # @!macro active_support
+      # @return [Boolean] false
+      def duplicable? = false
+    end
+
+    module SchedulerLifecycle
+      # @!macro active_support
+      # @return [Boolean] false
+      def duplicable? = false
+    end
+  end
+end