Module: caf_components/gen_transactional

A transactional plug to manage internal state safely.

CAF goal is to create and manage billions of long running, active, stateful proxies, i.e., CAs, where "long running" means years. In order to tolerate -without human intervention- failures, upgrades, migration, or other errors, the CA state has to be managed carefully.

A complication is that CA state is not only application state, but state associated with the plugins that the application uses.

Also, CAF always ensures that CA state is consistent with the externalized view of that state, i.e., CA actions that affect the external world.

For example, if a CA sends a message, and it keeps track of sent messages in its internal state, even in the presence of failures it should never forget that it sent that message.

CAF approach assumes:

  1. Operations that affect the external world are mediated by a plugin that makes them idempotent.

  2. Plugins defer these operations until commit time, ensuring that, before execution, a persistent record of them has been checkpointed to an external service.

  3. All plugins and application code coordinate using a two-phase commit protocol, so that disaggregated state is managed consistently.

  4. During recovery the last committed state is reloaded, and deferred operations in the checkpoint are retried until they succeed.

Methods __ca_setLogActionsTarget__ and __ca_lazyApply__ defer methods.

Methods __ca_init__ and __ca_resume__ handle initialization and recovery.

Methods __ca_begin__, __ca_prepare__, __ca_commit__ and __ca_abort__ implement the two-phase commit protocol.

Source:

Extends

Members

__ca_isTransactional__ :boolean

Run-time type information.

Type:
  • boolean
Source:

Methods

(static) constructor($, spec) → {Object}

Helper constructor method for a transactional component.

Description of types in file types.js.

Parameters:
Name Type Description
$ ctxType

A context containing references to other components.

spec specType

Configuration data for this component.

Source:
Throws:

If inputs are invalid.

Type
Error
Returns:

A new generic component.

Type
Object

__ca_abort__(cb)

Aborts the transaction.

CAF calls this method when an error was returned by the handler, or any transactional plugs propagated an error during prepare.

Note that an error during remote checkpointing cannot guarantee that the checkpoint was not made durable, and we need to assume that it did. This means that we need to shutdown the CA.

An implementation of this method should undo state changes and ignore deferred operations.

Parameters:
Name Type Description
cb cbType

A callback to continue after aborting.

Source:

__ca_begin__(msg, cb)

Begins a two phase commit transaction.

CAF calls this method before the application handler processes a message. A read-only copy of the message is passed as an argument to facilitate configuration.

Parameters:
Name Type Description
msg Object

The message to be processed.

cb cbType

A callback to continue the transaction.

Source:

__ca_commit__(cb)

Commits the transaction.

Called by CAF when all the prepare calls to transactional plugs were successful, and the new state of those plugs has been checkpointed using an external service.

An error during commit will shutdown the CA since we cannot abort committed transactions. See module:caf_components/gen_transactional#__ca_resume__ for the recovery strategy.

Parameters:
Name Type Description
cb cbType

A callback to continue after commiting.

Source:

__ca_init__(cb)

Initializes the state of this plug from scratch.

This method is called only once, when the plug is created.

Parameters:
Name Type Description
cb cbType

A callback to continue after initialization.

Source:

__ca_lazyApply__(method, args)

Queues an operation to be executed at commit time.

Internally, operations are made asynchronous and executed serially by adding an extra callback. The actual implementation of these operations is delegated to the logActionsTarget object.

Operations are assumed to be idempotent.

Parameters:
Name Type Description
method string

A method name to execute.

args Array.<any>

An array of method arguments.

Source:

__ca_prepare__(cb)

Prepares to commit the transaction.

CAF calls this method after the handler has succesfully processed the message.

If ready to commit, it returns in the callback a JSON serializable data structure reflecting the new state after processing the message.

Then, CAF checkpoints this data structure using a remote service.

To abort the transaction we return an error in the (node.js) callback. This will abort all the transactional plugs associated with the CA.

Parameters:
Name Type Description
cb cbType

A callback to continue or abort the transaction.

Source:

__ca_resume__(cp, cb)

Reloads the state of this plug from a previous checkpoint.

It also retries deferred operations in the checkpoint.

This method is called many times, for example, after recovering from a failure or restarting after migration.

Parameters:
Name Type Description
cp Object

The last checkpoint of the state of this plug.

cb cbType

A callback to continue after resuming.

Source:

__ca_setLogActionsTarget__(obj)

Sets a receiver object implementing all the delayed methods.

Parameters:
Name Type Description
obj Object

A receiver for delayed methods.

Source: