atomic-ruby 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a3ca7bf11c2aa032352d7be8554faf13818bf1e982514ff60761779e2ec1283d
-  data.tar.gz: 0b1965ea3c65e62d3c824e56ab673fc3e33f73f0283a39355aaf285f65a71b16
+  metadata.gz: afd2aac6df8cbc6d73dc79f925ab4f1d17288c3b1a146e2a52fea1ea1c343a30
+  data.tar.gz: 77ed011cf73f079f07b09eb7d9f74d7db2da564bee8aa0e878d61241582b7fe6
 SHA512:
-  metadata.gz: 9396b5a3a334cb5d89a17a09d59bf27ce1742b8d49720dae2c056a643ca1e0c5d32bbfded745c5557fd01b5fc420beaef3936540633adf090890f5b5a6a9b6c0
-  data.tar.gz: 022cec086bc16c8b5437d42c9053c7fb2eca0484aea0e5d66221a292367efaebc0d4c30dbe12ad4d640f5751d7f4e9f9a3f90445c45aef58548d56d6e152c64e
+  metadata.gz: 5053ea8e8d7158bf72fadf6d63b49a63a56550918df555237e1af42189bb2fddccc386d7ab485bbb1dbbb49cfe4633b827ff5c96ac94ab8e08f04da8c074e8b0
+  data.tar.gz: 3eea3c132563bab777877c5e1785fe4ef4e11ae089c06aa4acd46d0db6465309de68ec728fdead66de0c51ca71ac8ce46d58dfc034407115582bb97f3010ecaa

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 ## [Unreleased]
 
+## [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,254 @@
 # 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::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 AtomicRubyAtomicBankAccount
+  def initialize(balance)
+    @balance = AtomicRuby::Atom.new(balance)
+  end
+
+  def balance
+    @balance.value
+  end
+
+  def deposit(amount)
+    sleep(rand(0.1..0.2))
+    @balance.swap { |current| current + amount }
+  end
+end
+
+class ConcurrentRubyAtomicBankAccount
+  def initialize(balance)
+    @balance = Concurrent::Atom.new(balance)
+  end
+
+  def balance
+    @balance.value
+  end
+
+  def deposit(amount)
+    sleep(rand(0.1..0.2))
+    @balance.swap { |current| current + amount }
+  end
+end
+
+class SynchronizedBankAccount
+  attr_reader :balance
+
+  def initialize(balance)
+    @balance = balance
+    @mutex = Mutex.new
+  end
+
+  def deposit(amount)
+    sleep(rand(0.1..0.2))
+    @mutex.synchronize do
+      @balance += amount
+    end
+  end
+end
+
+balances = []
+
+r1 = Benchmark.measure do
+  account = SynchronizedBankAccount.new(100)
+  10_000.times.map { |i|
+    Thread.new { account.deposit(i) }
+  }.each(&:join)
+  balances << account.balance
+end
+
+r2 = Benchmark.measure do
+  account = ConcurrentRubyAtomicBankAccount.new(100)
+  10_000.times.map { |i|
+    Thread.new { account.deposit(i) }
+  }.each(&:join)
+  balances << account.balance
+end
+
+r3 = Benchmark.measure do
+  account = AtomicRubyAtomicBankAccount.new(100)
+  10_000.times.map { |i|
+    Thread.new { account.deposit(i) }
+  }.each(&:join)
+  balances << account.balance
+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:           #{r1.real.round(6)} seconds"
+puts "Concurrent Ruby Atomic Bank Account: #{r2.real.round(6)} seconds"
+puts "Atomic Ruby Atomic Bank Account:     #{r3.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.1.0
+
+Balances:
+Synchronized Bank Account Balance:           49995100
+Concurrent Ruby Atomic Bank Account Balance: 49995100
+Atomic Ruby Atomic Bank Account Balance:     49995100
+
+Benchmark Results:
+Synchronized Bank Account:           1.900873 seconds
+Concurrent Ruby Atomic Bank Account: 1.840683 seconds
+Atomic Ruby Atomic Bank Account:     1.755343 seconds
 ```
 
+</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(5)
+    when 1 then AtomicRuby::AtomicThreadPool.new(size: 5)
+    end
+
+    20.times do
+      pool << -> { sleep(0.25) }
+    end
+
+    20.times do
+      pool << -> { 100_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.1.0
+
+Benchmark Results:
+Concurrent Ruby Thread Pool:    1.133100 seconds
+Atomic Ruby Atomic Thread Pool: 1.088543 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;
@@ -66,7 +64,7 @@ static VALUE rb_cAtom_swap(VALUE 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 atomic_ruby_atom->value;
+  return (VALUE)RUBY_ATOMIC_PTR_LOAD(atomic_ruby_atom->value);
 }
 
 RUBY_FUNC_EXPORTED void Init_atomic_ruby(void) {
@@ -75,6 +73,6 @@ RUBY_FUNC_EXPORTED void Init_atomic_ruby(void) {
 
   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, "_swap", rb_cAtom_swap, 0);
+  rb_define_method(rb_cAtom, "_value", rb_cAtom_value, 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_thread_pool.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require_relative "atom"
+
+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 = Atom.new(false)
+
+      start
+    end
+
+    def <<(work)
+      unless Proc === work || work == :stop
+        raise UnsupportedWorkTypeError, "queued work must be a Proc"
+      end
+
+      if @stopping.value
+        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.swap { true }
+            when NilClass
+              if @stopping.value
+                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.2.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.2.0
 platform: ruby
 authors:
 - Joshua Young
@@ -27,6 +27,7 @@ files:
 - lib/atomic-ruby.rb
 - lib/atomic-ruby/atom.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 +42,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:
   - - ">="