farce 0 → 0.1.0

data/lib/farce/unshared/weak_set.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Unshared
+    # A thread-safe set that retains mutable elements weakly within one Ractor.
+    class WeakSet < Farce::Abstract::WeakSet
+      include Unshareable
+
+      private def new_map(...) = Farce::Unshared::WeakMap.new(...)
+    end
+  end
+end

data/lib/farce/unshared/weak_value_map.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Unshared
+    # A thread-safe map with weak values for use within one Ractor.
+    #
+    # @example Caching a mutable value without keeping it alive
+    #   value = []
+    #   map   = Farce::Unshared::WeakValueMap.new({ result: value })
+    #   map[:result].equal?(value) # => true
+    #
+    #   # The entry can disappear once its value is collected.
+    #   value = nil
+    class WeakValueMap < Abstract::WeakValueMap
+      include Unshareable
+
+      def initialize(
+        initial_mapping = nil,
+        normalize_keys: nil,
+        compare_by_identity: false,
+        compare_keys_by_identity: compare_by_identity,
+        compare_values_by_identity: compare_by_identity
+      )
+        initial_mapping = convert_entries(initial_mapping)
+        restoring  = Internal::KeyNormalizer.restoration?(normalize_keys)
+        normalizer = Internal::KeyNormalizer.build(normalize_keys, shareable: false)
+        populate   = initial_mapping && ((normalizer && !restoring) || !initial_mapping.is_a?(Hash))
+        @map       = Internal::UnsharedWeakValueMap.new(
+          populate ? nil : initial_mapping,
+          compare_by_identity:,
+          compare_keys_by_identity:,
+          compare_values_by_identity:,
+        )
+        Internal::KeyNormalizer.install_concurrent(self, normalizer) unless restoring
+        initial_mapping.each { |key, value| self[key] = value } if populate
+        Internal::KeyNormalizer.install_concurrent(self, normalizer) if restoring
+        super()
+      end
+    end
+  end
+end

data/lib/farce/unshared.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # Thread-safe containers for values used within one Ractor.
+  module Unshared
+    include Internal::Autoloads
+
+    # @overload enfarce(object, freeze: nil)
+    #   Converts vanilla Ruby objects into their {Farce::Unshared} equivalents.
+    #
+    #   @example
+    #     Farce::Unshared.enfarce({ foo: ["bar"] })
+    #     # =>  #<Farce::Unshared::Map {foo: #<Farce::Unshared::Vector ["bar"]>}>
+    #
+    #   @yield [object] Optional block, called with any object that doesn't have a specific conversion defined.
+    #   @yieldparam object [BasicObject] the object to convert
+    #   @yieldreturn [BasicObject] the converted object
+    #   @param object [BasicObject] The root object to convert
+    #   @param freeze [Boolean, nil]
+    #     Whether to freeze the converted objects.
+    #     If set to `nil` (default), the freezing behavior will depend on the original object's frozen state.
+    #   @return [BasicObject] the converted object
+    #   @see Farce.enfarce
+    def self.enfarce(object, **, &) = Internal::Converter.new(self, **, &).convert(object)
+  end
+end

data/lib/farce/vector.rb

@@ -0,0 +1,228 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # A Ractor-shareable vector with transfer modes for mutable values.
+  # Values stored through this vector's mode manager are automatically unwrapped.
+  #
+  # @example Atomically updating a collection
+  #   vector = Farce::Vector.new([[]], mode: :make_shareable)
+  #   vector.update(0) { |jobs| jobs + [:finished] } # => [:finished]
+  #
+  # @!method append(value, mode: nil, timeout: nil)
+  #   Append one value using the same options as {#push}.
+  #   @param value [BasicObject] The value to append.
+  #   @param mode [Symbol, nil] The transfer mode, or nil to use the default.
+  #   @param timeout [Numeric, nil] The maximum wait in seconds. Nil waits indefinitely.
+  #   @return [self, false] Self on success, or false on timeout.
+  class Vector < Farce::Abstract::Vector
+    include Shareable::Delegated
+
+    # @!macro modes
+    # @param source [Array, nil] Initial values. The source array is not retained.
+    # @param mode [Symbol] The default value transfer mode.
+    # @param compare_by_identity [Boolean] Whether values are compared by identity.
+    def initialize(source = nil, mode: :copy, compare_by_identity: false)
+      raise TypeError, "source must be an Array" unless source.nil? || source.is_a?(Array)
+      unless true.equal?(compare_by_identity) || false.equal?(compare_by_identity)
+        raise ArgumentError, "compare_by_identity must be true or false"
+      end
+
+      @compare_by_identity = compare_by_identity
+      @manager = ModeManager.new(mode:)
+      @vector = Internal::Vector.new(source&.map { @manager.wrap(it) }, compare_by_identity: true)
+      super()
+    end
+
+    # @api private
+    def transaction_wrapper(transaction) = Transaction::Vector.new(transaction, self, @vector, manager: @manager)
+
+    # @return [Symbol] The default transfer mode.
+    def mode = @manager.mode
+
+    # @api private
+    def marshal_dump
+      entries = @vector.snapshot.map { Internal::MarshalSupport.value(it) }
+      [1, entries, @manager, compare_by_identity?, frozen?]
+    end
+
+    # @api private
+    def marshal_load(data)
+      entries, @manager, identity, frozen = Internal::MarshalSupport.payload(data, 4)
+      @compare_by_identity = identity
+      @vector = Internal::Vector.new(compare_by_identity: true)
+      publish_shareable
+      entries.each { @vector.push(Internal::MarshalSupport.restore_value(it)) }
+      Internal::MarshalSupport.freeze(self, frozen)
+    end
+
+    # (see Farce::Abstract::Vector#compare_by_identity?)
+    def compare_by_identity? = @compare_by_identity
+
+    # (see Farce::Abstract::Vector#shareable_values?)
+    def shareable_values? = true
+
+    # (see Farce::Abstract::Vector#[])
+    def [](index) = @manager.unwrap(@vector[index])
+
+    # (see Farce::Abstract::Vector#[]=)
+    def []=(index, value)
+      check_frozen!
+      @vector[index] = @manager.wrap(value)
+      value
+    end
+
+    # (see Farce::Abstract::Vector#get)
+    def get(index, timeout: nil) = @manager.unwrap(@vector.get(index, timeout:))
+
+    # (see Farce::Abstract::Vector#store)
+    # @param mode [Symbol, nil] The transfer mode, or nil to use the default.
+    def store(index, value, mode: nil, timeout: nil)
+      check_frozen!
+      @manager.unwrap(@vector.store(index, @manager.wrap(value, mode:), timeout:))
+    end
+
+    # (see Farce::Abstract::Vector#push)
+    # @param mode [Symbol, nil] The transfer mode, or nil to use the default.
+    def push(value, mode: nil, timeout: nil)
+      check_frozen!
+      @vector.push(@manager.wrap(value, mode:), timeout:) ? self : false
+    end
+
+    # (see Farce::Abstract::Vector#pop)
+    def pop(timeout: nil) = @manager.unwrap(@vector.pop(timeout:))
+
+    # (see Farce::Abstract::Vector#swap)
+    # @!macro modes
+    # @param mode [Symbol, nil] The replacement's transfer mode, or nil to use the default.
+    def swap(index, replacement, mode: nil, timeout: nil)
+      check_frozen!
+      @manager.unwrap(@vector.swap(index, @manager.wrap(replacement, mode:), timeout:))
+    end
+
+    # (see Farce::Abstract::Vector#store_if_absent)
+    # @param mode [Symbol, nil] The result's transfer mode, or nil to use the default.
+    def store_if_absent(index, mode: nil, timeout: nil)
+      raise LocalJumpError, "no block given" unless block_given?
+      check_frozen!
+      @manager.unwrap(@vector.store_if_absent(index, timeout:) do
+        value = yield
+        check_frozen!
+        @manager.wrap(value, mode:)
+      end)
+    end
+
+    # (see Farce::Abstract::Vector#update)
+    # @!macro modes
+    # @param mode [Symbol, nil] The result's transfer mode, or nil to use the default.
+    def update(index, mode: nil, timeout: nil)
+      raise LocalJumpError, "no block given" unless block_given?
+      check_frozen!
+      @manager.unwrap(@vector.update(index, timeout:) do |current|
+        value = yield(@manager.unwrap(current))
+        check_frozen!
+        @manager.wrap(value, mode:)
+      end)
+    end
+
+    # (see Farce::Abstract::Vector#upsert)
+    # @!macro modes
+    # @param mode [Symbol, nil] The value transfer mode, or nil to use the default.
+    def upsert(index, initial, mode: nil, timeout: nil)
+      raise LocalJumpError, "no block given" unless block_given?
+      check_frozen!
+      @manager.unwrap(@vector.update(index, timeout:) do |current|
+        value = if nil.equal?(current)
+                  initial
+                else
+                  yielded = yield(@manager.unwrap(current))
+                  check_frozen!
+                  yielded
+                end
+        @manager.wrap(value, mode:)
+      end)
+    end
+
+    # (see Farce::Abstract::Vector#compare_and_set)
+    # @!macro modes
+    # @param mode [Symbol, nil] The replacement's transfer mode, or nil to use the default.
+    def compare_and_set(index, expected, replacement, mode: nil, timeout: nil)
+      check_frozen!
+      deadline = timeout_deadline(timeout)
+      expected = wrap_comparison(expected)
+      wrapped = false
+      loop do
+        current = @vector[index]
+        equal   = values_equal?(current, expected)
+        check_frozen!
+        return false unless equal
+        unless wrapped
+          replacement = @manager.wrap(replacement, mode:)
+          wrapped = true
+        end
+        return true if @vector.compare_and_set(index, current, replacement, timeout: remaining_timeout(deadline))
+        return false if nil.equal?(current) || (deadline && Clock.now >= deadline)
+      end
+    end
+
+    # (see Farce::Abstract::Vector#wait_until_changed)
+    def wait_until_changed(index, expected, timeout: nil)
+      deadline = timeout_deadline(timeout)
+      expected = wrap_comparison(expected)
+      loop do
+        current = @vector[index]
+        return @manager.unwrap(current) unless values_equal?(current, expected)
+        return if deadline && Clock.now >= deadline
+        @vector.wait_until_changed(index, current, timeout: remaining_timeout(deadline))
+      end
+    end
+
+    # (see Farce::Abstract::Vector#wait_until_non_nil)
+    def wait_until_non_nil(index, timeout: nil) = @manager.unwrap(@vector.wait_until_non_nil(index, timeout:))
+
+    protected
+
+    def logical_value(value) = @manager.unwrap(value)
+
+    def build_derived_vector(values)
+      self.class.allocate.initialize_derived_vector(values, @manager, @compare_by_identity)
+    end
+
+    def initialize_derived_vector(values, manager, compare_by_identity)
+      @manager = manager
+      @compare_by_identity = compare_by_identity
+      @vector = Internal::Vector.new(values, compare_by_identity: true)
+      publish_shareable
+    end
+
+    attr_reader :manager
+
+    def reusable_operand_snapshot(other)
+      return unless other.is_a?(Farce::Vector)
+      return unless other.manager.equal?(@manager)
+      other.internal_vector.snapshot
+    end
+
+    private
+
+    def inspect_value(inspector, value) = super(inspector, value, @manager)
+    def derived_storage(value)          = @manager.wrap(value)
+    def freeze_backend                  = @vector
+    def wrap_comparison(value)          = @manager.wrap(value, mode: compare_by_identity? ? :local : :copy)
+    def values_equal?(left, right)      = @manager.same_value?(left, right, identity: compare_by_identity?)
+
+    def timeout_deadline(timeout)
+      return if timeout.nil?
+      timeout = Float(timeout)
+      raise ArgumentError, "timeout must be finite and non-negative" unless timeout.finite? && !timeout.negative?
+      Clock.now + timeout
+    end
+
+    def remaining_timeout(deadline)
+      return unless deadline
+      remaining = deadline - Clock.now
+      remaining.negative? ? 0 : remaining
+    end
+  end
+end

data/lib/farce/version.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # @return [String] the current version of Farce
+  VERSION = "0.1.0"
+end

data/lib/farce/walker/definitions.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  class Walker
+    define(BasicObject) do |object, walker|
+      names = send_to(object, :instance_variables)
+      next object if names.empty?
+      unless walker.modify
+        names.each { walker.visit(send_to(object, :instance_variable_get, it)) }
+        next object
+      end
+      values = names.map { send_to(object, :instance_variable_get, it) }
+      walker.update(object, values) do |target, results|
+        names.each_with_index do |name, index|
+          next if send_to(target, :instance_variable_get, name).equal?(results[index])
+          send_to(target, :instance_variable_set, name, results[index])
+        end
+        target
+      end
+    end
+
+    define(Module) do |object, walker|
+      if walker.constants
+        inherit = walker.constants == :inherited
+        constant_names = Internal.walker_constants(object, inherit).reject { object.autoload?(it, inherit) }
+        values = constant_names.map { object.const_get(it, inherit) }
+        object = walker.update(object, values) do |target, results|
+          constant_names.each_with_index do |name, index|
+            target.const_set(name, results[index]) unless target.const_get(name, inherit).equal?(results[index])
+          end
+          target
+        end
+      end
+      if walker.class_variables
+        variable_names = object.class_variables(walker.class_variables == :inherited)
+        values = variable_names.map { object.class_variable_get(it) }
+        object = walker.update(object, values) do |target, results|
+          variable_names.each_with_index do |name, index|
+            unless target.class_variable_get(name).equal?(results[index])
+              target.class_variable_set(name,
+                results[index])
+            end
+          end
+          target
+        end
+      end
+      super(object, walker)
+    end
+
+    define(Internal::Atom, Abstract::Atom) do |object, walker|
+      walker.update(object, [object.value]) do |target, results|
+        target.value = results.first unless target.value.equal?(results.first)
+        target
+      end
+    end
+
+    define(Array, Internal::Vector, Abstract::Vector) do |object, walker|
+      unless walker.modify
+        values = Internal::Vector === object ? object.snapshot : object
+        values.each { walker.visit(it) }
+        next(Array === object ? super(object, walker) : object)
+      end
+      values = Internal::Vector === object ? object.snapshot : object.to_a
+      result = walker.update(object, values) do |target, results|
+        results.each_with_index { |value, index| target[index] = value unless target[index].equal?(value) }
+        target
+      end
+      Array === object ? super(result, walker) : result
+    end
+
+    define(::Set, Abstract::Set) do |object, walker|
+      unless walker.modify
+        object.each { walker.visit(it) }
+        next object
+      end
+      walker.update(object, object.to_a, hash_keys: !object.compare_by_identity?) do |target, results|
+        results.each { walker.check_hash_key(it) } unless target.compare_by_identity?
+        target.clear
+        results.each { target.add(it) }
+        target
+      end
+    end
+
+    define(Hash, Abstract::Map) do |object, walker|
+      unless walker.modify
+        object.each do |key, value|
+          walker.visit(key)
+          walker.visit(value)
+        end
+        next(Hash === object ? super(object, walker) : object)
+      end
+      values = object.each.flat_map { |key, value| [key, value] }
+      identity = Hash === object ? object.compare_by_identity? : object.compare_keys_by_identity?
+      result = walker.update(object, values, hash_keys: !identity, key_stride: 2) do |target, results|
+        results.each_slice(2) { |key, _| walker.check_hash_key(key) } unless identity
+        target.clear
+        results.each_slice(2) { |key, value| target[key] = value }
+        target
+      end
+      Hash === object ? super(result, walker) : result
+    end
+
+    define(Abstract::ConcurrentMap) do |object, walker|
+      values = object.each.flat_map { |key, value| [key, value] }
+      walker.update(object, values, hash_keys: !object.compare_keys_by_identity?, key_stride: 2) do |target, results|
+        if !target.compare_keys_by_identity? && values.each_slice(2).any? { |key, _| walker.changed?(key) }
+          results.each_slice(2) { |key, _| walker.check_hash_key(key) }
+          target.clear
+          results.each_slice(2) { |key, value| target[key] = value }
+          next target
+        end
+        entries = []
+        values.each_slice(2).with_index do |(key, value), index|
+          new_key, result = results[index * 2, 2]
+          walker.check_hash_key(new_key) unless target.compare_keys_by_identity?
+          if !key.equal?(new_key)
+            entries << [key, new_key, result]
+          elsif !value.equal?(result)
+            until target.compare_and_set(key, value, result)
+              value = target[key]
+              result = walker.visit(value)
+            end
+          end
+        end
+        entries.each { |key, _, _| target.delete(key) }
+        entries.each { |_, key, value| target[key] = value } # rubocop:disable Style/CombinableLoops
+        target
+      end
+    end
+
+    define(Abstract::LeaseMap) do |object, walker|
+      object.auto_lease do
+        values = object.keys.flat_map { |key| [key, object[key]] }
+        walker.update(object, values, hash_keys: !object.compare_keys_by_identity?, key_stride: 2) do |target, results|
+          target.auto_lease do
+            results.each_slice(2) { |key, _| walker.check_hash_key(key) } unless target.compare_keys_by_identity?
+            values.each_slice(2).with_index do |(key, _), index|
+              target.delete(key) unless key.equal?(results[index * 2])
+            end
+            results.each_slice(2) { |key, value| target[key] = value }
+          end
+          target
+        end
+      end
+    end
+
+    define(Abstract::Lease) do |object, walker|
+      value = object.checkout
+      checked_out = true
+      walker.update(object, [value]) do |target, results|
+        unless checked_out
+          value = target.checkout
+          checked_out = true
+        end
+        begin
+          target.checkin(results.first)
+          checked_out = false
+          target
+        ensure
+          if checked_out
+            target.checkin(value)
+            checked_out = false
+          end
+        end
+      end
+    ensure
+      object.checkin(value) if checked_out
+      checked_out = false
+    end
+
+    define(Proc) do |object, walker|
+      if Internal.rebindable?(object)
+        object = walker.update(object, [object.binding.receiver]) do |target, results|
+          Farce.rebind(target, self: results.first)
+        end
+      end
+      super(object, walker)
+    end
+
+    define(Data) do |object, walker|
+      walker.rebuild_data(object)
+    end
+  end
+end