atomic-ruby 0.9.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6bef30ee19f89bf213e837f5ee565b4e0b2f926c422dd7204270f349a331142c
-  data.tar.gz: b19ac4ac6c8f363c891aae5c7ef4b4c39c80b420673f71890fe8c4f1974dee89
+  metadata.gz: b52931f98d46947d0d2f4dccffbe51e771c619d61b54457a223162be41624353
+  data.tar.gz: 3c91a27d99c3eb4d2a04f668bc5ebbc19c1c60b6a9fc688812df96c20bed37a4
 SHA512:
-  metadata.gz: 8afd84e8e6cc724949c88c6485bd51e8d3ba86e56852ad742136613ce2f4a36468de88b7c011a2061218ff7edb189a8e8a13f3049741d5a020862c8cc9760e7d
-  data.tar.gz: d5727d75e5b3c6f4cce6c7dd394b1fd7d64d48f3940124a27f2725e1947c6aac375604fb98364a24aa6bbcb50670680b3b755c566f5092829b21eff7bef98d10
+  metadata.gz: b3f6d04175439390f6b9f29d91bf3cfad5b95018f7363e3cb341c7512857008e285d3a462363108cb54e613ed898153e157d7c41b1e113d92c38053a52e5d5be
+  data.tar.gz: aadb6f2b22fa068d8599b1e0aea30bc6e52d4b97198c4e4078e465d172f168b8548c9ab2f4bd174298aa2f5d02cd421c868a896c4b0d53689706edeb2414ff35

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 ## [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
@@ -12,7 +19,7 @@
 
 ## [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,7 +98,7 @@ p latch.count #=> 0
 ```
 
 > [!NOTE]
-> `Atom`, `AtomicBoolean`, and `AtomicCountDownLatch` are Ractor-safe in Ruby 3.5+.
+> `Atom`, `AtomicBoolean`, and `AtomicCountDownLatch` are Ractor-safe in Ruby 4.0+.
 
 ## Benchmarks
 
@@ -210,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-11-05T10:35:48Z master 946d2d036f) +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.9.0
+atomic-ruby version:     0.10.0
 
 Balances:
 Synchronized Bank Account Balance:           975
@@ -220,9 +220,9 @@ Concurrent Ruby Atomic Bank Account Balance: 975
 Atomic Ruby Atomic Bank Account Balance:     975
 
 Benchmark Results:
-Synchronized Bank Account:           5.104234 seconds
-Concurrent Ruby Atomic Bank Account: 5.113334 seconds
-Atomic Ruby Atomic Bank Account:     5.097197 seconds
+Synchronized Bank Account:           5.112382 seconds
+Concurrent Ruby Atomic Bank Account: 5.113139 seconds
+Atomic Ruby Atomic Bank Account:     5.101891 seconds
 ```
 
 </details>
@@ -301,29 +301,29 @@ end
 ```
 > bundle exec rake compile && bundle exec ruby examples/atomic_boolean_benchmark.rb
 
-ruby version:            ruby 3.5.0dev (2025-11-05T10:35:48Z master 946d2d036f) +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.9.0
+atomic-ruby version:     0.10.0
 
 Warming up --------------------------------------
 Synchronized Boolean Toggle
-                       158.000 i/100ms
+                       120.000 i/100ms
 Concurrent Ruby Atomic Boolean Toggle
-                       113.000 i/100ms
+                        94.000 i/100ms
 Atomic Ruby Atomic Boolean Toggle
-                       122.000 i/100ms
+                       100.000 i/100ms
 Calculating -------------------------------------
 Synchronized Boolean Toggle
-                          1.521k (± 2.1%) i/s  (657.49 μs/i) -      7.742k in   5.092579s
+                          1.188k (± 8.9%) i/s  (841.70 μs/i) -      5.880k in   5.002927s
 Concurrent Ruby Atomic Boolean Toggle
-                          1.141k (± 1.6%) i/s  (876.12 μs/i) -      5.763k in   5.050298s
+                        889.224 (±11.8%) i/s    (1.12 ms/i) -      4.418k in   5.073535s
 Atomic Ruby Atomic Boolean Toggle
-                          1.243k (± 1.3%) i/s  (804.64 μs/i) -      6.222k in   5.007246s
+                        999.426 (± 4.3%) i/s    (1.00 ms/i) -      5.000k in   5.012997s
 
 Comparison:
-Synchronized Boolean Toggle:               1520.9 i/s
-Atomic Ruby Atomic Boolean Toggle:         1242.8 i/s - 1.22x  slower
-Concurrent Ruby Atomic Boolean Toggle:     1141.4 i/s - 1.33x  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>
@@ -379,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-11-05T10:35:48Z master 946d2d036f) +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.9.0
+atomic-ruby version:     0.10.0
 
 Benchmark Results:
-Concurrent Ruby Thread Pool:    5.169928 seconds
-Atomic Ruby Atomic Thread Pool: 4.831942 seconds
+Concurrent Ruby Thread Pool:    5.56943 seconds
+Atomic Ruby Atomic Thread Pool: 5.252876 seconds
 ```
 
 </details>

data/ext/atomic_ruby/atomic_ruby.c

@@ -131,12 +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_method(rb_cAtom, "_initialized_ractor", rb_cAtom_initialized_ractor, 0);
+  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

@@ -5,7 +5,7 @@
 #include "ruby/atomic.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

data/lib/atomic-ruby/atom.rb

@@ -1,17 +1,94 @@
+# 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(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_if_needed(block.call(old_value))
@@ -20,6 +97,15 @@ module AtomicRuby
 
     private
 
+    # 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)

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)
@@ -18,12 +71,35 @@ module AtomicRuby
       @name = name
 
       @state = Atom.new(queue: [], shutdown: false)
-      @started_threads = Atom.new(0)
+      @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|
         if current_state[:shutdown]
@@ -35,16 +111,98 @@ module AtomicRuby
       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
       @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|
@@ -64,6 +222,14 @@ module AtomicRuby
 
     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|
@@ -71,7 +237,7 @@ 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
@@ -92,12 +258,15 @@ module AtomicRuby
             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
@@ -107,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.9.0"
+  VERSION = "0.10.0"
 end

metadata

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