Skip to content

GCounter[optional A: (Integer[A] val & Unsigned)]

[Source]

A mutable grow-only counter. That is, the value can only be increased.

It is limited by the maximum value of the used unsigned integer datatype. Any operation that would lead to an overflow (if the maximum is the maximum value for the used unsigned integer type) will result in the value being set to the maximum. So once the maximum is reached, the GCounter will never change.

This data type tracks the state seen from each replica, thus the size of the state will grow proportionally with the number of total replicas. New replicas may be added as peers at any time, provided that they use unique ids. Read-only replicas which never change state and only observe need not use unique ids, and should use an id of zero, by convention.

The state of each replica represents the value incremented so far by that particular replica. This local value may only ever increase, never decrease. The total value of the counter is the sum of the local value of all replicas.

When converging state from other replicas, we retain the maximum observed value from each replica id. Because a higher value always implies later logical time for that replica, and we only keep the highest value seen from each replica, we will always retain the latest value seen from each replica.

Because the view of values from each other replica is eventually consistent, the summed value of the overall counter is also eventually consistent.

All mutator methods accept and return a convergent delta-state.

class ref GCounter[optional A: (Integer[A] val & Unsigned)] is
  Comparable[GCounter[A] ref] ref,
  Convergent[GCounter[A] ref] ref,
  Replicated ref

Implements

Constructors

create

[Source]

Instantiate the GCounter under the given unique replica id.

new ref create(
  id': ID)
: GCounter[A] ref^

Parameters

Returns

Public Functions

is_empty

[Source]

Return true if the data structure contains no information (bottom state).

fun box is_empty()
: Bool val

Returns

apply

[Source]

Return the current value of the counter (the sum of all replica values).

fun box apply()
: A

Returns

  • A

value

[Source]

Return the current value of the counter (the sum of all replica values).

fun box value()
: A

Returns

  • A

increment[optional D: GCounter[A] ref]

[Source]

Increment the counter by the given value. Accepts and returns a convergent delta-state.

fun ref increment[optional D: GCounter[A] ref](
  value': A = 1,
  delta': D = recover GCounter[A](0) end)
: D^

Parameters

  • value': A = 1
  • delta': D = recover GCounterA end

Returns

  • D^

converge

[Source]

Converge from the given GCounter into this one. For each replica state, we select the maximum value seen so far (grow-only). Returns true if the convergence added new information to the data structure.

fun ref converge(
  that: GCounter[A] box)
: Bool val

Parameters

Returns

string

[Source]

Return a best effort at printing the register. If A is Stringable, use the string representation of the value; otherwise print as a question mark.

fun box string()
: String iso^

Returns

eq

[Source]

fun box eq(
  that: GCounter[A] box)
: Bool val

Parameters

Returns

ne

[Source]

fun box ne(
  that: GCounter[A] box)
: Bool val

Parameters

Returns

lt

[Source]

fun box lt(
  that: GCounter[A] box)
: Bool val

Parameters

Returns

le

[Source]

fun box le(
  that: GCounter[A] box)
: Bool val

Parameters

Returns

gt

[Source]

fun box gt(
  that: GCounter[A] box)
: Bool val

Parameters

Returns

ge

[Source]

fun box ge(
  that: GCounter[A] box)
: Bool val

Parameters

Returns

from_tokens

[Source]

Deserialize an instance of this data structure from a stream of tokens.

fun ref from_tokens(
  that: TokensIterator ref)
: None val ?

Parameters

Returns

each_token

[Source]

Serialize the data structure, capturing each token into the given Tokens.

fun ref each_token(
  tokens: Tokens ref)
: None val

Parameters

Returns

compare

[Source]

fun box compare(
  that: GCounter[A] box)
: Compare

Parameters

Returns