Module: caf_sharing/SharedMap

A Shared Map provides a single writer/multiple reader dictionary with a distributed, replicated data structure.

Internally it uses persistent data structures (immutable.js) to maintain multiple versions in an efficient manner.

Multiple versions are needed because Sharing Actors require both Readers Isolation and Fairness for readers. Readers Isolation ensures that contents do not change during the processing of a message. Fairness allows local CAs to see the most recent locally available version, regardless of the behavior of other CAs.

CA message processing is always within a transaction, and changes to a Shared Map are part of that transaction. Therefore, changes wait for commit before they are externalized. Writer Atomicity guarantees that partial updates will never leak.

The consistency goals are read-your-writes for the single writer within a transaction. The other CAs have monotonic read consistency: no guarantees that they see the latest version, but they never see older versions.

Shared Maps can contain serialized functions (not closures) that can be evaluated as a method of the map, i.e., binding this to it, with applyMethod.

This implementation does NOT use ES6 Maps, and keys are always strings.

Source:

Methods

applyChanges(changes)

Applies a list of changes to keep the map up-to-date.

Parameters:
Name Type Description
changes mapUpdateType | Array.<mapUpdateType>

Deltas to be applied.

Source:
Throws:

If updates are invalid.

Type
Error

commit(ref)

Commits pending changes.

Parameters:
Name Type Description
ref refMapType

A reference to the map snapshot to be committed.

Source:
Throws:

If the map is read only, or there are no pending changes, or a concurrent update was detected.

Type
Error

getVersion(refopt) → {number}

Returns the current version of this map.

Parameters:
Name Type Attributes Description
ref refMapType <optional>

An optional reference to a map snapshot. It defaults to the current version.

Source:
Returns:

A version number.

Type
number

ref(readOnly) → {refMapType}

Returns a reference to a snapshot of the Shared Map.

Parameters:
Name Type Description
readOnly boolean

True if the reference should not allow changes.

Source:
Returns:

A reference to a Shared Map snapshot.

Type
refMapType

reset()

Resets this map.

The original state is lost, including pending commits.

Source:

toImmutableObject(refopt) → {Object}

Returns an Immutable.js map representing this object.

Parameters:
Name Type Attributes Description
ref refMapType <optional>

An optional reference to a map snapshot. It defaults to the current version.

Source:
Returns:

An Immutable.js map representing this object.

Type
Object

SharedMap(loggeropt, noExecopt, maxUpdatesopt)

Constructor.

A distributed, replicated dictionary with one writer and multiple readers.

Parameters:
Name Type Attributes Description
logger Object <optional>

A logger component to print warnings.

noExec boolean <optional>

True to disable execution of serialized methods.

maxUpdates number <optional>

The number of updates that should be remembered to facilitate client recovery. Beyond that a full dump is needed.

Source: