Class: Farce::Abstract::Atom Abstract

Inherits:

Object

• Object
• Farce::Abstract::Atom

Includes:

Value, Internal::Copyable, Internal::ValueSerialization, Internal::Inspect, Internal::MarshalSupport::Atom

Defined in:

lib/farce/abstract/atom.rb,
lib/farce/integrations/psych.rb,
lib/farce/integrations/active_support/blank.rb

Overview

This class is abstract.

Common interface and behavior for atomic references.

Concrete implementations decide how values are retained and transferred. A value may become nil without an explicit update when an implementation retains it weakly.

Direct Known Subclasses

WeakAtom, Farce::Atom, Local::Atom, Strict::Atom, Transaction::Atom, Unshared::Atom

ActiveSupport Integration

• #blank? ⇒ Boolean

  True if the atom's value is blank, false otherwise.

Methods included from Internal::ValueSerialization

#as_json, #to_msgpack

Methods included from Internal::Copyable

#duplicable?

Instance Method Summary

• #compare_and_set(expected, new_value, timeout: nil) ⇒ Boolean

  Atomically replace the current value if it matches the expected value.

• #compare_by_identity? ⇒ Boolean

  Whether comparisons use object identity instead of equality.

• #get(timeout: nil) { ... } ⇒ BasicObject^?

  Return the current value, waiting for any update in progress.

• #store(new_value, timeout: nil) { ... } ⇒ BasicObject^?

  Store a new value, waiting for any update in progress.

• #store_if_absent(timeout: nil) { ... } ⇒ BasicObject^?

  Compute and store a value if the current value is nil.

• #swap(new_value, timeout: nil) { ... } ⇒ BasicObject^?

  Replace the current value and return the previous value.

• #update(timeout: nil) {|current| ... } ⇒ BasicObject^?

  Atomically replace the current value with the result of a block.

• #upsert(initial_value, timeout: nil) {|current| ... } ⇒ BasicObject^?

  Store an initial value if the current value is nil, otherwise replace it with the result of a block.

• #value ⇒ BasicObject^?

  Return the current value without waiting for an update in progress.

• #value=(new_value) ⇒ BasicObject^?

  Store a new value.

• #wait_until(timeout: nil) {|value| ... } ⇒ BasicObject^?

  Wait until a block condition matches the current value.

• #wait_until_changed(expected, timeout: nil) { ... } ⇒ BasicObject^?

  Wait until the current value no longer matches an expected value.

• #wait_until_match(object, timeout: nil) ⇒ BasicObject^?

  Wait until object === value is true.

• #wait_until_non_nil(timeout: nil) { ... } ⇒ BasicObject^?

  Wait until the current value is not nil.

• #wait_until_value(object, timeout: nil) ⇒ BasicObject^?

  Wait until the current value equals an object using the configured comparison mode.

• #wait_while(timeout: nil) {|value| ... } ⇒ BasicObject^?

  Wait while the block returns a truthy value.

• #wait_while_match(object, timeout: nil) ⇒ BasicObject^?

  Wait while object === value is true.

• #wait_while_value { ... } ⇒ BasicObject^?

  Wait until the current value no longer matches an expected value.

Methods included from Internal::ValueSerialization

#as_extended_json, #to_bson, #to_bson_normalized_value, #to_cbor, #to_json

Methods included from Value

#unwrap

Instance Method Details

#blank? ⇒ Boolean

Note:

This methods is only available if ActiveSupport has been loaded.

Returns true if the atom's value is blank, false otherwise.

Returns:

• (Boolean) —

  true if the atom's value is blank, false otherwise.

# File 'lib/farce/integrations/active_support/blank.rb', line 34

def blank? = internal_atom.value.blank?

#compare_and_set(expected, new_value, timeout: nil) ⇒ Boolean

Atomically replace the current value if it matches the expected value.

Parameters:

• expected (BasicObject, nil) —

  the value to compare with the current value

• new_value (BasicObject, nil) —

  the replacement value

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

  the maximum number of seconds to wait

Returns:

• (Boolean) —

  whether the value was replaced

# File 'lib/farce/abstract/atom.rb', line 69

def compare_and_set(expected, new_value, timeout: nil)
  internal_atom.compare_and_set(expected, new_value, timeout:)
end

#compare_by_identity? ⇒ Boolean

Whether comparisons use object identity instead of equality.

Returns:

• (Boolean)

# File 'lib/farce/abstract/atom.rb', line 24

def compare_by_identity? = internal_atom.compare_by_identity?

#get(timeout: nil) { ... } ⇒ BasicObject^?

Return the current value, waiting for any update in progress.

Parameters:

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

  the maximum number of seconds to wait

Yields:

• called when the timeout expires

Returns:

• (BasicObject, nil) —

  the current value or the fallback result

# File 'lib/farce/abstract/atom.rb', line 41

def get(timeout: nil, &) = internal_atom.get(timeout:, &)

#store(new_value, timeout: nil) { ... } ⇒ BasicObject^?

Store a new value, waiting for any update in progress.

Parameters:

• new_value (BasicObject, nil) —

  the new value

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

  the maximum number of seconds to wait

Yields:

• called when the timeout expires

Returns:

• (BasicObject, nil) —

  the stored value or the fallback result

# File 'lib/farce/abstract/atom.rb', line 48

def store(new_value, timeout: nil, &) = internal_atom.store(new_value, timeout:, &)

#store_if_absent(timeout: nil) { ... } ⇒ BasicObject^?

Compute and store a value if the current value is nil.

Parameters:

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

  the maximum number of seconds to wait

Yields:

• computes the value to store when the current value is nil

Yield Returns:

• (BasicObject, nil) —

  the value to store

Returns:

• (BasicObject, nil) —

  the current or newly stored value, or nil when the timeout expires

# File 'lib/farce/abstract/atom.rb', line 62

def store_if_absent(timeout: nil, &) = internal_atom.store_if_absent(timeout:, &)

#swap(new_value, timeout: nil) { ... } ⇒ BasicObject^?

Replace the current value and return the previous value.

Parameters:

• new_value (BasicObject, nil) —

  the new value

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

  the maximum number of seconds to wait

Yields:

• called when the timeout expires

Returns:

• (BasicObject, nil) —

  the previous value or the fallback result

# File 'lib/farce/abstract/atom.rb', line 55

def swap(new_value, timeout: nil, &) = internal_atom.swap(new_value, timeout:, &)

#update(timeout: nil) {|current| ... } ⇒ BasicObject^?

Atomically replace the current value with the result of a block.

Parameters:

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

  the maximum number of seconds to wait

Yields:

• receives the current value and computes its replacement

Yield Parameters:

• current (BasicObject, nil) —

  the current value

Yield Returns:

• (BasicObject, nil) —

  the replacement value

Returns:

• (BasicObject, nil) —

  the replacement value, or nil when the timeout expires

# File 'lib/farce/abstract/atom.rb', line 79

def update(timeout: nil, &) = internal_atom.update(timeout:, &)

#upsert(initial_value, timeout: nil) {|current| ... } ⇒ BasicObject^?

Store an initial value if the current value is nil, otherwise replace it with the result of a block.

Parameters:

• initial_value (BasicObject, nil) —

  the value to store when the current value is nil

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

  the maximum number of seconds to wait

Yields:

• receives a non-nil current value and computes its replacement

Yield Parameters:

• current (BasicObject) —

  the current value

Yield Returns:

• (BasicObject, nil) —

  the replacement value

Returns:

• (BasicObject, nil) —

  the replacement or initial value, or nil when the timeout expires

# File 'lib/farce/abstract/atom.rb', line 88

def upsert(initial_value, timeout: nil, &) = internal_atom.upsert(initial_value, timeout:, &)

#value ⇒ BasicObject^?

Return the current value without waiting for an update in progress.

Returns:

• (BasicObject, nil) —

  the current value

# File 'lib/farce/abstract/atom.rb', line 28

def value = internal_atom.value

#value=(new_value) ⇒ BasicObject^?

Store a new value.

Parameters:

• new_value (BasicObject, nil) —

  the new value

Returns:

• (BasicObject, nil) —

  the new value

# File 'lib/farce/abstract/atom.rb', line 33

def value=(new_value)
  store(new_value)
end

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

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 (BasicObject, nil) —

  the current value

Yield Returns:

• (Boolean) —

  whether the value matches

Returns:

• (BasicObject, nil) —

  the matching value, or nil on timeout

Raises:

• (LocalJumpError) —

  if no block is given

# File 'lib/farce/abstract/atom.rb', line 97

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

#wait_until_changed(expected, timeout: nil) { ... } ⇒ BasicObject^?

Wait until the current value no longer matches an expected value.

Parameters:

• expected (BasicObject, nil) —

  the value to compare with the current value

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

  the maximum number of seconds to wait

Yields:

• called when the timeout expires

Returns:

• (BasicObject, nil) —

  the changed value or the fallback result

# File 'lib/farce/abstract/atom.rb', line 142

def wait_until_changed(expected, timeout: nil, &)
  internal_atom.wait_until_changed(expected, timeout:, &)
end

#wait_until_match(object, timeout: nil) ⇒ BasicObject^?

Wait until object === value is true.

Parameters:

• object (#===) —

  the pattern to match

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

  the total seconds available

Returns:

• (BasicObject, nil) —

  the matching value, or nil on timeout

# File 'lib/farce/abstract/atom.rb', line 133

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

#wait_until_non_nil(timeout: nil) { ... } ⇒ BasicObject^?

Wait until the current value is not nil.

Parameters:

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

  the maximum number of seconds to wait

Yields:

• called when the timeout expires

Returns:

• (BasicObject, nil) —

  the non-nil value or the fallback result

# File 'lib/farce/abstract/atom.rb', line 150

def wait_until_non_nil(timeout: nil, &) = internal_atom.wait_until_non_nil(timeout:, &)

#wait_until_value(object, timeout: nil) ⇒ BasicObject^?

Wait until the current value equals an object using the configured comparison mode.

Parameters:

• object (BasicObject, nil) —

  the value to compare with the current value

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

  the total seconds available

Returns:

• (BasicObject, nil) —

  the matching value, or nil on timeout

# File 'lib/farce/abstract/atom.rb', line 125

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

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

Wait while the block returns a truthy value.

Parameters:

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

  the total seconds available

Yield Parameters:

• value (BasicObject, nil) —

  the current value

Yield Returns:

• (BasicObject) —

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

Returns:

• (BasicObject, nil) —

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

Raises:

• (LocalJumpError) —

  if no block is given

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

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) ⇒ BasicObject^?

Wait while object === value is true.

Parameters:

• object (#===) —

  the pattern to stop matching

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

  the total seconds available

Returns:

• (BasicObject, nil) —

  the first nonmatching value, or nil on timeout

# File 'lib/farce/abstract/atom.rb', line 114

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

#wait_while_value { ... } ⇒ BasicObject^?

Wait until the current value no longer matches an expected value.

Parameters:

• expected (BasicObject, nil) —

  the value to compare with the current value

• timeout (Numeric, nil) —

  the maximum number of seconds to wait

Yields:

• called when the timeout expires

Returns:

• (BasicObject, nil) —

  the changed value or the fallback result

# File 'lib/farce/abstract/atom.rb', line 119

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