atomic-ruby 0.14.1 → 0.15.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1310b5db37f97fe6e8a8e9da89083554f2bc5cd4500027e853e268d99db15cc6
-  data.tar.gz: 94039f36f8c248fc2bbc60529deff3c72d933d6c6e638d6f70136f64ad798825
+  metadata.gz: af7a35affcaa2790e6944ee01eb6af8f4d92b5c2479bb1995128742a562fd395
+  data.tar.gz: d3908277e6ef09a70f7d46a057a5db7f60c179885d980b4fbbf407bdade6b073
 SHA512:
-  metadata.gz: 9ad6f1cefcf6a6f39635baa7e2d384e6d6a4e273927c9a442bcb4a63036172dcc1c222fb4fd02d61878205db8163f91f70b4a8a753c48c2de760bc74950987f7
-  data.tar.gz: 448588150ab485b7a1cb6f7dfe892feba5b15c7b32d6d766570ef4097ec48a3ee0a7fbdc20fa92e9875d7701ee42e31660df9c759d24243f250a7987357d870b
+  metadata.gz: f5a3525b194636ddb439c0c8e9597e3ed1870a8c0165bc1582cb120a45c49b30a8cf6bd60f393a9e3e0c848abf760b181dce1b9b3026199ff8ffb2ba833dcc1a
+  data.tar.gz: e89a1f593774fc1722bfc8a9229385682e33a10df705ba78da3c67f904ab566c770b7aebdebc32069ed7f4dfc2781ad52165f08f10cf3fd4e4d723c41687e02f

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 ## [Unreleased]
 
+## [0.15.1] - 2026-08-30
+
+- Prevent OS scheduling delays from stopping adaptive thread pool growth
+
+## [0.15.0] - 2026-08-29
+
+- Add adaptive scaling to `AtomicThreadPool` with `max_size:`
+
 ## [0.14.1] - 2026-08-20
 
 - Fix O(n) in `AtomicThreadPool#length` by tracking the alive count

data/README.md

@@ -120,6 +120,18 @@ p results           #=> [8, 7, 10, 9, 6, 5, 3, 4, 2, 1]
 p results.sort      #=> [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
 ```
 
+Pass `max_size` to let the pool temporarily add workers when queued work is
+held up by blocking operations. The pool measures time spent blocked outside
+the GVL and CPU time used by its workers, so it does not add more threads when
+Ruby execution is the bottleneck. It returns to `size` when the queue drains.
+
+```ruby
+pool = AtomicThreadPool.new(size: 4, max_size: 16)
+
+# Grow without a limit
+pool = AtomicThreadPool.new(size: 4, max_size: Float::INFINITY)
+```
+
 `AtomicCountDownLatch`:
 
 ```ruby
@@ -256,7 +268,7 @@ puts "Atomic Ruby Atomic Bank Account:     #{results[2].real.round(6)} seconds"
 
 ruby version:            ruby 4.0.6 (2026-07-14 revision 03b6d3f889) +YJIT +PRISM [arm64-darwin23]
 concurrent-ruby version: 1.3.6
-atomic-ruby version:     0.14.1
+atomic-ruby version:     0.15.1
 
 Balances:
 Synchronized Bank Account Balance:           975
@@ -347,7 +359,7 @@ end
 
 ruby version:            ruby 4.0.6 (2026-07-14 revision 03b6d3f889) +YJIT +PRISM [arm64-darwin23]
 concurrent-ruby version: 1.3.6
-atomic-ruby version:     0.14.1
+atomic-ruby version:     0.15.1
 
 Warming up --------------------------------------
           Synchronized Boolean Toggle   157.000 i/100ms
@@ -430,7 +442,7 @@ end
 > bundle exec rake clobber && bundle exec rake compile && bundle exec ruby examples/atomic_condition_variable_benchmark.rb
 
 ruby version:        ruby 4.0.6 (2026-07-14 revision 03b6d3f889) +YJIT +PRISM [arm64-darwin23]
-atomic-ruby version: 0.14.1
+atomic-ruby version: 0.15.1
 
 Warming up --------------------------------------
       Synchronized Condition Variable Wait/Signal     3.977k i/100ms
@@ -505,7 +517,7 @@ end
 > bundle exec rake clobber && bundle exec rake compile && bundle exec ruby examples/atomic_queue_benchmark.rb
 
 ruby version:        ruby 4.0.6 (2026-07-14 revision 03b6d3f889) +YJIT +PRISM [arm64-darwin23]
-atomic-ruby version: 0.14.1
+atomic-ruby version: 0.15.1
 
 Warming up --------------------------------------
       Synchronized Queue Push/Pop   181.000 i/100ms
@@ -575,11 +587,11 @@ puts "Atomic Ruby Atomic Thread Pool: #{results[1].real.round(6)} seconds"
 
 ruby version:            ruby 4.0.6 (2026-07-14 revision 03b6d3f889) +YJIT +PRISM [arm64-darwin23]
 concurrent-ruby version: 1.3.8
-atomic-ruby version:     0.14.1
+atomic-ruby version:     0.15.1
 
 Benchmark Results:
-Concurrent Ruby Thread Pool:    5.046895 seconds
-Atomic Ruby Atomic Thread Pool: 4.717221 seconds
+Concurrent Ruby Thread Pool:    5.079561 seconds
+Atomic Ruby Atomic Thread Pool: 4.99168 seconds
 ```
 
 </details>

data/ext/atomic_ruby/atomic_ruby.c

@@ -521,6 +521,197 @@ static VALUE rb_cAtomicConditionVariable_waiter_count(VALUE self) {
   return UINT2NUM((unsigned int)RUBY_ATOMIC_LOAD(atomic_ruby_condition_variable->count));
 }
 
+typedef enum {
+  ATOMIC_RUBY_THREAD_POOL_WORKER_INACTIVE,
+  ATOMIC_RUBY_THREAD_POOL_WORKER_RUNNING,
+  ATOMIC_RUBY_THREAD_POOL_WORKER_WAITING,
+  ATOMIC_RUBY_THREAD_POOL_WORKER_BLOCKED
+} atomic_ruby_thread_pool_worker_phase_t;
+
+typedef struct {
+  _Atomic unsigned int running_count;
+  _Atomic unsigned int waiting_count;
+  _Atomic unsigned int blocked_count;
+  _Atomic unsigned long long running_time;
+  _Atomic unsigned long long waiting_time;
+  _Atomic unsigned long long blocked_time;
+  _Atomic unsigned long long running_cpu_time;
+} atomic_ruby_thread_pool_monitor_t;
+
+typedef struct {
+  atomic_ruby_thread_pool_monitor_t *monitor;
+  atomic_ruby_thread_pool_worker_phase_t phase;
+  unsigned long long phase_started_at;
+  unsigned long long running_cpu_started_at;
+} atomic_ruby_thread_pool_worker_state_t;
+
+static rb_internal_thread_specific_key_t atomic_ruby_thread_pool_worker_key;
+
+static void atomic_ruby_thread_pool_monitor_free(void *ptr) {
+  xfree(ptr);
+}
+
+static size_t atomic_ruby_thread_pool_monitor_memsize(const void *ptr) {
+  return sizeof(atomic_ruby_thread_pool_monitor_t);
+}
+
+static const rb_data_type_t atomic_ruby_thread_pool_monitor_type = {
+  .wrap_struct_name = "AtomicRuby::ThreadPoolMonitor",
+  .function = {
+    .dfree = atomic_ruby_thread_pool_monitor_free,
+    .dsize = atomic_ruby_thread_pool_monitor_memsize
+  },
+  .flags = RUBY_TYPED_FREE_IMMEDIATELY | RUBY_TYPED_WB_PROTECTED
+};
+
+static unsigned long long atomic_ruby_monotonic_time(void) {
+  struct timespec time;
+  if (clock_gettime(CLOCK_MONOTONIC, &time) == -1) return 0;
+
+  return (unsigned long long)time.tv_sec * 1000000000ULL + (unsigned long long)time.tv_nsec;
+}
+
+static unsigned long long atomic_ruby_thread_cpu_time(void) {
+  struct timespec time;
+  if (clock_gettime(CLOCK_THREAD_CPUTIME_ID, &time) == -1) return 0;
+
+  return (unsigned long long)time.tv_sec * 1000000000ULL + (unsigned long long)time.tv_nsec;
+}
+
+static void atomic_ruby_thread_pool_worker_leave_phase(atomic_ruby_thread_pool_worker_state_t *state, unsigned long long now) {
+  unsigned long long elapsed = now != 0 && state->phase_started_at != 0 && now >= state->phase_started_at ? now - state->phase_started_at : 0;
+
+  switch (state->phase) {
+    case ATOMIC_RUBY_THREAD_POOL_WORKER_RUNNING: {
+      unsigned long long cpu_now = atomic_ruby_thread_cpu_time();
+      unsigned long long cpu_elapsed = cpu_now != 0 && state->running_cpu_started_at != 0 && cpu_now >= state->running_cpu_started_at
+        ? cpu_now - state->running_cpu_started_at
+        : 0;
+      atomic_fetch_sub_explicit(&state->monitor->running_count, 1, memory_order_relaxed);
+      atomic_fetch_add_explicit(&state->monitor->running_time, elapsed, memory_order_relaxed);
+      atomic_fetch_add_explicit(&state->monitor->running_cpu_time, cpu_elapsed, memory_order_relaxed);
+      break;
+    }
+    case ATOMIC_RUBY_THREAD_POOL_WORKER_WAITING:
+      atomic_fetch_sub_explicit(&state->monitor->waiting_count, 1, memory_order_relaxed);
+      atomic_fetch_add_explicit(&state->monitor->waiting_time, elapsed, memory_order_relaxed);
+      break;
+    case ATOMIC_RUBY_THREAD_POOL_WORKER_BLOCKED:
+      atomic_fetch_sub_explicit(&state->monitor->blocked_count, 1, memory_order_relaxed);
+      atomic_fetch_add_explicit(&state->monitor->blocked_time, elapsed, memory_order_relaxed);
+      break;
+    case ATOMIC_RUBY_THREAD_POOL_WORKER_INACTIVE:
+      break;
+  }
+}
+
+static void atomic_ruby_thread_pool_worker_enter_phase(atomic_ruby_thread_pool_worker_state_t *state, atomic_ruby_thread_pool_worker_phase_t phase, unsigned long long now) {
+  state->phase = phase;
+  state->phase_started_at = now;
+
+  switch (phase) {
+    case ATOMIC_RUBY_THREAD_POOL_WORKER_RUNNING:
+      atomic_fetch_add_explicit(&state->monitor->running_count, 1, memory_order_relaxed);
+      state->running_cpu_started_at = atomic_ruby_thread_cpu_time();
+      break;
+    case ATOMIC_RUBY_THREAD_POOL_WORKER_WAITING:
+      atomic_fetch_add_explicit(&state->monitor->waiting_count, 1, memory_order_relaxed);
+      break;
+    case ATOMIC_RUBY_THREAD_POOL_WORKER_BLOCKED:
+      atomic_fetch_add_explicit(&state->monitor->blocked_count, 1, memory_order_relaxed);
+      break;
+    case ATOMIC_RUBY_THREAD_POOL_WORKER_INACTIVE:
+      break;
+  }
+}
+
+static void atomic_ruby_thread_pool_event_callback(rb_event_flag_t event, const rb_internal_thread_event_data_t *event_data, void *user_data) {
+  atomic_ruby_thread_pool_worker_state_t *state = rb_internal_thread_specific_get(event_data->thread, atomic_ruby_thread_pool_worker_key);
+  if (state == NULL || state->phase == ATOMIC_RUBY_THREAD_POOL_WORKER_INACTIVE) return;
+
+  unsigned long long now = atomic_ruby_monotonic_time();
+  atomic_ruby_thread_pool_worker_leave_phase(state, now);
+
+  switch (event) {
+    case RUBY_INTERNAL_THREAD_EVENT_READY:
+      atomic_ruby_thread_pool_worker_enter_phase(state, ATOMIC_RUBY_THREAD_POOL_WORKER_WAITING, now);
+      break;
+    case RUBY_INTERNAL_THREAD_EVENT_RESUMED:
+      atomic_ruby_thread_pool_worker_enter_phase(state, ATOMIC_RUBY_THREAD_POOL_WORKER_RUNNING, now);
+      break;
+    case RUBY_INTERNAL_THREAD_EVENT_SUSPENDED:
+      atomic_ruby_thread_pool_worker_enter_phase(state, ATOMIC_RUBY_THREAD_POOL_WORKER_BLOCKED, now);
+      break;
+  }
+}
+
+static VALUE rb_cThreadPoolMonitor_allocate(VALUE klass) {
+  atomic_ruby_thread_pool_monitor_t *monitor;
+  VALUE obj = TypedData_Make_Struct(klass, atomic_ruby_thread_pool_monitor_t, &atomic_ruby_thread_pool_monitor_type, monitor);
+  atomic_init(&monitor->running_count, 0);
+  atomic_init(&monitor->waiting_count, 0);
+  atomic_init(&monitor->blocked_count, 0);
+  atomic_init(&monitor->running_time, 0);
+  atomic_init(&monitor->waiting_time, 0);
+  atomic_init(&monitor->blocked_time, 0);
+  atomic_init(&monitor->running_cpu_time, 0);
+  return obj;
+}
+
+static VALUE rb_cThreadPoolMonitor_register_worker(VALUE self) {
+  atomic_ruby_thread_pool_monitor_t *monitor;
+  TypedData_Get_Struct(self, atomic_ruby_thread_pool_monitor_t, &atomic_ruby_thread_pool_monitor_type, monitor);
+
+  VALUE thread = rb_thread_current();
+  atomic_ruby_thread_pool_worker_state_t *state = ALLOC(atomic_ruby_thread_pool_worker_state_t);
+  state->monitor = monitor;
+  state->phase = ATOMIC_RUBY_THREAD_POOL_WORKER_INACTIVE;
+  state->phase_started_at = 0;
+  state->running_cpu_started_at = 0;
+  rb_internal_thread_specific_set(thread, atomic_ruby_thread_pool_worker_key, state);
+  return Qnil;
+}
+
+static VALUE rb_cThreadPoolMonitor_unregister_worker(VALUE self) {
+  VALUE thread = rb_thread_current();
+  atomic_ruby_thread_pool_worker_state_t *state = rb_internal_thread_specific_get(thread, atomic_ruby_thread_pool_worker_key);
+  if (state == NULL) return Qnil;
+
+  atomic_ruby_thread_pool_worker_leave_phase(state, atomic_ruby_monotonic_time());
+  rb_internal_thread_specific_set(thread, atomic_ruby_thread_pool_worker_key, NULL);
+  xfree(state);
+  return Qnil;
+}
+
+static VALUE rb_cThreadPoolMonitor_start_work(VALUE self) {
+  atomic_ruby_thread_pool_worker_state_t *state = rb_internal_thread_specific_get(rb_thread_current(), atomic_ruby_thread_pool_worker_key);
+  atomic_ruby_thread_pool_worker_enter_phase(state, ATOMIC_RUBY_THREAD_POOL_WORKER_RUNNING, atomic_ruby_monotonic_time());
+  return Qnil;
+}
+
+static VALUE rb_cThreadPoolMonitor_stop_work(VALUE self) {
+  atomic_ruby_thread_pool_worker_state_t *state = rb_internal_thread_specific_get(rb_thread_current(), atomic_ruby_thread_pool_worker_key);
+  atomic_ruby_thread_pool_worker_leave_phase(state, atomic_ruby_monotonic_time());
+  state->phase = ATOMIC_RUBY_THREAD_POOL_WORKER_INACTIVE;
+  return Qnil;
+}
+
+static VALUE rb_cThreadPoolMonitor_snapshot(VALUE self) {
+  atomic_ruby_thread_pool_monitor_t *monitor;
+  TypedData_Get_Struct(self, atomic_ruby_thread_pool_monitor_t, &atomic_ruby_thread_pool_monitor_type, monitor);
+
+  return rb_ary_new_from_args(
+    7,
+    UINT2NUM(atomic_load_explicit(&monitor->running_count, memory_order_relaxed)),
+    UINT2NUM(atomic_load_explicit(&monitor->waiting_count, memory_order_relaxed)),
+    UINT2NUM(atomic_load_explicit(&monitor->blocked_count, memory_order_relaxed)),
+    ULL2NUM(atomic_load_explicit(&monitor->running_time, memory_order_relaxed)),
+    ULL2NUM(atomic_load_explicit(&monitor->waiting_time, memory_order_relaxed)),
+    ULL2NUM(atomic_load_explicit(&monitor->blocked_time, memory_order_relaxed)),
+    ULL2NUM(atomic_load_explicit(&monitor->running_cpu_time, memory_order_relaxed))
+  );
+}
+
 RUBY_FUNC_EXPORTED void Init_atomic_ruby(void) {
 #ifdef ATOMIC_RUBY_RACTOR_SAFE
   rb_ext_ractor_safe(true);
@@ -563,4 +754,21 @@ RUBY_FUNC_EXPORTED void Init_atomic_ruby(void) {
   rb_define_private_method(rb_cAtomicConditionVariable, "_shift_thread", rb_cAtomicConditionVariable_shift_thread, 0);
   rb_define_private_method(rb_cAtomicConditionVariable, "_drain_threads", rb_cAtomicConditionVariable_drain_threads, 0);
   rb_define_private_method(rb_cAtomicConditionVariable, "_waiter_count", rb_cAtomicConditionVariable_waiter_count, 0);
+
+  atomic_ruby_thread_pool_worker_key = rb_internal_thread_specific_key_create();
+  rb_internal_thread_add_event_hook(
+    atomic_ruby_thread_pool_event_callback,
+    RUBY_INTERNAL_THREAD_EVENT_READY |
+      RUBY_INTERNAL_THREAD_EVENT_RESUMED |
+      RUBY_INTERNAL_THREAD_EVENT_SUSPENDED,
+    NULL
+  );
+  VALUE rb_cThreadPoolMonitor = rb_define_class_under(rb_mAtomicRuby, "ThreadPoolMonitor", rb_cObject);
+  rb_define_alloc_func(rb_cThreadPoolMonitor, rb_cThreadPoolMonitor_allocate);
+  rb_define_method(rb_cThreadPoolMonitor, "register_worker", rb_cThreadPoolMonitor_register_worker, 0);
+  rb_define_method(rb_cThreadPoolMonitor, "unregister_worker", rb_cThreadPoolMonitor_unregister_worker, 0);
+  rb_define_method(rb_cThreadPoolMonitor, "start_work", rb_cThreadPoolMonitor_start_work, 0);
+  rb_define_method(rb_cThreadPoolMonitor, "stop_work", rb_cThreadPoolMonitor_stop_work, 0);
+  rb_define_method(rb_cThreadPoolMonitor, "snapshot", rb_cThreadPoolMonitor_snapshot, 0);
+  rb_funcall(rb_mAtomicRuby, rb_intern("private_constant"), 1, ID2SYM(rb_intern("ThreadPoolMonitor")));
 }

data/ext/atomic_ruby/atomic_ruby.h

@@ -3,8 +3,12 @@
 
 #include "ruby.h"
 #include "ruby/atomic.h"
+#include "ruby/thread.h"
 #include "ruby/version.h"
 
+#include <stdatomic.h>
+#include <time.h>
+
 #if RUBY_API_VERSION_CODE >= 40000
 #define ATOMIC_RUBY_RACTOR_SAFE 1
 #include "ruby/ractor.h"

data/lib/atomic-ruby/atomic_thread_pool.rb

@@ -7,11 +7,13 @@ require_relative "atomic_condition_variable"
 require_relative "atomic_queue"
 
 module AtomicRuby
-  # Provides a fixed-size thread pool using atomic operations for work queuing.
+  # Provides a thread pool using atomic operations for work queuing.
   #
-  # AtomicThreadPool maintains a fixed number of worker threads that process
-  # work items from an {AtomicQueue}. Both enqueueing and dequeueing are O(1)
-  # and lock-free, so concurrent producers and consumers never block one
+  # AtomicThreadPool maintains a baseline number of worker threads that process
+  # work items from an {AtomicQueue}. When `max_size` is provided, it can
+  # temporarily add workers when work remains queued and its workers spend most
+  # of their time blocked outside the GVL. Both enqueueing and dequeueing are
+  # O(1) and lock-free, so concurrent producers and consumers never block one
   # another.
   #
   # @example Basic usage
@@ -31,6 +33,11 @@ module AtomicRuby
   #   pool.shutdown
   #   puts results.sort #=> [0, 2, 4, 6, 8, 10, 12, 14, 16, 18]
   #
+  # @example Scaling for blocking work
+  #   pool = AtomicThreadPool.new(size: 2, max_size: 8)
+  #   20.times { pool << proc { Net::HTTP.get(uri) } }
+  #   pool.shutdown
+  #
   # @example Monitoring pool state
   #   pool = AtomicThreadPool.new(size: 3)
   #   puts pool.length        #=> 3
@@ -44,6 +51,12 @@ module AtomicRuby
   # @note This class is NOT Ractor-safe as it contains mutable thread state
   #   that cannot be safely shared across ractors.
   class AtomicThreadPool
+    AUTOSCALE_GROWTH_SAMPLES = 3
+    AUTOSCALE_IDLE_TIME = 1
+    AUTOSCALE_INTERVAL = 0.01
+    AUTOSCALE_WINDOW = 0.05
+    private_constant :AUTOSCALE_GROWTH_SAMPLES, :AUTOSCALE_IDLE_TIME, :AUTOSCALE_INTERVAL, :AUTOSCALE_WINDOW
+
     class Error < StandardError; end
 
     # Error raised when attempting to enqueue work after shutdown.
@@ -52,15 +65,26 @@ module AtomicRuby
       def message = "cannot queue work after shutdown"
     end
 
-    # Creates a new thread pool with the specified size.
-    #
-    # @param size [Integer] The number of worker threads to create (must be positive)
+    # Creates a new thread pool with the specified baseline size.
+    #
+    # When `max_size` is greater than `size`, the pool adds temporary workers
+    # if work remains queued while its active workers spend most of their time
+    # blocked outside the GVL, but not when Ruby execution is using the
+    # available CPU.
+    # Temporary workers leave after the queue remains empty, returning the pool
+    # to its baseline size. Omitting `max_size` creates a fixed-size pool.
+    #
+    # @param size [Integer] The baseline number of worker threads (must be positive)
+    # @param max_size [Integer, Float, nil] Maximum number of worker threads,
+    #   `Float::INFINITY` for no limit, or nil for a fixed-size pool
     # @param name [String, nil] Optional name for the thread pool (used in thread names)
     # @param on_error [Proc, nil] Optional error handler called with the exception when
     #   a work item raises. Receives the exception as its argument. When nil, errors
     #   are printed to stderr
     #
     # @raise [ArgumentError] if size is not a positive integer
+    # @raise [ArgumentError] if max_size is not an integer greater than or equal
+    #   to size or `Float::INFINITY`
     # @raise [ArgumentError] if name is provided but not a string
     # @raise [ArgumentError] if on_error is provided but not a Proc
     #
@@ -70,17 +94,23 @@ module AtomicRuby
     # @example Create a named pool
     #   pool = AtomicThreadPool.new(size: 2, name: "Database Workers")
     #
+    # @example Create an adaptive pool
+    #   pool = AtomicThreadPool.new(size: 2, max_size: 8)
+    #
     # @example Create a pool with a custom error handler
     #   errors = []
     #   pool = AtomicThreadPool.new(size: 2, on_error: ->(err) { errors << err })
     #
-    # @rbs (size: Integer, ?name: String?, ?on_error: Proc?) -> void
-    def initialize(size:, name: nil, on_error: nil)
+    # @rbs (size: Integer, ?max_size: (Integer | Float)?, ?name: String?, ?on_error: Proc?) -> void
+    def initialize(size:, max_size: nil, name: nil, on_error: nil)
       raise ArgumentError, "size must be a positive Integer" unless size.is_a?(Integer) && size > 0
+      valid_max_size = max_size.nil? || max_size == Float::INFINITY || (max_size.is_a?(Integer) && max_size >= size)
+      raise ArgumentError, "max_size must be an Integer greater than or equal to size or Float::INFINITY" unless valid_max_size
       raise ArgumentError, "name must be a String" unless name.nil? || name.is_a?(String)
       raise ArgumentError, "on_error must be a Proc" unless on_error.nil? || on_error.is_a?(Proc)
 
       @size = size
+      @max_size = max_size || size
       @name = name
       @on_error = on_error
 
@@ -90,6 +120,12 @@ module AtomicRuby
       @alive_thread_count = Atom.new(0)
       @active_thread_count = Atom.new(0)
       @threads = []
+      @next_thread_number = 0
+      if adaptive?
+        @autoscale_available = AtomicConditionVariable.new
+        @trim_requested = AtomicBoolean.new(false)
+        @thread_pool_monitor = ThreadPoolMonitor.new
+      end
 
       start
     end
@@ -120,15 +156,17 @@ module AtomicRuby
     def <<(work)
       raise EnqueuedWorkAfterShutdownError if @shutdown.true?
 
+      @trim_requested&.make_false
       @queue.push(work)
       @work_available.signal
+      @autoscale_available&.signal
     end
 
     # Returns the number of currently alive worker threads.
     #
     # This count decreases as the pool shuts down and threads terminate.
-    # During normal operation, this should equal the size parameter
-    # passed to the constructor.
+    # An adaptive pool may report a value between the `size` and `max_size`
+    # parameters passed to the constructor.
     #
     # @return [Integer] The number of alive worker threads
     #
@@ -222,7 +260,9 @@ module AtomicRuby
       return if @shutdown.true?
 
       @shutdown.make_true
+      @autoscale_available&.broadcast
       @work_available.broadcast
+      @autoscaler&.join
       @threads.each(&:join)
     end
 
@@ -238,49 +278,189 @@ module AtomicRuby
     #
     # @rbs () -> void
     def start
-      @size.times do |num|
-        @threads << Thread.new(num) do |idx|
-          thread_name = String.new("AtomicThreadPool thread #{idx}")
+      @size.times { spawn_worker }
+
+      if adaptive?
+        @autoscaler = Thread.new do
+          thread_name = String.new("AtomicThreadPool autoscaler")
           thread_name << " for #{@name}" if @name
           Thread.current.name = thread_name
+          autoscale
+        end
+      end
 
-          @alive_thread_count.swap { |current_count| current_count + 1 }
+      Thread.pass until @alive_thread_count.value == @size
+    end
 
-          begin
-            loop do
-              work = nil
-              should_shutdown = false
+    # Returns whether the pool may grow beyond its baseline size.
+    #
+    # @return [true, false]
+    #
+    # @rbs () -> bool
+    def adaptive?
+      @max_size > @size
+    end
+
+    # Creates a worker thread.
+    #
+    # Temporary workers leave after the queue remains empty.
+    #
+    # @param temporary [true, false] whether the worker belongs above the baseline
+    # @return [Thread]
+    #
+    # @rbs (?temporary: bool) -> Thread
+    def spawn_worker(temporary: false)
+      thread_number = @next_thread_number
+      @next_thread_number += 1
+
+      thread = Thread.new(thread_number) do |idx|
+        thread_name = String.new("AtomicThreadPool thread #{idx}")
+        thread_name << " for #{@name}" if @name
+        Thread.current.name = thread_name
 
-              @work_available.wait do
-                work = @queue.pop
-                should_shutdown = @shutdown.true? && @queue.empty? unless work
-                work || should_shutdown
+        @thread_pool_monitor&.register_worker
+        @alive_thread_count.swap { |current_count| current_count + 1 }
+
+        begin
+          loop do
+            work = nil
+            should_exit = false
+
+            @work_available.wait do
+              work = @queue.pop
+              unless work
+                should_exit = @shutdown.true? && @queue.empty?
+                should_exit ||= temporary && @trim_requested.true? && @queue.empty?
               end
+              work || should_exit
+            end
 
-              break if should_shutdown
-
-              @active_thread_count.swap { |current_count| current_count + 1 }
-              begin
-                work.call
-              rescue => err
-                if @on_error
-                  @on_error.call(err)
-                else
-                  warn "#{thread_name} rescued:"
-                  warn err.full_message
-                end
-              ensure
-                @active_thread_count.swap { |current_count| current_count - 1 }
+            break if should_exit
+
+            @active_thread_count.swap { |current_count| current_count + 1 }
+            begin
+              @thread_pool_monitor&.start_work
+              work.call
+            rescue => err
+              if @on_error
+                @on_error.call(err)
+              else
+                warn "#{thread_name} rescued:"
+                warn err.full_message
               end
+            ensure
+              @thread_pool_monitor&.stop_work
+              @active_thread_count.swap { |current_count| current_count - 1 }
             end
-          ensure
-            @alive_thread_count.swap { |current_count| current_count - 1 }
           end
+        ensure
+          @alive_thread_count.swap { |current_count| current_count - 1 }
+          @thread_pool_monitor&.unregister_worker
         end
       end
-      @threads.freeze
 
-      Thread.pass until @alive_thread_count.value == @size
+      @threads << thread
+      thread
+    end
+
+    # Adds temporary workers while queued work is held up by blocked workers.
+    #
+    # @return [void]
+    #
+    # @rbs () -> void
+    def autoscale
+      previous_snapshot = @thread_pool_monitor.snapshot
+      pressure_started_at = nil
+      idle_started_at = nil
+      growth_samples = 0
+      phase_samples = [0, 0, 0]
+
+      loop do
+        @autoscale_available.wait do
+          @shutdown.true? || !@queue.empty? || @alive_thread_count.value > @size
+        end
+        break if @shutdown.true?
+
+        now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        snapshot = @thread_pool_monitor.snapshot
+
+        if @queue.empty?
+          pressure_started_at = nil
+          previous_snapshot = snapshot
+          idle_started_at ||= now
+          growth_samples = 0
+          phase_samples.fill(0)
+
+          if now - idle_started_at >= AUTOSCALE_IDLE_TIME
+            @trim_requested.make_true
+            @work_available.broadcast
+          end
+        else
+          @trim_requested.make_false
+          idle_started_at = nil
+
+          if pressure_started_at.nil?
+            previous_snapshot = snapshot
+            pressure_started_at = now
+            phase_samples.fill(0)
+          elsif now - pressure_started_at >= AUTOSCALE_WINDOW
+            if should_grow?(previous_snapshot, snapshot, phase_samples, now - pressure_started_at)
+              growth_samples += 1
+              if growth_samples >= AUTOSCALE_GROWTH_SAMPLES
+                spawn_worker(temporary: true)
+                growth_samples = 0
+              end
+            else
+              growth_samples = 0
+            end
+            previous_snapshot = snapshot
+            pressure_started_at = now
+            phase_samples.fill(0)
+          else
+            3.times { |index| phase_samples[index] += snapshot[index] }
+          end
+        end
+
+        sleep AUTOSCALE_INTERVAL
+      end
+    end
+
+    # Returns whether another worker is likely to improve throughput.
+    #
+    # Requiring workers to spend a majority of their time blocked outside the
+    # GVL recognizes blocking operations. The pool only grows while its workers
+    # use less than half of one CPU, avoiding extra threads when Ruby
+    # execution is the bottleneck without mistaking OS scheduling delays for
+    # GVL contention.
+    #
+    # @param previous_snapshot [Array<Integer>] previous GVL state snapshot
+    # @param snapshot [Array<Integer>] current GVL state snapshot
+    # @param phase_samples [Array<Integer>] sampled current GVL states
+    # @param elapsed_time [Float] seconds covered by the snapshots
+    # @return [true, false]
+    #
+    # @rbs (Array[Integer] previous_snapshot, Array[Integer] snapshot, Array[Integer] phase_samples, Float elapsed_time) -> bool
+    def should_grow?(previous_snapshot, snapshot, phase_samples, elapsed_time)
+      @threads.select!(&:alive?)
+      workers = @threads
+      return false if workers.length >= @max_size
+      return false if @active_thread_count.value < workers.length
+
+      running_time = snapshot[3] - previous_snapshot[3]
+      waiting_time = snapshot[4] - previous_snapshot[4]
+      blocked_time = snapshot[5] - previous_snapshot[5]
+      running_cpu_time = snapshot[6] - previous_snapshot[6]
+      total_time = running_time + waiting_time + blocked_time
+
+      minimum_measured_time = (AUTOSCALE_WINDOW * 1_000_000_000 * workers.length / 2).to_i
+      if total_time < minimum_measured_time
+        running_time, waiting_time, blocked_time = phase_samples
+        total_time = running_time + waiting_time + blocked_time
+      end
+
+      total_time.positive? &&
+        blocked_time * 2 > total_time &&
+        running_cpu_time * 2 < elapsed_time * 1_000_000_000
     end
   end
 end

data/lib/atomic-ruby/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module AtomicRuby
-  VERSION = "0.14.1"
+  VERSION = "0.15.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: atomic-ruby
 version: !ruby/object:Gem::Version
-  version: 0.14.1
+  version: 0.15.1
 platform: ruby
 authors:
 - Joshua Young