Class: AtomicRuby::AtomicBoolean

Inherits:
Object
  • Object
show all
Defined in:
lib/atomic-ruby/atomic_boolean.rb

Overview

Note:

This class is Ractor-safe in Ruby 4.0+ when compiled with ractor support.

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.

Examples:

Basic usage

boolean = AtomicBoolean.new(false)
puts boolean.false? #=> true
boolean.toggle
puts boolean.true?  #=> true

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

Atomic flag setting

flag = AtomicBoolean.new(false)
flag.make_true
puts flag.value #=> true

Instance Method Summary collapse

Constructor Details

#initialize(boolean) ⇒ AtomicBoolean

Creates a new atomic boolean with the given initial value.

Examples:

boolean = AtomicBoolean.new(true)
boolean = AtomicBoolean.new(false)

Invalid usage

AtomicBoolean.new(nil)     #=> raises ArgumentError
AtomicBoolean.new("true")  #=> raises ArgumentError

Parameters:

  • boolean (true, false) —

    The initial boolean value

Raises:

  • (ArgumentError) —

    if the value is not a boolean (TrueClass or FalseClass)



48
49
50
51
52
53
54
55
56
 
# File 'lib/atomic-ruby/atomic_boolean.rb', line 48

def initialize(boolean)
  unless boolean.is_a?(TrueClass) || boolean.is_a?(FalseClass)
    raise ArgumentError, "boolean must be a TrueClass or FalseClass"
  end

  @boolean = Atom.new(boolean)

  Ractor.make_shareable(self) if RACTOR_SAFE
end

Instance Method Details

#false? ⇒ true, false

Tests if the current value is false.

Examples:

boolean = AtomicBoolean.new(false)
puts boolean.false? #=> true
puts boolean.true?  #=> false

Returns:

  • (true, false) —

    true if the atomic value is false, false otherwise



99
100
101
 
# File 'lib/atomic-ruby/atomic_boolean.rb', line 99

def false?
  value == false
end

#make_false ⇒ false

Atomically sets the value to false.

This operation uses compare-and-swap to ensure atomicity, making it safe for concurrent access.

Examples:

boolean = AtomicBoolean.new(true)
boolean.make_false
puts boolean.value #=> false

Returns:

  • (false) —

    Always returns false (the new value)



133
134
135
 
# File 'lib/atomic-ruby/atomic_boolean.rb', line 133

def make_false
  @boolean.swap { false }
end

#make_true ⇒ true

Atomically sets the value to true.

This operation uses compare-and-swap to ensure atomicity, making it safe for concurrent access.

Examples:

boolean = AtomicBoolean.new(false)
boolean.make_true
puts boolean.value #=> true

Returns:

  • (true) —

    Always returns true (the new value)



116
117
118
 
# File 'lib/atomic-ruby/atomic_boolean.rb', line 116

def make_true
  @boolean.swap { true }
end

#toggle ⇒ true, false

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.

Examples:

boolean = AtomicBoolean.new(false)
boolean.toggle #=> true
boolean.toggle #=> false

Thread-safe toggling

boolean = AtomicBoolean.new(false)
10.times.map { Thread.new { boolean.toggle } }.each(&:join)

Returns:

  • (true, false) —

    The new boolean value after toggling



154
155
156
 
# File 'lib/atomic-ruby/atomic_boolean.rb', line 154

def toggle
  @boolean.swap { |current_value| !current_value }
end

#true? ⇒ true, false

Tests if the current value is true.

Examples:

boolean = AtomicBoolean.new(true)
puts boolean.true?  #=> true
puts boolean.false? #=> false

Returns:

  • (true, false) —

    true if the atomic value is true, false otherwise



85
86
87
 
# File 'lib/atomic-ruby/atomic_boolean.rb', line 85

def true?
  value == true
end

#value ⇒ true, false

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.

Examples:

boolean = AtomicBoolean.new(true)
puts boolean.value #=> true

Returns:

  • (true, false) —

    The current atomic boolean value



71
72
73
 
# File 'lib/atomic-ruby/atomic_boolean.rb', line 71

def value
  @boolean.value
end