farce 0.5.0-aarch64-linux-gnu → 0.6.0-aarch64-linux-gnu

data/lib/farce/local/counter.rb

@@ -50,19 +50,13 @@ module Farce
 
       # Increment the counter atomically.
       # @param by [Numeric, String, #to_int] the amount, converted to an Integer
-      # @return [self]
-      def increment(by = 1)
-        internal_counter.increment(by)
-        self
-      end
+      # @return [Integer] the value produced by this atomic update
+      def increment(by = 1) = internal_counter.increment(by)
 
       # Decrement the counter atomically.
       # @param by [Numeric, String, #to_int] the amount, converted to an Integer
-      # @return [self]
-      def decrement(by = 1)
-        internal_counter.decrement(by)
-        self
-      end
+      # @return [Integer] the value produced by this atomic update
+      def decrement(by = 1) = internal_counter.decrement(by)
 
       alias subtract decrement
       alias remove   decrement

data/lib/farce/map.rb

@@ -48,7 +48,14 @@ module Farce
 
     private
 
-    def new_map(**)    = Internal::StrictMap.new(**)
+    def new_map(
+      compare_by_identity:        false,
+      compare_keys_by_identity:   compare_by_identity,
+      compare_values_by_identity: compare_by_identity
+    )
+      Internal::StrictMap.new(compare_by_identity:, compare_keys_by_identity:, compare_values_by_identity:)
+    end
+
     def freeze_backend = @map
 
     Internal.prepare_map_access(self, :modes)

data/lib/farce/memoize.rb

@@ -77,7 +77,8 @@ module Farce
   #
   #     @param mode [Symbol]
   #       The mode of the memoization. Ignored for any scope other than `:global`.
-  #       Defaults to `:raise` with `weak: true`, which supports only `:raise`, `:make_shareable`, and `:dedup`.
+  #       Use `:strict` to cache shareable results directly, including with `weak: true`.
+  #       Defaults to `:raise` with `weak: true`, which also supports `:make_shareable` and `:dedup`.
   #
   #     @param weak [Boolean]
   #       Whether to use weak memoization.
@@ -159,9 +160,13 @@ module Farce
 
         case scope
         when :global
-          modes = weak ? Internal::WeakModeManager::MODES : MODES
-          raise ArgumentError, "unsupported mode: #{mode.inspect}" unless modes.include?(mode)
-          init = "::Farce::#{atom_class}.new(mode: #{mode.inspect})"
+          if mode == :strict
+            init = "::Farce::Strict::#{atom_class}.new"
+          else
+            modes = weak ? Internal::WeakModeManager::MODES : MODES
+            raise ArgumentError, "unsupported mode: #{mode.inspect}" unless modes.include?(mode)
+            init = "::Farce::#{atom_class}.new(mode: #{mode.inspect})"
+          end
           args = methods.join(", ")
           args += ", mode: #{mode.inspect}" unless mode == :smart
         when :unshared
@@ -187,7 +192,7 @@ module Farce
           initializer << "  #{ivar} = #{init}\n"
           module_eval <<~RUBY, __FILE__, __LINE__ + 1
             #{visibility} def #{method}
-              value = #{ivar}.store_if_absent do
+              value = #{ivar}.value || #{ivar}.store_if_absent do
                 result = super()
                 nil.equal?(result) ? NIL_VALUE : result
               end

data/lib/farce/shareable.rb

@@ -13,6 +13,9 @@ module Farce
   #   object = MyClass.new
   #   Ractor.shareable?(object) # => true
   module Shareable
+    # @api private
+    def self.included(base) = Internal.prepare_shareable_class(base)
+
     # A structurally frozen wrapper whose logical frozen state is owned by its backend.
     # The including class must implement a private `freeze_backend` method.
     #

data/lib/farce/strict/weak_cache.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Strict
+    # A weak cache that allows reusing previously generated values without holding strong references to them.
+    # Only shareable keys and values can be used.
+    #
+    # @example
+    #   cache = Farce::Strict::WeakCache.new
+    #   value = cache.store_if_absent(:key) { ExpensiveClass.new.freeze }
+    class WeakCache
+      include Shareable::Delegated
+      include Internal::Inspect
+
+      # Creates a new WeakCache instance if it outperforms {Strict::WeakValueMap} on the current platform.
+      # Otherwise it creates a standard WeakValueMap instance.
+      # @return [WeakCache, Strict::WeakValueMap] The created cache instance.
+      def self.create(...) = Internal.native_weak_maps? ? Strict::WeakValueMap.new(...) : WeakCache.new(...)
+
+      # @param initial_mapping [Hash, Farce::Abstract::Map, #each, nil]
+      #   The entries to store initially. Each iteration must yield a key-value pair.
+      #   Nil creates an empty map.
+      # @param compare_by_identity [Boolean]
+      #   Whether keys use object identity instead of `hash` and `eql?`.
+      def initialize(initial_mapping = nil, compare_by_identity: false)
+        @map = Strict::WeakValueMap.new(initial_mapping, compare_keys_by_identity: compare_by_identity)
+        initialize_cache
+        super()
+      end
+
+      # @api private
+      def marshal_dump = [1, @map]
+
+      # @api private
+      def marshal_load(data)
+        @map, = Internal::MarshalSupport.payload(data, 1)
+        initialize_cache
+        publish_shareable
+      end
+
+      # Retrieves or stores a value for the given key.
+      # The block is called to generate the value if the key is absent.
+      # Concurrent calls for the same key reuse the generated value.
+      # Once that value is collected, a later call generates it again.
+      #
+      # @param key [BasicObject] The key to look up.
+      # @yield Called without arguments when the key is absent.
+      # @yieldreturn [BasicObject] The value to store and return.
+      # @return [BasicObject] The associated value.
+      def store_if_absent(key, &)
+        raise LocalJumpError, "no block given" unless block_given?
+        @cache.store_if_absent(key, &)
+      end
+
+      alias compute_if_absent store_if_absent
+
+      # Store a value only when the key is absent.
+      # Existing nil and false values count as present.
+      # @param key [BasicObject] The key to look up or store.
+      # @param value [BasicObject] The value to store if the key is absent.
+      # @return [BasicObject, nil] The existing value, or nil when a value was inserted.
+      def put_if_absent(key, value)
+        inserted = false
+        previous = store_if_absent(key) do
+          inserted = true
+          value
+        end
+        inserted ? nil : previous
+      end
+
+      # Look up a value without generating it.
+      # @param key [BasicObject] The key to look up.
+      # @return [BasicObject, nil] The associated value, or nil if the key is absent.
+      def [](key) = @cache.fetch(key) { nil } # rubocop:disable Style/RedundantFetchBlock
+
+      # Return a lookup key and its associated value if present.
+      # @param key [BasicObject] The key to look up.
+      # @return [Array(BasicObject, BasicObject), nil] The pair `[key, value]`, or nil if the key is absent.
+      def assoc(key)
+        value = fetch(key) { return nil }
+        [key, value]
+      end
+
+      # Return whether a live entry exists, including entries with nil or false values.
+      # @param key [BasicObject] The key to look up.
+      # @return [Boolean]
+      def key?(key)
+        @cache.fetch(key) { return false }
+        true
+      end
+
+      alias has_key? key?
+      alias include? key?
+      alias member?  key?
+
+      # Look up a value in nested maps or arrays.
+      # @param key [BasicObject] The key to look up.
+      # @param rest [Array<BasicObject>] Additional keys or indices for the nested value.
+      # @return [BasicObject, nil] The nested value, or nil if an intermediate value is absent or nil.
+      def dig(key, *rest)
+        value = self[key]
+        return value if rest.empty? || value.nil?
+        value.dig(*rest)
+      end
+
+      # Return the stored key matching a lookup key.
+      # @param key [BasicObject] The key to look up.
+      # @return [BasicObject, nil] The stored key, or nil if the key is absent.
+      def getkey(key) = @map.getkey(key)
+
+      # Fetch the value associated with a key, using the same missing-key behavior as Hash#fetch.
+      # If both a default and a block are provided, the block takes precedence.
+      #
+      # @overload fetch(key)
+      #   @param key [BasicObject] The key to look up.
+      #   @return [BasicObject] The associated value.
+      #   @raise [KeyError] If the key is absent.
+      #
+      # @overload fetch(key, default)
+      #   @param key [BasicObject] The key to look up.
+      #   @param default [BasicObject] The value to return if the key is absent.
+      #   @return [BasicObject] The associated value or `default`.
+      #
+      # @overload fetch(key)
+      #   @param key [BasicObject] The key to look up.
+      #   @yield [key] Called if the key is absent.
+      #   @yieldparam key [BasicObject] The missing key.
+      #   @yieldreturn [BasicObject] The value to return.
+      #   @return [BasicObject] The associated value or the block result.
+      def fetch(*arguments)
+        unless arguments.length.between?(1, 2)
+          raise ArgumentError, "wrong number of arguments (given #{arguments.length}, expected 1..2)"
+        end
+
+        key, default = arguments
+        warn "block supersedes default value argument", uplevel: 1 if block_given? && arguments.length == 2
+        @cache.fetch(key) do
+          return yield(key) if block_given?
+          return default if arguments.length == 2
+          raise KeyError.new("key not found: #{key.inspect}", receiver: self, key: key)
+        end
+      end
+
+      # Fetch values in the requested order, using {#fetch} for missing keys.
+      # @param keys [Array<BasicObject>] The keys to look up.
+      # @yield [key] Called for each missing key.
+      # @yieldparam key [BasicObject] The missing key.
+      # @yieldreturn [BasicObject] The fallback value, which is not stored.
+      # @return [Array<BasicObject>] The associated values or block results.
+      def fetch_values(*keys, &) = keys.map { fetch(it, &) }
+
+      # Look up values in the requested order, returning nil for missing keys.
+      # @param keys [Array<BasicObject>] The keys to look up.
+      # @return [Array<BasicObject>] The associated values, with nil for missing keys.
+      def values_at(*keys) = keys.map { self[it] }
+
+      # @return [Boolean] Whether keys are compared by identity instead of `hash` and `eql?`.
+      def compare_keys_by_identity? = @map.compare_keys_by_identity?
+
+      # (see #compare_keys_by_identity?)
+      def compare_by_identity? = compare_keys_by_identity?
+
+      # @return [Boolean] Whether keys must be Ractor-shareable, including copied mutable strings.
+      def shareable_keys? = true
+
+      # @return [Boolean] Whether values must be Ractor-shareable.
+      def shareable_values? = true
+
+      # @return [Boolean] Whether keys are referenced weakly.
+      def weak_keys? = false
+
+      # @return [Boolean] Whether values are referenced weakly.
+      def weak_values? = true
+
+      # @api private
+      def inspect_with(inspector)
+        super do
+          yield if block_given?
+          inspector.breakable
+          inspector.group("{", "}") do
+            inspector.breakable ""
+            inspector.seplist(@map, nil, :each) do |key, value|
+              inspector.group { inspector.hash_pair(key, value) }
+            end
+          end
+        end
+      end
+
+      alias to_s inspect
+
+      private
+
+      def initialize_cache = @cache = Internal.native_weak_maps? ? @map : Internal::WeakCacheMirror.new(@map)
+      def freeze_backend   = @map
+    end
+  end
+end

data/lib/farce/vector.rb

@@ -26,14 +26,15 @@ module Farce
     # @raise [ArgumentError] If the size is negative.
     def initialize(source = nil, mode: :smart, compare_by_identity: false)
       source = normalize_vector_source(source)
-      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
+      raise TypeError, "source must be an Array" unless source.nil? || Integer === source || source.is_a?(Array)
 
-      @compare_by_identity = compare_by_identity
+      @compare_by_identity = compare_by_identity ? true : false
       @manager = ModeManager.new(mode:)
-      @vector = Internal::Vector.new(source&.map { @manager.wrap(it) }, compare_by_identity: true)
+      if source && !(Integer === source)
+        source = source.map { @manager.wrap(it) }
+        raise TypeError, "source must be an Array" unless source.nil? || source.is_a?(Array)
+      end
+      @vector = Internal::Vector.new_for_modes(source)
       super()
     end
 
@@ -53,7 +54,7 @@ module Farce
     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)
+      @vector = Internal::Vector.new_for_modes(nil)
       publish_shareable
       entries.each { @vector.push(Internal::MarshalSupport.restore_value(it)) }
       Internal::MarshalSupport.freeze(self, frozen)

data/lib/farce/version.rb

@@ -4,5 +4,5 @@
 
 module Farce
   # @return [String] the current version of Farce
-  VERSION = "0.5.0"
+  VERSION = "0.6.0"
 end

data/lib/farce/walker/definitions.rb

@@ -190,6 +190,24 @@ module Farce
       super(object, walker)
     end
 
+    define(Struct) do |object, walker|
+      result = walker.update(object, object.to_a) do |target, results|
+        results.each_with_index { |value, index| target[index] = value unless target[index].equal?(value) }
+        target
+      end
+      super(result, walker)
+    end
+
+    define(Range) do |object, walker|
+      names = object.instance_variables
+      values = [object.begin, object.end, *names.map { object.instance_variable_get(it) }]
+      walker.update(object, values) do |target, results|
+        names.each_with_index { |name, index| target.instance_variable_set(name, results[index + 2]) }
+        Internal.initialize_range(target, results[0], results[1], object.exclude_end?)
+        target
+      end
+    end
+
     define(Data) do |object, walker|
       walker.rebuild_data(object)
     end

data/lib/farce/walker/modification.rb

@@ -172,14 +172,14 @@ module Farce
         node ? node.changed == true : (@seen.key?(object) && !@seen[object].equal?(object))
       end
 
-      # Follow pending references to check that hashing cannot reach unfinished Data.
+      # Follow pending references to check that hashing cannot reach unfinished values.
       def hashable?(object)
-        return true unless @unfinished_data && !@unfinished_data.empty?
+        return true unless @unfinished_values && !@unfinished_values.empty?
         !Walker.visit(object, constants:, class_variables:) do |value, traversal|
-          traversal.return(true) if @unfinished_data.key?(value)
+          traversal.return(true) if @unfinished_values.key?(value)
           node = @nodes[value] || @destinations&.[](value)
           if node && node.plans
-            traversal.return(true) if @unfinished_data.key?(node.destination)
+            traversal.return(true) if @unfinished_values.key?(node.destination)
             node.plans.each { |plan| plan.children.each { traversal.visit(resolved(it)) } }
           else
             traversal.traverse
@@ -188,10 +188,10 @@ module Farce
         end
       end
 
-      # Reject keys and set elements whose Data dependencies are still being built.
+      # Reject keys and set elements whose immutable dependencies are still being built.
       def check_hash_key(object)
         return object if hashable?(object)
-        raise ArgumentError, "hash key or set element refers to an unfinished Data value"
+        raise ArgumentError, "hash key or set element refers to an unfinished Data or Range value"
       end
 
       private
@@ -217,19 +217,19 @@ module Farce
           dirty        ||= plan.hash_keys && (index % plan.key_stride).zero? && child && child.changed
         end
         node.changed ||= dirty
-        plan.dirty = dirty
+        plan.dirty = dirty || (Range === node.destination && @unfinished_values&.key?(node.destination))
       end
 
-      # Choose a writable destination, copying lazily or allocating unfinished Data.
+      # Choose a writable destination, copying lazily or allocating unfinished values.
       def prepare(node, rebuild: false)
         previous = node.destination
         return previous unless rebuild || previous.equal?(node.original)
         object = node.original
         return object if Internal::Noncopyable === object || Abstract::LeaseMap === object
         destination =
-          if Data === object
+          if Data === object || Range === object
             value = object.class.allocate
-            (@unfinished_data ||= {}.compare_by_identity)[value] = true
+            (@unfinished_values ||= {}.compare_by_identity)[value] = true
             value
           elsif @modify == true
             send_to(object, :frozen?) ? send_to(object, :clone, freeze: false) : object
@@ -241,6 +241,7 @@ module Farce
         (@destinations ||= {}.compare_by_identity)[destination] = node unless destination.equal?(object)
         node.destination = destination
         node.result = destination if !node.skipped && (node.result.equal?(object) || node.result.equal?(previous))
+        node.plans&.each { it.dirty = true } if Range === destination
         destination
       end
 
@@ -259,7 +260,7 @@ module Farce
           node.destination = result
           node.result = result if node.result.equal?(old)
         end
-        @unfinished_data&.delete(node.destination) if Data === node.destination
+        @unfinished_values&.delete(node.destination) if Data === node.destination || Range === node.destination
         return unless node.cyclic
         plan.target = node.destination
         plan.applied = plan.results.dup
@@ -281,6 +282,9 @@ module Farce
         if freeze
           node.changed = true unless send_to(node.result, :frozen?)
           prepare(node) if @modify != true && node.result.equal?(node.original) && !send_to(node.result, :frozen?)
+          if Range === node.destination && @unfinished_values&.key?(node.destination)
+            node.plans&.each { apply(node, it) }
+          end
           send_to(node.result, :freeze)
         end
         finalize_node(node) if finalize
@@ -308,15 +312,25 @@ module Farce
               freezing = !node.skipped && (node.freeze_result || @freeze == true)
               needed   = node.plans&.any?(&:dirty) || (freezing && @modify != true && !send_to(node.original, :frozen?))
               prepare(node) if needed
-              next unless Data === node.destination && send_to(node.destination, :frozen?) && node.plans&.any? do |plan|
-                plan.applied && plan.results.each_with_index.any? { |value, index| !value.equal?(plan.applied[index]) }
+              next unless Data === node.destination || Range === node.destination
+              # Rebuild only after this destination's own assignments become stale.
+              next unless node.plans&.any? do |plan|
+                plan.target.equal?(node.destination) && plan.applied &&
+                  plan.results.each_with_index.any? { |value, index| !value.equal?(plan.applied[index]) }
               end
               prepare(node, rebuild: true)
             end
             break if component.each_with_index.all? { |node, index| node.destination.equal?(destinations[index]) }
           end
 
-          component.sort_by { Data === it.destination ? 2 : (it.plans&.any?(&:hash_keys) ? 1 : 0) }.each do |node|
+          ordered = component.sort_by do |node|
+            if Data === node.destination || Range === node.destination
+              2
+            else
+              node.plans&.any?(&:hash_keys) ? 1 : 0
+            end
+          end
+          ordered.each do |node|
             @node           = node
             @current_object = node.original
             node.plans&.each do |plan|

data/lib/farce/walker.rb

@@ -140,14 +140,18 @@ module Farce
     end
 
     # Transform a graph using the callback's return values.
+    #
     # Call {#traverse} to transform an object's children. Returning another value
     # replaces the object without automatically visiting that replacement.
     # Unchanged branches retain their identity, including when copy is enabled.
+    #
     # Changed cycles are connected before results are frozen or finalized.
     # A cyclic callback may run again as child replacements become known. Keep
     # callbacks repeatable and put publication or caching in {#finalize}.
     # Use {#freeze_result} instead of freezing a preliminary traversal result.
+    #
     # Data values are rebuilt only when members change, using their normal initializer.
+    # Ranges are rebuilt when endpoints or instance variables change.
     # Noncopyable coordination objects, such as leases, are updated in place.
     # Constants and class variables are assigned only when their value
     # changes identity. Constant replacement can emit Ruby redefinition warnings.
@@ -156,6 +160,7 @@ module Farce
     #
     # A walk is not an atomic snapshot or update. Coordinate concurrent writers
     # when transforming container structure, especially map keys.
+    #
     # @param object [BasicObject] the root object
     # @!macro walker_module_options
     # @param copy [Boolean, Symbol] false to edit mutable objects in place, true to
@@ -171,7 +176,7 @@ module Farce
     # @raise [ArgumentError] if copy is neither a boolean nor a Symbol
     # @raise [ArgumentError] if cyclic callbacks do not converge within 32 passes,
     #   or a cyclic finalizer replaces its result
-    # @raise [ArgumentError] if a hash key or set element refers to a Data value
+    # @raise [ArgumentError] if a hash key or set element refers to a Data or Range value
     #   still being constructed. Identity-based containers do not hash their keys.
     def self.modify(object, copy: false, freeze: nil, constants: true, class_variables: true, &callback)
       raise LocalJumpError, "no block given" unless callback
@@ -263,9 +268,11 @@ module Farce
     def remember(object, result) = @seen[object] = result
 
     # Visit child values and describe how to assign their replacements.
+    #
     # The assignment block only runs during modification and may run again for cycles.
     # It receives a writable target and the resolved children. Do not mutate object
     # outside this block. Return the result of update from a traversal definition.
+    #
     # @param object [BasicObject] the object being traversed
     # @param values [Array] child references in assignment order
     # @param hash_keys [Boolean] rebuild when key descendants change in place
@@ -288,6 +295,7 @@ module Farce
     # and requested freezing. Registering another finalizer replaces the first.
     # Cyclic finalizers must preserve identity. Acyclic finalizers may return a
     # canonical replacement, which is propagated to the parent.
+    #
     # @yieldparam result [BasicObject] the settled result
     # @yieldparam cyclic [Boolean] whether the node belongs to a cycle
     # @yieldreturn [BasicObject] the final result

data/lib/farce/weak_key_map.rb

@@ -23,7 +23,7 @@ module Farce
 
     private
 
-    def new_map(**)    = Internal::StrictWeakKeyMap.new(**)
+    def new_map(...) = Internal::StrictWeakKeyMap.new(...)
     def freeze_backend = @map
   end
 

data/lib/farce/weak_map.rb

@@ -25,7 +25,7 @@ module Farce
 
     private
 
-    def new_map(**)    = Internal::StrictWeakMap.new(**)
+    def new_map(...) = Internal::StrictWeakMap.new(...)
     def freeze_backend = @map
   end
 

data/lib/farce/weak_value_map.rb

@@ -24,7 +24,7 @@ module Farce
 
     private
 
-    def new_map(**)    = Internal::StrictWeakValueMap.new(**)
+    def new_map(...) = Internal::StrictWeakValueMap.new(...)
     def freeze_backend = @map
   end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: farce
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: aarch64-linux-gnu
 authors:
 - Konstantin Haase
@@ -72,6 +72,7 @@ files:
 - ext/farce/transaction.h
 - ext/farce/tree_map.c
 - ext/farce/trie.c
+- ext/farce/trie_search.h
 - ext/farce/unshareable.c
 - ext/farce/unshared_io_pool.h
 - ext/farce/unshared_signal.c
@@ -79,6 +80,7 @@ files:
 - ext/farce/unsupported.c
 - ext/farce/vector.c
 - ext/farce/weak_map.c
+- ext/farce/weak_references.h
 - ext/java/org/farce/BoundedMap.java
 - ext/java/org/farce/FiberScheduler.java
 - ext/java/org/farce/PriorityKey.java
@@ -196,6 +198,7 @@ files:
 - lib/farce/engine/ruby/shared/vault.rb
 - lib/farce/engine/ruby/shared/vault_weak_map.rb
 - lib/farce/engine/ruby/shared/weak_atom.rb
+- lib/farce/engine/ruby/shared/weak_cache_mirror.rb
 - lib/farce/engine/ruby/shared/weak_map.rb
 - lib/farce/engine/shared.rb
 - lib/farce/engine/shared/atom.rb
@@ -220,6 +223,7 @@ files:
 - lib/farce/engine/shared/strict_tree_map.rb
 - lib/farce/engine/shared/transaction_map_backend.rb
 - lib/farce/engine/shared/trie.rb
+- lib/farce/engine/shared/trie/ignore_case.rb
 - lib/farce/engine/shared/trie_builder.rb
 - lib/farce/engine/shared/unshareable.rb
 - lib/farce/engine/shared/unshared_atom.rb
@@ -427,6 +431,7 @@ files:
 - lib/farce/strict/tree_map.rb
 - lib/farce/strict/vector.rb
 - lib/farce/strict/weak_atom.rb
+- lib/farce/strict/weak_cache.rb
 - lib/farce/strict/weak_key_map.rb
 - lib/farce/strict/weak_map.rb
 - lib/farce/strict/weak_set.rb