farce 0.4.1 → 0.5.0

data/lib/farce/abstract/counter.rb

@@ -7,6 +7,22 @@ module Farce
     # @abstract Common numeric interface and atomic operations for counters.
     # @note This is a module rather than a class so {Farce::Counter} can inherit
     #   directly from the native counter and avoid delegation overhead.
+    #
+    # @!method initial
+    #   @return [Integer] The initial value retained by reset and copies.
+    #
+    # @!method value
+    #   @return [Integer] The current value of the counter.
+    #
+    # @!method increment(by = 1)
+    #   Increment the counter by the given amount (default is 1).
+    #   @param [Numeric, String, #to_int] by The amount, converted to an Integer.
+    #   @return [self] Returns self for chaining.
+    #
+    # @!method decrement(by = 1)
+    #   Decrement the counter by the given amount (default is 1).
+    #   @param [Numeric, String, #to_int] by The amount, converted to an Integer.
+    #   @return [self] Returns self for chaining.
     module Counter
       include Internal::MarshalSupport::Counter
       include Internal::Copyable
@@ -24,6 +40,24 @@ module Farce
       include Value
       include Internal::ValueSerialization
 
+      # Pass the current value to the given block, replacing it with the block's result.
+      # May retry if the value changes during the block's execution.
+      #
+      # Provided for compatibility with `Concurrent::AtomicFixnum`.
+      #
+      # @yield [count] Calculate the new value based on the current value.
+      # @yieldparam count [Integer] the current value of the atomic fixnum.
+      # @yieldreturn [Integer] the new value to replace the current value.
+      # @return [Integer] the new value after the block has been applied.
+      def update
+        raise LocalJumpError, "no block given" unless block_given?
+        while true
+          current   = value
+          new_value = yield(current)
+          return new_value if compare_and_set(current, new_value)
+        end
+      end
+
       # Wait until the current value differs from the expected value.
       # @param expected [Integer] the value to wait to change from
       # @param timeout [Numeric, nil] the total seconds available
@@ -35,7 +69,7 @@ module Farce
           observed = signal.generation
           current = value
           return current unless expected == current
-          break unless signal.wait(observed, timeout: Internal.remaining_timeout(deadline))
+          break unless signal.wait(observed, timeout: Clock.remaining(deadline))
         end
         yield if block_given?
       end

data/lib/farce/abstract/executor.rb

@@ -12,7 +12,7 @@ module Farce
     #
     # @abstract Use a scheduler or pool class.
     #
-    # @!method schedule(*args, mode: :smart, auto_local: true)
+    # @!method schedule(*args, mode: :smart, auto_local: true, timeout: nil)
     #   @abstract This method must be implemented by concrete executor subclasses.
     #
     #   Schedules a block for execution.
@@ -36,12 +36,18 @@ module Farce
     #     Whether to automatically use a local mode when possible. Defaults to `true`.
     #     May be ignored by some executors.
     #
+    #   @param timeout [Numeric, nil]
+    #     Maximum seconds to wait for ownership and queue space. Nil waits indefinitely.
+    #     Zero only submits if no waiting is needed. Must be finite and non-negative.
+    #     An expired attempt returns `nil` and does not enqueue the task.
+    #     This does not limit task execution time. Executors without a queue may ignore it.
+    #
     #   @yield [*args] The block to be executed by the scheduler.
     #   @yieldparam args [Array] The arguments passed to the block.
     #   @yieldreceiver [BasicObject, nil]
     #     Local mode will not touch the block's binding (self stays the same), but other modes may change it to `nil`.
     #
-    #   @return [self]
+    #   @return [self, nil] self when submitted, or nil when the scheduling timeout expires.
     #
     # @!method close
     #   @abstract This method must be implemented by concrete executor subclasses.
@@ -84,7 +90,9 @@ module Farce
       # Attempts to submit a task. Queue-based executors return `nil` when full
       # instead of waiting for space. Other executors behave like {#schedule}.
       #
-      # @param (see #schedule)
+      # @param args (see #schedule)
+      # @param mode (see #schedule)
+      # @param auto_local (see #schedule)
       # @return [self, nil] self when submitted, or nil when the queue is full.
       def try_schedule(...) = schedule(...)
 
@@ -98,14 +106,16 @@ module Farce
       # 1. If {#local?} returns true, and it would run in local mode (either due to `auto_local` or explicitly set
       #    `mode: :local`), it executes the block directly without enqueuing it.
       # 2. It blocks until the block has been executed, either immediately in local mode or after being scheduled.
+      # A `timeout` only limits scheduling waits. Once submitted, this waits for completion without a timeout.
       #
       # @param (see #schedule)
-      # @return [self]
-      def execute(*, mode: :smart, auto_local: true, &callback)
+      # @return [self, nil] self after execution, or nil when the scheduling timeout expires.
+      def execute(*, mode: :smart, auto_local: true, timeout: nil, &callback)
         raise LocalJumpError, "Cannot yield without a block" unless block_given?
         raise SchedulerClosedError, "cannot execute task on a closed scheduler" if closed?
 
-        if (auto_local || mode == :local) && local?
+        deadline = scheduling_deadline(timeout)
+        if (auto_local || mode == :local) && local?(wait: timeout.nil?)
           raise SchedulerClosedError, "cannot execute task on a closed scheduler" if closed?
           yield(*)
           return self
@@ -115,16 +125,29 @@ module Farce
         signal   = Signal.new
         callback = Ractor.shareable_proc(&callback) unless Ractor.shareable?(callback)
 
-        schedule(callback, ran, signal, *, mode:, auto_local:) do |callback, ran, signal, *args|
+        submitted = schedule(callback, ran, signal, *, mode:, auto_local:,
+          timeout: Clock.remaining(deadline)) do |callback, ran, signal, *args|
           callback.call(*args)
         ensure
           ran.set
           signal.broadcast
         end
+        return unless submitted
 
         signal.wait_until { ran.value }
         self
       end
+
+      private
+
+      def scheduling_deadline(timeout)
+        return if timeout.nil?
+        timeout = Float(timeout)
+        unless timeout.finite? && !timeout.negative?
+          raise ArgumentError, "timeout must be a finite, non-negative number or nil"
+        end
+        Clock.timeout(timeout)
+      end
     end
   end
 end

data/lib/farce/abstract/flag.rb

@@ -61,9 +61,21 @@ module Farce
 
       # @return [Boolean] whether the flag is set
       def set? = value
+      alias true? set?
 
       # @return [Boolean] whether the flag is unset
       def unset? = !value
+      alias false? unset?
+
+      # Explicitly sets the value to true.
+      # Provided for compatibility with `Concurrent::AtomicBoolean`.
+      # @return [Boolean] true if the value has changed
+      def make_true = compare_and_set(false, true)
+
+      # Explicitly sets the value to false.
+      # Provided for compatibility with `Concurrent::AtomicBoolean`.
+      # @return [Boolean] true if the value has changed
+      def make_false = compare_and_set(true, false)
 
       # Wait until the flag becomes true.
       # @param timeout [Numeric, nil] the total seconds available

data/lib/farce/abstract/pool.rb

@@ -13,21 +13,6 @@ module Farce
     class Pool < Executor
       include Internal::Inspect
 
-      # @return [Float] Maximum queue wait before adding a worker.
-      attr_reader :grow_after
-
-      # @return [Integer, nil] Soft task limit for each worker.
-      attr_reader :max_inflight
-
-      # @return [Integer] Maximum worker count.
-      attr_reader :max_size
-
-      # @return [Integer] Minimum worker count.
-      attr_reader :min_size
-
-      # @return [Float, nil] Idle time before an extra worker retires.
-      attr_reader :shrink_after
-
       # Create and start an elastic pool using the configured fiber scheduler.
       # An explicit constructor block overrides the configured default.
       #
@@ -49,6 +34,7 @@ module Farce
         initialize_configuration(min_size:, max_size:, max_inflight:, grow_after:, shrink_after:, backend:)
         @constructor  = prepare_constructor(constructor)
         @queue        = new_queue(capacity: capacity && Integer(capacity))
+        @queue.interrupt(settings, settings.generation)
         @state        = Internal::Atom.new(:running)
         @error        = Internal::Atom.new
         @worker_count = Internal::Atom.new(0)
@@ -57,25 +43,92 @@ module Farce
         super()
         publish_pool
         begin
-          @min_size.times { start_worker }
+          settings.min_size.times { start_worker }
         rescue Exception # rubocop:disable Lint/RescueException
           close
           raise
         end
       end
 
+      # @return [Float] Maximum queue wait before adding a worker.
+      def grow_after = settings.grow_after
+
+      # @return [Integer, nil] Soft task limit for each worker.
+      def max_inflight = settings.max_inflight
+
+      # @return [Integer] Maximum worker count.
+      def max_size = settings.max_size
+
+      # @return [Integer] Minimum worker count.
+      def min_size = settings.min_size
+
+      # @return [Float, nil] Idle time before an extra worker retires.
+      def shrink_after = settings.shrink_after
+
+      # @api private
+      def settings = @settings.value
+
+      # Pending-task capacity. A smaller capacity preserves already queued tasks.
+      # @return [Integer, nil]
+      def capacity = @queue.capacity
+
+      # Resize the pending-task queue. Nil makes the queue unbounded on CRuby.
+      # JRuby and TruffleRuby retain their initial bounded or unbounded choice.
+      def capacity=(value)
+        @queue.capacity = value.nil? ? nil : Integer(value)
+      end
+
+      # Start and retain at least this many workers. Must not exceed max_size.
+      def min_size=(value)
+        value = Integer(value)
+        update_settings(min_size: value)
+        value
+      end
+
+      # Limit worker count. Excess workers retire when their running tasks leave them idle.
+      # Must be positive and at least min_size.
+      def max_size=(value)
+        value = Integer(value)
+        update_settings(max_size: value)
+        value
+      end
+
+      # Set the soft per-worker task limit. Nil disables the limit.
+      def max_inflight=(value)
+        value &&= Integer(value)
+        update_settings(max_inflight: value)
+        value
+      end
+
+      # Change the queue wait before adding a worker. Rechecks existing queued work.
+      def grow_after=(value)
+        value = duration(value, :grow_after)
+        update_settings(grow_after: value)
+        value
+      end
+
+      # Change the idle timeout. Nil disables idle retirement. Restarts idle waits.
+      def shrink_after=(value)
+        value = duration(value, :shrink_after, nil_allowed: true)
+        update_settings(shrink_after: value)
+        value
+      end
+
       # Enqueue a task for any worker in the pool.
       #
       # Ractor pools reject local transfer. Thread pools preserve the block and
       # arguments. With `auto_local: false`, they accept only local or smart modes.
+      # A `timeout` limits waiting for queue space. Expiry returns `nil` without
+      # enqueuing the task. Accepted tasks have no execution timeout.
       #
-      # @overload schedule(*args, mode: :smart, auto_local: true)
+      # @overload schedule(*args, mode: :smart, auto_local: true, timeout: nil)
       #   @!macro modes
       #   @param args [Array<Object>] Positional arguments passed to the task block.
       #   @param mode [Symbol] Argument transfer mode.
       #   @param auto_local [Boolean] Whether to use local transfer in a thread pool.
+      #   @param timeout [Numeric, nil] Maximum scheduling wait in seconds. Nil waits indefinitely, zero polls.
       #   @yield [*args] Task to execute.
-      #   @return [Pool] self.
+      #   @return [self, nil] self when submitted, or nil when the scheduling timeout expires.
       #   @raise [PoolClosedError] If the pool is closing or closed.
       def schedule(...) = enqueue_task(false, ...)
 
@@ -83,9 +136,13 @@ module Farce
       # Arguments and transfer modes follow {#schedule}.
       #
       # @overload try_schedule(*args, mode: :smart, auto_local: true)
-      #   @param (see Farce::Abstract::Executor#schedule)
+      #   @param args (see Farce::Abstract::Executor#schedule)
+      #   @param mode (see Farce::Abstract::Executor#schedule)
+      #   @param auto_local (see Farce::Abstract::Executor#schedule)
       #   @return [self, nil] self when submitted, or nil when the queue is full.
-      def try_schedule(...) = enqueue_task(true, ...)
+      def try_schedule(*, mode: :smart, auto_local: true, &)
+        enqueue_task(true, *, mode:, auto_local:, &)
+      end
 
       # Stop accepting tasks and drain queued work.
       #
@@ -124,7 +181,9 @@ module Farce
       def drained? = closing? && @queue.closed?
 
       # Return whether all configured workers have been started.
-      def at_max_size? = size >= @max_size
+      # @overload at_max_size?
+      #   @return [Boolean]
+      def at_max_size?(settings = self.settings) = size >= settings.max_size
 
       # Return the generation used by workers waiting for admission.
       # @api private
@@ -140,19 +199,22 @@ module Farce
 
       # Record that a task left the shared queue.
       # @api private
-      def task_taken
-        return if @pressure.value.nil? || at_max_size?
+      def task_taken(settings = self.settings)
+        return if @pressure.value.nil? || at_max_size?(settings)
         return unless queue_empty?
         @pressure.value = nil
-        arm_scaler if @queue.size.positive?
+        arm_scaler(settings) if @queue.size.positive?
       end
 
       # Reserve a worker retirement above the minimum size.
       # @api private
-      def retire_worker
+      def retire_worker(excess: false, expected: nil)
         retired = false
         @worker_count.update do |count|
-          if state == :running && count > @min_size && queue_empty?
+          settings = self.settings
+          next count if expected && !expected.equal?(settings)
+          limit = excess ? settings.max_size : settings.min_size
+          if state == :running && count > limit && (excess || queue_empty?)
             retired = true
             count - 1
           else
@@ -162,9 +224,28 @@ module Farce
         retired
       end
 
+      # Recheck idle dispatchers after an excess worker finishes its last task.
+      # @api private
+      def wake_retiring_workers
+        return admission_changed if closed?
+        updated = @settings.update { |current| current.with(generation: current.generation + 1) }
+        @queue.interrupt(updated, updated.generation)
+        admission_changed
+      end
+
+      # Finish an already reserved retirement before attempting replacement.
+      # @api private
+      def worker_retired
+        ensure_minimum
+        admission_changed
+      rescue Exception => e # rubocop:disable Lint/RescueException
+        @error.compare_and_set(nil, Envelope.new(e))
+      end
+
       # Remove a stopped worker and preserve its failure.
       # @api private
       def worker_stopped(error, replace: true)
+        settings = self.settings
         @worker_count.update { |count| count - 1 }
         @error.compare_and_set(nil, Envelope.new(error)) if error
         if closing?
@@ -173,11 +254,11 @@ module Farce
           end
         elsif state == :running && replace
           begin
-            start_worker while size < @min_size
+            start_worker(settings) while size < settings.min_size
           rescue Exception # rubocop:disable Lint/RescueException
             nil
           end
-          arm_scaler if @queue.size.positive?
+          arm_scaler(settings) if @queue.size.positive?
         end
         admission_changed
       end
@@ -185,41 +266,44 @@ module Farce
       # Recheck delayed queue pressure and grow by one worker.
       # @api private
       def scale_if_needed(started)
+        settings = self.settings
         return unless state == :running && @pressure.value == started
         age = @queue.oldest_age
         return clear_pressure(started) unless age
-        return reschedule_scaler(started, @grow_after - age) if age < @grow_after
+        return reschedule_scaler(started, settings.grow_after - age) if age < settings.grow_after
 
-        start_worker unless at_max_size?
-        return clear_pressure(started) if queue_empty? || at_max_size?
+        start_worker(settings) unless at_max_size?(settings)
+        return clear_pressure(started) if queue_empty? || at_max_size?(settings)
 
         next_started = @queue.generation
-        schedule_scaler(next_started) if @pressure.compare_and_set(started, next_started)
+        schedule_scaler(next_started, settings.grow_after) if @pressure.compare_and_set(started, next_started)
       rescue Exception => e # rubocop:disable Lint/RescueException
         @error.compare_and_set(nil, Envelope.new(e))
       end
 
       # @api private
       def inspect_with(inspector)
+        settings = self.settings
         super do
           inspector.attribute(:state,        state)
           inspector.attribute(:backend,      @backend)
           inspector.attribute(:size,         size)
-          inspector.attribute(:min_size,     @min_size)
-          inspector.attribute(:max_size,     @max_size)
-          inspector.attribute(:max_inflight, @max_inflight) if @max_inflight
+          inspector.attribute(:min_size,     settings.min_size)
+          inspector.attribute(:max_size,     settings.max_size)
+          inspector.attribute(:max_inflight, settings.max_inflight) if settings.max_inflight
           yield if block_given?
         end
       end
 
       private
 
-      def enqueue_task(non_block, *args, mode: :smart, auto_local: true, &block)
+      def enqueue_task(non_block, *args, mode: :smart, auto_local: true, timeout: nil, &block)
         raise PoolClosedError, "cannot schedule task on a closed pool" if closed?
         raise LocalJumpError, "Cannot schedule without a block" unless block
 
+        deadline = scheduling_deadline(timeout)
         task = prepare_task(args, block, mode, auto_local)
-        return unless non_block ? @queue.try_push(task) : @queue.push(task)
+        return unless non_block ? @queue.try_push(task) : @queue.push(task, timeout: Clock.remaining(deadline))
         arm_scaler
         self
       rescue ClosedQueueError
@@ -227,6 +311,28 @@ module Farce
         raise PoolClosedError, "cannot schedule task on a closed pool"
       end
 
+      def update_settings(**changes)
+        raise PoolClosedError, "cannot configure a closed pool" if closed?
+        updated = @settings.update do |current|
+          value = current.with(**changes, generation: current.generation + 1)
+          raise ArgumentError, "min_size must be non-negative" if value.min_size.negative?
+          raise ArgumentError, "max_size must be positive" unless value.max_size.positive?
+          raise ArgumentError, "min_size must not exceed max_size" if value.min_size > value.max_size
+          raise ArgumentError, "max_inflight must be positive" if value.max_inflight && !value.max_inflight.positive?
+          value
+        end
+        @queue.interrupt(updated, updated.generation)
+        admission_changed
+        ensure_minimum
+        @pressure.value = nil
+        arm_scaler
+        updated
+      end
+
+      def ensure_minimum
+        start_worker while state == :running && size < settings.min_size
+      end
+
       def initialize_configuration(min_size:, max_size:, max_inflight:, grow_after:, shrink_after:, backend:)
         @min_size     = Integer(min_size)
         @max_size     = Integer(max_size)
@@ -235,6 +341,10 @@ module Farce
         @shrink_after = duration(shrink_after, :shrink_after, nil_allowed: true)
         @backend      = backend
         validate_sizes
+        @settings = Internal::Atom.new(Internal::PoolSettings.new(
+          min_size: @min_size, max_size: @max_size, max_inflight: @max_inflight,
+          grow_after: @grow_after, shrink_after: @shrink_after, generation: 0,
+        ))
       end
 
       def prepare_constructor(constructor)
@@ -266,11 +376,11 @@ module Farce
         value
       end
 
-      def start_worker(drain: false, only_if_empty: false)
+      def start_worker(settings = self.settings, drain: false, only_if_empty: false)
         reserved = false
         @worker_count.update do |count|
           can_start = state == :running || (drain && closing? && !queue_empty?)
-          if can_start && count < @max_size && (!only_if_empty || count.zero?)
+          if can_start && count < settings.max_size && (!only_if_empty || count.zero?)
             reserved = true
             count + 1
           else
@@ -288,17 +398,17 @@ module Farce
           &@constructor
         )
         launch_scheduler(scheduler)
-        admission_changed if at_max_size?
+        admission_changed if at_max_size?(settings)
         true
       rescue Exception => e # rubocop:disable Lint/RescueException
         worker ? worker.stopped(e, replace: false) : @worker_count.update { |count| count - 1 }
         raise
       end
 
-      def arm_scaler
-        return if at_max_size? || queue_empty? || state != :running
-        start_worker(only_if_empty: true) if size.zero?
-        return if at_max_size?
+      def arm_scaler(settings = self.settings)
+        return if at_max_size?(settings) || queue_empty? || state != :running
+        start_worker(settings, only_if_empty: true) if size.zero?
+        return if at_max_size?(settings)
 
         started = @queue.generation
         age     = @queue.oldest_age
@@ -306,13 +416,13 @@ module Farce
         return unless age
         return unless @pressure.compare_and_set(nil, started)
 
-        remaining = @grow_after - age
+        remaining = settings.grow_after - age
         remaining = 0 if remaining.negative?
 
         schedule_scaler(started, remaining)
       end
 
-      def schedule_scaler(started, delay = @grow_after)
+      def schedule_scaler(started, delay = settings.grow_after)
         Internal::PoolSupervisor.schedule(self, started, delay)
       end
 
@@ -322,8 +432,9 @@ module Farce
       end
 
       def clear_pressure(started)
+        settings = self.settings
         return unless @pressure.compare_and_set(started, nil)
-        arm_scaler if @queue.size.positive?
+        arm_scaler(settings) if @queue.size.positive?
       end
 
       def queue_empty? = @queue.size.zero? # rubocop:disable Style/ZeroLengthPredicate

data/lib/farce/abstract/priority_queue.rb

@@ -44,7 +44,7 @@ module Farce
                    end
 
           return result unless empty
-          remaining = remaining_timeout(deadline)
+          remaining = Clock.remaining(deadline)
           return block_given? ? yield : nil unless wait_pop(timeout: remaining)
         end
       end