Skip to content

DotContext

[Source]

This data structure is used internally. There shouldn't really be a reason to use it outside of that context, and be aware that if you do, there are unsound patterns of use to avoid. See the rest of the docstrings in this file for more information.

Represents the total set of "dots" received so far in known history, where each dot is a unique replica identifier and a sequence number.

As a memory optimization, we represent that total set in two structures: The _complete history and the _dot_cloud. By compacting from _dot_cloud into the _complete history, we can avoid letting memory grow without bound, as long as any gaps in history eventually get filled by incoming dots.

The _complete history represents the range of consecutive sequence numbers starting with zero that have already been observed for a given replica ID. Nothing new can be learned about this region of history.

The _dot_cloud represents the set of arbitrary (ID, N) pairings which have not yet been absorbed into _complete because they are not consecutive. When enough dots are accumulated into the _dot_cloud to be consecutive with the current threshold of _complete history, they can compacted into it.

class ref DotContext is
  Replicated ref

Implements

Constructors

create

[Source]

Instantiate under the given unique replica id.

It will only be possible to add dots values under this replica id, aside from converging it as external data with the converge function.

new ref create(
  id': ID)
: DotContext ref^

Parameters

Returns

Public Functions

clone

[Source]

Create a deep copy of this context.

fun box clone()
: DotContext ref

Returns

id

[Source]

Return the replica id used to instantiate this context.

fun box id()
: ID

Returns

contains

[Source]

Test if the given dot has been received yet in this causal history.

fun box contains(
  dot: _Dot)
: Bool val

Parameters

  • dot: _Dot

Returns

compact

[Source]

Reduce memory footprint by absorbing as many members of the _dot_cloud set as possible into the _complete.

Dots which represent the next sequence number for a known ID are moved into the _complete by incrementing the sequence number for that ID. Every missing ID in the _complete is treated as zero, with the next sequence number expected being one.

Dots that are already present or outdated in the _complete (those whose sequence numbers are less than or equal to the known number for the same ID) are discarded.

All other dots are kept in the _dot_cloud.

The compaction operation does not lose any information.

fun ref compact()
: None val

Returns

next_dot

[Source]

Update _complete with the next sequence number for the local replica ID, also returning the resulting dot.

This is only valid when there are no dots for it in _dot_cloud, so that's why it can only be used with the id of the local replica.

WARNING: any set calls with compact_now = false must be followed compact before calling this function.

In the future, we want to consider refactoring this abstraction to make it more difficult to make a mistake that breaks these assumptions, using Pony idioms of having the type system prevent you from doing unsafe actions.

fun ref next_dot()
: _Dot

Returns

  • _Dot

set

[Source]

Add the given dot into the causal history represented here.

If compact_now is set to false, auto-compaction will be skipped. This is useful for optimizing sites where set is called many times, but proceed with care, because operations like next_dot depend on compaction; make sure compact is called after any such optimized group of set calls.

fun ref set(
  dot: _Dot,
  compact_now: Bool val = true)
: None val

Parameters

  • dot: _Dot
  • compact_now: Bool val = true

Returns

set_converge_disabled

[Source]

Set the new value of the _converge_disabled field, returning the old value.

While _converge_disabled is true, the following methods will be no-ops: converge, from_tokens, each_token.

This is used in situations where the context is shared by many instances.

fun ref set_converge_disabled(
  value': Bool val)
: Bool val

Parameters

Returns

converge

[Source]

Add all dots from that causal history into this one.

The consecutive ranges in _complete can be updated to the maximum range. The _dot_cloud can be updated by taking the union of the two sets.

fun ref converge(
  that: DotContext box)
: Bool val

Parameters

Returns

compare

[Source]

Compare the dots in this causal context with those in the other one. Returns two boolean values, representing differences that are present. The first return value is true if this context has dots missing in that one. The other return value is true if that context has dots missing in this one.

fun box compare(
  that: DotContext box)
: (Bool val , Bool val)

Parameters

Returns

string

[Source]

Return a best effort at printing the data structure. This is intended for debugging purposes only.

fun box string()
: String iso^

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 box each_token(
  tokens: Tokens ref)
: None val

Parameters

Returns