Class monitor

#include <keychain/monitor/monitor.hpp>

Namespace: keychain

Inheritance: monitor

Description

monitor subscribes to block updates from the blockchain and updates the database cache state of persona and contact accordingly. monitor updates attributes such as number of confirmations, public keys and metadata, certificate transaction data. A thread for monitoring the blockchain state is created in the on_start() method.

Method on_* names should be read as "what the monitor should do in response to the underlying execution environment entering the specified state". For instance, you should call on_start once your activity/application has been started.

Specifically, note that the monitor thread is not started during on_start; it is merely created. This is because some execution environments (namely mobile device environments) prefer to decouple the creation and start states of applications and intend the start process to be as lightweight as possible. You would call on_resume to actually start the thread, generally an action corresponding to an application state being "resumed".

Without at least one monitor the gateway will run out of sync with the blockchain and will cause the gateway to not be able to perform cryptographic operations properly on subsequent data. Thus, you should ensure that a monitor is instantiated within the current Activity.

Since: v2.0

Public Constructors

Constructor

monitor(std::string db_path, kc::settings settings)

Creates a monitor with the given settings parameters for connecting to the blockchain and db_path pointing to a Keychain database.

Public Member Functions

Return type Method and Description

kc::code

on_pause()

Pause the monitor thread

kc::code

on_resume()

Run/resume the monitor thread

kc::code

on_start()

Create the monitor thread if it did not exist

kc::code

on_stop()

Stop and destroy the monitor thread if it exists

Public Member Functions Detail

on_pause

kc::code on_pause()

Pause the monitor thread. Block the monitor thread if it was unblocked and running. The thread will remain blocked until on_resume() is called.

Returns:

The Keychain library error code indicating success or failure

on_resume

kc::code on_resume()

Run/resume the monitor thread. This method starts/unblocks the monitor thread if it was blocked or not running. If the thread does not exist upon calling on_resume(), on_resume() will call on_start() to create the thread. The thread will remain running until on_pause() is called.

Returns:

The Keychain library error code indicating success or failure

on_start

kc::code on_start()

Create the monitor thread if it did not exist. Note that this does not start the thread. Use on_resume() to do that

Returns:

The Keychain library error code indicating success or failure

on_stop

kc::code on_stop()

Stop and destroy the monitor thread if it exists. If the thread is running upon entry in this method, this method will (safely) cause the thread to stop execution before destroying the thread.

As of this version of the library, the worst-case complexity of the stopping process is linear in the number of blockchain certificates and addresses that exist in the database. We expect to reduce this to logarithmic if not constant time in a subsequent release. Until then, some environments (particularly mobile environments) may incur delays in switching activity/application contexts during long-running and stress-test scenarios.

Returns:

The Keychain library error code indicating success or failure

Thread Safety

This class is fully thread-safe; any of its methods may be invoked in multiple threads concurrently.

Idempotence

This class’s methods are idempotent.