farce 0.4.1-java → 0.6.0-java

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

@@ -0,0 +1,319 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # Ractor-friendly memoization module.
+  #
+  # Replaces the following pattern:
+  #
+  # ```ruby
+  # class MyClass
+  #   def time
+  #     @time ||= Time.now
+  #   end
+  # end
+  # ```
+  #
+  # Using `Farce::Memoize` instead gives you:
+  #
+  # * Allows memoization after freezing
+  # * Is Ractor-safe (with optional scoping or transfer modes) and thread-safe
+  # * Adds one instance variable per memoized method (avoids hash lookup and doesn't bust Ruby's data structures)
+  # * Is Marshal-dump/load friendly
+  # * Allows weak memoization, where the memoized value is kept until it is garbage collected
+  # * Does not need to run code on the main Ractor for memoization
+  #
+  # Methods with arguments cannot be memoized. Explicitly use a {Farce::Abstract::Map map} instead.
+  #
+  # @example Using `memoize` method
+  #   class MyClass
+  #     include Farce::Memoize
+  #     memoize def time = Time.now
+  #   end
+  #
+  #   instance    = MyClass.new
+  #   first_time  = instance.time
+  #   second_time = instance.time
+  #
+  #   first_time == second_time      # => true
+  #   first_time == MyClass.new.time # => false
+  #
+  # @example Scope-specific memoization
+  #   class MyClass
+  #     include Farce::Memoize
+  #
+  #     def first = expensive_computation(0)
+  #     def last  = expensive_computation(-1)
+  #
+  #     # Memoize separately per Ractor
+  #     memoize :first, :last, scope: :ractor
+  #   end
+  #
+  # @example Setting a mode
+  #   class MyClass
+  #     include Farce::Memoize
+  #     memoize :expensive, mode: :make_shareable
+  #     def expensive = expensive_computation
+  #   end
+  #
+  # @example Without `memoize` extension
+  #   class MyClass
+  #     include Farce::Memoize[:time]
+  #     def time = Time.now
+  #   end
+  #
+  # @see Farce::Lazy
+  # @see Farce::LazyRef
+  #
+  # @!macro memoize_params
+  #   @overload $0(*methods, scope: :global, mode: :smart, weak: false, visibility: nil)
+  #     @param methods [Array<Symbol>]
+  #       The methods to memoize
+  #
+  #     @param scope [Symbol]
+  #       The scope of the memoization.
+  #       In addition to the {Farce::SCOPES normal scopes} it may also be set to `:global` or `:unshared`.
+  #
+  #     @param mode [Symbol]
+  #       The mode of the memoization. Ignored for any scope other than `:global`.
+  #       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.
+  #       If enabled, memoized values may be garbage collected when no longer referenced.
+  #       In this case, next access to the memoized method may recompute the value.
+  #
+  #     @param visibility [Symbol, nil]
+  #       The visibility of the memoized methods.
+  #       May be one of `:public`, `:protected`, or `:private`.
+  #       If set to `nil`, {Farce::Memoize#memoize} will attempt to infer the visibility based on the context.
+  #       Other methods will default to `:public`.
+  module Memoize
+    # A named module preserves the nil marker's identity across Marshal round trips.
+    NIL_VALUE = Module.new.freeze
+    private_constant :NIL_VALUE
+
+    # Mixins used to implement memoization for different methods, scopes, and modes
+    # @see Farce::Memoize
+    class Mixin < Module
+      KNOWN = Strict::Map.new
+      private_constant :KNOWN
+
+      # @!macro memoize_params
+      # Creates or retrieves a memoization mixin for the given methods and options.
+      # @return [Mixin] the memoization mixin
+      def self.new(*methods, **options)
+        return super unless self == Mixin
+        methods = Farce.dedup(methods.map(&:to_sym).uniq.sort)
+        options = Farce.dedup(normalize_options(options))
+        map     = KNOWN.store_if_absent(options) { Strict::Map.new }
+        map.store_if_absent(methods) { super(methods, **options) }
+      end
+
+      # @api private
+      def self.normalize_options(options)
+        options[:visibility] &&= options[:visibility].to_sym
+
+        options[:scope]      ||= :global
+        options[:visibility] ||= :public
+        options[:weak]       ||= false
+
+        if options[:scope] == :global
+          options[:mode] ||= options[:weak] ? :raise : :smart
+        else
+          options.delete(:mode)
+        end
+
+        options
+      end
+      private_class_method :normalize_options
+
+      # @return [Array<Symbol>] the memoized methods
+      attr_reader :memoized_methods
+
+      # @return [Symbol] the scope of the memoization
+      attr_reader :scope
+
+      # @return [Symbol, nil] the transfer mode, or nil for a scoped cache
+      attr_reader :mode
+
+      # @return [Symbol] the visibility of the memoized methods
+      attr_reader :visibility
+
+      # @api private
+      def initialize(methods, scope:, weak:, mode: nil, visibility: :public)
+        @memoized_methods = methods
+        @scope            = scope
+        @mode             = mode
+        @weak             = !!weak # rubocop:disable Style/DoubleNegation
+        @visibility       = visibility
+
+        super()
+
+        unless %i[public protected private].include?(visibility)
+          raise ArgumentError, "unsupported visibility: #{visibility.inspect}"
+        end
+
+        atom_class = weak ? "WeakAtom" : "Atom"
+
+        case scope
+        when :global
+          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
+          init = "::Farce::Unshared::#{atom_class}.new"
+          args = "#{methods.join(", ")}, scope: :unshared"
+        when *SCOPES
+          init = "::Farce::Local::#{atom_class}.new(scope: #{scope.inspect})"
+          args = "#{methods.join(", ")}, scope: #{scope.inspect}"
+        else
+          raise ArgumentError, "unsupported scope: #{scope.inspect}"
+        end
+
+        set_temporary_name(-"Farce::Memoize[#{args}]") if instance_of?(Mixin)
+        initializer = +""
+        # Overlapping mixins need separate slots. Stable names also survive Marshal across processes.
+        slot = "#{methods.join(",").unpack1("H*")}_#{scope}_#{mode}_#{@weak}_#{visibility}"
+
+        methods.each do |method|
+          unless method =~ /\A[a-z_]\w*[!?]?\z/i && method != :initialize
+            raise ArgumentError, "unsuitable method name: #{method.inspect}"
+          end
+          ivar = "@_#{method.to_s.unpack1("H*")}_memoize_#{slot}_atom"
+          initializer << "  #{ivar} = #{init}\n"
+          module_eval <<~RUBY, __FILE__, __LINE__ + 1
+            #{visibility} def #{method}
+              value = #{ivar}.value || #{ivar}.store_if_absent do
+                result = super()
+                nil.equal?(result) ? NIL_VALUE : result
+              end
+              value unless NIL_VALUE.equal?(value)
+            end
+          RUBY
+        end
+
+        # Explicit forwarding preserves nested constructor keywords on JRuby.
+        module_eval <<~RUBY, __FILE__, __LINE__ + 1
+          def initialize(*, **, &)
+            #{initializer}
+            super
+          end
+        RUBY
+      end
+
+      # @return [Boolean] whether the memoization is weak
+      def weak? = @weak
+
+      # allow `include Farce::Memoize[...]` to work like `prepend`
+      private def append_features(base) = base.prepend(self)
+    end
+
+    # @api private
+    def self.append_features(base) = base.extend(self)
+    private_class_method :append_features
+
+    # Creates or retrieves the memoization mixin for the given methods, scope, and mode
+    # @!macro memoize_params
+    # @return [Mixin] memoization mixin for the given methods, scope, and mode
+    def self.[](...) = Mixin.new(...)
+
+    # @!macro memoize_params
+    # Creates a memoization mixin for the given arguments and adds it to the current class.
+    #
+    # Can be used as a prefix to `def`:
+    #
+    # ```ruby
+    # memoize def some_method = expensive_computation
+    # ```
+    #
+    # Or called separately with the method names, useful for passing additional options:
+    #
+    # ```ruby
+    # def some_method = expensive_computation
+    #
+    # # memoize some_method per thread
+    # memoize :some_method, scope: :thread
+    # ```
+    #
+    # ## Visibility of Memoized Methods
+    #
+    # If no visibility is provided, it will determine the visibility based on the existing method definitions.
+    # If none exist, it will default to public. This happens when `memoize` is called.
+    # Make sure you set the visibility before calling this method.
+    #
+    # This works:
+    #
+    # ```ruby
+    # memoize private def some_method = expensive_computation
+    # ```
+    #
+    # As does this:
+    #
+    # ```ruby
+    # private
+    # memoize def some_method = expensive_computation
+    # ```
+    #
+    # Or this:
+    #
+    # ```ruby
+    # private def some_method = expensive_computation
+    # memoize :some_method
+    # ```
+    #
+    # But this doesn't, as the mixin's method will end up public:
+    #
+    # ```ruby
+    # private memoize def some_method = expensive_computation
+    # ```
+    #
+    # Same for this one, as the mixin's method will also end up public:
+    #
+    # ```ruby
+    # memoize :some_method
+    # private def some_method = expensive_computation
+    # ```
+    #
+    # You can of course set visibility explicitly when calling `memoize`:
+    #
+    # ```ruby
+    # memoize :some_method, visibility: :private
+    # ```
+    #
+    # @return [Array<Symbol>] the list of memoized methods
+    def memoize(*methods, visibility: nil, warn: true, **)
+      if visibility.nil?
+        groups = methods.group_by do |method|
+          next :protected if protected_method_defined?(method)
+          next :private   if private_method_defined?(method)
+          :public
+        end
+        return groups.flat_map { memoize(*_2, visibility: _1, warn:, **) }
+      end
+
+      if warn
+        methods.each do |name|
+          method = instance_method(name)
+          next if method.parameters.empty?
+          warn "#{method.owner}##{name} expects parameters and may be unsuitable for memoization"
+        rescue NameError => e
+          raise e unless e.name == name.to_sym
+        end
+      end
+
+      mixin = Farce::Memoize[*methods, visibility:, **]
+      prepend mixin
+
+      mixin.memoized_methods
+    end
+  end
+end

data/lib/farce/pool.rb

@@ -11,6 +11,11 @@ module Farce
   # `min_size` retire after `shrink_after` without queued or running work.
   # By default, the pool starts with no workers and can shrink back to zero.
   #
+  # Worker limits, task limits, scaling delays, and queue capacity can change while
+  # the pool runs. Lowering `max_size` retires extra workers as they become idle.
+  # Busy workers keep queued work runnable. Raising `min_size` starts workers
+  # immediately. Queued tasks are retained.
+  #
   # Most importantly, it exposes a {#schedule} method compatible with {Scheduler#schedule}.
   #
   # @example

data/lib/farce/priority_queue.rb

@@ -42,7 +42,7 @@ module Farce
         result = @reverse_order ? @queue.pop_last { empty = true } : @queue.pop { empty = true }
 
         return @manager.unwrap(result) unless empty
-        remaining = remaining_timeout(deadline)
+        remaining = Clock.remaining(deadline)
         return block_given? ? yield : nil unless wait_pop(timeout: remaining)
       end
     end

data/lib/farce/publisher.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # A message multiplexer.
+  # Implements the publisher-subscriber protocol.
+  #
+  # @example
+  #   publisher = Farce::Publisher.new
+  #
+  #   # Count how many messages have been received
+  #   counter = Farce::Counter.new
+  #   publisher.subscribe(counter)
+  #
+  #   # Trigger a callback whenever a message is published
+  #   publisher.subscribe do |message|
+  #     puts "Received message: #{message}"
+  #   end
+  #
+  #   # Send messages to a queue
+  #   queue = Farce::Queue.new
+  #   publisher.subscribe(queue)
+  #
+  #   # Keep track of the last published value
+  #   atom = Farce::Atom.new
+  #   publisher.subscribe(atom)
+  #
+  #   # Send messages to a Ractor
+  #   ractor = Ractor.new do
+  #     while message = Ractor.receive
+  #       puts "Received message in Ractor: #{message}"
+  #     end
+  #   end
+  #   publisher.subscribe(ractor)
+  #
+  #   # Publish some messages
+  #   publisher.publish("Hello, world!")
+  #   publisher.publish("Another message")
+  #
+  #   queue.pop     # => "Hello, world!"
+  #   atom.value    # => "Another message"
+  #   counter.value # => 2
+  class Publisher < Farce::Abstract::Publisher
+    include Shareable::Unfreezable
+
+    # @overload initialize(*subscribers)
+    #   (see Farce::Abstract#initialize)
+    def initialize(*subscribers)
+      @map = Strict::Map.new
+      super()
+      subscribers.each { subscribe(it) }
+    end
+
+    private attr_reader :map
+  end
+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/signal.rb

@@ -80,7 +80,7 @@ module Farce
         result   = yield
         return result if result
 
-        remaining = deadline - Clock.now if deadline
+        remaining = Clock.remaining(deadline)
         return if remaining && !remaining.positive?
         return unless wait(observed, timeout: remaining)
       end

data/lib/farce/strict/publisher.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Strict
+    # Strict variant of {Farce::Publisher}.
+    class Publisher < Farce::Abstract::Publisher
+      include Shareable::Unfreezable
+
+      # @overload initialize(*subscribers)
+      #   (see Farce::Abstract#initialize)
+      def initialize(*subscribers)
+        @map = Strict::Map.new
+        super()
+        subscribers.each { subscribe(it) }
+      end
+
+      # (see Farce::Abstract::Publisher#publish)
+      def publish(message = nil)
+        return super if Ractor.shareable?(message)
+        raise Ractor::IsolationError, "value must be Ractor-shareable"
+      end
+      alias send      publish
+      alias <<        publish
+      alias broadcast publish
+
+      private attr_reader :map
+    end
+  end
+end

data/lib/farce/strict/vector.rb

@@ -8,10 +8,11 @@ module Farce
     class Vector < Abstract::Vector
       include Shareable::Delegated
 
-      # @param source [Array, nil] Initial values. The source array is not retained.
+      # @param source [Array, Integer, nil] Initial values or a size filled with nil. The source array is not retained.
       # @param compare_by_identity [Boolean] Whether values are compared by identity.
+      # @raise [ArgumentError] If the size is negative.
       def initialize(source = nil, compare_by_identity: false)
-        @vector = Internal::Vector.new(source, compare_by_identity:)
+        @vector = Internal::Vector.new(normalize_vector_source(source), compare_by_identity:)
         super()
       end
 

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