farce 0.2.0-arm-linux-gnu → 0.3.0-arm-linux-gnu

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b3b75367e471eaa033e832d3dce0e50d7286b2b4f1da9873a0b5fa55f9d9ce0f
-  data.tar.gz: 5f2531148719ccd407e5e5451069b2df80e290607c8e4f2dc65300aa21246fb8
+  metadata.gz: d8295409e81c0cbabd7868166bfbf29d456d99babab6dee561feb8d3676a865d
+  data.tar.gz: 4fdf1d5d80980fca658668abf24ca9395524e65d30e4e4ce20745463c157117f
 SHA512:
-  metadata.gz: 35cbb56604adae3e1ca7105a3bd0a7c72d4d5e63126988767c4235c87a4bd4b04e3335714bb4bdcab696588c317398cfe07a5ca5bc357ddb9f4b796164283cd1
-  data.tar.gz: f8d44d695172b5994d1e75da5b7f4a850717d88356451a932ce9fb347ddb6a3ffcbe01e624ce2a8b70d9b8c632c2eb03ac18a32c105114c74f8b7c9a6e98ad89
+  metadata.gz: 86ebdae86e939f495543480a53b7df19aed571cadd1207a605122737424d14f6033584e0d96869ceafb9bf9383d34020b8ff388f4569b523f8d5cfa8f73b665f
+  data.tar.gz: 65d5fbdf1843f628c60f5e07e49b551ae4f1354c34afa72e02b95b18615a0d86d1a97c6bf4203c9933ce27ff34c433b07be01baa5721e907edcef22d8a241178

data/CHANGELOG.md

@@ -4,6 +4,53 @@ Farce follows [Semantic Versioning 2.0](http://semver.org/). Any public method o
 
 ## Development Releases
 
+### Farce 0.3.0 (2026-10-13)
+
+#### New Features
+
+##### Breaking Changes
+
+* `Abstract::Scheduler` is no longer a superclass of `Pool`. Use `Abstract::Executor` instead.
+
+##### Executor Improvements
+
+`Scheduler` and `Pool` have the following improvements:
+
+* They now support `try_schedule`, which discards tasks and returns `nil` when their internal queues are at capacity.
+* They now have `Unshared` and `Local` variants, running in a Ractor-local context (Pool will manage a Thread pool instead of a Ractor pool).
+
+Creates a thread pool with a maximum size of 2 and a queue capacity of 10:
+
+```ruby
+# A thread pool local to the current Ractor
+thread_pool = Farce::Unshared::Pool.new(max_size: 2, capacity: 10)
+
+# this should only run approximately 10 tasks on CRuby
+500.times { thread_pool.try_schedule { puts "Task executed" } }
+```
+
+##### Tasks
+
+A new class, `Task`, has been introduced to represent asynchronous tasks that can be scheduled and executed within Farce's executor framework,
+executed manually, or handed off to any other executor supporting procs or callable objects.
+
+```ruby
+task = Farce::Task.schedule do
+  puts "Task started"
+  sleep 1
+  :success
+ensure
+  puts "Task finished"
+end
+
+task.alive? # => true
+task.value  # => :success (blocks until the task completes)
+```
+
+#### Bug Fixes
+
+* Calling `wait_*` methods on atoms on JRuby no longer blocks a fiber scheduler.
+
 ### Farce 0.2.0 (2026-10-11)
 
 #### New Features

data/README.md

@@ -117,6 +117,7 @@ puts output
       - [`Farce.schedule`](#farceschedule)
       - [Schedulers](#schedulers)
       - [Ractor Pools](#ractor-pools)
+      - [Tasks](#tasks)
       - [Third-Party Fiber Schedulers](#third-party-fiber-schedulers)
     - [Integrations](#integrations)
       - [Active Support](#active-support)
@@ -1222,6 +1223,43 @@ pool = Farce::Pool.new(min_size: 4, max_size: 10, grow_after: 0.1)
 pool.schedule { puts "Hello from the pool!" }
 ```
 
+#### Tasks
+
+If you want to retrieve the result of an asynchronous operation, or monitor if it is still running, you can use `Farce::Task`:
+
+```ruby
+task = Farce::Task.schedule(1, 2) do |a, b|
+  sleep 1 # simulate intense computation
+  a + b
+end
+
+task.alive? # => true
+task.value  # => 3 (after approximately 1 second)
+task.join   # would block, but doesn't, as the task has already completed
+```
+
+Tasks can also be created without immediately scheduling them, allowing you to control when and how they are executed:
+
+```ruby
+task = Farce::Task.new { :success }
+task.alive?     # => true
+task.value(0.1) # => nil (after 100 milliseconds)
+
+Farce.schedule(&task)
+task.value # => :success
+```
+
+This allows you to use third-party executors:
+
+```ruby
+require "concurrent"
+executor = Concurrent.global_fast_executor
+task     = Farce::Task.new { :success }
+executor.post(&task)
+
+task.value # => :success
+```
+
 #### Third-Party Fiber Schedulers
 
 Both `Farce::Scheduler` and `Farce::Pool` run a Fiber scheduler under the hood to execute tasks. This is a Farce-internal scheduler by default, but you can replace it with your own if you want:
@@ -1420,7 +1458,7 @@ Other classes Farce provides include:
 * `Exchanger`: A synchronization point for two-way data swapping between Threads, Ractors, and/or Fibers. Drop-in replacement for concurrent-ruby's exchanger.
 * `Lazy`: Lazily initialized value.
 * `LazyRef`: A [reference](#references) for a lazily initialized value.
-* `ThreadScheduler`: An alternative [scheduler](#scheduling-code) creating a new thread for each unit of work. Used on TruffleRuby.
+* `ThreadExecutor`: A [task executor](#scheduling-code) creating a new thread for each unit of work. Used on TruffleRuby.
 * `Walker`: A tool for walking a Ruby object tree.
 * `WeakValue`: A value object version of [`WeakRef`](#weakref). Allows handling references more explicitly, without automatic method delegation.
 

data/docs/modes.md

@@ -391,6 +391,7 @@ The same choices appear in several Farce APIs. Containers normally default to `:
 | `Farce::WeakAtom` | `new`, `store`, `update`, and other replacement operations | Weakly held values. Supports only `:raise`, `:make_shareable`, and `:dedup`. Defaults to `:raise`. |
 | `Farce::Atom` | `new`, `store`, `swap`, `update`, and other replacement operations | The stored value. |
 | `Farce::Lazy`, `Farce::LazyRef` | `new` | The result computed once by the factory. |
+| `Farce::Task` | `new`, `schedule`, `try_schedule`, `in_parallel`, `on_main`, `add_argument` | Arguments and the successful result. `add_argument` overrides the mode for one argument. Scheduling can select local mode automatically. |
 | `Farce::Molecule` | `define`, `new` | Newly created field atoms. |
 | `Farce::Vector` | `new`, `push`, `store`, `update`, and other replacement operations | Element values. |
 | `Farce::WeakSet` | `new`, `add`, `add?` | Weakly held elements. Supports only `:raise`, `:make_shareable`, and `:dedup`. Defaults to `:raise`. |
@@ -400,9 +401,11 @@ The same choices appear in several Farce APIs. Containers normally default to `:
 | `Farce::TreeMap` | `new` | Values only. Keys follow the tree map's own rules. |
 | `Farce::LRUMap` | `new` | Values only. Individual value hits and writes update eviction order. |
 | `Farce::LFUMap` | `new` | Values only. Individual value hits and writes update eviction frequency. |
-| `Farce::Scheduler` | `schedule` | Task arguments, with automatic local transfer enabled by default. |
-| `Farce::ThreadScheduler` | `schedule`, `execute` | Accepts scheduler options but always keeps arguments local. |
-| `Farce::Pool` | `schedule` | Task arguments. `:local` is rejected. |
+| `Farce::Scheduler` | `schedule`, `try_schedule` | Task arguments, with automatic local transfer enabled by default. |
+| `Farce::Unshared::Scheduler`, `Farce::Local::Scheduler` | `schedule`, `try_schedule`, `execute` | Always local. With `auto_local: false`, only `:local` and smart modes are accepted. |
+| `Farce::ThreadExecutor` | `schedule`, `try_schedule`, `execute` | Accepts scheduler options but always keeps arguments local. |
+| `Farce::Pool` | `schedule`, `try_schedule` | Task arguments. `:local` is rejected. |
+| `Farce::Unshared::Pool`, `Farce::Local::Pool` | `schedule`, `try_schedule`, `execute` | Always local. With `auto_local: false`, only `:local` and smart modes are accepted. |
 
 `Farce::Lazy` runs its shareable factory once and applies the mode to the result. With
 `:copy`, each Ractor receives its own cached copy. Use `Farce::Strict::Lazy` when the
@@ -541,7 +544,7 @@ For containers that retain values, `:copy` gives each Ractor its own copy of a s
 
 ### Pass task data as arguments
 
-`Scheduler#schedule` and `Pool#schedule` accept `mode:` for task arguments. Pass mutable data as arguments instead of capturing it from the surrounding scope. A non-local task's block must be convertible to a shareable proc.
+Schedulers and pools accept `mode:` for task arguments in `schedule` and `try_schedule`. Pass mutable data as arguments instead of capturing it from the surrounding scope. A non-local task's block must be convertible to a shareable proc.
 
 ```ruby
 pool = Farce::Pool.new(max_size: 2)
@@ -557,7 +560,7 @@ pool.close
 results.close
 ```
 
-A scheduler defaults to `auto_local: true`, preserving the block and its arguments when scheduling from its owning Ractor. Set `auto_local: false` to enforce the requested mode there. A pool may choose another Ractor for any task, so it rejects `:local` and does not apply automatic local transfer.
+A scheduler defaults to `auto_local: true`, preserving the block and its arguments when scheduling from its owning Ractor. Set `auto_local: false` to enforce the requested mode there. `Farce::Pool` may choose another Ractor for any task, so it rejects `:local` and does not apply automatic local transfer. If you want a Pool with `local` support, use `Farce::Unshared::Pool` or `Farce::Local::Pool` instead.
 
 ## Under the hood
 

data/docs/scopes.md

@@ -238,7 +238,7 @@ Pass the needed data as task arguments when crossing an execution boundary. Use
 
 ## Classes that support scopes
 
-These classes accept the same five scopes. The scope determines which backing container or resource an operation uses. Each class retains its own behavior, such as queue ordering or weak references.
+The classes in this table accept the same five scopes. The scope determines which backing container or resource an operation uses. Each class retains its own behavior, such as queue ordering or weak references.
 
 | Class | What each scope gets |
 | --- | --- |
@@ -266,6 +266,8 @@ These classes accept the same five scopes. The scope determines which backing co
 | `Farce::Local::Lease` | An independently initialized resource to borrow. |
 | `Farce::Local::LeaseMap` | An independently initialized set of named resources. |
 | `Farce::Local::LeasePool` | A pool with its own resources and capacity. |
+| `Farce::Local::Scheduler` | A task scheduler with its own worker and lifecycle. |
+| `Farce::Local::Pool` | An elastic pool of thread workers with independent scaling and lifecycle. |
 
 ### Count within each scope
 

data/docs/variants.md

@@ -174,6 +174,15 @@ end
       <td align="center" style="text-align: center">➖</td> <!-- Unsafe -->
       <td align="center" style="text-align: center">✅</td> <!-- Transaction -->
     </tr>
+    <tr>
+      <td><tt>Pool</tt></td>
+      <td align="center" style="text-align: center">✅</td> <!-- Farce -->
+      <td align="center" style="text-align: center">➖</td> <!-- Strict -->
+      <td align="center" style="text-align: center">✅</td> <!-- Local -->
+      <td align="center" style="text-align: center">✅</td> <!-- Unshared -->
+      <td align="center" style="text-align: center">🔗</td> <!-- Unsafe -->
+      <td align="center" style="text-align: center">➖</td> <!-- Transaction -->
+    </tr>
     <tr>
       <td><tt>Port</tt></td>
       <td align="center" style="text-align: center">✅</td> <!-- Farce -->
@@ -201,6 +210,15 @@ end
       <td align="center" style="text-align: center">🔗</td> <!-- Unsafe -->
       <td align="center" style="text-align: center">➖</td> <!-- Transaction -->
     </tr>
+    <tr>
+      <td><tt>Scheduler</tt></td>
+      <td align="center" style="text-align: center">✅</td> <!-- Farce -->
+      <td align="center" style="text-align: center">➖</td> <!-- Strict -->
+      <td align="center" style="text-align: center">✅</td> <!-- Local -->
+      <td align="center" style="text-align: center">✅</td> <!-- Unshared -->
+      <td align="center" style="text-align: center">🔗</td> <!-- Unsafe -->
+      <td align="center" style="text-align: center">➖</td> <!-- Transaction -->
+    </tr>
     <tr>
       <td><tt>Set</tt></td>
       <td align="center" style="text-align: center">✅</td> <!-- Farce -->

data/lib/farce/abstract/executor.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Abstract
+    # A task executor that can submit work or wait for it to finish.
+    #
+    # {#schedule} submits a task. {#execute} waits for the task to finish and may
+    # run it directly when execution is local. Concrete executors decide where
+    # tasks run and how their arguments are transferred.
+    #
+    # @abstract Use a scheduler or pool class.
+    #
+    # @!method schedule(*args, mode: :smart, auto_local: true)
+    #   @abstract This method must be implemented by concrete executor subclasses.
+    #
+    #   Schedules a block for execution.
+    #   What actually happens depends on the concrete executor implementation.
+    #   Some executors may ignore the `auto_local` option. Some might treat every mode as `:local`.
+    #
+    #   The executor may choose to block until the task has been executed, but most will add it to a queue of pending
+    #   tasks, only blocking when that queue's capacity has been reached.
+    #
+    #   @!macro modes
+    #
+    #   @param args [Array]
+    #     Arguments to pass to the scheduled block.
+    #     May be handled according to `mode`.
+    #
+    #   @param mode [Symbol]
+    #     The mode in which to schedule the task. Defaults to `:smart`.
+    #     May be ignored by some executors.
+    #
+    #   @param auto_local [Boolean]
+    #     Whether to automatically use a local mode when possible. Defaults to `true`.
+    #     May be ignored by some executors.
+    #
+    #   @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]
+    #
+    # @!method close
+    #   @abstract This method must be implemented by concrete executor subclasses.
+    #   Closes the executor, releasing any resources it holds.
+    #   Once closed, the executor cannot be used to schedule new tasks.
+    #   Will drain any pending tasks before fully closing. If tasks are running indefinitely, it may block.
+    #   @return [self]
+    #
+    # @!method closed?
+    #   @abstract This method must be implemented by concrete executor subclasses.
+    #   @return [Boolean] Whether the executor is closed.
+    #
+    # @!method state
+    #   @abstract This method must be implemented by concrete executor subclasses.
+    #   @return [Symbol]
+    #     The current state of the executor.
+    #
+    #     Common states include:
+    #     * `:initialized`, `:launching` and `:setup` for the setup phase.
+    #     * `:running` for the execution phase.
+    #     * `:closing`, `:closed`, and `:error` for the termination phase.
+    #
+    #     Not all executors will implement every state.
+    #
+    # @!method ractor_shareable?
+    #   @abstract Executors should include {Shareable} or {Unshareable}, which implement this method.
+    #   @return [Boolean] Whether the executor is safe to use across Ractors.
+    class Executor
+      include Internal::Noncopyable
+
+      # An error that occurred during the executor's operation, if any.
+      # This is primarily for scheduling errors, not execution errors.
+      # You can check this if the {#state} is `:error`.
+      def error = nil
+
+      # @param wait [Boolean] Whether to wait for the owner to be non-nil before checking if the executor is local.
+      # @return [Boolean] Whether the executor is local for the current Ractor.
+      def local?(wait: true) = false # rubocop:disable Lint/UnusedMethodArgument
+
+      # 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)
+      # @return [self, nil] self when submitted, or nil when the queue is full.
+      def try_schedule(...) = schedule(...)
+
+      # Closes the executor in every scope.
+      # For executors without scopes, this behaves like {#close}.
+      #
+      # @return [self]
+      def close_all = close
+
+      # Like {#schedule}, with two differences:
+      # 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.
+      #
+      # @param (see #schedule)
+      # @return [self]
+      def execute(*, mode: :smart, auto_local: true, &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?
+          raise SchedulerClosedError, "cannot execute task on a closed scheduler" if closed?
+          yield(*)
+          return self
+        end
+
+        ran      = Farce::Flag.new(false)
+        signal   = Signal.new
+        callback = Ractor.shareable_proc(&callback) unless Ractor.shareable?(callback)
+
+        schedule(callback, ran, signal, *, mode:, auto_local:) do |callback, ran, signal, *args|
+          callback.call(*args)
+        ensure
+          ran.set
+          signal.broadcast
+        end
+
+        signal.wait_until { ran.value }
+        self
+      end
+    end
+  end
+end

data/lib/farce/abstract/pool.rb

@@ -0,0 +1,334 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Abstract
+    # A task scheduler with a dynamically sized pool of workers.
+    #
+    # Pools accept work through {#schedule}. {#close} rejects new tasks and drains
+    # queued work. Concrete pools use either Ractor or Thread workers.
+    #
+    # @abstract Use {Farce::Pool}, {Unshared::Pool}, or {Local::Pool}.
+    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.
+      #
+      # `max_inflight` is a soft limit. A worker may exceed it when its scheduler
+      # has no runnable fibers or when the pool has reached `max_size`.
+      #
+      # @param min_size [Integer] Workers started immediately and retained while open.
+      # @param max_size [Integer] Maximum workers allowed.
+      # @param max_inflight [Integer, nil] Soft task limit for each worker.
+      # @param grow_after [Numeric] Queue wait before adding another worker.
+      # @param shrink_after [Numeric, nil] Idle time before an extra worker retires.
+      # @param capacity [Integer, nil] Pending-task capacity.
+      # @param backend [Symbol] IO backend for the built-in scheduler.
+      # @yieldreturn [Object] Fiber scheduler constructed in each worker.
+      def initialize(min_size: 0, max_size: 4, max_inflight: 64,
+                     grow_after: 0.005, shrink_after: 30, capacity: 1024,
+                     backend: Internal::FROZEN_CONFIG.io_backend, &constructor)
+        constructor ||= Internal::FROZEN_CONFIG.fiber_scheduler_constructor
+        initialize_configuration(min_size:, max_size:, max_inflight:, grow_after:, shrink_after:, backend:)
+        @constructor  = prepare_constructor(constructor)
+        @queue        = new_queue(capacity: capacity && Integer(capacity))
+        @state        = Internal::Atom.new(:running)
+        @error        = Internal::Atom.new
+        @worker_count = Internal::Atom.new(0)
+        @pressure     = Internal::Atom.new
+        @admission    = Internal::Signal.new
+        super()
+        publish_pool
+        begin
+          @min_size.times { start_worker }
+        rescue Exception # rubocop:disable Lint/RescueException
+          close
+          raise
+        end
+      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.
+      #
+      # @overload schedule(*args, mode: :smart, auto_local: true)
+      #   @!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.
+      #   @yield [*args] Task to execute.
+      #   @return [Pool] self.
+      #   @raise [PoolClosedError] If the pool is closing or closed.
+      def schedule(...) = enqueue_task(false, ...)
+
+      # Enqueues a task without waiting for queue space.
+      # Arguments and transfer modes follow {#schedule}.
+      #
+      # @overload try_schedule(*args, mode: :smart, auto_local: true)
+      #   @param (see Farce::Abstract::Executor#schedule)
+      #   @return [self, nil] self when submitted, or nil when the queue is full.
+      def try_schedule(...) = enqueue_task(true, ...)
+
+      # Stop accepting tasks and drain queued work.
+      #
+      # @return [Pool] self.
+      def close
+        return self if closed?
+        @state.compare_and_set(:running, :closing)
+        @queue.seal
+        admission_changed
+        if size.zero?
+          @queue.closed? ? finish_close : start_worker(drain: true)
+        end
+        self
+      end
+
+      # Return the first worker error, if any.
+      def error
+        value = @error.value
+        value.is_a?(Envelope) ? value.value : value
+      end
+
+      # Return the current number of running and starting workers.
+      def size = @worker_count.value
+
+      # Return the current pool state.
+      def state = @state.value
+
+      # Return whether the pool rejects new tasks.
+      def closed? = state != :running
+
+      # Return whether the pool is draining queued work.
+      def closing? = state == :closing
+
+      # Return whether closing workers have drained all admitted submissions.
+      # @api private
+      def drained? = closing? && @queue.closed?
+
+      # Return whether all configured workers have been started.
+      def at_max_size? = size >= @max_size
+
+      # Return the generation used by workers waiting for admission.
+      # @api private
+      def admission_generation = @admission.generation
+
+      # Wait for worker capacity or a pool state change.
+      # @api private
+      def wait_for_admission(generation) = @admission.wait(generation)
+
+      # Wake workers waiting at their soft admission limit.
+      # @api private
+      def admission_changed = @admission.broadcast
+
+      # Record that a task left the shared queue.
+      # @api private
+      def task_taken
+        return if @pressure.value.nil? || at_max_size?
+        return unless queue_empty?
+        @pressure.value = nil
+        arm_scaler if @queue.size.positive?
+      end
+
+      # Reserve a worker retirement above the minimum size.
+      # @api private
+      def retire_worker
+        retired = false
+        @worker_count.update do |count|
+          if state == :running && count > @min_size && queue_empty?
+            retired = true
+            count - 1
+          else
+            count
+          end
+        end
+        retired
+      end
+
+      # Remove a stopped worker and preserve its failure.
+      # @api private
+      def worker_stopped(error, replace: true)
+        @worker_count.update { |count| count - 1 }
+        @error.compare_and_set(nil, Envelope.new(error)) if error
+        if closing?
+          if size.zero?
+            error && !drained? ? start_worker(drain: true) : finish_close
+          end
+        elsif state == :running && replace
+          begin
+            start_worker while size < @min_size
+          rescue Exception # rubocop:disable Lint/RescueException
+            nil
+          end
+          arm_scaler if @queue.size.positive?
+        end
+        admission_changed
+      end
+
+      # Recheck delayed queue pressure and grow by one worker.
+      # @api private
+      def scale_if_needed(started)
+        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
+
+        start_worker unless at_max_size?
+        return clear_pressure(started) if queue_empty? || at_max_size?
+
+        next_started = @queue.generation
+        schedule_scaler(next_started) 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)
+        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
+          yield if block_given?
+        end
+      end
+
+      private
+
+      def enqueue_task(non_block, *args, mode: :smart, auto_local: true, &block)
+        raise PoolClosedError, "cannot schedule task on a closed pool" if closed?
+        raise LocalJumpError, "Cannot schedule without a block" unless block
+
+        task = prepare_task(args, block, mode, auto_local)
+        return unless non_block ? @queue.try_push(task) : @queue.push(task)
+        arm_scaler
+        self
+      rescue ClosedQueueError
+        raise unless closed?
+        raise PoolClosedError, "cannot schedule task on a closed pool"
+      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)
+        @max_inflight = max_inflight && Integer(max_inflight)
+        @grow_after   = duration(grow_after, :grow_after)
+        @shrink_after = duration(shrink_after, :shrink_after, nil_allowed: true)
+        @backend      = backend
+        validate_sizes
+      end
+
+      def prepare_constructor(constructor)
+        return constructor if !constructor || Ractor.shareable?(constructor)
+        Ractor.shareable_proc(&constructor)
+      end
+
+      def prepare_task(args, block, mode, _auto_local)
+        raise ArgumentError, "local transfer is not supported by a pool" if mode == :local
+        Internal::ScheduledTask.new(args, block, mode)
+      end
+
+      def new_queue(capacity:) = Internal::Queue.new(capacity:, track_age: true)
+      def new_worker = Internal::PoolWorker.new(self)
+      def new_scheduler(**, &) = Farce::Scheduler.new(**, &)
+      def launch_scheduler(scheduler) = scheduler.launch_ractor
+
+      def validate_sizes
+        raise ArgumentError, "min_size must be non-negative" if @min_size.negative?
+        raise ArgumentError, "max_size must be positive" unless @max_size.positive?
+        raise ArgumentError, "min_size must not exceed max_size" if @min_size > @max_size
+        raise ArgumentError, "max_inflight must be positive" if @max_inflight && !@max_inflight.positive?
+      end
+
+      def duration(value, name, nil_allowed: false)
+        return if value.nil? && nil_allowed
+        value = Float(value)
+        raise ArgumentError, "#{name} must be finite and non-negative" if !value.finite? || value.negative?
+        value
+      end
+
+      def start_worker(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?)
+            reserved = true
+            count + 1
+          else
+            count
+          end
+        end
+        return false unless reserved
+
+        worker = new_worker
+        scheduler = new_scheduler(
+          backend:     @backend,
+          queue:       @queue,
+          pool_worker: worker,
+          queue_owner: false,
+          &@constructor
+        )
+        launch_scheduler(scheduler)
+        admission_changed if at_max_size?
+        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?
+
+        started = @queue.generation
+        age     = @queue.oldest_age
+
+        return unless age
+        return unless @pressure.compare_and_set(nil, started)
+
+        remaining = @grow_after - age
+        remaining = 0 if remaining.negative?
+
+        schedule_scaler(started, remaining)
+      end
+
+      def schedule_scaler(started, delay = @grow_after)
+        Internal::PoolSupervisor.schedule(self, started, delay)
+      end
+
+      def reschedule_scaler(started, delay)
+        next_started = @queue.generation
+        schedule_scaler(next_started, delay) if @pressure.compare_and_set(started, next_started)
+      end
+
+      def clear_pressure(started)
+        return unless @pressure.compare_and_set(started, nil)
+        arm_scaler if @queue.size.positive?
+      end
+
+      def queue_empty? = @queue.size.zero? # rubocop:disable Style/ZeroLengthPredicate
+
+      def finish_close = @state.compare_and_set(:closing, :closed)
+    end
+  end
+end