atomic-ruby 0.15.3 → 0.15.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a50be9a8594152f8d07b2338588a01be6aecadf55f993ea6cc4c2431e80e2b76
-  data.tar.gz: eb9c45d8dff70d0697d3d62ba5a539e3d71e42c21ea7ab6b646d44fde69f39ac
+  metadata.gz: 6022f081e7f3e4ce545c40989e5a644beea0697da5d840f645ae3764fbb80e4e
+  data.tar.gz: 94b4312e55cfbda05127bde7ac74efd98da8708cb9835e718e7c02641f1d241a
 SHA512:
-  metadata.gz: abde2bc85010be3634caeaf66d262acf1c5c70c50af5e9e420a43c87071965bd543a475b01b5d1b0d1569682802595e936a9d224e636896a681e5c3c85d98a77
-  data.tar.gz: e93d7b35c3ccdba9c82906587c24455c248655ffbe3f9d4141e4cb029705306f80c13b36f6a0ce7193a33701758ad0a9c2f77a7aa0c94ad92e49392ba899c055
+  metadata.gz: bbcef6942791f3611e55c7c9806bd5daa4b71dd4bae4bedd255c0d1598e16c0ba50a19ae92423768fca04a4baafd80f464877f60960a7e43be0fc08ed2ffb3a3
+  data.tar.gz: '0883a4a401963ad0db23713c6ae6917bec1c3bd1cd3bd8ecff069cc63c99b3000a914ee0c9345cd9f2495f88f0d6da6c35a51057b80a56877409ba19ce3c5e4f'

data/CHANGELOG.md

@@ -1,6 +1,15 @@
 ## [Unreleased]
 
-## [0.15.2] - 2026-08-31
+## [0.15.5] - 2026-09-03
+
+- Adapt `AtomicThreadPool` scaling to workload pressure
+
+## [0.15.4] - 2026-09-01
+
+- Keep temporary `AtomicThreadPool` workers alive for five seconds
+- Speed up `AtomicThreadPool` scaling for blocking work
+
+## [0.15.3] - 2026-08-31
 
 - Prevent enqueues from racing `AtomicThreadPool#shutdown`
 - Remove interrupted waiters from `AtomicConditionVariable`

data/README.md

@@ -122,8 +122,10 @@ 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.
+the GVL and CPU time used while running Ruby, so it does not add more threads
+when Ruby execution is the bottleneck. Temporary workers remain available
+between blocking bursts, but retire when Ruby execution becomes the bottleneck
+or they remain idle.
 
 ```ruby
 pool = AtomicThreadPool.new(size: 4, max_size: 16)
@@ -268,7 +270,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.8
-atomic-ruby version:     0.15.3
+atomic-ruby version:     0.15.5
 
 Balances:
 Synchronized Bank Account Balance:           975
@@ -359,7 +361,7 @@ end
 
 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.15.3
+atomic-ruby version:     0.15.5
 
 Warming up --------------------------------------
           Synchronized Boolean Toggle   165.000 i/100ms
@@ -442,7 +444,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.15.3
+atomic-ruby version: 0.15.5
 
 Warming up --------------------------------------
       Synchronized Condition Variable Wait/Signal     4.062k i/100ms
@@ -517,7 +519,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.15.3
+atomic-ruby version: 0.15.5
 
 Warming up --------------------------------------
       Synchronized Queue Push/Pop   184.000 i/100ms
@@ -547,7 +549,7 @@ require "benchmark"
 require "concurrent-ruby"
 require_relative "../lib/atomic-ruby"
 
-results = []
+fixed_results = []
 
 2.times do |idx|
   result = Benchmark.measure do
@@ -569,7 +571,36 @@ results = []
     pool.wait_for_termination if idx == 0
   end
 
-  results << result
+  fixed_results << result
+end
+
+adaptive_results = []
+
+2.times do |idx|
+  result = Benchmark.measure do
+    pool = case idx
+    when 0 then Concurrent.new_io_executor
+    when 1 then AtomicThreadPool.new(size: 1, max_size: Float::INFINITY)
+    end
+    latch = case idx
+    when 0 then Concurrent::CountDownLatch.new(100)
+    when 1 then AtomicCountDownLatch.new(100)
+    end
+
+    100.times do
+      pool << proc do
+        sleep(0.2)
+        latch.count_down
+      end
+    end
+
+    latch.wait
+    pool.shutdown
+    # concurrent-ruby's #shutdown does not wait for threads to terminate
+    pool.wait_for_termination if idx == 0
+  end
+
+  adaptive_results << result
 end
 
 puts "\n"
@@ -577,9 +608,13 @@ puts "ruby version:            #{RUBY_DESCRIPTION}"
 puts "concurrent-ruby version: #{Concurrent::VERSION}"
 puts "atomic-ruby version:     #{AtomicRuby::VERSION}"
 puts "\n"
-puts "Benchmark Results:"
-puts "Concurrent Ruby Thread Pool:    #{results[0].real.round(6)} seconds"
-puts "Atomic Ruby Atomic Thread Pool: #{results[1].real.round(6)} seconds"
+puts "Fixed Pool Results:"
+puts "Concurrent Ruby Fixed Thread Pool: #{fixed_results[0].real.round(6)} seconds"
+puts "Atomic Ruby Fixed Thread Pool:     #{fixed_results[1].real.round(6)} seconds"
+puts "\n"
+puts "Adaptive Pool Results:"
+puts "Concurrent Ruby IO Thread Pool:   #{adaptive_results[0].real.round(6)} seconds"
+puts "Atomic Ruby Adaptive Thread Pool: #{adaptive_results[1].real.round(6)} seconds"
 ```
 
 ```
@@ -587,11 +622,15 @@ 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.15.3
+atomic-ruby version:     0.15.5
 
-Benchmark Results:
-Concurrent Ruby Thread Pool:    5.012798 seconds
-Atomic Ruby Atomic Thread Pool: 4.755237 seconds
+Fixed Pool Results:
+Concurrent Ruby Fixed Thread Pool: 5.05313 seconds
+Atomic Ruby Fixed Thread Pool:     4.753026 seconds
+
+Adaptive Pool Results:
+Concurrent Ruby IO Thread Pool:   0.221072 seconds
+Atomic Ruby Adaptive Thread Pool: 0.233328 seconds
 ```
 
 </details>
@@ -645,7 +684,7 @@ puts "Atomic Ruby Atomic Count Down Latch: #{results[1].total.round(6)} CPU seco
 
 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.15.3
+atomic-ruby version:     0.15.5
 
 Benchmark Results:
 Concurrent Ruby Count Down Latch:    0.000511 CPU seconds, 2.001465 elapsed seconds

data/lib/atomic-ruby/atomic_thread_pool.rb

@@ -51,11 +51,11 @@ 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
+    AUTOSCALE_IDLE_TIME = 5
+    AUTOSCALE_INITIAL_WINDOW = 0.002
+    AUTOSCALE_MAX_WINDOW = 0.05
+    AUTOSCALE_SAMPLES_PER_WINDOW = 5
+    private_constant :AUTOSCALE_IDLE_TIME, :AUTOSCALE_INITIAL_WINDOW, :AUTOSCALE_MAX_WINDOW, :AUTOSCALE_SAMPLES_PER_WINDOW
 
     class Error < StandardError; end
 
@@ -71,8 +71,9 @@ module AtomicRuby
     # 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.
+    # Temporary workers remain available between blocking bursts, but retire
+    # when Ruby execution becomes the bottleneck or they remain idle. 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,
@@ -123,7 +124,8 @@ module AtomicRuby
       @next_thread_number = 0
       if adaptive?
         @autoscale_available = AtomicConditionVariable.new
-        @trim_requested = AtomicBoolean.new(false)
+        @idle_trim_requested = AtomicBoolean.new(false)
+        @ruby_cpu_trim_requested = AtomicBoolean.new(false)
         @thread_pool_monitor = ThreadPoolMonitor.new
         @thread_pool_monitor.start
       end
@@ -156,7 +158,7 @@ module AtomicRuby
     # @rbs (Proc work) -> void
     def <<(work)
       Thread.handle_interrupt(Exception => :never) do
-        @trim_requested&.make_false
+        @idle_trim_requested&.make_false
         raise EnqueuedWorkAfterShutdownError unless @queue.push(work)
 
         @work_available.signal
@@ -310,7 +312,8 @@ module AtomicRuby
 
     # Creates a worker thread.
     #
-    # Temporary workers leave after the queue remains empty.
+    # Temporary workers retire when Ruby execution becomes the bottleneck or
+    # they remain idle.
     #
     # @param temporary [true, false] whether the worker belongs above the baseline
     # @return [Thread]
@@ -334,10 +337,13 @@ module AtomicRuby
             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?
+              should_exit = temporary && @ruby_cpu_trim_requested.true?
+              unless should_exit
+                work = @queue.pop
+                unless work
+                  should_exit = @shutdown.true? && @queue.empty?
+                  should_exit ||= temporary && @idle_trim_requested.true? && @queue.empty?
+                end
               end
               work || should_exit
             end
@@ -345,6 +351,10 @@ module AtomicRuby
             break if should_exit
 
             @active_thread_count.swap { |current_count| current_count + 1 }
+            if temporary
+              work_started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+              running_cpu_time_at_start = @thread_pool_monitor.snapshot[6]
+            end
             begin
               @thread_pool_monitor&.start_work
               work.call
@@ -358,6 +368,14 @@ module AtomicRuby
             ensure
               @thread_pool_monitor&.stop_work
               @active_thread_count.swap { |current_count| current_count - 1 }
+              if temporary && !@queue.empty?
+                elapsed_time = Process.clock_gettime(Process::CLOCK_MONOTONIC) - work_started_at
+                running_cpu_time = @thread_pool_monitor.snapshot[6] - running_cpu_time_at_start
+                if running_cpu_time * 2 >= elapsed_time * 1_000_000_000
+                  @ruby_cpu_trim_requested.make_true
+                  @work_available.broadcast
+                end
+              end
             end
           end
         ensure
@@ -370,7 +388,10 @@ module AtomicRuby
       thread
     end
 
-    # Adds temporary workers while queued work is held up by blocked workers.
+    # Scales temporary workers in response to workload pressure.
+    #
+    # Sampling starts aggressively so the pool can react to short bursts, then
+    # backs off when more workers would not improve throughput.
     #
     # @return [void]
     #
@@ -379,10 +400,11 @@ module AtomicRuby
       previous_snapshot = @thread_pool_monitor.snapshot
       pressure_started_at = nil
       idle_started_at = nil
-      growth_samples = 0
       phase_samples = [0, 0, 0]
+      sampling_window = AUTOSCALE_INITIAL_WINDOW
 
       loop do
+        @ruby_cpu_trim_requested.make_false if @alive_thread_count.value <= @size
         @autoscale_available.wait do
           @shutdown.true? || !@queue.empty? || @alive_thread_count.value > @size
         end
@@ -395,30 +417,37 @@ module AtomicRuby
           pressure_started_at = nil
           previous_snapshot = snapshot
           idle_started_at ||= now
-          growth_samples = 0
           phase_samples.fill(0)
+          sampling_window = AUTOSCALE_INITIAL_WINDOW
 
           if now - idle_started_at >= AUTOSCALE_IDLE_TIME
-            @trim_requested.make_true
+            @idle_trim_requested.make_true
             @work_available.broadcast
           end
         else
-          @trim_requested.make_false
+          @idle_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
+          elsif now - pressure_started_at >= sampling_window
+            case scaling_direction(previous_snapshot, snapshot, phase_samples, now - pressure_started_at)
+            when :up
+              @ruby_cpu_trim_requested.make_false
+              worker_count = @threads.length
+              workers_to_add = [worker_count, @queue.size, @max_size - worker_count].min
+              workers_to_add.times { spawn_worker(temporary: true) }
+              sampling_window = AUTOSCALE_INITIAL_WINDOW
+            when :down
+              unless @ruby_cpu_trim_requested.true?
+                @ruby_cpu_trim_requested.make_true
+                @work_available.broadcast
               end
+              sampling_window = [sampling_window * 2, AUTOSCALE_MAX_WINDOW].min
             else
-              growth_samples = 0
+              sampling_window = [sampling_window * 2, AUTOSCALE_MAX_WINDOW].min
             end
             previous_snapshot = snapshot
             pressure_started_at = now
@@ -428,30 +457,28 @@ module AtomicRuby
           end
         end
 
-        sleep AUTOSCALE_INTERVAL
+        sleep((@queue.empty? ? AUTOSCALE_MAX_WINDOW : sampling_window) / AUTOSCALE_SAMPLES_PER_WINDOW)
       end
     end
 
-    # Returns whether another worker is likely to improve throughput.
+    # Returns the direction in which the pool should scale.
     #
     # 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.
+    # GVL recognizes blocking operations. The pool grows while Ruby execution
+    # uses less than half of one CPU and shrinks when Ruby execution becomes
+    # 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]
+    # @return [:up, :down, nil]
     #
-    # @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)
+    # @rbs (Array[Integer] previous_snapshot, Array[Integer] snapshot, Array[Integer] phase_samples, Float elapsed_time) -> (:up | :down)?
+    def scaling_direction(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
+      return if @active_thread_count.value < workers.length
 
       running_time = snapshot[3] - previous_snapshot[3]
       waiting_time = snapshot[4] - previous_snapshot[4]
@@ -459,15 +486,17 @@ module AtomicRuby
       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
+      minimum_measured_time = (elapsed_time * 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
+      ruby_cpu_bound = running_cpu_time * 2 >= elapsed_time * 1_000_000_000
+      blocking = total_time.positive? && blocked_time * 2 > total_time && !ruby_cpu_bound
+
+      return :up if blocking && workers.length < @max_size
+      return :down if ruby_cpu_bound && workers.length > @size
     end
   end
 end

data/lib/atomic-ruby/version.rb

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

metadata

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