farce 0.4.1-java → 0.5.0-java

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

data/lib/farce/abstract/publisher.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Abstract
+    # @abstract Shared superclass for all publisher implementations.
+    #
+    # Implements a publisher-subscriber (pub-sub) pattern.
+    # @see Farce::Publisher
+    class Publisher
+      include Internal::Freeze::Unfreezable
+      include Internal::Noncopyable
+
+      # @param subscribers [Array]
+      #   the initial subscribers to add to the publisher, see {#subscribe}
+      def initialize(*subscribers)
+        @closed = Farce::Flag.new
+        super()
+        subscribers.each { subscribe(it) }
+      end
+
+      # @return [Boolean] whether the publisher is closed.
+      def closed? = @closed.value
+
+      # Publishes the given payload to all current subscribers.
+      #
+      # Full bounded queues drop new messages.
+      # Failed publishing attempts to closed or frozen receivers cancel their subscriptions.
+      #
+      # @param payload [BasicObject] the payload to publish
+      # @return [self] the publisher itself
+      def publish(payload = nil)
+        raise "Cannot publish to a closed publisher" if closed?
+        map.each_value { it.publish(payload) }
+        self
+      end
+      alias send      publish
+      alias <<        publish
+      alias broadcast publish
+
+      # @overload subscribe(subscriber)
+      #   Adds a subscriber to the publisher.
+      #   Register additional subscriber classes with {Subscription.define}.
+      #   Publisher subscribers forward messages synchronously to their own subscribers.
+      #   Avoid subscribing publishers in a cycle.
+      #
+      #   @example Forward messages to another publisher
+      #     upstream.subscribe(downstream)
+      #     upstream.publish(:message) # also publishes to downstream's subscribers
+      #
+      #   @param subscriber [BasicObject]
+      #     The subscriber to add.
+      #     Standard-library queues are supported by unshared and local publishers and retain the original payload.
+      #     A full `Thread::SizedQueue` drops new messages. Publishing to a closed queue cancels its subscription.
+      #
+      #     Calls one of the following methods:
+      #     * {Ractor#send}
+      #     * {Ractor::Port#send}
+      #     * {Queue#try_push}
+      #     * `Thread::Queue#push`
+      #     * `Thread::SizedQueue#push` (nonblocking)
+      #     * {Counter#increment} (without arguments)
+      #     * {Flag#set}
+      #     * {Atom#value=}
+      #     * {Set#<<}
+      #     * {Vector#<<}
+      #     * {Signal#broadcast} (without arguments)
+      #     * {Publisher#publish}
+      #     * {Farce::Concurrent::Event#set} (without arguments)
+      #     * {Farce::Concurrent::CountDownLatch#count_down} (without arguments)
+      #     * `Proc#call`
+      #
+      #     The concurrent-ruby integration supports these subscribers with unshared and local publishers:
+      #     * `Concurrent::AtomicReference#value=`
+      #     * `Concurrent::AtomicFixnum#increment` (without arguments)
+      #     * `Concurrent::AtomicBoolean#make_true`
+      #     * `Concurrent::Event#set` (without arguments)
+      #     * `Concurrent::CountDownLatch#count_down` (without arguments)
+      #
+      #     Set the default `mode`, `auto_local`, `capacity`, and similar options via initializers for these classes
+      #     to influence how data transfer is handled.
+      #
+      #     Support for additional subscribers can be added via {Subscription.define}.
+      #
+      # @overload subscribe(*args, mode: nil, scheduler: nil, capacity: nil)
+      #   Adds a subscription callback.
+      #   Messages run in order on the selected scheduler. A full queue drops new messages.
+      #   Unsubscribing drains queued messages and stops the callback.
+      #
+      #   @example
+      #     counter = Farce::Counter.new
+      #
+      #     publisher.subscribe(counter) do |counter, payload|
+      #       counter.increment
+      #       puts "Message ##{counter}: #{payload.inspect}"
+      #     end
+      #
+      #   @param args [Array] additional arguments to pass to the subscriber
+      #   @param mode [Symbol, nil] The transfer mode to use
+      #   @param scheduler [#schedule, nil] The scheduler to use for running the block
+      #   @param capacity [Integer, nil] the maximum queued messages, or nil for an unbounded queue
+      #   @yield [*args, payload] the block to be called with the given arguments and payload
+      #   @yieldparam args [Array] the additional arguments passed to the block
+      #   @yieldparam payload [Object] the payload sent via {#publish}
+      #
+      # @return [Subscription] the created subscription
+      def subscribe(...) = block_given? ? create_subscription(...) : add_subscription(...)
+      alias monitor subscribe
+
+      # @param subscriber [BasicObject] the subscriber to retrieve the subscription for
+      # @return [Subscription, nil] the subscription for the given subscriber, or nil if none exists.
+      def subscription_for(subscriber)
+        if subscriber.is_a?(Subscription)
+          return unless subscriber.publisher.equal?(self)
+          subscription = map[subscriber.key]
+          subscription if subscription.equal?(subscriber)
+        else
+          map[subscriber.__id__]
+        end
+      end
+
+      # @return [Boolean] whether the given subscriber is currently subscribed.
+      def subscribed?(subscriber) = !!subscription_for(subscriber)&.subscribed?
+
+      # Unsubscribes the given subscriber from the publisher.
+      # @param subscriber [BasicObject] the subscriber to unsubscribe
+      # @return [void]
+      def unsubscribe(subscriber) = subscription_for(subscriber)&.unsubscribe
+      alias cancel    unsubscribe
+      alias unmonitor unsubscribe
+
+      private
+
+      def default_mode = :smart
+      def map          = raise NoMethodError, "Subclasses must implement the private `map` method"
+
+      def add_subscription(subscriber)
+        if subscriber.is_a?(Subscription)
+          existing = subscription_for(subscriber)
+          return existing if existing
+          subscriber = subscriber.subscriber
+        end
+        return create_subscription(source: subscriber, &subscriber) if subscriber.is_a?(Proc)
+
+        map = self.map
+        map.store_if_absent(subscriber.__id__) { build_subscription(subscriber, map) }
+      end
+
+      def create_subscription(*, capacity: nil, mode: nil, scheduler: nil, source: nil, &callback)
+        mode      ||= default_mode
+        callback    = Ractor.shareable_proc(&callback) unless mode == :local || Ractor.shareable?(callback)
+        scheduler ||= Farce
+        queue       = Farce::Queue.new(capacity:, mode:)
+        map         = self.map
+        created     = false
+        subscription = map.store_if_absent((source || queue).__id__) do
+          created = true
+          build_subscription(queue, map, callback: true, source:)
+        end
+        return subscription unless created
+
+        scheduler.schedule(queue, callback, subscription, *, mode:) do |queue, callback, subscription, *args|
+          loop do
+            begin
+              payload = queue.pop
+            rescue ClosedQueueError
+              break
+            end
+            callback.call(*args, payload)
+          end
+        ensure
+          subscription.unsubscribe
+          queue.close
+        end
+
+        scheduled = true
+        subscription
+      ensure
+        unless scheduled
+          subscription&.unsubscribe if created
+          queue&.close
+        end
+      end
+
+      def build_subscription(...) = Subscription.build(self, ...)
+    end
+  end
+end

data/lib/farce/abstract/queue.rb

@@ -11,8 +11,11 @@ module Farce
     #
     # Queues have a blocking and non-blocking interface.
     #
-    # @!attribute [r] capacity
-    #   @abstract
+    # @!attribute [rw] capacity
+    #   Assign a positive limit, or `nil` for an unbounded queue.
+    #   Changes preserve queued values. Local queues change only the current scope.
+    #   On JRuby and TruffleRuby, normal FIFO queues retain their initial bounded or unbounded choice.
+    #   Switching between these states may raise `ArgumentError`. Priority and timer queues support both.
     #   @return [Integer, nil] The maximum number of items the queue can hold.
     #
     # @!attribute [r] num_waiting
@@ -173,10 +176,33 @@ module Farce
 
       # Whether the queue is at capacity.
       # @return [Boolean] `true` if the queue is at capacity, `false` otherwise.
-      def full? = capacity && size >= capacity
+      def full?
+        limit = capacity
+        limit && size >= limit
+      end
 
       def capacity = internal_queue.capacity
 
+      # Change the limit without discarding queued values. Returns immediately.
+      #
+      # New pushes wait while the queue is at or above the new limit.
+      # Increasing or removing the limit wakes blocked producers.
+      #
+      # Local queues change only the current scope. New scopes retain the constructor limit.
+      #
+      # Priority and timer queues support bounded and unbounded transitions on every engine.
+      #
+      # FIFO queues on JRuby and TruffleRuby retain their initial bounded or unbounded choice.
+      #
+      # @param value [Integer, nil] the positive capacity, or `nil` to remove the limit
+      # @return [Integer, nil] the new capacity
+      # @raise [ArgumentError] if the capacity is not positive
+      # @raise [ArgumentError] on JRuby and TruffleRuby, normal FIFO queues may reject transitions
+      #   between bounded and unbounded states
+      def capacity=(value)
+        internal_queue.capacity = value.nil? ? nil : Integer(value)
+      end
+
       def clear
         internal_queue.clear
         self