Module: Farce::Abstract::Flag Abstract

Includes:
Value, Internal::Copyable, Internal::ValueSerialization, Internal::Inspect, Internal::MarshalSupport::Flag
Included in:
Flag, Local::Flag
Defined in:
lib/farce/abstract/flag.rb

Overview

This module is abstract.

Common boolean interface and serialization for atomic flags.

Note:

This is a module rather than a class so Flag can inherit directly from the native flag and avoid delegation overhead.

Instance Method Summary collapse

Methods included from Internal::ValueSerialization

#as_extended_json, #as_json, #to_bson, #to_bson_normalized_value, #to_cbor, #to_json, #to_msgpack

Methods included from Value

#blank?, #unwrap

Methods included from Internal::Copyable

#duplicable?

Instance Method Details

#compare_and_set(expected_value, replacement_value) ⇒ Boolean

Replace the value only if it matches the expected value.

Parameters:

  • expected_value (Boolean) —

    the expected current value

  • replacement_value (Boolean) —

    the new value

Returns:

  • (Boolean) —

    whether the replacement succeeded

Raises:

  • (ArgumentError) —

    if either argument is not true or false



55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
 
# File 'lib/farce/abstract/flag.rb', line 55

module Flag
  include Internal::MarshalSupport::Flag
  include Internal::Copyable
  include Value
  include Internal::ValueSerialization
  include Internal::Inspect

  # @return [Boolean] whether the flag is set
  def set? = value
  alias true? set?

  # @return [Boolean] whether the flag is unset
  def unset? = !value
  alias false? unset?

  # Explicitly sets the value to true.
  # Provided for compatibility with `Concurrent::AtomicBoolean`.
  # @return [Boolean] true if the value has changed
  def make_true = compare_and_set(false, true)

  # Explicitly sets the value to false.
  # Provided for compatibility with `Concurrent::AtomicBoolean`.
  # @return [Boolean] true if the value has changed
  def make_false = compare_and_set(true, false)

  # Wait until the flag becomes true.
  # @param timeout [Numeric, nil] the total seconds available
  # @yield called when the timeout expires
  # @return [Boolean, BasicObject, nil] the changed value or timeout fallback
  def wait_until_set(timeout: nil, &) = wait_until_changed(false, timeout:, &)
  alias wait_until_true  wait_until_set
  alias wait_while_unset wait_until_set
  alias wait_while_false wait_until_set

  # Wait until the flag becomes false.
  # @param timeout [Numeric, nil] the total seconds available
  # @yield called when the timeout expires
  # @return [Boolean, BasicObject, nil] the changed value or timeout fallback
  def wait_until_unset(timeout: nil, &) = wait_until_changed(true, timeout:, &)
  alias wait_until_false wait_until_unset
  alias wait_while_set   wait_until_unset
  alias wait_while_true  wait_until_unset

  # Wait until a block condition matches the current value.
  # One timeout budget covers all checks and waits. The block is not interrupted.
  # @yieldparam value [Boolean] the current value
  # @yieldreturn [Boolean] whether the value matches
  # @param timeout [Numeric, nil] the total seconds available
  # @return [Boolean, nil] the matching value, or nil on timeout
  # @raise [LocalJumpError] if no block is given
  def wait_until(timeout: nil, &) = Internal.wait_until(self, timeout:, &)

  # Wait while the block returns a truthy value.
  # @yieldparam value [Boolean] the current value
  # @yieldreturn [BasicObject] a truthy value to keep waiting, or nil or false to stop
  # @param timeout [Numeric, nil] the total seconds available
  # @return [Boolean, nil] the value when the condition becomes false, or nil on timeout
  # @raise [LocalJumpError] if no block is given
  def wait_while(timeout: nil)
    raise LocalJumpError, "no block given" unless block_given?
    wait_until(timeout:) { |value| !yield(value) }
  end

  # Wait while `object === value` is true.
  # @param object [#===] the pattern to stop matching
  # @param timeout [Numeric, nil] the total seconds available
  # @return [Boolean, nil] the first nonmatching value, or nil on timeout
  def wait_while_match(object, timeout: nil)
    wait_while(timeout:) { |value| object === value } # rubocop:disable Style/CaseEquality
  end

  # (see #wait_until_changed)
  def wait_while_value(...) = wait_until_changed(...)

  # Wait until `object == value` is true.
  # @param object [BasicObject] the value to compare with the current value
  # @param timeout [Numeric, nil] the total seconds available
  # @return [Boolean, nil] the matching value, or nil on timeout
  def wait_until_value(object, timeout: nil)
    wait_until(timeout:) { |value| object == value }
  end

  # Wait until `object === value` is true.
  # @param object [#===] the pattern to match
  # @param timeout [Numeric, nil] the total seconds available
  # @return [Boolean, nil] the matching value, or nil on timeout
  def wait_until_match(object, timeout: nil)
    wait_until(timeout:) { |value| object === value } # rubocop:disable Style/CaseEquality
  end

  # @api private
  def inspect_with(inspector)
    begin
      current = value
    rescue StandardError
      # FrozenError may inspect an allocated flag before it is initialized.
      return inspector.object_with_address(self)
    end

    super do
      yield if block_given?
      inspector.breakable
      inspector.object(current)
    end
  end
end

#make_false ⇒ Boolean

Explicitly sets the value to false. Provided for compatibility with Concurrent::AtomicBoolean.

Returns:

  • (Boolean) —

    true if the value has changed



78
 
# File 'lib/farce/abstract/flag.rb', line 78

def make_false = compare_and_set(true, false)

#make_true ⇒ Boolean

Explicitly sets the value to true. Provided for compatibility with Concurrent::AtomicBoolean.

Returns:

  • (Boolean) —

    true if the value has changed



73
 
# File 'lib/farce/abstract/flag.rb', line 73

def make_true = compare_and_set(false, true)

#set ⇒ true

Set the flag to true.

Returns:

  • (true) 


55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
 
# File 'lib/farce/abstract/flag.rb', line 55

module Flag
  include Internal::MarshalSupport::Flag
  include Internal::Copyable
  include Value
  include Internal::ValueSerialization
  include Internal::Inspect

  # @return [Boolean] whether the flag is set
  def set? = value
  alias true? set?

  # @return [Boolean] whether the flag is unset
  def unset? = !value
  alias false? unset?

  # Explicitly sets the value to true.
  # Provided for compatibility with `Concurrent::AtomicBoolean`.
  # @return [Boolean] true if the value has changed
  def make_true = compare_and_set(false, true)

  # Explicitly sets the value to false.
  # Provided for compatibility with `Concurrent::AtomicBoolean`.
  # @return [Boolean] true if the value has changed
  def make_false = compare_and_set(true, false)

  # Wait until the flag becomes true.
  # @param timeout [Numeric, nil] the total seconds available
  # @yield called when the timeout expires
  # @return [Boolean, BasicObject, nil] the changed value or timeout fallback
  def wait_until_set(timeout: nil, &) = wait_until_changed(false, timeout:, &)
  alias wait_until_true  wait_until_set
  alias wait_while_unset wait_until_set
  alias wait_while_false wait_until_set

  # Wait until the flag becomes false.
  # @param timeout [Numeric, nil] the total seconds available
  # @yield called when the timeout expires
  # @return [Boolean, BasicObject, nil] the changed value or timeout fallback
  def wait_until_unset(timeout: nil, &) = wait_until_changed(true, timeout:, &)
  alias wait_until_false wait_until_unset
  alias wait_while_set   wait_until_unset
  alias wait_while_true  wait_until_unset

  # Wait until a block condition matches the current value.
  # One timeout budget covers all checks and waits. The block is not interrupted.
  # @yieldparam value [Boolean] the current value
  # @yieldreturn [Boolean] whether the value matches
  # @param timeout [Numeric, nil] the total seconds available
  # @return [Boolean, nil] the matching value, or nil on timeout
  # @raise [LocalJumpError] if no block is given
  def wait_until(timeout: nil, &) = Internal.wait_until(self, timeout:, &)

  # Wait while the block returns a truthy value.
  # @yieldparam value [Boolean] the current value
  # @yieldreturn [BasicObject] a truthy value to keep waiting, or nil or false to stop
  # @param timeout [Numeric, nil] the total seconds available
  # @return [Boolean, nil] the value when the condition becomes false, or nil on timeout
  # @raise [LocalJumpError] if no block is given
  def wait_while(timeout: nil)
    raise LocalJumpError, "no block given" unless block_given?
    wait_until(timeout:) { |value| !yield(value) }
  end

  # Wait while `object === value` is true.
  # @param object [#===] the pattern to stop matching
  # @param timeout [Numeric, nil] the total seconds available
  # @return [Boolean, nil] the first nonmatching value, or nil on timeout
  def wait_while_match(object, timeout: nil)
    wait_while(timeout:) { |value| object === value } # rubocop:disable Style/CaseEquality
  end

  # (see #wait_until_changed)
  def wait_while_value(...) = wait_until_changed(...)

  # Wait until `object == value` is true.
  # @param object [BasicObject] the value to compare with the current value
  # @param timeout [Numeric, nil] the total seconds available
  # @return [Boolean, nil] the matching value, or nil on timeout
  def wait_until_value(object, timeout: nil)
    wait_until(timeout:) { |value| object == value }
  end

  # Wait until `object === value` is true.
  # @param object [#===] the pattern to match
  # @param timeout [Numeric, nil] the total seconds available
  # @return [Boolean, nil] the matching value, or nil on timeout
  def wait_until_match(object, timeout: nil)
    wait_until(timeout:) { |value| object === value } # rubocop:disable Style/CaseEquality
  end

  # @api private
  def inspect_with(inspector)
    begin
      current = value
    rescue StandardError
      # FrozenError may inspect an allocated flag before it is initialized.
      return inspector.object_with_address(self)
    end

    super do
      yield if block_given?
      inspector.breakable
      inspector.object(current)
    end
  end
end

#set? ⇒ Boolean Also known as: true?

Returns whether the flag is set.

Returns:

  • (Boolean) —

    whether the flag is set



63
 
# File 'lib/farce/abstract/flag.rb', line 63

def set? = value

#store(value) ⇒ Boolean

Set the flag to the given value.

Parameters:

  • value (Boolean) —

    the new value

Returns:

  • (Boolean) —

    the new value

Raises:

  • (ArgumentError) —

    if the value is not true or false



55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
 
# File 'lib/farce/abstract/flag.rb', line 55

module Flag
  include Internal::MarshalSupport::Flag
  include Internal::Copyable
  include Value
  include Internal::ValueSerialization
  include Internal::Inspect

  # @return [Boolean] whether the flag is set
  def set? = value
  alias true? set?

  # @return [Boolean] whether the flag is unset
  def unset? = !value
  alias false? unset?

  # Explicitly sets the value to true.
  # Provided for compatibility with `Concurrent::AtomicBoolean`.
  # @return [Boolean] true if the value has changed
  def make_true = compare_and_set(false, true)

  # Explicitly sets the value to false.
  # Provided for compatibility with `Concurrent::AtomicBoolean`.
  # @return [Boolean] true if the value has changed
  def make_false = compare_and_set(true, false)

  # Wait until the flag becomes true.
  # @param timeout [Numeric, nil] the total seconds available
  # @yield called when the timeout expires
  # @return [Boolean, BasicObject, nil] the changed value or timeout fallback
  def wait_until_set(timeout: nil, &) = wait_until_changed(false, timeout:, &)
  alias wait_until_true  wait_until_set
  alias wait_while_unset wait_until_set
  alias wait_while_false wait_until_set

  # Wait until the flag becomes false.
  # @param timeout [Numeric, nil] the total seconds available
  # @yield called when the timeout expires
  # @return [Boolean, BasicObject, nil] the changed value or timeout fallback
  def wait_until_unset(timeout: nil, &) = wait_until_changed(true, timeout:, &)
  alias wait_until_false wait_until_unset
  alias wait_while_set   wait_until_unset
  alias wait_while_true  wait_until_unset

  # Wait until a block condition matches the current value.
  # One timeout budget covers all checks and waits. The block is not interrupted.
  # @yieldparam value [Boolean] the current value
  # @yieldreturn [Boolean] whether the value matches
  # @param timeout [Numeric, nil] the total seconds available
  # @return [Boolean, nil] the matching value, or nil on timeout
  # @raise [LocalJumpError] if no block is given
  def wait_until(timeout: nil, &) = Internal.wait_until(self, timeout:, &)

  # Wait while the block returns a truthy value.
  # @yieldparam value [Boolean] the current value
  # @yieldreturn [BasicObject] a truthy value to keep waiting, or nil or false to stop
  # @param timeout [Numeric, nil] the total seconds available
  # @return [Boolean, nil] the value when the condition becomes false, or nil on timeout
  # @raise [LocalJumpError] if no block is given
  def wait_while(timeout: nil)
    raise LocalJumpError, "no block given" unless block_given?
    wait_until(timeout:) { |value| !yield(value) }
  end

  # Wait while `object === value` is true.
  # @param object [#===] the pattern to stop matching
  # @param timeout [Numeric, nil] the total seconds available
  # @return [Boolean, nil] the first nonmatching value, or nil on timeout
  def wait_while_match(object, timeout: nil)
    wait_while(timeout:) { |value| object === value } # rubocop:disable Style/CaseEquality
  end

  # (see #wait_until_changed)
  def wait_while_value(...) = wait_until_changed(...)

  # Wait until `object == value` is true.
  # @param object [BasicObject] the value to compare with the current value
  # @param timeout [Numeric, nil] the total seconds available
  # @return [Boolean, nil] the matching value, or nil on timeout
  def wait_until_value(object, timeout: nil)
    wait_until(timeout:) { |value| object == value }
  end

  # Wait until `object === value` is true.
  # @param object [#===] the pattern to match
  # @param timeout [Numeric, nil] the total seconds available
  # @return [Boolean, nil] the matching value, or nil on timeout
  def wait_until_match(object, timeout: nil)
    wait_until(timeout:) { |value| object === value } # rubocop:disable Style/CaseEquality
  end

  # @api private
  def inspect_with(inspector)
    begin
      current = value
    rescue StandardError
      # FrozenError may inspect an allocated flag before it is initialized.
      return inspector.object_with_address(self)
    end

    super do
      yield if block_given?
      inspector.breakable
      inspector.object(current)
    end
  end
end

#swap(value) ⇒ Boolean

Replace the value and return its previous state.

Parameters:

  • value (Boolean) —

    the new value

Returns:

  • (Boolean) —

    the previous value

Raises:

  • (ArgumentError) —

    if the value is not true or false



55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
 
# File 'lib/farce/abstract/flag.rb', line 55

module Flag
  include Internal::MarshalSupport::Flag
  include Internal::Copyable
  include Value
  include Internal::ValueSerialization
  include Internal::Inspect

  # @return [Boolean] whether the flag is set
  def set? = value
  alias true? set?

  # @return [Boolean] whether the flag is unset
  def unset? = !value
  alias false? unset?

  # Explicitly sets the value to true.
  # Provided for compatibility with `Concurrent::AtomicBoolean`.
  # @return [Boolean] true if the value has changed
  def make_true = compare_and_set(false, true)

  # Explicitly sets the value to false.
  # Provided for compatibility with `Concurrent::AtomicBoolean`.
  # @return [Boolean] true if the value has changed
  def make_false = compare_and_set(true, false)

  # Wait until the flag becomes true.
  # @param timeout [Numeric, nil] the total seconds available
  # @yield called when the timeout expires
  # @return [Boolean, BasicObject, nil] the changed value or timeout fallback
  def wait_until_set(timeout: nil, &) = wait_until_changed(false, timeout:, &)
  alias wait_until_true  wait_until_set
  alias wait_while_unset wait_until_set
  alias wait_while_false wait_until_set

  # Wait until the flag becomes false.
  # @param timeout [Numeric, nil] the total seconds available
  # @yield called when the timeout expires
  # @return [Boolean, BasicObject, nil] the changed value or timeout fallback
  def wait_until_unset(timeout: nil, &) = wait_until_changed(true, timeout:, &)
  alias wait_until_false wait_until_unset
  alias wait_while_set   wait_until_unset
  alias wait_while_true  wait_until_unset

  # Wait until a block condition matches the current value.
  # One timeout budget covers all checks and waits. The block is not interrupted.
  # @yieldparam value [Boolean] the current value
  # @yieldreturn [Boolean] whether the value matches
  # @param timeout [Numeric, nil] the total seconds available
  # @return [Boolean, nil] the matching value, or nil on timeout
  # @raise [LocalJumpError] if no block is given
  def wait_until(timeout: nil, &) = Internal.wait_until(self, timeout:, &)

  # Wait while the block returns a truthy value.
  # @yieldparam value [Boolean] the current value
  # @yieldreturn [BasicObject] a truthy value to keep waiting, or nil or false to stop
  # @param timeout [Numeric, nil] the total seconds available
  # @return [Boolean, nil] the value when the condition becomes false, or nil on timeout
  # @raise [LocalJumpError] if no block is given
  def wait_while(timeout: nil)
    raise LocalJumpError, "no block given" unless block_given?
    wait_until(timeout:) { |value| !yield(value) }
  end

  # Wait while `object === value` is true.
  # @param object [#===] the pattern to stop matching
  # @param timeout [Numeric, nil] the total seconds available
  # @return [Boolean, nil] the first nonmatching value, or nil on timeout
  def wait_while_match(object, timeout: nil)
    wait_while(timeout:) { |value| object === value } # rubocop:disable Style/CaseEquality
  end

  # (see #wait_until_changed)
  def wait_while_value(...) = wait_until_changed(...)

  # Wait until `object == value` is true.
  # @param object [BasicObject] the value to compare with the current value
  # @param timeout [Numeric, nil] the total seconds available
  # @return [Boolean, nil] the matching value, or nil on timeout
  def wait_until_value(object, timeout: nil)
    wait_until(timeout:) { |value| object == value }
  end

  # Wait until `object === value` is true.
  # @param object [#===] the pattern to match
  # @param timeout [Numeric, nil] the total seconds available
  # @return [Boolean, nil] the matching value, or nil on timeout
  def wait_until_match(object, timeout: nil)
    wait_until(timeout:) { |value| object === value } # rubocop:disable Style/CaseEquality
  end

  # @api private
  def inspect_with(inspector)
    begin
      current = value
    rescue StandardError
      # FrozenError may inspect an allocated flag before it is initialized.
      return inspector.object_with_address(self)
    end

    super do
      yield if block_given?
      inspector.breakable
      inspector.object(current)
    end
  end
end

#toggle ⇒ Boolean

Atomically invert the value.

Returns:

  • (Boolean) —

    the new value



55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
 
# File 'lib/farce/abstract/flag.rb', line 55

module Flag
  include Internal::MarshalSupport::Flag
  include Internal::Copyable
  include Value
  include Internal::ValueSerialization
  include Internal::Inspect

  # @return [Boolean] whether the flag is set
  def set? = value
  alias true? set?

  # @return [Boolean] whether the flag is unset
  def unset? = !value
  alias false? unset?

  # Explicitly sets the value to true.
  # Provided for compatibility with `Concurrent::AtomicBoolean`.
  # @return [Boolean] true if the value has changed
  def make_true = compare_and_set(false, true)

  # Explicitly sets the value to false.
  # Provided for compatibility with `Concurrent::AtomicBoolean`.
  # @return [Boolean] true if the value has changed
  def make_false = compare_and_set(true, false)

  # Wait until the flag becomes true.
  # @param timeout [Numeric, nil] the total seconds available
  # @yield called when the timeout expires
  # @return [Boolean, BasicObject, nil] the changed value or timeout fallback
  def wait_until_set(timeout: nil, &) = wait_until_changed(false, timeout:, &)
  alias wait_until_true  wait_until_set
  alias wait_while_unset wait_until_set
  alias wait_while_false wait_until_set

  # Wait until the flag becomes false.
  # @param timeout [Numeric, nil] the total seconds available
  # @yield called when the timeout expires
  # @return [Boolean, BasicObject, nil] the changed value or timeout fallback
  def wait_until_unset(timeout: nil, &) = wait_until_changed(true, timeout:, &)
  alias wait_until_false wait_until_unset
  alias wait_while_set   wait_until_unset
  alias wait_while_true  wait_until_unset

  # Wait until a block condition matches the current value.
  # One timeout budget covers all checks and waits. The block is not interrupted.
  # @yieldparam value [Boolean] the current value
  # @yieldreturn [Boolean] whether the value matches
  # @param timeout [Numeric, nil] the total seconds available
  # @return [Boolean, nil] the matching value, or nil on timeout
  # @raise [LocalJumpError] if no block is given
  def wait_until(timeout: nil, &) = Internal.wait_until(self, timeout:, &)

  # Wait while the block returns a truthy value.
  # @yieldparam value [Boolean] the current value
  # @yieldreturn [BasicObject] a truthy value to keep waiting, or nil or false to stop
  # @param timeout [Numeric, nil] the total seconds available
  # @return [Boolean, nil] the value when the condition becomes false, or nil on timeout
  # @raise [LocalJumpError] if no block is given
  def wait_while(timeout: nil)
    raise LocalJumpError, "no block given" unless block_given?
    wait_until(timeout:) { |value| !yield(value) }
  end

  # Wait while `object === value` is true.
  # @param object [#===] the pattern to stop matching
  # @param timeout [Numeric, nil] the total seconds available
  # @return [Boolean, nil] the first nonmatching value, or nil on timeout
  def wait_while_match(object, timeout: nil)
    wait_while(timeout:) { |value| object === value } # rubocop:disable Style/CaseEquality
  end

  # (see #wait_until_changed)
  def wait_while_value(...) = wait_until_changed(...)

  # Wait until `object == value` is true.
  # @param object [BasicObject] the value to compare with the current value
  # @param timeout [Numeric, nil] the total seconds available
  # @return [Boolean, nil] the matching value, or nil on timeout
  def wait_until_value(object, timeout: nil)
    wait_until(timeout:) { |value| object == value }
  end

  # Wait until `object === value` is true.
  # @param object [#===] the pattern to match
  # @param timeout [Numeric, nil] the total seconds available
  # @return [Boolean, nil] the matching value, or nil on timeout
  def wait_until_match(object, timeout: nil)
    wait_until(timeout:) { |value| object === value } # rubocop:disable Style/CaseEquality
  end

  # @api private
  def inspect_with(inspector)
    begin
      current = value
    rescue StandardError
      # FrozenError may inspect an allocated flag before it is initialized.
      return inspector.object_with_address(self)
    end

    super do
      yield if block_given?
      inspector.breakable
      inspector.object(current)
    end
  end
end

#unset ⇒ false

Set the flag to false.

Returns:

  • (false) 


55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
 
# File 'lib/farce/abstract/flag.rb', line 55

module Flag
  include Internal::MarshalSupport::Flag
  include Internal::Copyable
  include Value
  include Internal::ValueSerialization
  include Internal::Inspect

  # @return [Boolean] whether the flag is set
  def set? = value
  alias true? set?

  # @return [Boolean] whether the flag is unset
  def unset? = !value
  alias false? unset?

  # Explicitly sets the value to true.
  # Provided for compatibility with `Concurrent::AtomicBoolean`.
  # @return [Boolean] true if the value has changed
  def make_true = compare_and_set(false, true)

  # Explicitly sets the value to false.
  # Provided for compatibility with `Concurrent::AtomicBoolean`.
  # @return [Boolean] true if the value has changed
  def make_false = compare_and_set(true, false)

  # Wait until the flag becomes true.
  # @param timeout [Numeric, nil] the total seconds available
  # @yield called when the timeout expires
  # @return [Boolean, BasicObject, nil] the changed value or timeout fallback
  def wait_until_set(timeout: nil, &) = wait_until_changed(false, timeout:, &)
  alias wait_until_true  wait_until_set
  alias wait_while_unset wait_until_set
  alias wait_while_false wait_until_set

  # Wait until the flag becomes false.
  # @param timeout [Numeric, nil] the total seconds available
  # @yield called when the timeout expires
  # @return [Boolean, BasicObject, nil] the changed value or timeout fallback
  def wait_until_unset(timeout: nil, &) = wait_until_changed(true, timeout:, &)
  alias wait_until_false wait_until_unset
  alias wait_while_set   wait_until_unset
  alias wait_while_true  wait_until_unset

  # Wait until a block condition matches the current value.
  # One timeout budget covers all checks and waits. The block is not interrupted.
  # @yieldparam value [Boolean] the current value
  # @yieldreturn [Boolean] whether the value matches
  # @param timeout [Numeric, nil] the total seconds available
  # @return [Boolean, nil] the matching value, or nil on timeout
  # @raise [LocalJumpError] if no block is given
  def wait_until(timeout: nil, &) = Internal.wait_until(self, timeout:, &)

  # Wait while the block returns a truthy value.
  # @yieldparam value [Boolean] the current value
  # @yieldreturn [BasicObject] a truthy value to keep waiting, or nil or false to stop
  # @param timeout [Numeric, nil] the total seconds available
  # @return [Boolean, nil] the value when the condition becomes false, or nil on timeout
  # @raise [LocalJumpError] if no block is given
  def wait_while(timeout: nil)
    raise LocalJumpError, "no block given" unless block_given?
    wait_until(timeout:) { |value| !yield(value) }
  end

  # Wait while `object === value` is true.
  # @param object [#===] the pattern to stop matching
  # @param timeout [Numeric, nil] the total seconds available
  # @return [Boolean, nil] the first nonmatching value, or nil on timeout
  def wait_while_match(object, timeout: nil)
    wait_while(timeout:) { |value| object === value } # rubocop:disable Style/CaseEquality
  end

  # (see #wait_until_changed)
  def wait_while_value(...) = wait_until_changed(...)

  # Wait until `object == value` is true.
  # @param object [BasicObject] the value to compare with the current value
  # @param timeout [Numeric, nil] the total seconds available
  # @return [Boolean, nil] the matching value, or nil on timeout
  def wait_until_value(object, timeout: nil)
    wait_until(timeout:) { |value| object == value }
  end

  # Wait until `object === value` is true.
  # @param object [#===] the pattern to match
  # @param timeout [Numeric, nil] the total seconds available
  # @return [Boolean, nil] the matching value, or nil on timeout
  def wait_until_match(object, timeout: nil)
    wait_until(timeout:) { |value| object === value } # rubocop:disable Style/CaseEquality
  end

  # @api private
  def inspect_with(inspector)
    begin
      current = value
    rescue StandardError
      # FrozenError may inspect an allocated flag before it is initialized.
      return inspector.object_with_address(self)
    end

    super do
      yield if block_given?
      inspector.breakable
      inspector.object(current)
    end
  end
end

#unset? ⇒ Boolean Also known as: false?

Returns whether the flag is unset.

Returns:

  • (Boolean) —

    whether the flag is unset



67
 
# File 'lib/farce/abstract/flag.rb', line 67

def unset? = !value

#value ⇒ Boolean

Returns the current value.

Returns:

  • (Boolean) —

    the current value



55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
 
# File 'lib/farce/abstract/flag.rb', line 55

module Flag
  include Internal::MarshalSupport::Flag
  include Internal::Copyable
  include Value
  include Internal::ValueSerialization
  include Internal::Inspect

  # @return [Boolean] whether the flag is set
  def set? = value
  alias true? set?

  # @return [Boolean] whether the flag is unset
  def unset? = !value
  alias false? unset?

  # Explicitly sets the value to true.
  # Provided for compatibility with `Concurrent::AtomicBoolean`.
  # @return [Boolean] true if the value has changed
  def make_true = compare_and_set(false, true)

  # Explicitly sets the value to false.
  # Provided for compatibility with `Concurrent::AtomicBoolean`.
  # @return [Boolean] true if the value has changed
  def make_false = compare_and_set(true, false)

  # Wait until the flag becomes true.
  # @param timeout [Numeric, nil] the total seconds available
  # @yield called when the timeout expires
  # @return [Boolean, BasicObject, nil] the changed value or timeout fallback
  def wait_until_set(timeout: nil, &) = wait_until_changed(false, timeout:, &)
  alias wait_until_true  wait_until_set
  alias wait_while_unset wait_until_set
  alias wait_while_false wait_until_set

  # Wait until the flag becomes false.
  # @param timeout [Numeric, nil] the total seconds available
  # @yield called when the timeout expires
  # @return [Boolean, BasicObject, nil] the changed value or timeout fallback
  def wait_until_unset(timeout: nil, &) = wait_until_changed(true, timeout:, &)
  alias wait_until_false wait_until_unset
  alias wait_while_set   wait_until_unset
  alias wait_while_true  wait_until_unset

  # Wait until a block condition matches the current value.
  # One timeout budget covers all checks and waits. The block is not interrupted.
  # @yieldparam value [Boolean] the current value
  # @yieldreturn [Boolean] whether the value matches
  # @param timeout [Numeric, nil] the total seconds available
  # @return [Boolean, nil] the matching value, or nil on timeout
  # @raise [LocalJumpError] if no block is given
  def wait_until(timeout: nil, &) = Internal.wait_until(self, timeout:, &)

  # Wait while the block returns a truthy value.
  # @yieldparam value [Boolean] the current value
  # @yieldreturn [BasicObject] a truthy value to keep waiting, or nil or false to stop
  # @param timeout [Numeric, nil] the total seconds available
  # @return [Boolean, nil] the value when the condition becomes false, or nil on timeout
  # @raise [LocalJumpError] if no block is given
  def wait_while(timeout: nil)
    raise LocalJumpError, "no block given" unless block_given?
    wait_until(timeout:) { |value| !yield(value) }
  end

  # Wait while `object === value` is true.
  # @param object [#===] the pattern to stop matching
  # @param timeout [Numeric, nil] the total seconds available
  # @return [Boolean, nil] the first nonmatching value, or nil on timeout
  def wait_while_match(object, timeout: nil)
    wait_while(timeout:) { |value| object === value } # rubocop:disable Style/CaseEquality
  end

  # (see #wait_until_changed)
  def wait_while_value(...) = wait_until_changed(...)

  # Wait until `object == value` is true.
  # @param object [BasicObject] the value to compare with the current value
  # @param timeout [Numeric, nil] the total seconds available
  # @return [Boolean, nil] the matching value, or nil on timeout
  def wait_until_value(object, timeout: nil)
    wait_until(timeout:) { |value| object == value }
  end

  # Wait until `object === value` is true.
  # @param object [#===] the pattern to match
  # @param timeout [Numeric, nil] the total seconds available
  # @return [Boolean, nil] the matching value, or nil on timeout
  def wait_until_match(object, timeout: nil)
    wait_until(timeout:) { |value| object === value } # rubocop:disable Style/CaseEquality
  end

  # @api private
  def inspect_with(inspector)
    begin
      current = value
    rescue StandardError
      # FrozenError may inspect an allocated flag before it is initialized.
      return inspector.object_with_address(self)
    end

    super do
      yield if block_given?
      inspector.breakable
      inspector.object(current)
    end
  end
end

#value=(value) ⇒ BasicObject

Alias for #store



55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
 
# File 'lib/farce/abstract/flag.rb', line 55

module Flag
  include Internal::MarshalSupport::Flag
  include Internal::Copyable
  include Value
  include Internal::ValueSerialization
  include Internal::Inspect

  # @return [Boolean] whether the flag is set
  def set? = value
  alias true? set?

  # @return [Boolean] whether the flag is unset
  def unset? = !value
  alias false? unset?

  # Explicitly sets the value to true.
  # Provided for compatibility with `Concurrent::AtomicBoolean`.
  # @return [Boolean] true if the value has changed
  def make_true = compare_and_set(false, true)

  # Explicitly sets the value to false.
  # Provided for compatibility with `Concurrent::AtomicBoolean`.
  # @return [Boolean] true if the value has changed
  def make_false = compare_and_set(true, false)

  # Wait until the flag becomes true.
  # @param timeout [Numeric, nil] the total seconds available
  # @yield called when the timeout expires
  # @return [Boolean, BasicObject, nil] the changed value or timeout fallback
  def wait_until_set(timeout: nil, &) = wait_until_changed(false, timeout:, &)
  alias wait_until_true  wait_until_set
  alias wait_while_unset wait_until_set
  alias wait_while_false wait_until_set

  # Wait until the flag becomes false.
  # @param timeout [Numeric, nil] the total seconds available
  # @yield called when the timeout expires
  # @return [Boolean, BasicObject, nil] the changed value or timeout fallback
  def wait_until_unset(timeout: nil, &) = wait_until_changed(true, timeout:, &)
  alias wait_until_false wait_until_unset
  alias wait_while_set   wait_until_unset
  alias wait_while_true  wait_until_unset

  # Wait until a block condition matches the current value.
  # One timeout budget covers all checks and waits. The block is not interrupted.
  # @yieldparam value [Boolean] the current value
  # @yieldreturn [Boolean] whether the value matches
  # @param timeout [Numeric, nil] the total seconds available
  # @return [Boolean, nil] the matching value, or nil on timeout
  # @raise [LocalJumpError] if no block is given
  def wait_until(timeout: nil, &) = Internal.wait_until(self, timeout:, &)

  # Wait while the block returns a truthy value.
  # @yieldparam value [Boolean] the current value
  # @yieldreturn [BasicObject] a truthy value to keep waiting, or nil or false to stop
  # @param timeout [Numeric, nil] the total seconds available
  # @return [Boolean, nil] the value when the condition becomes false, or nil on timeout
  # @raise [LocalJumpError] if no block is given
  def wait_while(timeout: nil)
    raise LocalJumpError, "no block given" unless block_given?
    wait_until(timeout:) { |value| !yield(value) }
  end

  # Wait while `object === value` is true.
  # @param object [#===] the pattern to stop matching
  # @param timeout [Numeric, nil] the total seconds available
  # @return [Boolean, nil] the first nonmatching value, or nil on timeout
  def wait_while_match(object, timeout: nil)
    wait_while(timeout:) { |value| object === value } # rubocop:disable Style/CaseEquality
  end

  # (see #wait_until_changed)
  def wait_while_value(...) = wait_until_changed(...)

  # Wait until `object == value` is true.
  # @param object [BasicObject] the value to compare with the current value
  # @param timeout [Numeric, nil] the total seconds available
  # @return [Boolean, nil] the matching value, or nil on timeout
  def wait_until_value(object, timeout: nil)
    wait_until(timeout:) { |value| object == value }
  end

  # Wait until `object === value` is true.
  # @param object [#===] the pattern to match
  # @param timeout [Numeric, nil] the total seconds available
  # @return [Boolean, nil] the matching value, or nil on timeout
  def wait_until_match(object, timeout: nil)
    wait_until(timeout:) { |value| object === value } # rubocop:disable Style/CaseEquality
  end

  # @api private
  def inspect_with(inspector)
    begin
      current = value
    rescue StandardError
      # FrozenError may inspect an allocated flag before it is initialized.
      return inspector.object_with_address(self)
    end

    super do
      yield if block_given?
      inspector.breakable
      inspector.object(current)
    end
  end
end

#wait_until(timeout: nil) {|value| ... } ⇒ Boolean?

Wait until a block condition matches the current value. One timeout budget covers all checks and waits. The block is not interrupted.

Parameters:

  • timeout (Numeric, nil) (defaults to: nil) —

    the total seconds available

Yield Parameters:

  • value (Boolean) —

    the current value

Yield Returns:

  • (Boolean) —

    whether the value matches

Returns:

  • (Boolean, nil) —

    the matching value, or nil on timeout

Raises:

  • (LocalJumpError) —

    if no block is given



105
 
# File 'lib/farce/abstract/flag.rb', line 105

def wait_until(timeout: nil, &) = Internal.wait_until(self, timeout:, &)

#wait_until_changed(expected, timeout: nil) { ... } ⇒ Boolean, ...

Wait until the current value differs from the expected value.

Parameters:

  • expected (Boolean) —

    the value to wait to change from

  • timeout (Numeric, nil) (defaults to: nil) —

    the total seconds available

Yields:

  • called when the timeout expires

Returns:

  • (Boolean, BasicObject, nil) —

    the changed value or timeout fallback

Raises:

  • (ArgumentError) —

    if expected is not true or false



55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
 
# File 'lib/farce/abstract/flag.rb', line 55

module Flag
  include Internal::MarshalSupport::Flag
  include Internal::Copyable
  include Value
  include Internal::ValueSerialization
  include Internal::Inspect

  # @return [Boolean] whether the flag is set
  def set? = value
  alias true? set?

  # @return [Boolean] whether the flag is unset
  def unset? = !value
  alias false? unset?

  # Explicitly sets the value to true.
  # Provided for compatibility with `Concurrent::AtomicBoolean`.
  # @return [Boolean] true if the value has changed
  def make_true = compare_and_set(false, true)

  # Explicitly sets the value to false.
  # Provided for compatibility with `Concurrent::AtomicBoolean`.
  # @return [Boolean] true if the value has changed
  def make_false = compare_and_set(true, false)

  # Wait until the flag becomes true.
  # @param timeout [Numeric, nil] the total seconds available
  # @yield called when the timeout expires
  # @return [Boolean, BasicObject, nil] the changed value or timeout fallback
  def wait_until_set(timeout: nil, &) = wait_until_changed(false, timeout:, &)
  alias wait_until_true  wait_until_set
  alias wait_while_unset wait_until_set
  alias wait_while_false wait_until_set

  # Wait until the flag becomes false.
  # @param timeout [Numeric, nil] the total seconds available
  # @yield called when the timeout expires
  # @return [Boolean, BasicObject, nil] the changed value or timeout fallback
  def wait_until_unset(timeout: nil, &) = wait_until_changed(true, timeout:, &)
  alias wait_until_false wait_until_unset
  alias wait_while_set   wait_until_unset
  alias wait_while_true  wait_until_unset

  # Wait until a block condition matches the current value.
  # One timeout budget covers all checks and waits. The block is not interrupted.
  # @yieldparam value [Boolean] the current value
  # @yieldreturn [Boolean] whether the value matches
  # @param timeout [Numeric, nil] the total seconds available
  # @return [Boolean, nil] the matching value, or nil on timeout
  # @raise [LocalJumpError] if no block is given
  def wait_until(timeout: nil, &) = Internal.wait_until(self, timeout:, &)

  # Wait while the block returns a truthy value.
  # @yieldparam value [Boolean] the current value
  # @yieldreturn [BasicObject] a truthy value to keep waiting, or nil or false to stop
  # @param timeout [Numeric, nil] the total seconds available
  # @return [Boolean, nil] the value when the condition becomes false, or nil on timeout
  # @raise [LocalJumpError] if no block is given
  def wait_while(timeout: nil)
    raise LocalJumpError, "no block given" unless block_given?
    wait_until(timeout:) { |value| !yield(value) }
  end

  # Wait while `object === value` is true.
  # @param object [#===] the pattern to stop matching
  # @param timeout [Numeric, nil] the total seconds available
  # @return [Boolean, nil] the first nonmatching value, or nil on timeout
  def wait_while_match(object, timeout: nil)
    wait_while(timeout:) { |value| object === value } # rubocop:disable Style/CaseEquality
  end

  # (see #wait_until_changed)
  def wait_while_value(...) = wait_until_changed(...)

  # Wait until `object == value` is true.
  # @param object [BasicObject] the value to compare with the current value
  # @param timeout [Numeric, nil] the total seconds available
  # @return [Boolean, nil] the matching value, or nil on timeout
  def wait_until_value(object, timeout: nil)
    wait_until(timeout:) { |value| object == value }
  end

  # Wait until `object === value` is true.
  # @param object [#===] the pattern to match
  # @param timeout [Numeric, nil] the total seconds available
  # @return [Boolean, nil] the matching value, or nil on timeout
  def wait_until_match(object, timeout: nil)
    wait_until(timeout:) { |value| object === value } # rubocop:disable Style/CaseEquality
  end

  # @api private
  def inspect_with(inspector)
    begin
      current = value
    rescue StandardError
      # FrozenError may inspect an allocated flag before it is initialized.
      return inspector.object_with_address(self)
    end

    super do
      yield if block_given?
      inspector.breakable
      inspector.object(current)
    end
  end
end

#wait_until_match(object, timeout: nil) ⇒ Boolean?

Wait until object === value is true.

Parameters:

  • object (#===) —

    the pattern to match

  • timeout (Numeric, nil) (defaults to: nil) —

    the total seconds available

Returns:

  • (Boolean, nil) —

    the matching value, or nil on timeout



141
142
143
 
# File 'lib/farce/abstract/flag.rb', line 141

def wait_until_match(object, timeout: nil)
  wait_until(timeout:) { |value| object === value } # rubocop:disable Style/CaseEquality
end

#wait_until_set(timeout: nil) { ... } ⇒ Boolean, ... Also known as: wait_until_true, wait_while_unset, wait_while_false

Wait until the flag becomes true.

Parameters:

  • timeout (Numeric, nil) (defaults to: nil) —

    the total seconds available

Yields:

  • called when the timeout expires

Returns:

  • (Boolean, BasicObject, nil) —

    the changed value or timeout fallback



84
 
# File 'lib/farce/abstract/flag.rb', line 84

def wait_until_set(timeout: nil, &) = wait_until_changed(false, timeout:, &)

#wait_until_unset(timeout: nil) { ... } ⇒ Boolean, ... Also known as: wait_until_false, wait_while_set, wait_while_true

Wait until the flag becomes false.

Parameters:

  • timeout (Numeric, nil) (defaults to: nil) —

    the total seconds available

Yields:

  • called when the timeout expires

Returns:

  • (Boolean, BasicObject, nil) —

    the changed value or timeout fallback



93
 
# File 'lib/farce/abstract/flag.rb', line 93

def wait_until_unset(timeout: nil, &) = wait_until_changed(true, timeout:, &)

#wait_until_value(object, timeout: nil) ⇒ Boolean?

Wait until object == value is true.

Parameters:

  • object (BasicObject) —

    the value to compare with the current value

  • timeout (Numeric, nil) (defaults to: nil) —

    the total seconds available

Returns:

  • (Boolean, nil) —

    the matching value, or nil on timeout



133
134
135
 
# File 'lib/farce/abstract/flag.rb', line 133

def wait_until_value(object, timeout: nil)
  wait_until(timeout:) { |value| object == value }
end

#wait_while(timeout: nil) {|value| ... } ⇒ Boolean?

Wait while the block returns a truthy value.

Parameters:

  • timeout (Numeric, nil) (defaults to: nil) —

    the total seconds available

Yield Parameters:

  • value (Boolean) —

    the current value

Yield Returns:

  • (BasicObject) —

    a truthy value to keep waiting, or nil or false to stop

Returns:

  • (Boolean, nil) —

    the value when the condition becomes false, or nil on timeout

Raises:

  • (LocalJumpError) —

    if no block is given



113
114
115
116
 
# File 'lib/farce/abstract/flag.rb', line 113

def wait_while(timeout: nil)
  raise LocalJumpError, "no block given" unless block_given?
  wait_until(timeout:) { |value| !yield(value) }
end

#wait_while_match(object, timeout: nil) ⇒ Boolean?

Wait while object === value is true.

Parameters:

  • object (#===) —

    the pattern to stop matching

  • timeout (Numeric, nil) (defaults to: nil) —

    the total seconds available

Returns:

  • (Boolean, nil) —

    the first nonmatching value, or nil on timeout



122
123
124
 
# File 'lib/farce/abstract/flag.rb', line 122

def wait_while_match(object, timeout: nil)
  wait_while(timeout:) { |value| object === value } # rubocop:disable Style/CaseEquality
end

#wait_while_value { ... } ⇒ Boolean, ...

Wait until the current value differs from the expected value.

Parameters:

  • expected (Boolean) —

    the value to wait to change from

  • timeout (Numeric, nil) —

    the total seconds available

Yields:

  • called when the timeout expires

Returns:

  • (Boolean, BasicObject, nil) —

    the changed value or timeout fallback

Raises:

  • (ArgumentError) —

    if expected is not true or false



127
 
# File 'lib/farce/abstract/flag.rb', line 127

def wait_while_value(...) = wait_until_changed(...)