atomic-ruby 0.15.4 → 0.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e7c0136cf37fe5133affc1f090fa517636f5bfda0f5f43564a4877eee15bae3f
-  data.tar.gz: 0ae3a3aadabcc2bb69621df62188800451289a46032fa57a49c1af9326bcc31e
+  metadata.gz: ecdfa4ed4bb185acac2d6ce288418318e23c1e4825fddff06d74a702d19d0d39
+  data.tar.gz: d2c935cb440869f1f622a30a585d71767ef57e3d08de78f332810e63acff1aa5
 SHA512:
-  metadata.gz: 1786faa43a25379cbe68c9de2372c6168a62ab225436c45bbf5049791c39191e3ed75955ab2f5f6385069ddeb86640aa11ba431ce9f2ab54335005a61bd42092
-  data.tar.gz: 704c7e7224c9eec351aa0174f597c10c992f4e1594921b8ca91e9ad2df43a6b3eb2c260b9b25ab2d47f8fb0934afa9739ed5312fb00d5d7519d9283c6bf68170
+  metadata.gz: 10e31be43b93f0d22de13ec3bea7f7d8bf411aa5282c5d36de2ee8da7693b968ab1aacbdc6c428317450670585bb857f0b8ecf657b71af6f18fcea9ab8c8c314
+  data.tar.gz: d99ed0322536e33b725a5ddda3202eced49bc71de567d6505079d3fbcd8b11b4df9d2216c834a5b0fa546105860eef3ccf0848d4455870992061991be6f772aa

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 ## [Unreleased]
 
+## [0.16.0] - 2026-10-18
+
+- Add `AtomicThreadPool#wait_for_capacity`
+
+## [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

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.4
+atomic-ruby version:     0.16.0
 
 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.4
+atomic-ruby version:     0.16.0
 
 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.4
+atomic-ruby version: 0.16.0
 
 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.4
+atomic-ruby version: 0.16.0
 
 Warming up --------------------------------------
       Synchronized Queue Push/Pop   184.000 i/100ms
@@ -618,17 +620,17 @@ puts "Atomic Ruby Adaptive Thread Pool: #{adaptive_results[1].real.round(6)} sec
 ```
 > bundle exec rake clobber && bundle exec rake compile && bundle exec ruby examples/atomic_thread_pool_benchmark.rb
 
-ruby version:            ruby 4.0.6 (2026-07-14 revision 03b6d3f889) +YJIT +PRISM [arm64-darwin23]
+ruby version:            ruby 4.0.7 (2026-09-15 revision 229531a6cf) +YJIT +PRISM [arm64-darwin23]
 concurrent-ruby version: 1.3.8
-atomic-ruby version:     0.15.4
+atomic-ruby version:     0.16.0
 
 Fixed Pool Results:
-Concurrent Ruby Fixed Thread Pool: 5.069464 seconds
-Atomic Ruby Fixed Thread Pool:     4.791382 seconds
+Concurrent Ruby Fixed Thread Pool: 5.147226 seconds
+Atomic Ruby Fixed Thread Pool:     4.743301 seconds
 
 Adaptive Pool Results:
-Concurrent Ruby IO Thread Pool:   0.22309 seconds
-Atomic Ruby Adaptive Thread Pool: 0.61561 seconds
+Concurrent Ruby IO Thread Pool:   0.217971 seconds
+Atomic Ruby Adaptive Thread Pool: 0.227701 seconds
 ```
 
 </details>
@@ -682,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.4
+atomic-ruby version:     0.16.0
 
 Benchmark Results:
 Concurrent Ruby Count Down Latch:    0.000511 CPU seconds, 2.001465 elapsed seconds

data/lib/atomic-ruby/atomic_thread_pool.rb

@@ -52,9 +52,10 @@ module AtomicRuby
   #   that cannot be safely shared across ractors.
   class AtomicThreadPool
     AUTOSCALE_IDLE_TIME = 5
-    AUTOSCALE_INTERVAL = 0.01
-    AUTOSCALE_WINDOW = 0.05
-    private_constant :AUTOSCALE_IDLE_TIME, :AUTOSCALE_INTERVAL, :AUTOSCALE_WINDOW
+    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
 
@@ -70,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 remain available between bursts before the pool returns
-    # 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,
@@ -116,13 +118,15 @@ module AtomicRuby
       @queue = AtomicQueue.new
       @shutdown = AtomicBoolean.new(false)
       @work_available = AtomicConditionVariable.new
+      @capacity_changed = AtomicConditionVariable.new
       @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)
+        @idle_trim_requested = AtomicBoolean.new(false)
+        @ruby_cpu_trim_requested = AtomicBoolean.new(false)
         @thread_pool_monitor = ThreadPoolMonitor.new
         @thread_pool_monitor.start
       end
@@ -155,7 +159,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
@@ -235,6 +239,25 @@ module AtomicRuby
       @active_thread_count.value
     end
 
+    # Blocks until the given block returns a truthy value, checking it again
+    # whenever a worker takes or finishes work.
+    #
+    # Useful for applying backpressure, such as holding off on accepting more
+    # work until the pool has capacity for it.
+    #
+    # @yieldreturn [untyped] Truthy to stop waiting, falsy to keep waiting
+    # @return [untyped] The first truthy value returned by the block
+    #
+    # @example Wait until no work is queued
+    #   pool = AtomicThreadPool.new(size: 2)
+    #   5.times { pool << proc { sleep(0.1) } }
+    #   pool.wait_for_capacity { pool.queue_length.zero? } #=> true
+    #
+    # @rbs () { () -> untyped } -> untyped
+    def wait_for_capacity(&block)
+      @capacity_changed.wait(&block)
+    end
+
     # Gracefully shuts down the thread pool.
     #
     # This method:
@@ -309,7 +332,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]
@@ -333,10 +357,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
@@ -344,6 +371,11 @@ module AtomicRuby
             break if should_exit
 
             @active_thread_count.swap { |current_count| current_count + 1 }
+            @capacity_changed.broadcast unless @capacity_changed.waiter_count.zero?
+            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
@@ -357,6 +389,15 @@ module AtomicRuby
             ensure
               @thread_pool_monitor&.stop_work
               @active_thread_count.swap { |current_count| current_count - 1 }
+              @capacity_changed.broadcast unless @capacity_changed.waiter_count.zero?
+              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
@@ -369,7 +410,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,8 +423,10 @@ module AtomicRuby
       pressure_started_at = nil
       idle_started_at = nil
       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
@@ -394,24 +440,36 @@ module AtomicRuby
           previous_snapshot = snapshot
           idle_started_at ||= now
           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)
+          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
+              sampling_window = [sampling_window * 2, AUTOSCALE_MAX_WINDOW].min
             end
             previous_snapshot = snapshot
             pressure_started_at = now
@@ -421,30 +479,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]
@@ -452,15 +508,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.4"
+  VERSION = "0.16.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: atomic-ruby
 version: !ruby/object:Gem::Version
-  version: 0.15.4
+  version: 0.16.0
 platform: ruby
 authors:
 - Joshua Young
@@ -52,7 +52,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.16
+rubygems_version: 4.0.20
 specification_version: 4
 summary: Atomic primitives for Ruby
 test_files: []