atomic-ruby 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a3ca7bf11c2aa032352d7be8554faf13818bf1e982514ff60761779e2ec1283d
-  data.tar.gz: 0b1965ea3c65e62d3c824e56ab673fc3e33f73f0283a39355aaf285f65a71b16
+  metadata.gz: 258cae699ce52593ad8958202446ff4ec5fffe8cd81771310d9a998dd10a3a09
+  data.tar.gz: 41af67fd11f30275d176691601f7f72863037583a0ecb70d3159da7d0e10e18a
 SHA512:
-  metadata.gz: 9396b5a3a334cb5d89a17a09d59bf27ce1742b8d49720dae2c056a643ca1e0c5d32bbfded745c5557fd01b5fc420beaef3936540633adf090890f5b5a6a9b6c0
-  data.tar.gz: 022cec086bc16c8b5437d42c9053c7fb2eca0484aea0e5d66221a292367efaebc0d4c30dbe12ad4d640f5751d7f4e9f9a3f90445c45aef58548d56d6e152c64e
+  metadata.gz: 3c49fea57c186b3f5b99f522d30aa94b5cf073b08e3b2179b58cd4da37daba3af5f8890b0abff209731e0bc4cdb350864b0d4a90e940cb4664763c4038b53f50
+  data.tar.gz: a4b0521b8a951ccb672e9f138983dc0f55f7fbaaf8a4848d17f9f88ff5dbfd6c4b46208252b45b0fec9cddb3432962711f961ef979d569b0d1962083c00706a6

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 ## [Unreleased]
 
+## [0.2.0] - 2025-06-08
+
+- Add `AtomicBoolean`
+
+## [0.2.0] - 2025-06-07
+
+- Add `AtomicThreadPool`
+- Require ruby >= 3.3
+- Make `Atom#value` atomic
+
 ## [0.1.0] - 2025-06-06
 
 - Initial release

data/README.md

@@ -1,36 +1,354 @@
 # AtomicRuby
 
+![Version](https://img.shields.io/gem/v/atomic-ruby)
+![Build](https://img.shields.io/github/actions/workflow/status/joshuay03/atomic-ruby/.github/workflows/main.yml?branch=main)
+
 Atomic primitives for Ruby.
 
 ## Installation
 
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
-
 Install the gem and add to the application's Gemfile by executing:
 
 ```bash
-bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+bundle add atomic-ruby
 ```
 
 If bundler is not being used to manage dependencies, install the gem by executing:
 
 ```bash
-gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+gem install atomic-ruby
 ```
 
 ## Usage
 
+`AtomicRuby::Atom`:
+
 ```ruby
 require "atomic-ruby"
 
 atom = AtomicRuby::Atom.new(0)
-puts atom.value # => 0
-atom.swap { |current| current + 1 }
-puts atom.value # => 1
-atom.swap { |current| current + 1 }
-puts atom.value # => 2
+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 #=> 2
+```
+
+`AtomicRuby::AtomicBoolean`:
+
+```ruby
+require "atomic-ruby"
+
+atom = AtomicRuby::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? #=> true
+```
+
+`AtomicRuby::AtomicThreadPool`:
+
+```ruby
+require "atomic-ruby"
+
+results = []
+
+pool = AtomicRuby::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]
+```
+
+## Benchmarks
+
+<details>
+
+<summary>AtomicRuby::Atom</summary>
+
+<br>
+
+```ruby
+# 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 = AtomicRuby::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
+        100.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 "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 compile && bundle exec ruby examples/atom_benchmark.rb
+
+ruby version:            ruby 3.4.4 (2025-05-14 revision a38531fd3f) +YJIT +PRISM [arm64-darwin24]
+concurrent-ruby version: 1.3.5
+atomic-ruby version:     0.2.0
+
+Balances:
+Synchronized Bank Account Balance:           3600
+Concurrent Ruby Atomic Bank Account Balance: 3600
+Atomic Ruby Atomic Bank Account Balance:     3600
+
+Benchmark Results:
+Synchronized Bank Account:           20.467293 seconds
+Concurrent Ruby Atomic Bank Account: 20.460731 seconds
+Atomic Ruby Atomic Bank Account:     20.455696 seconds
+```
+
+</details>
+
+<details>
+
+<summary>AtomicRuby::AtomicBoolean</summary>
+
+```ruby
+# frozen_string_literal: true
+
+require "benchmark/ips"
+require "concurrent-ruby"
+require_relative "../lib/atomic-ruby"
+
+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 = AtomicRuby::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 compile && bundle exec ruby examples/atomic_boolean_benchmark.rb
+
+ruby 3.4.4 (2025-05-14 revision a38531fd3f) +YJIT +PRISM [arm64-darwin24]
+Warming up --------------------------------------
+Synchronized Boolean Toggle
+                        83.000 i/100ms
+Concurrent Ruby Atomic Boolean Toggle
+                        58.000 i/100ms
+Atomic Ruby Atomic Boolean Toggle
+                        88.000 i/100ms
+Calculating -------------------------------------
+Synchronized Boolean Toggle
+                        775.552 (± 6.2%) i/s    (1.29 ms/i) -      3.901k in   5.051649s
+Concurrent Ruby Atomic Boolean Toggle
+                        741.655 (± 3.5%) i/s    (1.35 ms/i) -      3.712k in   5.011183s
+Atomic Ruby Atomic Boolean Toggle
+                        881.916 (± 2.8%) i/s    (1.13 ms/i) -      4.488k in   5.092910s
+
+Comparison:
+Atomic Ruby Atomic Boolean Toggle:      881.9 i/s
+Synchronized Boolean Toggle:            775.6 i/s - 1.14x  slower
+Concurrent Ruby Atomic Boolean Toggle:  741.7 i/s - 1.19x  slower
+```
+
+</details>
+
+<details>
+
+<summary>AtomicRuby::AtomicThreadPool</summary>
+
+<br>
+
+```ruby
+# 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 AtomicRuby::AtomicThreadPool.new(size: 20)
+    end
+
+    100.times do
+      pool << -> { sleep(0.2) }
+    end
+
+    100.times do
+      pool << -> { 1_000_000.times.map(&:itself).sum }
+    end
+
+    # concurrent-ruby does not wait for threads to die on shutdown
+    threads = if idx == 0
+      pool.instance_variable_get(:@pool).map { |worker| worker.instance_variable_get(:@thread) }
+    end
+    pool.shutdown
+    threads&.each(&:join)
+  end
+
+  results << result
+end
+
+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 compile && bundle exec ruby examples/atomic_thread_pool_benchmark.rb
+
+ruby version:            ruby 3.4.4 (2025-05-14 revision a38531fd3f) +YJIT +PRISM [arm64-darwin24]
+concurrent-ruby version: 1.3.5
+atomic-ruby version:     0.2.0
+
+Benchmark Results:
+Concurrent Ruby Thread Pool:    5.188700 seconds
+Atomic Ruby Atomic Thread Pool: 4.783689 seconds
+```
+
+</details>
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `bundle exec rake` to run the tests.

data/atomic-ruby.gemspec

@@ -11,7 +11,7 @@ Gem::Specification.new do |spec|
   spec.summary = "Atomic primitives for Ruby"
   spec.homepage = "https://github.com/joshuay03/atomic-ruby"
   spec.license = "MIT"
-  spec.required_ruby_version = ">= 3.2.0"
+  spec.required_ruby_version = ">= 3.3.0"
 
   spec.metadata["source_code_uri"] = spec.homepage
   spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/main/CHANGELOG.md"

data/ext/atomic_ruby/atomic_ruby.c

@@ -1,6 +1,4 @@
 #include "atomic_ruby.h"
-#include <stdlib.h>
-#include <string.h>
 
 typedef struct {
   volatile VALUE value;
@@ -50,6 +48,12 @@ static VALUE rb_cAtom_initialize(VALUE self, VALUE value) {
   return self;
 }
 
+static VALUE rb_cAtom_value(VALUE self) {
+  atomic_ruby_atom_t *atomic_ruby_atom;
+  TypedData_Get_Struct(self, atomic_ruby_atom_t, &atomic_ruby_atom_type, atomic_ruby_atom);
+  return (VALUE)RUBY_ATOMIC_PTR_LOAD(atomic_ruby_atom->value);
+}
+
 static VALUE rb_cAtom_swap(VALUE self) {
   atomic_ruby_atom_t *atomic_ruby_atom;
   TypedData_Get_Struct(self, atomic_ruby_atom_t, &atomic_ruby_atom_type, atomic_ruby_atom);
@@ -63,18 +67,12 @@ static VALUE rb_cAtom_swap(VALUE self) {
   return new_value;
 }
 
-static VALUE rb_cAtom_value(VALUE self) {
-  atomic_ruby_atom_t *atomic_ruby_atom;
-  TypedData_Get_Struct(self, atomic_ruby_atom_t, &atomic_ruby_atom_type, atomic_ruby_atom);
-  return atomic_ruby_atom->value;
-}
-
 RUBY_FUNC_EXPORTED void Init_atomic_ruby(void) {
   VALUE rb_mAtomicRuby = rb_define_module("AtomicRuby");
   VALUE rb_cAtom = rb_define_class_under(rb_mAtomicRuby, "Atom", rb_cObject);
 
   rb_define_alloc_func(rb_cAtom, rb_cAtom_allocate);
   rb_define_method(rb_cAtom, "_initialize", rb_cAtom_initialize, 1);
-  rb_define_method(rb_cAtom, "swap", rb_cAtom_swap, 0);
-  rb_define_method(rb_cAtom, "value", rb_cAtom_value, 0);
+  rb_define_method(rb_cAtom, "_value", rb_cAtom_value, 0);
+  rb_define_method(rb_cAtom, "_swap", rb_cAtom_swap, 0);
 }

data/lib/atomic-ruby/atom.rb

@@ -5,5 +5,13 @@ module AtomicRuby
     def initialize(value)
       _initialize(value)
     end
+
+    def value
+      _value
+    end
+
+    def swap(&block)
+      _swap(&block)
+    end
   end
 end

data/lib/atomic-ruby/atomic_boolean.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative "atom"
+
+module AtomicRuby
+  class AtomicBoolean
+    class InvalidBooleanError < StandardError; end
+
+    def initialize(value)
+      unless value.is_a?(TrueClass) || value.is_a?(FalseClass)
+        raise InvalidBooleanError, "expected boolean to be a `TrueClass` or `FalseClass`, got #{value.class}"
+      end
+
+      @atom = Atom.new(value)
+    end
+
+    def value
+      @atom.value
+    end
+
+    def true?
+      value == true
+    end
+
+    def false?
+      value == false
+    end
+
+    def make_true
+      @atom.swap { true }
+    end
+
+    def make_false
+      @atom.swap { false }
+    end
+
+    def toggle
+      @atom.swap { |current_value| !current_value }
+    end
+  end
+end

data/lib/atomic-ruby/atomic_thread_pool.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require_relative "atom"
+require_relative "atomic_boolean"
+
+module AtomicRuby
+  class AtomicThreadPool
+    class UnsupportedWorkTypeError < StandardError; end
+    class InvalidWorkQueueingError < StandardError; end
+
+    def initialize(size:)
+      @size = size
+      @queue = Atom.new([])
+      @threads = []
+      @started_threads = Atom.new(0)
+      @stopping = AtomicBoolean.new(false)
+
+      start
+    end
+
+    def <<(work)
+      unless work.is_a?(Proc) || work == :stop
+        raise UnsupportedWorkTypeError, "expected work to be a `Proc`, got #{work.class}"
+      end
+
+      if @stopping.true?
+        raise InvalidWorkQueueingError, "cannot queue work during or after pool shutdown"
+      end
+
+      @queue.swap { |queue| queue << work }
+      true
+    end
+
+    def length
+      @threads.select(&:alive?).length
+    end
+
+    def queue_length
+      @queue.value.length
+    end
+
+    def shutdown
+      self << :stop
+      @threads.each(&:join)
+      true
+    end
+
+    private
+
+    def start
+      @threads = @size.times.map do |num|
+        Thread.new(num) do |idx|
+          name = "AtomicRuby::AtomicThreadPool thread #{idx}"
+          Thread.current.name = name
+
+          @started_threads.swap { |count| count + 1 }
+
+          loop do
+            work = nil
+            @queue.swap { |queue| work = queue.last; queue[0..-2] }
+            case work
+            when Proc
+              begin
+                work.call
+              rescue => err
+                puts "#{name} rescued:"
+                puts "#{err.class}: #{err.message}"
+                puts err.backtrace.join("\n")
+              end
+            when :stop
+              @stopping.make_true
+            when NilClass
+              if @stopping.true?
+                break
+              else
+                Thread.pass
+              end
+            end
+          end
+        end
+      end
+
+      sleep(0.001) until @started_threads.value == @size
+    end
+  end
+end

data/lib/atomic-ruby/version.rb

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

data/lib/atomic-ruby.rb

@@ -3,6 +3,7 @@
 require_relative "atomic-ruby/version"
 require_relative "atomic-ruby/atomic_ruby"
 require_relative "atomic-ruby/atom"
+require_relative "atomic-ruby/atomic_thread_pool"
 
 module AtomicRuby
   class Error < StandardError; end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: atomic-ruby
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Joshua Young
@@ -26,7 +26,9 @@ files:
 - ext/atomic_ruby/extconf.rb
 - lib/atomic-ruby.rb
 - lib/atomic-ruby/atom.rb
+- lib/atomic-ruby/atomic_boolean.rb
 - lib/atomic-ruby/atomic_ruby.bundle
+- lib/atomic-ruby/atomic_thread_pool.rb
 - lib/atomic-ruby/version.rb
 homepage: https://github.com/joshuay03/atomic-ruby
 licenses:
@@ -41,7 +43,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.2.0
+      version: 3.3.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="