Atomic (CAS) primitives for Ruby.
Install the gem and add to the application's Gemfile by executing:
bundle add atomic-rubyIf bundler is not being used to manage dependencies, install the gem by executing:
gem install atomic-rubyAtom:
require "atomic-ruby"
atom = Atom.new(0)
p atom.value #=> 0
atom.swap { |current_value| current_value + 1 }
p atom.value #=> 1
atom.swap { |current_value| current_value + 1 }
p atom.value #=> 2AtomicBoolean:
require "atomic-ruby"
atom = AtomicBoolean.new(false)
p atom.value #=> false
p atom.false? #=> true
p atom.true? #=> false
atom.make_true
p atom.true? #=> true
atom.toggle
p atom.false? #=> trueAtomicConditionVariable:
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 #=> 0AtomicThreadPool:
require "atomic-ruby"
results = []
pool = AtomicThreadPool.new(size: 4)
p pool.length #=> 4
10.times do |idx|
work = proc do
sleep(0.5)
results << (idx + 1)
end
pool << work
end
p pool.queue_length #=> 10
sleep(0.5)
p pool.queue_length #=> 2 (YMMV)
pool.shutdown
p pool.length #=> 0
p pool.queue_length #=> 0
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]AtomicCountDownLatch:
require "atomic-ruby"
latch = AtomicCountDownLatch.new(3)
p latch.count #=> 3
threads = 3.times.map do
Thread.new do
sleep(rand(5))
latch.count_down
end
end
latch.wait
p latch.count #=> 0Note
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.
Atom
# frozen_string_literal: true
require "benchmark"
require "concurrent-ruby"
require_relative "../lib/atomic-ruby"
class SynchronizedBankAccount
def initialize(balance)
@balance = balance
@mutex = Mutex.new
end
def balance
@mutex.synchronize do
@balance
end
end
def deposit(amount)
@mutex.synchronize do
@balance += amount
end
end
end
class ConcurrentRubyAtomicBankAccount
def initialize(balance)
@balance = Concurrent::Atom.new(balance)
end
def balance
@balance.value
end
def deposit(amount)
@balance.swap { |current_balance| current_balance + amount }
end
end
class AtomicRubyAtomicBankAccount
def initialize(balance)
@balance = Atom.new(balance)
end
def balance
@balance.value
end
def deposit(amount)
@balance.swap { |current_balance| current_balance + amount }
end
end
balances = []
results = []
3.times do |idx|
klass = case idx
when 0 then SynchronizedBankAccount
when 1 then ConcurrentRubyAtomicBankAccount
when 2 then AtomicRubyAtomicBankAccount
end
result = Benchmark.measure do
account = klass.new(100)
5.times.map do |idx|
Thread.new do
25.times do
account.deposit(idx + 1)
sleep(0.2)
account.deposit(idx + 2)
end
end
end.each(&:join)
balances << account.balance
end
results << result
end
puts "\n"
puts "ruby version: #{RUBY_DESCRIPTION}"
puts "concurrent-ruby version: #{Concurrent::VERSION}"
puts "atomic-ruby version: #{AtomicRuby::VERSION}"
puts "\n"
puts "Balances:"
puts "Synchronized Bank Account Balance: #{balances[0]}"
puts "Concurrent Ruby Atomic Bank Account Balance: #{balances[1]}"
puts "Atomic Ruby Atomic Bank Account Balance: #{balances[2]}"
puts "\n"
puts "Benchmark Results:"
puts "Synchronized Bank Account: #{results[0].real.round(6)} seconds"
puts "Concurrent Ruby Atomic Bank Account: #{results[1].real.round(6)} seconds"
puts "Atomic Ruby Atomic Bank Account: #{results[2].real.round(6)} seconds"> bundle exec rake clobber && bundle exec rake compile && bundle exec ruby examples/atom_benchmark.rb
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.13.0
Balances:
Synchronized Bank Account Balance: 975
Concurrent Ruby Atomic Bank Account Balance: 975
Atomic Ruby Atomic Bank Account Balance: 975
Benchmark Results:
Synchronized Bank Account: 5.109724 seconds
Concurrent Ruby Atomic Bank Account: 5.137749 seconds
Atomic Ruby Atomic Bank Account: 5.101637 seconds
AtomicBoolean
# frozen_string_literal: true
require "benchmark/ips"
require "concurrent-ruby"
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 "concurrent-ruby version: #{Concurrent::VERSION}"
@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 Boolean Toggle") do
boolean = false
mutex = Mutex.new
20.times.map do
Thread.new do
100.times do
mutex.synchronize do
boolean = !boolean
end
end
end
end.each(&:join)
end
x.report("Concurrent Ruby Atomic Boolean Toggle") do
boolean = Concurrent::AtomicBoolean.new(false)
20.times.map do
Thread.new do
100.times do
# Not exactly atomic, but this
# is the closest matching API.
boolean.value = !boolean.value
end
end
end.each(&:join)
end
x.report("Atomic Ruby Atomic Boolean Toggle") do
boolean = AtomicBoolean.new(false)
20.times.map do
Thread.new do
100.times do
boolean.toggle
end
end
end.each(&:join)
end
x.compare!
end> bundle exec rake clobber && bundle exec rake compile && bundle exec ruby examples/atomic_boolean_benchmark.rb
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.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
AtomicConditionVariable
# 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 Condition Variable Wait/Signal 3.847k i/100ms
Atomic Ruby Atomic Condition Variable Wait/Signal 3.704k i/100ms
Calculating -------------------------------------
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 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
AtomicThreadPool
# frozen_string_literal: true
require "benchmark"
require "concurrent-ruby"
require_relative "../lib/atomic-ruby"
results = []
2.times do |idx|
result = Benchmark.measure do
pool = case idx
when 0 then Concurrent::FixedThreadPool.new(20)
when 1 then AtomicThreadPool.new(size: 20)
end
100.times do
pool << proc { sleep(0.2) }
end
100.times do
pool << proc { 1_000_000.times.map(&:itself).sum }
end
pool.shutdown
# concurrent-ruby's #shutdown does not wait for threads to terminate
pool.wait_for_termination if idx == 0
end
results << result
end
puts "\n"
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"> bundle exec rake clobber && bundle exec rake compile && bundle exec ruby examples/atomic_thread_pool_benchmark.rb
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.13.0
Benchmark Results:
Concurrent Ruby Thread Pool: 5.792203 seconds
Atomic Ruby Atomic Thread Pool: 5.504388 seconds
After checking out the repo, run bin/setup to install dependencies. Then, run bundle exec rake to run the tests.
You can also run bin/console for an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the
version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version,
push git commits and the created tag, and push the .gem file to rubygems.org.
Bug reports and pull requests are welcome on GitHub at https://github.com/[joshuay03]/atomic-ruby. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.
The gem is available as open source under the terms of the MIT License.
Everyone interacting in the AtomicRuby project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.