atomic-ruby 0.11.1 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4a9ae1ba9062331be3f6a5d74f170dbf88eb2ce6b142f3ef5077194ddeb1295e
-  data.tar.gz: 652fbf6d04d6efa3d57fc37643f85241e685950320d343e2341c155b0539bf93
+  metadata.gz: 540189a4554f5e046af0b5305063a96be9fa58cfac1740e5e6076d6b1c48cd40
+  data.tar.gz: 528fa3c2e94c0d403ec8792076a773d3e7ce800852f1472dbde8e9ce7bbfb6f8
 SHA512:
-  metadata.gz: 686a5aaeef7250102c57a7b5b9b2dbe5cdbe45105428a98217545d6c3b1183ef79696f64b5a7aa1135a0f260bdcb8c50b53b4455dc60785977687d62b8b3c47a
-  data.tar.gz: 2141ed20f4baf5e2f8cf175c69b8003bf62413e1e312b5b8bf402ea762d409bcbfc72bfc14955d6aa4319ee719c6d28880055e954d2bb69278f9154d71b5a970
+  metadata.gz: 8ad39592c8615f88aa0da987d1de06d87496c6c82481a9678c907937de65d308f4595e54008b0e357d99605fc660d8b35b986397ad0573e4b81dbf5de8926695
+  data.tar.gz: 46794d17727ab6b835210c7fc8e901d8c7daf37ff319c16b0efdb87cdc8bd9c95b6fb2dad171f96ca8d7b52b3fb8bd08cfde002f264cbe2155e6041310e74827

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 ## [Unreleased]
 
+## [0.13.0] - 2026-06-12
+
+- Replace `sleep` with `AtomicConditionVariable` in idle `AtomicThreadPool` workers
+- Add `AtomicConditionVariable`
+
+## [0.12.0] - 2026-05-18
+
+- Wake idle `AtomicThreadPool` workers on enqueue
+
 ## [0.11.1] - 2026-05-17
 
 - Replace `Thread.pass` busy-wait with `sleep` in idle `AtomicThreadPool` workers

data/README.md

@@ -49,6 +49,27 @@ atom.toggle
 p atom.false? #=> true
 ```
 
+`AtomicConditionVariable`:
+
+```ruby
+require "atomic-ruby"
+
+condvar = AtomicConditionVariable.new
+ready = AtomicBoolean.new(false)
+p condvar.waiter_count #=> 0
+
+waiter = Thread.new do
+  condvar.wait { ready.true? }
+end
+Thread.pass until condvar.waiter_count == 1
+p condvar.waiter_count #=> 1
+
+ready.make_true
+p condvar.signal #=> true
+waiter.join
+p condvar.waiter_count #=> 0
+```
+
 `AtomicThreadPool`:
 
 ```ruby
@@ -98,7 +119,7 @@ p latch.count #=> 0
 ```
 
 > [!NOTE]
-> `Atom`, `AtomicBoolean`, and `AtomicCountDownLatch` are Ractor-safe in Ruby 4.0+.
+> `Atom`, `AtomicBoolean`, and `AtomicCountDownLatch` are Ractor-safe in Ruby 4.0+. `AtomicConditionVariable` is not, since it parks `Thread` references which cannot be shared across ractors.
 
 ## Benchmarks
 
@@ -208,11 +229,11 @@ puts "Atomic Ruby Atomic Bank Account:     #{results[2].real.round(6)} seconds"
 ```
 
 ```
-> bundle exec rake compile && bundle exec ruby examples/atom_benchmark.rb
+> bundle exec rake clobber && bundle exec rake compile && bundle exec ruby examples/atom_benchmark.rb
 
-ruby version:            ruby 4.0.3 (2026-04-21 revision 85ddef263a) +YJIT +PRISM [arm64-darwin23]
+ruby version:            ruby 4.0.5 (2026-05-20 revision 64336ffd0e) +YJIT +PRISM [arm64-darwin23]
 concurrent-ruby version: 1.3.6
-atomic-ruby version:     0.11.0
+atomic-ruby version:     0.13.0
 
 Balances:
 Synchronized Bank Account Balance:           975
@@ -220,9 +241,9 @@ Concurrent Ruby Atomic Bank Account Balance: 975
 Atomic Ruby Atomic Bank Account Balance:     975
 
 Benchmark Results:
-Synchronized Bank Account:           5.106931 seconds
-Concurrent Ruby Atomic Bank Account: 5.106199 seconds
-Atomic Ruby Atomic Bank Account:     5.101662 seconds
+Synchronized Bank Account:           5.109724 seconds
+Concurrent Ruby Atomic Bank Account: 5.137749 seconds
+Atomic Ruby Atomic Bank Account:     5.101637 seconds
 ```
 
 </details>
@@ -299,31 +320,105 @@ end
 ```
 
 ```
-> bundle exec rake compile && bundle exec ruby examples/atomic_boolean_benchmark.rb
+> bundle exec rake clobber && bundle exec rake compile && bundle exec ruby examples/atomic_boolean_benchmark.rb
 
-ruby version:            ruby 4.0.3 (2026-04-21 revision 85ddef263a) +YJIT +PRISM [arm64-darwin23]
+ruby version:            ruby 4.0.5 (2026-05-20 revision 64336ffd0e) +YJIT +PRISM [arm64-darwin23]
 concurrent-ruby version: 1.3.6
-atomic-ruby version:     0.11.0
+atomic-ruby version:     0.13.0
+
+Warming up --------------------------------------
+          Synchronized Boolean Toggle   167.000 i/100ms
+Concurrent Ruby Atomic Boolean Toggle   132.000 i/100ms
+    Atomic Ruby Atomic Boolean Toggle   117.000 i/100ms
+Calculating -------------------------------------
+          Synchronized Boolean Toggle      1.653k (± 2.0%) i/s  (605.04 μs/i) -      8.350k in   5.052096s
+Concurrent Ruby Atomic Boolean Toggle      1.313k (± 2.1%) i/s  (761.45 μs/i) -      6.600k in   5.025579s
+    Atomic Ruby Atomic Boolean Toggle      1.230k (± 4.8%) i/s  (812.86 μs/i) -      6.201k in   5.040557s
+
+Comparison:
+          Synchronized Boolean Toggle:     1652.8 i/s
+Concurrent Ruby Atomic Boolean Toggle:     1313.3 i/s - 1.26x  slower
+    Atomic Ruby Atomic Boolean Toggle:     1230.2 i/s - 1.34x  slower
+```
+
+</details>
+
+<details>
+
+<summary>AtomicConditionVariable</summary>
+
+```ruby
+# frozen_string_literal: true
+
+require "benchmark/ips"
+require_relative "../lib/atomic-ruby"
+
+module Benchmark
+  module IPS
+    class Job
+      class StreamReport
+        def start_warming
+          @out.puts "\n"
+          @out.puts "ruby version:        #{RUBY_DESCRIPTION}"
+          @out.puts "atomic-ruby version: #{AtomicRuby::VERSION}"
+          @out.puts "\n"
+          @out.puts "Warming up --------------------------------------"
+        end
+      end
+    end
+  end
+end
+
+Benchmark.ips do |x|
+  x.report("Synchronized Condition Variable Wait/Signal") do
+    flag = false
+    mutex = Mutex.new
+    condvar = ConditionVariable.new
+
+    waiter = Thread.new do
+      mutex.synchronize do
+        condvar.wait(mutex) until flag
+      end
+    end
+
+    mutex.synchronize do
+      flag = true
+      condvar.signal
+    end
+    waiter.join
+  end
+
+  x.report("Atomic Ruby Atomic Condition Variable Wait/Signal") do
+    flag = AtomicBoolean.new(false)
+    condvar = AtomicConditionVariable.new
+
+    waiter = Thread.new { condvar.wait { flag.true? } }
+
+    flag.make_true
+    condvar.signal
+    waiter.join
+  end
+
+  x.compare!
+end
+```
+
+```
+> bundle exec rake clobber && bundle exec rake compile && bundle exec ruby examples/atomic_condition_variable_benchmark.rb
+
+ruby version:        ruby 4.0.5 (2026-05-20 revision 64336ffd0e) +YJIT +PRISM [arm64-darwin23]
+atomic-ruby version: 0.13.0
 
 Warming up --------------------------------------
-Synchronized Boolean Toggle
-                       135.000 i/100ms
-Concurrent Ruby Atomic Boolean Toggle
-                       117.000 i/100ms
-Atomic Ruby Atomic Boolean Toggle
-                       101.000 i/100ms
+      Synchronized Condition Variable Wait/Signal     3.847k i/100ms
+Atomic Ruby Atomic Condition Variable Wait/Signal     3.704k i/100ms
 Calculating -------------------------------------
-Synchronized Boolean Toggle
-                          1.414k (± 1.4%) i/s  (707.15 μs/i) -      7.155k in   5.060692s
-Concurrent Ruby Atomic Boolean Toggle
-                          1.149k (± 2.9%) i/s  (870.53 μs/i) -      5.850k in   5.097019s
-Atomic Ruby Atomic Boolean Toggle
-                          1.046k (± 2.1%) i/s  (955.57 μs/i) -      5.252k in   5.021118s
+      Synchronized Condition Variable Wait/Signal     38.661k (± 4.4%) i/s   (25.87 μs/i) -    196.197k in   5.074793s
+Atomic Ruby Atomic Condition Variable Wait/Signal     37.895k (± 4.7%) i/s   (26.39 μs/i) -    192.608k in   5.082648s
 
 Comparison:
-Synchronized Boolean Toggle:               1414.1 i/s
-Concurrent Ruby Atomic Boolean Toggle:     1148.7 i/s - 1.23x  slower
-Atomic Ruby Atomic Boolean Toggle:         1046.5 i/s - 1.35x  slower
+      Synchronized Condition Variable Wait/Signal:    38661.1 i/s
+Atomic Ruby Atomic Condition Variable Wait/Signal:    37895.2 i/s - same-ish: difference falls within error
 ```
 
 </details>
@@ -377,15 +472,15 @@ puts "Atomic Ruby Atomic Thread Pool: #{results[1].real.round(6)} seconds"
 ```
 
 ```
-> bundle exec rake compile && bundle exec ruby examples/atomic_thread_pool_benchmark.rb
+> bundle exec rake clobber && bundle exec rake compile && bundle exec ruby examples/atomic_thread_pool_benchmark.rb
 
-ruby version:            ruby 4.0.4 (2026-05-12 revision b89eb1bcbf) +YJIT +PRISM [arm64-darwin23]
+ruby version:            ruby 4.0.5 (2026-05-20 revision 64336ffd0e) +YJIT +PRISM [arm64-darwin23]
 concurrent-ruby version: 1.3.6
-atomic-ruby version:     0.11.1
+atomic-ruby version:     0.13.0
 
 Benchmark Results:
-Concurrent Ruby Thread Pool:    5.869825 seconds
-Atomic Ruby Atomic Thread Pool: 5.387304 seconds
+Concurrent Ruby Thread Pool:    5.792203 seconds
+Atomic Ruby Atomic Thread Pool: 5.504388 seconds
 ```
 
 </details>

data/lib/atomic-ruby/atomic_condition_variable.rb

@@ -0,0 +1,171 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+require_relative "atom"
+
+module AtomicRuby
+  # Provides lock-free wait/signal coordination using atomic operations.
+  #
+  # AtomicConditionVariable lets one or more threads park until another
+  # thread signals them, without the paired `Mutex` that Ruby's
+  # `ConditionVariable` requires. Coordination is done by publishing the
+  # set of parked threads through an {Atom}, so all in-process
+  # synchronisation stays on the gem's CAS path. Parking still uses
+  # `Thread.stop` and `Thread#wakeup`, which are the standard kernel-level
+  # primitives Ruby exposes for sleeping a thread.
+  #
+  # The lost-wakeup race in a naive `check-then-park` consumer is avoided
+  # by the {#wait} contract: a waiter registers itself before re-evaluating
+  # the predicate, so any signal that fires after the producer makes the
+  # predicate true is guaranteed to see the waiter and wake it. Ruby also
+  # remembers pending wakeups across `Thread.stop`, so a wakeup that
+  # arrives between the predicate check and the actual park is not lost.
+  #
+  # @example Basic usage
+  #   condvar = AtomicConditionVariable.new
+  #   ready = AtomicBoolean.new(false)
+  #
+  #   waiter = Thread.new do
+  #     condvar.wait { ready.true? }
+  #     puts "ready"
+  #   end
+  #
+  #   ready.make_true
+  #   condvar.signal
+  #
+  # @example Worker loop draining an atomic queue
+  #   condvar.wait do
+  #     work = nil
+  #     queue.swap do |q|
+  #       q.empty? ? q : (work = q.first; q.drop(1).freeze)
+  #     end
+  #     work
+  #   end
+  #
+  # @note This class is NOT Ractor-safe as it parks `Thread` references,
+  #   which cannot be shared across ractors.
+  class AtomicConditionVariable
+    # Creates a new condition variable with no parked threads.
+    #
+    # @example
+    #   condvar = AtomicConditionVariable.new
+    #
+    # @rbs () -> void
+    def initialize
+      @waiters = Atom.new([].freeze)
+    end
+
+    # Returns the number of currently parked waiters.
+    #
+    # This operation is atomic and thread-safe. The returned value reflects
+    # the state at the time of the call, but may change immediately after
+    # in concurrent environments.
+    #
+    # @return [Integer] The number of currently parked waiters
+    #
+    # @example
+    #   condvar = AtomicConditionVariable.new
+    #   puts condvar.waiter_count #=> 0
+    #
+    # @rbs () -> Integer
+    def waiter_count
+      @waiters.value.size
+    end
+
+    # Wakes one parked waiter, or no-ops if none are parked.
+    #
+    # If a waiter has registered itself but is not yet inside `Thread.stop`,
+    # Ruby remembers the wakeup and the next `Thread.stop` returns
+    # immediately.
+    #
+    # @return [true, false] true if a waiter was signalled, false otherwise
+    #
+    # @example
+    #   condvar = AtomicConditionVariable.new
+    #   condvar.signal #=> false
+    #
+    # @rbs () -> bool
+    def signal
+      target = nil
+      @waiters.swap do |waiters|
+        if waiters.empty?
+          waiters
+        else
+          target = waiters.first
+          waiters.drop(1).freeze
+        end
+      end
+      return false unless target
+
+      target.wakeup rescue nil
+      true
+    end
+
+    # Wakes every parked waiter.
+    #
+    # Each woken thread observes the wake the same way as with {#signal}.
+    #
+    # @return [Integer] The number of waiters signalled
+    #
+    # @example
+    #   condvar = AtomicConditionVariable.new
+    #   condvar.broadcast #=> 0
+    #
+    # @rbs () -> Integer
+    def broadcast
+      targets = nil
+      @waiters.swap do |waiters|
+        targets = waiters
+        [].freeze
+      end
+      targets.each { |thread| thread.wakeup rescue nil }
+      targets.size
+    end
+
+    # Blocks until the given block returns a truthy value, then returns that
+    # value.
+    #
+    # The block is evaluated optimistically first. If it returns truthy on
+    # that pass, no waiter is registered and the call returns immediately.
+    # Otherwise the calling thread registers itself, re-evaluates the
+    # block, and parks via `Thread.stop` until a {#signal} or {#broadcast}
+    # wakes it. The block may run more than once and may run concurrently
+    # with a signalling thread.
+    #
+    # @yieldreturn [untyped] Truthy to wake, falsy to keep waiting
+    # @return [untyped] The first truthy value returned by the block
+    #
+    # @example Simple wait
+    #   condvar = AtomicConditionVariable.new
+    #   ready = AtomicBoolean.new(false)
+    #
+    #   Thread.new do
+    #     sleep(1)
+    #     ready.make_true
+    #     condvar.signal
+    #   end
+    #
+    #   condvar.wait { ready.true? } #=> true
+    #
+    # @rbs () { () -> untyped } -> untyped
+    def wait
+      result = yield
+      return result if result
+
+      self_thread = Thread.current
+      loop do
+        @waiters.swap { |waiters| (waiters + [self_thread]).freeze }
+        result = yield
+        if result
+          @waiters.swap { |waiters| (waiters - [self_thread]).freeze }
+          return result
+        end
+
+        Thread.stop
+        @waiters.swap { |waiters| (waiters - [self_thread]).freeze }
+      end
+    end
+  end
+end
+
+AtomicConditionVariable = AtomicRuby::AtomicConditionVariable

data/lib/atomic-ruby/atomic_thread_pool.rb

@@ -2,6 +2,7 @@
 # frozen_string_literal: true
 
 require_relative "atom"
+require_relative "atomic_condition_variable"
 
 module AtomicRuby
   # Provides a fixed-size thread pool using atomic operations for work queuing.
@@ -86,6 +87,7 @@ module AtomicRuby
       @on_error = on_error
 
       @state = Atom.new(in: nil, out: nil, count: 0, shutdown: false)
+      @work_available = AtomicConditionVariable.new
       @started_thread_count = Atom.new(0)
       @active_thread_count = Atom.new(0)
       @threads = []
@@ -126,6 +128,8 @@ module AtomicRuby
         end
       end
       raise EnqueuedWorkAfterShutdownError if state[:shutdown]
+
+      @work_available.signal
     end
 
     # Returns the number of currently alive worker threads.
@@ -234,6 +238,7 @@ module AtomicRuby
       end
       return if already_shutdown
 
+      @work_available.broadcast
       @threads.each(&:join)
     end
 
@@ -261,40 +266,39 @@ module AtomicRuby
             work = nil
             should_shutdown = false
 
-            @state.swap do |current_state|
-              if current_state[:shutdown] && current_state[:in].nil? && current_state[:out].nil?
-                should_shutdown = true
-                current_state
-              elsif current_state[:out]
-                work = current_state[:out][:value]
-                current_state.merge(out: current_state[:out][:next], count: current_state[:count] - 1)
-              elsif current_state[:in]
-                new_out = reverse_list(current_state[:in])
-                work = new_out[:value]
-                current_state.merge(in: nil, out: new_out[:next], count: current_state[:count] - 1)
-              else
-                current_state
+            @work_available.wait do
+              @state.swap do |current_state|
+                if current_state[:shutdown] && current_state[:in].nil? && current_state[:out].nil?
+                  should_shutdown = true
+                  current_state
+                elsif current_state[:out]
+                  work = current_state[:out][:value]
+                  current_state.merge(out: current_state[:out][:next], count: current_state[:count] - 1)
+                elsif current_state[:in]
+                  new_out = reverse_list(current_state[:in])
+                  work = new_out[:value]
+                  current_state.merge(in: nil, out: new_out[:next], count: current_state[:count] - 1)
+                else
+                  current_state
+                end
               end
+              work || should_shutdown
             end
 
-            if should_shutdown
-              break
-            elsif work
-              @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_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
-            else
-              sleep 0.001
+            ensure
+              @active_thread_count.swap { |current_count| current_count - 1 }
             end
           end
         end

data/lib/atomic-ruby/version.rb

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

data/lib/atomic-ruby.rb

@@ -3,5 +3,6 @@
 require_relative "atomic-ruby/version"
 require_relative "atomic-ruby/atom"
 require_relative "atomic-ruby/atomic_boolean"
+require_relative "atomic-ruby/atomic_condition_variable"
 require_relative "atomic-ruby/atomic_thread_pool"
 require_relative "atomic-ruby/atomic_count_down_latch"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: atomic-ruby
 version: !ruby/object:Gem::Version
-  version: 0.11.1
+  version: 0.13.0
 platform: ruby
 authors:
 - Joshua Young
@@ -27,6 +27,7 @@ files:
 - lib/atomic-ruby.rb
 - lib/atomic-ruby/atom.rb
 - lib/atomic-ruby/atomic_boolean.rb
+- lib/atomic-ruby/atomic_condition_variable.rb
 - lib/atomic-ruby/atomic_count_down_latch.rb
 - lib/atomic-ruby/atomic_thread_pool.rb
 - lib/atomic-ruby/version.rb