farce 0.4.1 → 0.5.0

data/lib/farce/internal.rb

@@ -77,18 +77,12 @@ module Farce
       Clock.now + timeout
     end
 
-    def remaining_timeout(deadline)
-      return unless deadline
-      remaining = deadline - Clock.now
-      remaining.negative? ? 0 : remaining
-    end
-
     # Repeat with one timeout budget. Even a zero timeout permits the first check.
     def with_timeout(timeout)
       raise LocalJumpError, "no block given" unless block_given?
       deadline = timeout_deadline(timeout)
       loop do
-        yield remaining_timeout(deadline), deadline
+        yield Clock.remaining(deadline), deadline
         return if deadline && Clock.now >= deadline
       end
     end
@@ -98,10 +92,16 @@ module Farce
       with_timeout(timeout) do |_, deadline|
         current = keys.empty? ? receiver.value : receiver[*keys]
         return current if yield(current)
-        receiver.wait_until_changed(*keys, current, timeout: remaining_timeout(deadline)) { return }
+        receiver.wait_until_changed(*keys, current, timeout: Clock.remaining(deadline)) { return }
       end
     end
 
+    # An unchanged observation must permit waiting even when its equality is non-reflexive.
+    def value_changed?(current, expected, identity)
+      return false if BasicObject.instance_method(:equal?).bind_call(current, expected)
+      identity || !(current == expected) # rubocop:disable Style/InverseMethods -- != can be overridden independently.
+    end
+
     def garbage_collectable?(object)
       case object
       when Integer, Float, Complex, Rational, Symbol, true, false, nil then false

data/lib/farce/lazy.rb

@@ -59,6 +59,9 @@ module Farce
   # # Will only compute the expensive attribute once, and return the same value to all Ractors.
   # 5.times { Ractor.new(object) { it.expensive_attribute } }
   # ```
+  #
+  # @see Farce::Memoize
+  # @see Farce::LazyRef
   class Lazy < Farce::Abstract::Lazy
     include Shareable::Tracked
 

data/lib/farce/lazy_ref.rb

@@ -22,6 +22,9 @@ module Farce
   #   #   initialized.value # => 0
   #   #   lazy_ref[:key] = :value
   #   #   initialized.value # => 1
+  #   #
+  #   # @see Farce::Memoize
+  #   # @see Farce::Lazy
   #   class LazyRef < Farce::Reference
   #     # @!macro modes
   #     # @overload initialize(factory, mode: :smart)

data/lib/farce/local/lease.rb

@@ -34,10 +34,10 @@ module Farce
       # (see Farce::Abstract::Lease#checkout)
       def checkout(timeout: nil, &block)
         deadline = timeout_deadline(timeout)
-        lease    = scoped_lease(timeout: remaining_timeout(deadline))
+        lease    = scoped_lease(timeout: Clock.remaining(deadline))
         raise TimeoutError, "lease checkout timed out" unless lease
 
-        timeout = remaining_timeout(deadline)
+        timeout = Clock.remaining(deadline)
         block ? lease.checkout(timeout:, &block) : lease.checkout(timeout:)
       end
 
@@ -65,13 +65,6 @@ module Farce
         end
         Clock.now + timeout
       end
-
-      def remaining_timeout(deadline)
-        return unless deadline
-
-        remaining = deadline - Clock.now
-        remaining.positive? ? remaining : 0
-      end
     end
   end
 end

data/lib/farce/local/lease_map.rb

@@ -35,10 +35,10 @@ module Farce
 
       def checkout_canonical(key, missing_key:, timeout: nil, &)
         deadline = timeout_deadline(timeout)
-        map      = scoped_lease_map(timeout: remaining_timeout(deadline))
+        map      = scoped_lease_map(timeout: Clock.remaining(deadline))
         raise TimeoutError, "lease checkout timed out" unless map
 
-        map.checkout(key, timeout: remaining_timeout(deadline), receiver: self, missing_key:, &)
+        map.checkout(key, timeout: Clock.remaining(deadline), receiver: self, missing_key:, &)
       end
 
       def try_checkout_canonical(key, missing_key:, &)
@@ -68,13 +68,6 @@ module Farce
         end
         Clock.now + timeout
       end
-
-      def remaining_timeout(deadline)
-        return unless deadline
-
-        remaining = deadline - Clock.now
-        remaining.positive? ? remaining : 0
-      end
     end
   end
 end

data/lib/farce/local/pool.rb

@@ -7,7 +7,8 @@ module Farce
     # A shareable handle with an independent thread pool in each scope.
     #
     # Each pool uses the scaling settings and fiber scheduler configured at
-    # construction. Tasks always keep their block and argument references. Only
+    # construction. Changing settings tunes the current scope's pool. New scopes
+    # use the constructor settings. Tasks always keep their block and argument references. Only
     # local and smart modes are accepted when `auto_local` is false. A scheduler
     # constructor must be convertible to a shareable proc for use in each Ractor.
     # {#close} drains only the current scope's pool. {#close_all} drains every pool
@@ -31,14 +32,45 @@ module Farce
                      grow_after: 0.005, shrink_after: 30, capacity: 1024, scope: :ractor,
                      backend: Internal::FROZEN_CONFIG.io_backend, &constructor)
         initialize_configuration(min_size:, max_size:, max_inflight:, grow_after:, shrink_after:, backend:)
-        @constructor = prepare_constructor(constructor || Internal::FROZEN_CONFIG.fiber_scheduler_constructor)
-        @pools       = Strict::Map.new
-        @closed_all  = Internal::Flag.new(false)
+        @capacity           = capacity && Integer(capacity)
+        @constructor        = prepare_constructor(constructor || Internal::FROZEN_CONFIG.fiber_scheduler_constructor)
+        @pools              = Strict::Map.new
+        @closed_all         = Internal::Flag.new(false)
         @initialization_key = Object.new.freeze
         super(scope:, min_size: @min_size, max_size: @max_size, max_inflight: @max_inflight,
               grow_after: @grow_after, shrink_after: @shrink_after, capacity:, backend:)
       end
 
+      # Settings changes affect only the current scope. New scopes use constructor defaults.
+      # @api private
+      def settings = (pool = current_pool) ? pool.settings : @settings.value
+
+      def capacity = (pool = current_pool) ? pool.capacity : @capacity
+
+      def min_size=(value)
+        scoped_value.min_size = value
+      end
+
+      def max_size=(value)
+        scoped_value.max_size = value
+      end
+
+      def max_inflight=(value)
+        scoped_value.max_inflight = value
+      end
+
+      def grow_after=(value)
+        scoped_value.grow_after = value
+      end
+
+      def shrink_after=(value)
+        scoped_value.shrink_after = value
+      end
+
+      def capacity=(value)
+        scoped_value.capacity = value
+      end
+
       # Stop accepting work in this scope and drain its queued tasks.
       # @return [self]
       def close
@@ -74,7 +106,8 @@ module Farce
       def closed? = @closed_all.value || super
 
       Internal.delegate(self, :scoped_value, :drained?, :admission_generation, :wait_for_admission,
-        :admission_changed, :task_taken, :retire_worker, :worker_stopped, :scale_if_needed)
+        :admission_changed, :task_taken, :retire_worker, :wake_retiring_workers,
+        :worker_retired, :worker_stopped, :scale_if_needed)
 
       private
 

data/lib/farce/local/publisher.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Local
+    # Local variant of {Farce::Publisher}.
+    class Publisher < Abstract::Publisher
+      include Shareable::Unfreezable
+
+      # The scope with independent contents.
+      # @return [Symbol] The configured scope name.
+      attr_reader :scope
+
+      # @overload initialize(*subscribers)
+      #   (see Farce::Abstract#initialize)
+      def initialize(*, scope: :ractor)
+        raise ArgumentError, "Invalid scope: #{scope.inspect}" unless Farce::SCOPES.include?(scope)
+        @scope = scope
+        super(*)
+      end
+
+      private
+
+      def map = Internal::Storage.store_if_absent(self, scope:) { Unshared::Map.new }
+
+      def default_mode = :local
+    end
+  end
+end

data/lib/farce/local/scheduler.rb

@@ -56,6 +56,7 @@ module Farce
       def initialize(capacity: 1024, backend: Internal::FROZEN_CONFIG.io_backend, scope: :ractor,
                      worker: nil, &constructor)
         @constructor        = prepare_constructor(constructor || Internal::FROZEN_CONFIG.fiber_scheduler_constructor)
+        @capacity           = capacity && Integer(capacity)
         @backend            = backend
         @worker             = worker
         @schedulers         = Strict::Map.new
@@ -65,15 +66,26 @@ module Farce
         super(scope:, capacity: capacity && Integer(capacity), backend:)
       end
 
+      # Pending-task capacity in this scope. New scopes retain the constructor value.
+      def capacity = (scheduler = current_scheduler) ? scheduler.capacity : @capacity
+
+      # Resize the queue in this scope without starting a worker.
+      def capacity=(value)
+        raise SchedulerClosedError, "cannot configure a closed scheduler" if @closed_all.value
+        scoped_value.capacity = value
+      end
+
       # Enqueue a task in the current scope, preserving its block and arguments.
       # `mode` is ignored when `auto_local` is true. Otherwise, only local and smart modes are accepted.
-      # @overload schedule(*args, mode: :smart, auto_local: true)
+      # @overload schedule(*args, mode: :smart, auto_local: true, timeout: nil)
       #   @param (see Farce::Abstract::Executor#schedule)
-      #   @return [self]
+      #   @return [self, nil] self when submitted, or nil when the scheduling timeout expires.
       def schedule(...) = enqueue_task(false, ...)
 
       # (see Abstract::Scheduler#try_schedule)
-      def try_schedule(...) = enqueue_task(true, ...)
+      def try_schedule(*, mode: :smart, auto_local: true, &)
+        enqueue_task(true, *, mode:, auto_local:, &)
+      end
 
       # Starts a worker for the current scope. Other scopes retain their creation behavior.
       # @param executor [Class, nil] Thread or a custom executor that stays in this Ractor.
@@ -147,12 +159,13 @@ module Farce
 
       private
 
-      def enqueue_task(non_block, *, mode: :smart, auto_local: true, &block)
+      def enqueue_task(non_block, *, mode: :smart, auto_local: true, timeout: nil, &block)
         raise SchedulerClosedError, "cannot schedule task on a closed scheduler" if @closed_all.value
         scheduler = scoped_value
         raise SchedulerClosedError, "cannot schedule task on a closed scheduler" if scheduler.closed?
         raise LocalJumpError, "Cannot schedule without a block" unless block
 
+        deadline = scheduling_deadline(timeout)
         validate_local_mode(mode, auto_local)
         register_scheduler(scheduler)
 
@@ -160,7 +173,7 @@ module Farce
           if non_block
             scheduler.try_schedule(*, mode:, auto_local:, &block)
           else
-            scheduler.schedule(*, mode:, auto_local:, &block)
+            scheduler.schedule(*, mode:, auto_local:, timeout: Clock.remaining(deadline), &block)
           end
 
         submitted && self

data/lib/farce/local/vector.rb

@@ -8,10 +8,11 @@ module Farce
     #
     # @!method initialize(source = nil, compare_by_identity: false, scope: :ractor)
     #   @!macro scopes
-    #   @param source [Array, nil] the initial values
+    #   @param source [Array, Integer, nil] Initial values or a size filled with nil.
     #   @param compare_by_identity [Boolean] whether values are compared by identity
     #   @param scope [Symbol] the scope of the vector
     #   @return [Vector]
+    #   @raise [ArgumentError] If the size is negative.
     class Vector < Abstract::Vector
       include Shareable::Tracked
       include Scoped::Tracked
@@ -24,7 +25,7 @@ module Farce
         self.class.new(values, compare_by_identity: compare_by_identity?, scope:)
       end
 
-      private def new_scoped_value(...) = Internal::UnsharedVector.new(...)
+      private def new_scoped_value(source = nil, **) = Internal::UnsharedVector.new(normalize_vector_source(source), **)
     end
   end
 end

data/lib/farce/memoize.rb

@@ -0,0 +1,314 @@
+# 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`.
+  #       Defaults to `:raise` with `weak: true`, which supports only `:raise`, `: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
+          modes = weak ? Internal::WeakModeManager::MODES : MODES
+          raise ArgumentError, "unsupported mode: #{mode.inspect}" unless modes.include?(mode)
+          init = "::Farce::#{atom_class}.new(mode: #{mode.inspect})"
+          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}.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