atomic-ruby 0.8.1 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ecc5a5a825a6636db5718458318ba2650c05edb9a5a1198947f82e94596a974e
-  data.tar.gz: 7a08fbdf2e3362e03450ccb5d2342055c8e50832afae4bc709c5e1c5e187f88b
+  metadata.gz: b52931f98d46947d0d2f4dccffbe51e771c619d61b54457a223162be41624353
+  data.tar.gz: 3c91a27d99c3eb4d2a04f668bc5ebbc19c1c60b6a9fc688812df96c20bed37a4
 SHA512:
-  metadata.gz: f52cfbc19feaac870429dc893cbbf3541120e9beeaf20723d9f705b6a74835891473a299b682531d593e5adb1d2b3b75a0eed365b29e3490c1b921ea59aa4714
-  data.tar.gz: f797297e13eb693db8759e2bef195ed57288530dd05c8188b67dc1c9df1378476ed4e252b48385a2d951350e6e0f94f6b7aa3a2680d40885759d50fbdcdac1e9
+  metadata.gz: b3f6d04175439390f6b9f29d91bf3cfad5b95018f7363e3cb341c7512857008e285d3a462363108cb54e613ed898153e157d7c41b1e113d92c38053a52e5d5be
+  data.tar.gz: aadb6f2b22fa068d8599b1e0aea30bc6e52d4b97198c4e4078e465d172f168b8548c9ab2f4bd174298aa2f5d02cd421c868a896c4b0d53689706edeb2414ff35

data/CHANGELOG.md

@@ -1,12 +1,25 @@
 ## [Unreleased]
 
+## [0.10.0] - 2025-11-09
+
+- Add `AtomicThreadPool#active_count`
+- Make native extension methods private
+- Add YARD documentation and inline RBS type signatures
+- Replace ruby 3.5 references with 4.0
+
+## [0.9.0] - 2025-11-05
+
+- Switch `AtomicThreadPool` back to atomics now that Ractor safety is lazy
+- Don't enforce Ractor safety unless crossing Ractor boundaries
+- Add `AtomicThreadPool#size` and `AtomicThreadPool#queue_size` aliases
+
 ## [0.8.1] - 2025-11-01
 
 - Don't require `AtomicThreadPool#<<` to be given a shareable proc
 
 ## [0.8.0] - 2025-11-01
 
-- Fix Ractor safety (requires Ruby 3.5+)
+- Fix Ractor safety
 - Make `ArgumentError` messages consistent
 - Implement write barriers for `Atom`
 

data/README.md

@@ -98,18 +98,7 @@ p latch.count #=> 0
 ```
 
 > [!NOTE]
-> `Atom`, `AtomicBoolean`, and `AtomicCountDownLatch` are Ractor-safe in Ruby 3.5+.
->
-> When storing procs in atoms, create them using `Ractor.shareable_proc`, as `Ractor.make_shareable`
-> cannot convert regular procs to shareable ones when the proc's context is not shareable.
->
-> ```ruby
-> # This will raise an error in Ruby 3.5+ (proc created in non-shareable context)
-> atom = Atom.new(proc { puts "hello" })
->
-> # Use this instead
-> atom = Atom.new(Ractor.shareable_proc { puts "hello" })
-> ```
+> `Atom`, `AtomicBoolean`, and `AtomicCountDownLatch` are Ractor-safe in Ruby 4.0+.
 
 ## Benchmarks
 
@@ -221,9 +210,9 @@ 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.5.0dev (2025-10-31T18:08:15Z master 980e18496e) +YJIT +PRISM [arm64-darwin25]
+ruby version:            ruby 4.0.0dev (2025-11-08T15:08:09Z master 75d25a42e6) +YJIT +PRISM [arm64-darwin25]
 concurrent-ruby version: 1.3.5
-atomic-ruby version:     0.8.0
+atomic-ruby version:     0.10.0
 
 Balances:
 Synchronized Bank Account Balance:           975
@@ -231,9 +220,9 @@ Concurrent Ruby Atomic Bank Account Balance: 975
 Atomic Ruby Atomic Bank Account Balance:     975
 
 Benchmark Results:
-Synchronized Bank Account:           5.105459 seconds
-Concurrent Ruby Atomic Bank Account: 5.101044 seconds
-Atomic Ruby Atomic Bank Account:     5.091892 seconds
+Synchronized Bank Account:           5.112382 seconds
+Concurrent Ruby Atomic Bank Account: 5.113139 seconds
+Atomic Ruby Atomic Bank Account:     5.101891 seconds
 ```
 
 </details>
@@ -312,29 +301,29 @@ end
 ```
 > bundle exec rake compile && bundle exec ruby examples/atomic_boolean_benchmark.rb
 
-ruby version:            ruby 3.5.0dev (2025-10-31T18:08:15Z master 980e18496e) +YJIT +PRISM [arm64-darwin25]
+ruby version:            ruby 4.0.0dev (2025-11-08T15:08:09Z master 75d25a42e6) +YJIT +PRISM [arm64-darwin25]
 concurrent-ruby version: 1.3.5
-atomic-ruby version:     0.8.0
+atomic-ruby version:     0.10.0
 
 Warming up --------------------------------------
 Synchronized Boolean Toggle
-                       154.000 i/100ms
+                       120.000 i/100ms
 Concurrent Ruby Atomic Boolean Toggle
-                       127.000 i/100ms
+                        94.000 i/100ms
 Atomic Ruby Atomic Boolean Toggle
-                       139.000 i/100ms
+                       100.000 i/100ms
 Calculating -------------------------------------
 Synchronized Boolean Toggle
-                          1.458k (± 7.3%) i/s  (685.85 μs/i) -      7.392k in   5.102733s
+                          1.188k (± 8.9%) i/s  (841.70 μs/i) -      5.880k in   5.002927s
 Concurrent Ruby Atomic Boolean Toggle
-                          1.129k (± 9.7%) i/s  (886.10 μs/i) -      5.588k in   5.001783s
+                        889.224 (±11.8%) i/s    (1.12 ms/i) -      4.418k in   5.073535s
 Atomic Ruby Atomic Boolean Toggle
-                          1.476k (± 6.0%) i/s  (677.44 μs/i) -      7.367k in   5.017482s
+                        999.426 (± 4.3%) i/s    (1.00 ms/i) -      5.000k in   5.012997s
 
 Comparison:
-Atomic Ruby Atomic Boolean Toggle:         1476.1 i/s
-Synchronized Boolean Toggle:               1458.1 i/s - same-ish: difference falls within error
-Concurrent Ruby Atomic Boolean Toggle:     1128.5 i/s - 1.31x  slower
+Synchronized Boolean Toggle:               1188.1 i/s
+Atomic Ruby Atomic Boolean Toggle:          999.4 i/s - 1.19x  slower
+Concurrent Ruby Atomic Boolean Toggle:      889.2 i/s - 1.34x  slower
 ```
 
 </details>
@@ -390,13 +379,13 @@ 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.5.0dev (2025-10-31T18:08:15Z master 980e18496e) +YJIT +PRISM [arm64-darwin25]
+ruby version:            ruby 4.0.0dev (2025-11-08T15:08:09Z master 75d25a42e6) +YJIT +PRISM [arm64-darwin25]
 concurrent-ruby version: 1.3.5
-atomic-ruby version:     0.8.1
+atomic-ruby version:     0.10.0
 
 Benchmark Results:
-Concurrent Ruby Thread Pool:    5.139026 seconds
-Atomic Ruby Atomic Thread Pool: 4.833597 seconds
+Concurrent Ruby Thread Pool:    5.56943 seconds
+Atomic Ruby Atomic Thread Pool: 5.252876 seconds
 ```
 
 </details>

data/ext/atomic_ruby/atomic_ruby.c

@@ -2,11 +2,17 @@
 
 typedef struct {
   volatile VALUE value;
+#ifdef ATOMIC_RUBY_RACTOR_SAFE
+  VALUE initialized_ractor;
+#endif
 } atomic_ruby_atom_t;
 
 static void atomic_ruby_atom_mark(void *ptr) {
   atomic_ruby_atom_t *atomic_ruby_atom = (atomic_ruby_atom_t *)ptr;
   rb_gc_mark_movable(atomic_ruby_atom->value);
+#ifdef ATOMIC_RUBY_RACTOR_SAFE
+  rb_gc_mark_movable(atomic_ruby_atom->initialized_ractor);
+#endif
 }
 
 static void atomic_ruby_atom_free(void *ptr) {
@@ -21,6 +27,9 @@ static size_t atomic_ruby_atom_memsize(const void *ptr) {
 static void atomic_ruby_atom_compact(void *ptr) {
   atomic_ruby_atom_t *atomic_ruby_atom = (atomic_ruby_atom_t *)ptr;
   atomic_ruby_atom->value = rb_gc_location(atomic_ruby_atom->value);
+#ifdef ATOMIC_RUBY_RACTOR_SAFE
+  atomic_ruby_atom->initialized_ractor = rb_gc_location(atomic_ruby_atom->initialized_ractor);
+#endif
 }
 
 static const rb_data_type_t atomic_ruby_atom_type = {
@@ -38,35 +47,54 @@ static const rb_data_type_t atomic_ruby_atom_type = {
 #endif
 };
 
+#ifdef ATOMIC_RUBY_RACTOR_SAFE
+static void ensure_value_shareable(VALUE self, atomic_ruby_atom_t *atom, VALUE value) {
+  bool check_shareable = NIL_P(atom->initialized_ractor);
+
+  if (!check_shareable) {
+    VALUE current_ractor = rb_funcall(rb_cRactor, rb_intern("current"), 0);
+    if (current_ractor != atom->initialized_ractor) {
+      check_shareable = true;
+      RB_OBJ_WRITE(self, &atom->initialized_ractor, Qnil);
+    }
+  }
+
+  if (check_shareable && !rb_ractor_shareable_p(value)) {
+    rb_raise(rb_eArgError, "value must be a shareable object when used across ractors");
+  }
+}
+#endif
+
 static VALUE rb_cAtom_allocate(VALUE klass) {
   atomic_ruby_atom_t *atomic_ruby_atom;
   VALUE obj = TypedData_Make_Struct(klass, atomic_ruby_atom_t, &atomic_ruby_atom_type, atomic_ruby_atom);
   RB_OBJ_WRITE(obj, &atomic_ruby_atom->value, Qnil);
-  return obj;
-}
-
 #ifdef ATOMIC_RUBY_RACTOR_SAFE
-static void check_value_shareable(VALUE value) {
-  if (!rb_ractor_shareable_p(value)) {
-    rb_raise(rb_eArgError, "value must be a shareable object");
-  }
-}
+  VALUE current_ractor = rb_funcall(rb_cRactor, rb_intern("current"), 0);
+  RB_OBJ_WRITE(obj, &atomic_ruby_atom->initialized_ractor, current_ractor);
 #endif
+  return obj;
+}
 
 static VALUE rb_cAtom_initialize(VALUE self, VALUE value) {
   atomic_ruby_atom_t *atomic_ruby_atom;
   TypedData_Get_Struct(self, atomic_ruby_atom_t, &atomic_ruby_atom_type, atomic_ruby_atom);
+  RB_OBJ_WRITE(self, &atomic_ruby_atom->value, value);
 #ifdef ATOMIC_RUBY_RACTOR_SAFE
-  check_value_shareable(value);
+  rb_obj_freeze(self);
+  FL_SET_RAW(self, RUBY_FL_SHAREABLE);
 #endif
-  RB_OBJ_WRITE(self, &atomic_ruby_atom->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);
+  VALUE value = (VALUE)RUBY_ATOMIC_PTR_LOAD(atomic_ruby_atom->value);
+#ifdef ATOMIC_RUBY_RACTOR_SAFE
+  ensure_value_shareable(self, atomic_ruby_atom, value);
+#endif
+  return value;
 }
 
 static VALUE rb_cAtom_swap(VALUE self) {
@@ -78,7 +106,7 @@ static VALUE rb_cAtom_swap(VALUE self) {
     expected_old_value = atomic_ruby_atom->value;
     new_value = rb_yield(expected_old_value);
 #ifdef ATOMIC_RUBY_RACTOR_SAFE
-    check_value_shareable(new_value);
+    ensure_value_shareable(self, atomic_ruby_atom, new_value);
 #endif
   } while (RUBY_ATOMIC_VALUE_CAS(atomic_ruby_atom->value, expected_old_value, new_value) != expected_old_value);
   RB_OBJ_WRITTEN(self, expected_old_value, new_value);
@@ -86,6 +114,14 @@ static VALUE rb_cAtom_swap(VALUE self) {
   return new_value;
 }
 
+#ifdef ATOMIC_RUBY_RACTOR_SAFE
+static VALUE rb_cAtom_initialized_ractor(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->initialized_ractor;
+}
+#endif
+
 RUBY_FUNC_EXPORTED void Init_atomic_ruby(void) {
 #ifdef ATOMIC_RUBY_RACTOR_SAFE
   rb_ext_ractor_safe(true);
@@ -95,11 +131,12 @@ RUBY_FUNC_EXPORTED void Init_atomic_ruby(void) {
   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, "_value", rb_cAtom_value, 0);
-  rb_define_method(rb_cAtom, "_swap", rb_cAtom_swap, 0);
+  rb_define_private_method(rb_cAtom, "_initialize", rb_cAtom_initialize, 1);
+  rb_define_private_method(rb_cAtom, "_value", rb_cAtom_value, 0);
+  rb_define_private_method(rb_cAtom, "_swap", rb_cAtom_swap, 0);
 
 #ifdef ATOMIC_RUBY_RACTOR_SAFE
+  rb_define_private_method(rb_cAtom, "_initialized_ractor", rb_cAtom_initialized_ractor, 0);
   rb_define_const(rb_mAtomicRuby, "RACTOR_SAFE", Qtrue);
 #else
   rb_define_const(rb_mAtomicRuby, "RACTOR_SAFE", Qfalse);

data/ext/atomic_ruby/atomic_ruby.h

@@ -3,11 +3,11 @@
 
 #include "ruby.h"
 #include "ruby/atomic.h"
-#include "ruby/ractor.h"
 #include "ruby/version.h"
 
-#if RUBY_API_VERSION_CODE >= 30500
+#if RUBY_API_VERSION_CODE >= 40000
 #define ATOMIC_RUBY_RACTOR_SAFE 1
+#include "ruby/ractor.h"
 #endif
 
 #endif /* ATOMIC_RUBY_ATOM_H */

data/ext/atomic_ruby/extconf.rb

@@ -2,9 +2,6 @@
 
 require "mkmf"
 
-# Makes all symbols private by default to avoid unintended conflict
-# with other gems. To explicitly export symbols you can use RUBY_FUNC_EXPORTED
-# selectively, or entirely remove this flag.
 append_cflags("-fvisibility=hidden")
 
 create_makefile("atomic_ruby/atomic_ruby")

data/lib/atomic-ruby/atom.rb

@@ -1,29 +1,114 @@
+# rbs_inline: enabled
 # frozen_string_literal: true
 
 require "atomic_ruby/atomic_ruby"
 
 module AtomicRuby
+  # Provides atomic reference semantics using Compare-And-Swap (CAS) operations.
+  #
+  # An Atom allows for lock-free, thread-safe updates to a single reference value.
+  # The core operation is {#swap}, which atomically updates the value based on
+  # the current value, retrying if another thread modifies it concurrently.
+  #
+  # @example Basic usage
+  #   atom = Atom.new(0)
+  #   atom.swap { |current_value| current_value + 1 }
+  #   puts atom.value #=> 1
+  #
+  # @example Thread-safe counter
+  #   counter = Atom.new(0)
+  #   threads = 10.times.map do
+  #     Thread.new { 100.times { counter.swap { |current_count| current_count + 1 } } }
+  #   end
+  #   threads.each(&:join)
+  #   puts counter.value #=> 1000
+  #
+  # @example Non-mutating array operations
+  #   atom = Atom.new([])
+  #   atom.swap { |current_array| current_array + [1] }
+  #   atom.swap { |current_array| current_array + [2] }
+  #   puts atom.value #=> [1, 2]
+  #
+  # @note This class is Ractor-safe in Ruby 4.0+ when compiled with ractor support.
+  #   Values that cross ractor boundaries are automatically made shareable.
   class Atom
+    # Creates a new atomic reference with the given initial value.
+    #
+    # @param value [untyped] The initial value to store atomically
+    #
+    # @example
+    #   atom = Atom.new(42)
+    #   atom = Atom.new([1, 2, 3])
+    #   atom = Atom.new({ key: "value" })
+    #
+    # @rbs (untyped value) -> void
     def initialize(value)
-      _initialize(make_shareable(value))
-
-      freeze if RACTOR_SAFE
+      _initialize(value)
     end
 
+    # Returns the current value stored in the atom.
+    #
+    # 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 [untyped] The current atomic value
+    #
+    # @example
+    #   atom = Atom.new("hello")
+    #   puts atom.value #=> "hello"
+    #
+    # @rbs () -> untyped
     def value
       _value
     end
 
+    # Atomically updates the value using a compare-and-swap operation.
+    #
+    # The block receives the current value and must return the new value.
+    # If another thread modifies the atom between reading the current value
+    # and attempting to update it, the operation retries with the new current value.
+    #
+    # @yieldparam current_value [untyped] The current atomic value
+    # @yieldreturn [untyped] The new value to store atomically
+    # @return [untyped] The new value that was successfully stored
+    #
+    # @example Increment a counter
+    #   atom = Atom.new(0)
+    #   new_value = atom.swap { |current_value| current_value + 1 }
+    #   puts new_value #=> 1
+    #
+    # @example Append to array (non-mutating)
+    #   atom = Atom.new([1, 2])
+    #   atom.swap { |current_array| current_array + [3] }
+    #   puts atom.value #=> [1, 2, 3]
+    #
+    # @example Conditional update
+    #   atom = Atom.new(10)
+    #   atom.swap { |current_value| current_value > 5 ? current_value * 2 : current_value }
+    #   puts atom.value #=> 20
+    #
+    # @rbs () { (untyped) -> untyped } -> untyped
     def swap(&block)
       _swap do |old_value|
-        make_shareable(block.call(old_value))
+        make_shareable_if_needed(block.call(old_value))
       end
     end
 
     private
 
-    def make_shareable(value)
-      if RACTOR_SAFE
+    # Makes a value shareable when crossing ractor boundaries.
+    #
+    # This method ensures ractor safety by automatically making values
+    # shareable when they need to cross ractor boundaries in Ruby 4.0+.
+    #
+    # @param value [untyped] The value to potentially make shareable
+    # @return [untyped] The original value or shareable version
+    #
+    # @rbs (untyped value) -> untyped
+    def make_shareable_if_needed(value)
+      if RACTOR_SAFE &&
+         (_initialized_ractor.nil? || Ractor.current != _initialized_ractor)
         Ractor.make_shareable(value)
       else
         value

data/lib/atomic-ruby/atomic_boolean.rb

@@ -1,9 +1,50 @@
+# rbs_inline: enabled
 # frozen_string_literal: true
 
 require_relative "atom"
 
 module AtomicRuby
+  # Provides atomic boolean semantics with thread-safe toggle operations.
+  #
+  # AtomicBoolean wraps a boolean value in an atomic reference, providing
+  # lock-free operations for common boolean manipulations like toggling,
+  # setting to true/false, and checking the current state.
+  #
+  # @example Basic usage
+  #   boolean = AtomicBoolean.new(false)
+  #   puts boolean.false? #=> true
+  #   boolean.toggle
+  #   puts boolean.true?  #=> true
+  #
+  # @example Thread-safe toggle
+  #   boolean = AtomicBoolean.new(false)
+  #   threads = 10.times.map do
+  #     Thread.new { 100.times { boolean.toggle } }
+  #   end
+  #   threads.each(&:join)
+  #   # Final state depends on whether total toggles is even or odd
+  #
+  # @example Atomic flag setting
+  #   flag = AtomicBoolean.new(false)
+  #   flag.make_true
+  #   puts flag.value #=> true
+  #
+  # @note This class is Ractor-safe in Ruby 4.0+ when compiled with ractor support.
   class AtomicBoolean
+    # Creates a new atomic boolean with the given initial value.
+    #
+    # @param boolean [true, false] The initial boolean value
+    # @raise [ArgumentError] if the value is not a boolean (TrueClass or FalseClass)
+    #
+    # @example
+    #   boolean = AtomicBoolean.new(true)
+    #   boolean = AtomicBoolean.new(false)
+    #
+    # @example Invalid usage
+    #   AtomicBoolean.new(nil)     #=> raises ArgumentError
+    #   AtomicBoolean.new("true")  #=> raises ArgumentError
+    #
+    # @rbs (bool boolean) -> void
     def initialize(boolean)
       unless boolean.is_a?(TrueClass) || boolean.is_a?(FalseClass)
         raise ArgumentError, "boolean must be a TrueClass or FalseClass"
@@ -14,26 +55,102 @@ module AtomicRuby
       Ractor.make_shareable(self) if RACTOR_SAFE
     end
 
+    # Returns the current boolean value stored in the atom.
+    #
+    # 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 [true, false] The current atomic boolean value
+    #
+    # @example
+    #   boolean = AtomicBoolean.new(true)
+    #   puts boolean.value #=> true
+    #
+    # @rbs () -> bool
     def value
       @boolean.value
     end
 
+    # Tests if the current value is true.
+    #
+    # @return [true, false] true if the atomic value is true, false otherwise
+    #
+    # @example
+    #   boolean = AtomicBoolean.new(true)
+    #   puts boolean.true?  #=> true
+    #   puts boolean.false? #=> false
+    #
+    # @rbs () -> bool
     def true?
       value == true
     end
 
+    # Tests if the current value is false.
+    #
+    # @return [true, false] true if the atomic value is false, false otherwise
+    #
+    # @example
+    #   boolean = AtomicBoolean.new(false)
+    #   puts boolean.false? #=> true
+    #   puts boolean.true?  #=> false
+    #
+    # @rbs () -> bool
     def false?
       value == false
     end
 
+    # Atomically sets the value to true.
+    #
+    # This operation uses compare-and-swap to ensure atomicity,
+    # making it safe for concurrent access.
+    #
+    # @return [true] Always returns true (the new value)
+    #
+    # @example
+    #   boolean = AtomicBoolean.new(false)
+    #   boolean.make_true
+    #   puts boolean.value #=> true
+    #
+    # @rbs () -> true
     def make_true
       @boolean.swap { true }
     end
 
+    # Atomically sets the value to false.
+    #
+    # This operation uses compare-and-swap to ensure atomicity,
+    # making it safe for concurrent access.
+    #
+    # @return [false] Always returns false (the new value)
+    #
+    # @example
+    #   boolean = AtomicBoolean.new(true)
+    #   boolean.make_false
+    #   puts boolean.value #=> false
+    #
+    # @rbs () -> false
     def make_false
       @boolean.swap { false }
     end
 
+    # Atomically toggles the boolean value.
+    #
+    # Changes true to false and false to true using a compare-and-swap
+    # operation, making it safe for concurrent access from multiple threads.
+    #
+    # @return [true, false] The new boolean value after toggling
+    #
+    # @example
+    #   boolean = AtomicBoolean.new(false)
+    #   boolean.toggle #=> true
+    #   boolean.toggle #=> false
+    #
+    # @example Thread-safe toggling
+    #   boolean = AtomicBoolean.new(false)
+    #   10.times.map { Thread.new { boolean.toggle } }.each(&:join)
+    #
+    # @rbs () -> bool
     def toggle
       @boolean.swap { |current_value| !current_value }
     end

data/lib/atomic-ruby/atomic_count_down_latch.rb

@@ -1,12 +1,69 @@
+# rbs_inline: enabled
 # frozen_string_literal: true
 
 require_relative "atom"
 
 module AtomicRuby
+  # Provides a countdown synchronization primitive using atomic operations.
+  #
+  # AtomicCountDownLatch is a synchronization aid that allows one or more threads
+  # to wait until a set of operations being performed in other threads completes.
+  # The latch is initialized with a count, and threads can wait for the count
+  # to reach zero or decrement the count atomically.
+  #
+  # @example Basic usage
+  #   latch = AtomicCountDownLatch.new(3)
+  #
+  #   # Start 3 worker threads
+  #   3.times do |worker_id|
+  #     Thread.new do
+  #       puts "Worker #{worker_id} starting"
+  #       sleep(rand(2))
+  #       puts "Worker #{worker_id} finished"
+  #       latch.count_down
+  #     end
+  #   end
+  #
+  #   latch.wait # Wait for all workers to complete
+  #   puts "All workers finished!"
+  #
+  # @example Waiting for initialization
+  #   latch = AtomicCountDownLatch.new(1)
+  #
+  #   # Start initialization in background
+  #   Thread.new do
+  #     puts "Initializing..."
+  #     sleep(2)
+  #     puts "Initialization complete"
+  #     latch.count_down
+  #   end
+  #
+  #   puts "Waiting for initialization..."
+  #   latch.wait
+  #   puts "Ready to proceed!"
+  #
+  # @note This class is Ractor-safe in Ruby 4.0+ when compiled with ractor support.
   class AtomicCountDownLatch
     class Error < StandardError; end
+
+    # Error raised when attempting to count down a latch that is already at zero.
     class AlreadyCountedDownError < Error; end
 
+    # Creates a new countdown latch with the specified count.
+    #
+    # @param count [Integer] The initial count value (must be positive)
+    #
+    # @raise [ArgumentError] if count is not a positive integer
+    #
+    # @example
+    #   latch = AtomicCountDownLatch.new(5)  # Wait for 5 events
+    #   latch = AtomicCountDownLatch.new(1)  # Simple binary latch
+    #
+    # @example Invalid usage
+    #   AtomicCountDownLatch.new(0)   #=> raises ArgumentError
+    #   AtomicCountDownLatch.new(-1)  #=> raises ArgumentError
+    #
+    # @rbs (Integer count) -> void
     def initialize(count)
       unless count.is_a?(Integer) && count > 0
         raise ArgumentError, "count must be a positive Integer"
@@ -17,10 +74,48 @@ module AtomicRuby
       Ractor.make_shareable(self) if RACTOR_SAFE
     end
 
+    # Returns the current count value.
+    #
+    # 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 current count (0 or positive)
+    #
+    # @example
+    #   latch = AtomicCountDownLatch.new(3)
+    #   puts latch.count #=> 3
+    #   latch.count_down
+    #   puts latch.count #=> 2
+    #
+    # @rbs () -> Integer
     def count
       @count.value
     end
 
+    # Atomically decrements the count by one.
+    #
+    # If the count reaches zero, any threads waiting on {#wait} will be unblocked.
+    # This operation uses compare-and-swap to ensure atomicity and prevent
+    # race conditions.
+    #
+    # @return [Integer] The new count value after decrementing
+    #
+    # @raise [AlreadyCountedDownError] if the count is already zero
+    #
+    # @example
+    #   latch = AtomicCountDownLatch.new(2)
+    #   latch.count_down #=> 1
+    #   latch.count_down #=> 0
+    #   latch.count_down #=> raises AlreadyCountedDownError
+    #
+    # @example Thread-safe countdown
+    #   latch = AtomicCountDownLatch.new(10)
+    #   10.times do
+    #     Thread.new { latch.count_down }
+    #   end
+    #
+    # @rbs () -> Integer
     def count_down
       already_counted_down = false
       new_count = @count.swap do |current_count|
@@ -36,6 +131,40 @@ module AtomicRuby
       new_count
     end
 
+    # Blocks the current thread until the count reaches zero.
+    #
+    # This method will block the calling thread until other threads have
+    # called {#count_down} enough times to reduce the count to zero.
+    # The method uses busy-waiting (Thread.pass) to check the count.
+    #
+    # @return [void]
+    #
+    # @example Simple wait
+    #   latch = AtomicCountDownLatch.new(1)
+    #
+    #   Thread.new do
+    #     sleep(2)
+    #     latch.count_down
+    #   end
+    #
+    #   latch.wait # Blocks for ~2 seconds
+    #   puts "Latch opened!"
+    #
+    # @example Waiting for multiple events
+    #   latch = AtomicCountDownLatch.new(3)
+    #
+    #   3.times do |event_id|
+    #     Thread.new do
+    #       sleep(1 + event_id)
+    #       puts "Event #{event_id} completed"
+    #       latch.count_down
+    #     end
+    #   end
+    #
+    #   latch.wait # Waits for all 3 events
+    #   puts "All events completed!"
+    #
+    # @rbs () -> void
     def wait
       Thread.pass while @count.value > 0
     end

data/lib/atomic-ruby/atomic_thread_pool.rb

@@ -1,15 +1,68 @@
+# rbs_inline: enabled
 # frozen_string_literal: true
 
 require_relative "atom"
 
 module AtomicRuby
+  # Provides a fixed-size thread pool using atomic operations for work queuing.
+  #
+  # AtomicThreadPool maintains a fixed number of worker threads that process
+  # work items from an atomic queue. The pool uses compare-and-swap operations
+  # for thread-safe work enqueueing and state management.
+  #
+  # @example Basic usage
+  #   pool = AtomicThreadPool.new(size: 4)
+  #   pool << proc { puts "Hello from worker thread!" }
+  #   pool << proc { puts "Another work item" }
+  #   pool.shutdown
+  #
+  # @example Processing work with results
+  #   results = []
+  #   pool = AtomicThreadPool.new(size: 2, name: "Calculator")
+  #
+  #   10.times do |index|
+  #     pool << proc { results << index * 2 }
+  #   end
+  #
+  #   pool.shutdown
+  #   puts results.sort #=> [0, 2, 4, 6, 8, 10, 12, 14, 16, 18]
+  #
+  # @example Monitoring pool state
+  #   pool = AtomicThreadPool.new(size: 3)
+  #   puts pool.length        #=> 3
+  #   puts pool.queue_length  #=> 0
+  #   puts pool.active_count  #=> 0
+  #
+  #   5.times { pool << proc { sleep(1) } }
+  #   puts pool.queue_length  #=> 2 (3 workers busy, 2 queued)
+  #   puts pool.active_count  #=> 3 (3 workers processing)
+  #
+  # @note This class is NOT Ractor-safe as it contains mutable thread state
+  #   that cannot be safely shared across ractors.
   class AtomicThreadPool
     class Error < StandardError; end
 
+    # Error raised when attempting to enqueue work after shutdown.
     class EnqueuedWorkAfterShutdownError < Error
+      # @rbs () -> String
       def message = "cannot queue work after shutdown"
     end
 
+    # Creates a new thread pool with the specified size.
+    #
+    # @param size [Integer] The number of worker threads to create (must be positive)
+    # @param name [String, nil] Optional name for the thread pool (used in thread names)
+    #
+    # @raise [ArgumentError] if size is not a positive integer
+    # @raise [ArgumentError] if name is provided but not a string
+    #
+    # @example Create a basic pool
+    #   pool = AtomicThreadPool.new(size: 4)
+    #
+    # @example Create a named pool
+    #   pool = AtomicThreadPool.new(size: 2, name: "Database Workers")
+    #
+    # @rbs (size: Integer, ?name: String?) -> void
     def initialize(size:, name: nil)
       raise ArgumentError, "size must be a positive Integer" unless size.is_a?(Integer) && size > 0
       raise ArgumentError, "name must be a String" unless name.nil? || name.is_a?(String)
@@ -17,30 +70,139 @@ module AtomicRuby
       @size = size
       @name = name
 
-      @queue = Queue.new
-      @state = Atom.new(shutdown: false)
-      @started_threads = Atom.new(0)
+      @state = Atom.new(queue: [], shutdown: false)
+      @started_thread_count = Atom.new(0)
+      @active_thread_count = Atom.new(0)
       @threads = []
 
       start
     end
 
+    # Enqueues work to be executed by the thread pool.
+    #
+    # The work item must respond to #call (typically a Proc or lambda).
+    # Work items are executed in FIFO order by available worker threads.
+    # If all workers are busy, the work is queued atomically.
+    #
+    # @param work [#call] A callable object to be executed by a worker thread
+    #
+    # @raise [EnqueuedWorkAfterShutdownError] if the pool has been shut down
+    #
+    # @example Enqueue a simple task
+    #   pool << proc { puts "Hello World" }
+    #
+    # @example Enqueue a lambda with parameters
+    #   calculator = ->(a, b) { puts a + b }
+    #   pool << proc { calculator.call(2, 3) }
+    #
+    # @example Enqueue work that captures variables
+    #   name = "Alice"
+    #   pool << proc { puts "Processing #{name}" }
+    #
+    # @rbs (Proc work) -> void
     def <<(work)
       state = @state.swap do |current_state|
-        @queue.push(work) unless current_state[:shutdown]
-        current_state
+        if current_state[:shutdown]
+          current_state
+        else
+          current_state.merge(queue: [*current_state[:queue], work])
+        end
       end
       raise EnqueuedWorkAfterShutdownError if state[:shutdown]
     end
 
+    # Returns the number of currently alive worker threads.
+    #
+    # This count decreases as the pool shuts down and threads terminate.
+    # During normal operation, this should equal the size parameter
+    # passed to the constructor.
+    #
+    # @return [Integer] The number of alive worker threads
+    #
+    # @example
+    #   pool = AtomicThreadPool.new(size: 4)
+    #   puts pool.length #=> 4
+    #   pool.shutdown
+    #   puts pool.length #=> 0
+    #
+    # @rbs () -> Integer
     def length
       @threads.select(&:alive?).length
     end
+    # Alias for {#length}.
+    # @rbs () -> Integer
+    alias size length
 
+    # Returns the number of work items currently queued for execution.
+    #
+    # This represents work that has been enqueued but not yet picked up
+    # by a worker thread. A high queue length indicates that work is
+    # being submitted faster than it can be processed.
+    #
+    # @return [Integer] The number of queued work items
+    #
+    # @example
+    #   pool = AtomicThreadPool.new(size: 2)
+    #   5.times { pool << proc { sleep(1) } }
+    #   puts pool.queue_length #=> 3 (2 workers busy, 3 queued)
+    #
+    # @rbs () -> Integer
     def queue_length
-      @queue.size
+      @state.value[:queue].length
+    end
+    # Alias for {#queue_length}.
+    # @rbs () -> Integer
+    alias queue_size queue_length
+
+    # Returns the number of worker threads currently executing work.
+    #
+    # This represents threads that have picked up a work item and are
+    # actively processing it. The count includes threads in the middle
+    # of executing work.call, but excludes threads that are idle or
+    # waiting for work.
+    #
+    # @return [Integer] The number of threads actively processing work
+    #
+    # @example Monitor active workers
+    #   pool = AtomicThreadPool.new(size: 4)
+    #   puts pool.active_count #=> 0
+    #
+    #   5.times { pool << proc { sleep(1) } }
+    #   sleep(0.1) # Give threads time to pick up work
+    #   puts pool.active_count #=> 4 (all workers busy)
+    #   puts pool.queue_length #=> 1 (one item still queued)
+    #
+    # @example Calculate total load
+    #   total_load = pool.active_count + pool.queue_length
+    #   puts "Total pending work: #{total_load}"
+    #
+    # @rbs () -> Integer
+    def active_count
+      @active_thread_count.value
     end
 
+    # Gracefully shuts down the thread pool.
+    #
+    # This method:
+    # 1. Marks the pool as shutdown (preventing new work from being enqueued)
+    # 2. Waits for all currently queued work to complete
+    # 3. Waits for all worker threads to terminate
+    #
+    # After shutdown, all worker threads will be terminated and the pool
+    # cannot be restarted. Attempting to enqueue work after shutdown
+    # will raise an exception.
+    #
+    # @return [void]
+    #
+    # @raise [EnqueuedWorkAfterShutdownError] if work is enqueued after shutdown
+    #
+    # @example
+    #   pool = AtomicThreadPool.new(size: 4)
+    #   10.times { |index| pool << proc { puts index } }
+    #   pool.shutdown # waits for all work to complete
+    #   puts pool.length #=> 0
+    #
+    # @rbs () -> void
     def shutdown
       already_shutdown = false
       @state.swap do |current_state|
@@ -53,13 +215,21 @@ module AtomicRuby
       end
       return if already_shutdown
 
-      Thread.pass until @queue.empty?
+      Thread.pass until @state.value[:queue].empty?
 
       @threads.each(&:join)
     end
 
     private
 
+    # Starts the worker threads for the thread pool.
+    #
+    # This method is called automatically during initialization.
+    # It creates the specified number of worker threads and waits
+    # for all threads to be fully started before returning.
+    #
+    # @return [void]
+    # @rbs () -> void
     def start
       @size.times do |num|
         @threads << Thread.new(num) do |idx|
@@ -67,30 +237,36 @@ module AtomicRuby
           thread_name << " for #{@name}" if @name
           Thread.current.name = thread_name
 
-          @started_threads.swap { |current_count| current_count + 1 }
+          @started_thread_count.swap { |current_count| current_count + 1 }
 
           loop do
             work = nil
             should_shutdown = false
 
             @state.swap do |current_state|
-              if current_state[:shutdown] && @queue.empty?
+              if current_state[:shutdown] && current_state[:queue].empty?
                 should_shutdown = true
+                current_state
+              elsif current_state[:queue].empty?
+                current_state
               else
-                work = @queue.pop(timeout: 0)
+                work = current_state[:queue].first
+                current_state.merge(queue: current_state[:queue].drop(1))
               end
-              current_state
             end
 
             if should_shutdown
               break
             elsif work
+              @active_thread_count.swap { |current_count| current_count + 1 }
               begin
                 work.call
               rescue => err
                 puts "#{thread_name} rescued:"
                 puts "#{err.class}: #{err.message}"
                 puts err.backtrace.join("\n")
+              ensure
+                @active_thread_count.swap { |current_count| current_count - 1 }
               end
             else
               Thread.pass
@@ -100,7 +276,7 @@ module AtomicRuby
       end
       @threads.freeze
 
-      Thread.pass until @started_threads.value == @size
+      Thread.pass until @started_thread_count.value == @size
     end
   end
 end

data/lib/atomic-ruby/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: atomic-ruby
 version: !ruby/object:Gem::Version
-  version: 0.8.1
+  version: 0.10.0
 platform: ruby
 authors:
 - Joshua Young