Class: Farce::Counter

Inherits:
Internal::Counter
  • Object
show all
Includes:
Abstract::Counter, Shareable::Native
Defined in:
lib/farce/counter.rb

Overview

Ractor-shareable, atomic counter. This is a stateful, numeric object.

Values are converted to Integers. On CRuby, the stored value and arithmetic deltas must fit in a signed 64-bit integer. An overflow raises RangeError without changing the stored value. Conditional-operation bounds may be wider, but a resulting stored value must still fit.

On CRuby, subclasses must not add Ruby instance variables.

Examples:

Cross-Ractor counting

counter = Farce::Counter.new
counter.value # => 0

# Increase the counter by 1
counter.increment
counter.value # => 1

# Increase the counter by 5 on another Ractor
Ractor.new(counter) { it.add(5) }

# Give the other ractor time to run
sleep 0.1

counter.value # => 6

Counter as a numeric value

counter = Farce::Counter.new(10.0)
counter.to_i  # => 10
counter + 5   # => 15
2.5 * counter # => 25.0

require "active_support/all"
counter.minutes.to_i # => 600

Instance Method Summary collapse

Methods included from Shareable

#ractor_shareable?

Methods included from Abstract::Counter

#add, #decrement_if_above, included, #increment_if_below, #reset, #wait_until, #wait_until_above, #wait_until_below, #wait_until_changed, #wait_until_match, #wait_until_value, #wait_while, #wait_while_above, #wait_while_below, #wait_while_match, #wait_while_value

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 Abstract::Value

#blank?, #unwrap

Methods included from Internal::Copyable

#duplicable?

Constructor Details

#initialize(value = 0) ⇒ Counter

Returns a new instance of Counter.

Parameters:

  • value (Numeric, String, #to_int) (defaults to: 0) —

    The initial value, converted to an Integer.

Raises:

  • (FrozenError) 


61
62
63
64
 
# File 'lib/farce/counter.rb', line 61

def initialize(value = 0)
  raise FrozenError.new("can't initialize a frozen counter", receiver: self) if frozen?
  super(Integer(value))
end

Dynamic Method Handling

This class handles dynamic methods through the method_missing method in the class Farce::Abstract::Counter

Instance Method Details

#decrement(by = 1) ⇒ self Also known as: subtract, remove

Decrement the counter by the given amount (default is 1).

Parameters:

  • by (Numeric, String, #to_int) (defaults to: 1) —

    The amount, converted to an Integer.

Returns:

  • (self) —

    Returns self for chaining.



56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
 
# File 'lib/farce/counter.rb', line 56

class Counter < Internal::Counter
  include Abstract::Counter
  include Shareable::Native

  # @param [Numeric, String, #to_int] value The initial value, converted to an Integer.
  def initialize(value = 0)
    raise FrozenError.new("can't initialize a frozen counter", receiver: self) if frozen?
    super(Integer(value))
  end

  alias subtract decrement
  alias remove   decrement

  private :change_signal
end

#increment(by = 1) ⇒ self

Increment the counter by the given amount (default is 1).

Parameters:

  • by (Numeric, String, #to_int) (defaults to: 1) —

    The amount, converted to an Integer.

Returns:

  • (self) —

    Returns self for chaining.



56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
 
# File 'lib/farce/counter.rb', line 56

class Counter < Internal::Counter
  include Abstract::Counter
  include Shareable::Native

  # @param [Numeric, String, #to_int] value The initial value, converted to an Integer.
  def initialize(value = 0)
    raise FrozenError.new("can't initialize a frozen counter", receiver: self) if frozen?
    super(Integer(value))
  end

  alias subtract decrement
  alias remove   decrement

  private :change_signal
end

#initial ⇒ Integer

Returns The initial value retained by reset and copies.

Returns:

  • (Integer) —

    The initial value retained by reset and copies.



56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
 
# File 'lib/farce/counter.rb', line 56

class Counter < Internal::Counter
  include Abstract::Counter
  include Shareable::Native

  # @param [Numeric, String, #to_int] value The initial value, converted to an Integer.
  def initialize(value = 0)
    raise FrozenError.new("can't initialize a frozen counter", receiver: self) if frozen?
    super(Integer(value))
  end

  alias subtract decrement
  alias remove   decrement

  private :change_signal
end

#value ⇒ Integer

Returns The current value of the counter.

Returns:

  • (Integer) —

    The current value of the counter.



56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
 
# File 'lib/farce/counter.rb', line 56

class Counter < Internal::Counter
  include Abstract::Counter
  include Shareable::Native

  # @param [Numeric, String, #to_int] value The initial value, converted to an Integer.
  def initialize(value = 0)
    raise FrozenError.new("can't initialize a frozen counter", receiver: self) if frozen?
    super(Integer(value))
  end

  alias subtract decrement
  alias remove   decrement

  private :change_signal
end