farce 0.0.1.alpha2-x86_64-linux-gnu

data/lib/farce/abstract/weak_atom.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Abstract
+    # @abstract Common superclass for weak atomic references.
+    #
+    # A weak atom does not keep its current value alive. Its value becomes `nil`
+    # after garbage collection when no strong references remain. Collection
+    # timing is controlled by the garbage collector. In-flight operations may
+    # temporarily retain values they observe. Updates are serialized even when
+    # collection changes the observed value.
+    class WeakAtom < Atom
+      # @param value [BasicObject, nil] the initial value
+      # @param compare_by_identity [Boolean] whether comparisons use object identity instead of equality
+      def initialize(value = nil, compare_by_identity: false)
+        @atom = internal_atom_class.new(value, compare_by_identity:)
+        super()
+      end
+
+      private
+
+      # @abstract
+      # simplecov:disable
+      def internal_atom_class
+        raise NoMethodError, "Farce::Abstract::WeakAtom should not be instantiated directly. Use a subclass instead."
+      end
+      # simplecov:enable
+    end
+  end
+end

data/lib/farce/abstract/weak_key_map.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Abstract
+    # @abstract Common superclass for concurrent maps that retain keys weakly.
+    class WeakKeyMap < ConcurrentMap
+      def weak_keys? = true
+    end
+  end
+end

data/lib/farce/abstract/weak_map.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Abstract
+    # @abstract Common superclass for concurrent maps that retain keys and values weakly.
+    class WeakMap < ConcurrentMap
+      def weak_keys?   = true
+      def weak_values? = true
+    end
+  end
+end

data/lib/farce/abstract/weak_set.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Abstract
+    # @abstract A set whose elements are retained weakly.
+    # Heap elements can disappear once no other strong reference remains.
+    class WeakSet < Set
+    end
+  end
+end

data/lib/farce/abstract/weak_value_map.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Abstract
+    # @abstract Common superclass for concurrent maps that retain values weakly.
+    class WeakValueMap < ConcurrentMap
+      def weak_values? = true
+    end
+  end
+end

data/lib/farce/abstract.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # Module holding abstract versions of classes that have multiple public implementations.
+  #
+  # Subclasses of these can be found under the following namespaces:
+  # * {Farce} - for Ractor-shareable implementations
+  # * {Farce::Local} - implementations scoped by Ractor/Thread/Fiber/etc
+  # * {Farce::Strict} - for Ractor-shareable implementations accepting only shareable values
+  # * {Farce::Unshared} - for Ractor-unshareable implementations
+  # * {Farce::Unsafe} – for implementations that are not thread-safe
+  module Abstract
+    include Internal::Autoloads
+  end
+end

data/lib/farce/atom.rb

@@ -0,0 +1,293 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # A Ractor-shareable atomic reference that strongly retains its current value and can hold non-shareable values.
+  #
+  # Values are transferred according to the atom's default {#mode}, or an operation-specific mode where supported.
+  # Values returned by the atom are automatically unwrapped. Updates are serialized, and comparison operations compare
+  # the stored values without claiming or opening their envelopes when possible.
+  #
+  # @example Creating a new atom
+  #   atom = Farce::Atom.new("initial value")
+  #   atom.value # => "initial value"
+  #
+  #   # atoms are ractor-shareable
+  #   Ractor.new(atom) do |atom|
+  #     atom.update { |current| current + " updated" } # => "initial value updated"
+  #   end
+  #
+  #   # waits for the other ractor to perform its update
+  #   atom.wait_until_changed "initial value"
+  #
+  # @example Updating a counter atomically
+  #   # Note: Farce::Counter would have better performance
+  #   counter = Farce::Atom.new(0)
+  #   counter.update { |count| count + 1 } # => 1
+  #   counter.compare_and_set(1, 2)        # => true
+  #   counter.value                        # => 2
+  #
+  # @example Automatically making values shareable
+  #   atom = Farce::Atom.new([], mode: :make_shareable)
+  #   atom.update { |items| items + [:job] } # => [:job]
+  #   atom.value                    # => [:job]
+  #   Ractor.shareable?(atom.value) # => true
+  class Atom < Farce::Abstract::Atom
+    include Shareable::Delegated
+
+    NIL_VALUE = Object.new.freeze
+    TIMED_OUT = Object.new.freeze
+    private_constant :NIL_VALUE, :TIMED_OUT
+
+    # @!macro modes
+    # @param value [BasicObject, nil] the initial value
+    # @param compare_by_identity [Boolean] whether comparisons use object identity instead of equality
+    # @param mode [Symbol] the default mode used to transfer values between Ractors
+    def initialize(value = nil, compare_by_identity: false, mode: :copy)
+      unless compare_by_identity == true || compare_by_identity == false
+        raise ArgumentError, "compare_by_identity must be a boolean"
+      end
+
+      @manager             = ModeManager.new(mode:)
+      @compare_by_identity = compare_by_identity
+      @atom                = Internal::Atom.new(wrap_value(value), compare_by_identity: true)
+      super()
+    end
+
+    # @api private
+    def marshal_dump
+      stored = @atom.value
+      stored = nil if NIL_VALUE.equal?(stored)
+      [1, Internal::MarshalSupport.value(stored), @manager, compare_by_identity?, frozen?]
+    end
+
+    # @api private
+    def marshal_load(data)
+      stored, @manager, identity, frozen = Internal::MarshalSupport.payload(data, 4)
+      @compare_by_identity               = identity
+      @atom                              = Internal::Atom.new(NIL_VALUE, compare_by_identity: true)
+      publish_shareable
+      value = Internal::MarshalSupport.restore_value(stored)
+      @atom.store(nil.equal?(value) ? NIL_VALUE : value)
+      Internal::MarshalSupport.freeze(self, frozen)
+    end
+
+    # @api private
+    def transaction_wrapper(transaction)
+      Transaction::Atom.new(transaction, self, @atom, manager: @manager, nil_value: NIL_VALUE)
+    end
+
+    # The default mode used to transfer values between Ractors.
+    # @return [Symbol]
+    def mode = @manager.mode
+
+    # Whether comparisons use object identity instead of equality.
+    # @return [Boolean]
+    def compare_by_identity? = @compare_by_identity
+
+    # Return the current value without waiting for an update in progress.
+    # @return [BasicObject, nil] the current value
+    def value = unwrap_value(@atom.value)
+
+    # Store a value using the default mode.
+    # @param new_value [BasicObject, nil] the new value
+    # @return [BasicObject, nil] the new value
+    def value=(new_value)
+      store(new_value)
+    end
+
+    # Return the current value, waiting for any update in progress.
+    # @param timeout [Numeric, nil] the maximum number of seconds to wait
+    # @yield called when the timeout expires
+    # @return [BasicObject, nil] the current value or the fallback result
+    def get(timeout: nil, &) = unwrap_result(@atom.get(timeout:) { TIMED_OUT }, &)
+
+    # Store a new value, waiting for any update in progress.
+    # @!macro modes
+    # @param new_value [BasicObject, nil] the new value
+    # @param mode [Symbol, nil] the transfer mode, or nil to use the atom's default mode
+    # @param timeout [Numeric, nil] the maximum number of seconds to wait
+    # @yield called when the timeout expires
+    # @return [BasicObject, nil] the stored value or the fallback result
+    def store(new_value, mode: nil, timeout: nil, &)
+      check_frozen!
+      new_value = wrap_value(new_value, mode:)
+      unwrap_result(@atom.store(new_value, timeout:) { TIMED_OUT }, &)
+    end
+
+    # Replace the current value and return the previous value.
+    # @!macro modes
+    # @param new_value [BasicObject, nil] the new value
+    # @param mode [Symbol, nil] the transfer mode, or nil to use the atom's default mode
+    # @param timeout [Numeric, nil] the maximum number of seconds to wait
+    # @yield called when the timeout expires
+    # @return [BasicObject, nil] the previous value or the fallback result
+    def swap(new_value, mode: nil, timeout: nil, &)
+      check_frozen!
+      new_value = wrap_value(new_value, mode:)
+      unwrap_result(@atom.swap(new_value, timeout:) { TIMED_OUT }, &)
+    end
+
+    # Compute and store a value if the current value is nil.
+    # @!macro modes
+    # @param mode [Symbol, nil] the transfer mode, or nil to use the atom's default mode
+    # @param timeout [Numeric, nil] the maximum number of seconds to wait
+    # @yield computes the value to store when the current value is nil
+    # @yieldreturn [BasicObject, nil] the value to store
+    # @return [BasicObject, nil] the current or newly stored value, or nil when the timeout expires
+    def store_if_absent(mode: nil, timeout: nil)
+      raise LocalJumpError, "no block given" unless block_given?
+      check_frozen!
+
+      result = @atom.update(timeout:) do |current|
+        next current unless NIL_VALUE.equal?(current)
+
+        value = yield
+        check_frozen!
+        wrap_value(value, mode:)
+      end
+      unwrap_value(result)
+    end
+
+    # Atomically replace the current value if it matches the expected value.
+    # @!macro modes
+    # @param expected [BasicObject, nil] the value to compare with the current value
+    # @param new_value [BasicObject, nil] the replacement value
+    # @param mode [Symbol, nil] the replacement's transfer mode, or nil to use the atom's default mode
+    # @param timeout [Numeric, nil] the maximum number of seconds to wait
+    # @return [Boolean] whether the value was replaced
+    def compare_and_set(expected, new_value, mode: nil, timeout: nil)
+      check_frozen!
+      expected = wrap_comparison(expected)
+      matched  = false
+
+      @atom.update(timeout:) do |current|
+        equal = values_equal?(current, expected)
+        check_frozen!
+        next current unless equal
+
+        matched = true
+        wrap_value(new_value, mode:)
+      end
+      matched
+    end
+
+    # Atomically replace the current value with the result of a block.
+    # @!macro modes
+    # @param mode [Symbol, nil] the result's transfer mode, or nil to use the atom's default mode
+    # @param timeout [Numeric, nil] the maximum number of seconds to wait
+    # @yield receives the current value and computes its replacement
+    # @yieldparam current [BasicObject, nil] the current value
+    # @yieldreturn [BasicObject, nil] the replacement value
+    # @return [BasicObject, nil] the replacement value, or nil when the timeout expires
+    def update(mode: nil, timeout: nil)
+      raise LocalJumpError, "no block given" unless block_given?
+      check_frozen!
+      result = @atom.update(timeout:) do |current|
+        value = yield(unwrap_value(current))
+        check_frozen!
+        wrap_value(value, mode:)
+      end
+      unwrap_value(result)
+    end
+
+    # Store an initial value if the current value is nil, otherwise replace it with the result of a block.
+    # @!macro modes
+    # @param initial_value [BasicObject, nil] the value to store when the current value is nil
+    # @param mode [Symbol, nil] the transfer mode, or nil to use the atom's default mode
+    # @param timeout [Numeric, nil] the maximum number of seconds to wait
+    # @yield receives a non-nil current value and computes its replacement
+    # @yieldparam current [BasicObject] the current value
+    # @yieldreturn [BasicObject, nil] the replacement value
+    # @return [BasicObject, nil] the current replacement or initial value, or nil when the timeout expires
+    def upsert(initial_value, mode: nil, timeout: nil)
+      raise LocalJumpError, "no block given" unless block_given?
+      check_frozen!
+
+      result = @atom.update(timeout:) do |current|
+        if NIL_VALUE.equal?(current)
+          wrap_value(initial_value, mode:)
+        else
+          value = yield(unwrap_value(current))
+          check_frozen!
+          wrap_value(value, mode:)
+        end
+      end
+      unwrap_value(result)
+    end
+
+    # Wait until the current value no longer matches an expected value.
+    # @param expected [BasicObject, nil] the value to compare with the current value
+    # @param timeout [Numeric, nil] the maximum number of seconds to wait
+    # @yield called when the timeout expires
+    # @return [BasicObject, nil] the changed value or the fallback result
+    def wait_until_changed(expected, timeout: nil, &)
+      expected = wrap_comparison(expected)
+      deadline = Internal.timeout_deadline(timeout)
+
+      while true
+        current = @atom.get(timeout: Internal.remaining_timeout(deadline)) { TIMED_OUT }
+        return unwrap_result(current, &) if TIMED_OUT.equal?(current)
+        return unwrap_value(current) unless values_equal?(current, expected)
+
+        result = @atom.wait_until_changed(current, timeout: Internal.remaining_timeout(deadline)) { TIMED_OUT }
+        return unwrap_result(result, &) if TIMED_OUT.equal?(result)
+      end
+    end
+
+    # Wait until the current value is not nil.
+    # @param timeout [Numeric, nil] the maximum number of seconds to wait
+    # @yield called when the timeout expires
+    # @return [BasicObject, nil] the non-nil value or the fallback result
+    def wait_until_non_nil(timeout: nil, &) = wait_until_changed(nil, timeout:, &)
+
+    # @api private
+    def inspect_with(inspector)
+      super do
+        yield if block_given?
+        inspector.attribute(:mode, mode)
+      end
+    end
+
+    private
+
+    def freeze_backend = @atom
+
+    def wrap_value(value, mode: nil)
+      value.nil? ? NIL_VALUE : @manager.wrap(value, mode:)
+    end
+
+    def wrap_comparison(value)
+      mode = compare_by_identity? ? :local : :copy
+      wrap_value(value, mode:)
+    end
+
+    def unwrap_value(value)
+      return if NIL_VALUE.equal?(value)
+
+      @manager.unwrap(value)
+    end
+
+    def inspect_value(inspector, prefix = "value=")
+      value = @atom.value
+      value = nil if NIL_VALUE.equal?(value)
+      inspector.breakable if prefix
+
+      if @manager.managed_envelope?(value)
+        inspector.from_envelope(value, prefix)
+      else
+        inspector.text(prefix) if prefix
+        inspector.object(value)
+      end
+    end
+
+    def unwrap_result(result)
+      return unwrap_value(result) unless TIMED_OUT.equal?(result)
+
+      yield if block_given?
+    end
+
+    def values_equal?(left, right) = @manager.same_value?(left, right, identity: compare_by_identity?)
+  end
+end

data/lib/farce/class_mirror.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # Map Ruby classes to a parallel inheritance hierarchy.
+  # Undefined classes use the nearest defined ancestor's mirror.
+  # An optional block turns each lookup into a cached value for that source class.
+  #
+  # @example Specialize behavior with ordinary method inheritance
+  #   mirror = Farce::ClassMirror.new
+  #   mirror.define(Object) { def label = "object" }
+  #   mirror.define(Array) { def label = "array of #{super}" }
+  #   mirror[Array].new.label # => "array of object"
+  class ClassMirror
+    include Farce::Shareable::Tracked
+
+    # @param base_class [Class] the mirror for BasicObject
+    # @yieldparam mirror [Class] the nearest defined mirror class
+    # @yieldparam klass [Class] the class passed to {#[]}
+    # @yieldreturn [Object] a Ractor-shareable value to cache for klass
+    # @note The block must be convertible to a shareable proc.
+    def initialize(base_class = Class.new, &)
+      raise TypeError, "Class expected, got #{base_class.class}" unless base_class.is_a?(Class)
+      @mapping  = Strict::Map.new({ BasicObject => base_class })
+      @cache    = Strict::WeakKeyMap.new
+      @callback = block_given? ? Ractor.shareable_proc(&) : nil
+      super()
+    end
+
+    # @api private
+    def marshal_dump
+      raise TypeError, "class mirror callbacks cannot be marshaled" if @callback
+      [1, @mapping.to_h, frozen?]
+    end
+
+    # @api private
+    def marshal_load(data)
+      mapping, frozen     = Internal::MarshalSupport.payload(data, 2)
+      @mapping            = Strict::Map.new(mapping)
+      @cache              = Strict::WeakKeyMap.new
+      @callback           = nil
+      @farce_freeze_state = Internal::Flag.new(false)
+      publish_shareable
+      Internal::MarshalSupport.freeze(self, frozen)
+    end
+
+    # Look up a mirror or the cached result of the constructor block.
+    # @param klass [Class] the source class
+    # @return [Object] the mirror class or the block result
+    # @raise [TypeError] if klass is not a Class
+    def [](klass)
+      raise TypeError, "Class expected, got #{klass.class}" unless klass.is_a?(Class)
+      @cache.store_if_absent(klass) do
+        result = lookup(klass)
+        @callback ? @callback.call(result, klass) : result
+      end
+    end
+
+    # Define or extend a mirror class from the main Ractor.
+    # Missing ancestors are defined automatically. The block defines methods
+    # in an included module, so `super` can call earlier definitions.
+    # Existing lookup results are invalidated after each definition.
+    # @param klass [Class] the source class
+    # @yield evaluated as a module body
+    # @return [Class] the mirror class
+    # @raise [Ractor::IsolationError] outside the main Ractor
+    # @raise [TypeError] if klass is not a Class
+    def define(klass, &)
+      check_frozen!
+      raise Ractor::IsolationError, "must be called from main Ractor" unless Ractor.main?
+      raise TypeError, "Class expected, got #{klass.class}" unless klass.is_a?(Class)
+      mixin  = Module.new(&) if block_given?
+      mirror = @mapping.store_if_absent(klass) { Class.new(define(klass.superclass)) }
+      mirror.include(mixin) if mixin
+      @cache.clear
+      mirror
+    end
+
+    private
+
+    def lookup(klass)
+      raise TypeError, "Class expected, got #{klass.class}" unless klass.is_a?(Class)
+      @mapping.fetch(klass) { lookup(klass.superclass) }
+    end
+  end
+end

data/lib/farce/clock.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # Wrapper module for clock-related functionality.
+  # Converts everything to a monotonic clock time in seconds, from when `farce/clock` was loaded.
+  # @see Farce.clock
+  module Clock
+    extend self
+
+    CLOCK_MONOTONIC = Process::CLOCK_MONOTONIC
+    CUTOFF_CLOCK    = 600           # 10 minutes
+    CUTOFF_TIME     = 1_000_000_000 # September 9, 2001 or 31-ish years ¯\_(ツ)_/¯
+    MONOTONIC       = Process.clock_gettime(CLOCK_MONOTONIC)
+    REAL_TIME       = Process.clock_gettime(Process::CLOCK_REALTIME)
+    TIME_DIFF       = REAL_TIME - MONOTONIC
+    private_constant :CLOCK_MONOTONIC, :CUTOFF_CLOCK, :CUTOFF_TIME, :MONOTONIC, :REAL_TIME, :TIME_DIFF
+
+    # Converts the given value to a monotonic clock time in seconds, assuming that it already represents a clock time.
+    # Returns the current clock time if no value is given.
+    #
+    # Same as calling {#parse parse(clock: value)}
+    #
+    # @param value [nil, #to_f] the value to convert to clock time
+    # @raise [ArgumentError] if the resulting clock time is NaN
+    # @return [Float] the clock time in seconds
+    def clock(value) = validate_timestamp(value ? value.to_f : current)
+
+    # Returns the current monotonic clock time in seconds.
+    # @return [Float] the clock time in seconds
+    def current = Process.clock_gettime(CLOCK_MONOTONIC) - MONOTONIC
+
+    # Converts the given value to a monotonic clock time in seconds.
+    #
+    # @param value [nil, Numeric, Time, ActiveSupport::Duration, Hash]
+    #   The value to convert to clock time
+    #
+    #   If the value is `nil`, it is treated as the current time.
+    #
+    #   ActiveSupport durations are relative offsets when the ActiveSupport integration is loaded.
+    #
+    #   Other numeric values use the following cutoffs:
+    #   * Up to 600 (10 minutes): Offsets from the current time.
+    #   * Greater than 600, up to one billion: Clock times (like the value returned by {#current}).
+    #   * Greater than one billion: UNIX timestamps (like the value returned by `Time.now.to_f`).
+    #
+    #   Hashes may contain up to one key-value pair, with the key being one of the following:
+    #   * `:at`, `:time`, or `:timeout_at` for {#time fixed times}
+    #   * `:delay`, `:in`, `:offset`, `:timeout`, or `:wait` for {#offset relative offsets}
+    #   * `:clock` for {#clock clock times}
+    #
+    # @raise [ArgumentError] if the resulting clock time is NaN
+    # @return [Float] the clock time in seconds
+    def parse(value = nil)
+      case value
+      when nil, UNDEFINED then return current
+      when Float, Integer then return value > CUTOFF_CLOCK ? time(value) : offset(value)
+      when Time           then return time(value)
+      when Hash
+        case value.size
+        when 0 then return current
+        when 1
+          return time(value[:at]) if value.key?(:at)
+          method = argument = nil
+          value.each_pair { |key, option| method, argument = key, option }
+          return public_send(method, argument)
+        end
+      else
+        return at(value.to_time) if value.respond_to?(:to_time)
+        return parse(value.to_f) if value.is_a?(Numeric)
+      end
+      raise TypeError, "Cannot convert #{value.inspect} to clock time"
+    end
+
+    # Converts the given value to a monotonic clock time in seconds.
+    # The value is assumed to be a fixed point in time (independent of the current time).
+    #
+    # If the value is numeric and greater than one billion, it is treated as a UNIX timestamp.
+    # Meaning that you can't pass a clock time greater than 31 years, or a timestamp before September 9, 2001.
+    #
+    # @param value [Numeric, Time] the value to convert to clock time
+    # @raise [ArgumentError] if the resulting clock time is NaN
+    # @return [Float] the clock time in seconds
+    def time(value)
+      case value
+      when Float, Integer then timestamp = value > CUTOFF_TIME ? value - REAL_TIME : Float(value)
+      when Time           then timestamp = value.to_f - REAL_TIME
+      when Numeric        then return time(value.to_f)
+      else raise TypeError, "Cannot convert #{value.class} to clock time"
+      end
+      validate_timestamp(timestamp)
+    end
+
+    # Converts the given value to a monotonic clock time in seconds.
+    # The value is assumed to be a relative offset from the current time.
+    #
+    # @param value [Numeric] the value to convert to clock time
+    # @raise [ArgumentError] if the resulting clock time is NaN
+    # @return [Float] the clock time in seconds
+    def offset(value)
+      return validate_timestamp(current + value.to_f) if value.is_a?(Numeric)
+      raise TypeError, "Cannot convert #{value.class} to clock time"
+    end
+
+    alias now        current
+    alias at         time
+    alias timeout_at time
+    alias delay      offset
+    alias in         offset
+    alias timeout    offset
+    alias wait       offset
+
+    private
+
+    def validate_timestamp(timestamp)
+      raise ArgumentError, "timestamp must not be NaN" if timestamp.nan?
+      timestamp
+    end
+  end
+end