Class Monitor

Package: keychain.core.monitor

Inheritance: Monitor

Description

Monitor subscribes to block updates from the blockchain and updates the database cache state of personas and contacts. 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(db_path: str, 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

int

on_pause()

Pause the monitor thread

int

on_resume()

Run/resume the monitor thread

int

on_start()

Create the monitor thread if it did not exist

int

on_stop()

Stop and destroy the monitor thread if it exists

Public Member Functions Detail

on_pause

on_pause() → None

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

on_resume

on_resume() → None

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.

on_start

on_start() → None

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

on_stop

on_stop() → None

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 it.

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.