Provide a description of the software system, including its functionality and matters relating to the overall system and design. Feel free to split this up into subsections, or use data flow diagrams or process flow diagrams.
ISpace is an abstraction that allows a client to perform high-level actions (produce & consume) on an underlying tuplespace implementation.
The only implementation available is RSpace. It's core characteristics are:
- It holds an LMDBStore instance (LMDB backed IStore implementation)
- It holds an LMDBTrieStore instance (LMDB backed ITrieStore implementation)
- It holds a Log instance
- It requires four
serializers to be in scope
Serialize[C] for channels
Serialize[P] for patterns
Serialize[A] for data
Serialize[K] for continuations
The LMDBStore sits directly on the LMDB database. It introduces low level entities:
and according CRUD actions for each.
Internally, entities are bundled in GNATs.
Each action requires a transaction to be open.
LMDBStore allows checkpoint creation.
This is required to allow #rollback.
The StoreEventsCounter gathers metrics.
The LMDBStore depends on Codecs for base entities. These can be derived from
On the lowest level the LMDBStore relies on the available codecs to encode/decode data.
The underlying LMDB instance is divided into:
Additional tracking structures:
This structure is used as part of the checkpoint & rollback mechanism.
The LMDBStore holds an instance of LMDBTrieStore. This is used as the store to keep checkpoints.
The available implementation is based on Merkle Patricia Trie.
The underlying store is split into:
The root db holds the current root, and tries holds all the pieces of data.
This implementation uses the concept of Skip (Extension) Nodes.
Assumptions and Dependencies
Lightning Memory-mapped Database
"An ultra-fast, ultra-compact, crash-proof key-value embedded data store."
http://www.lmdb.tech/doc/index.html (Doxygen documentation for C version)
JNR-FFI Wrapper Library for use from Scala
Protocol Buffers (serialization format)
"...are a language-neutral, platform-neutral extensible mechanism for serializing structured data."
Both Rholang objects and Blockchain blocks will be serialized to and deserialized from binary using the Protocol Buffer serialization format.
The serialized data will be stored in LMDB as the value portion of the key-value pair.
"...is a protocol buffer compiler plugin for Scala. It will generate Scala case classes, parsers and serializers for your protocol buffers."
We use Kamon as our monitoring toolkit. Below is the overview of metrics published by RSpace:
* COMM event counters distinguished by the operation which triggered the event:
* Spans tracing execution times of all operations:
Analogous metrics exist for the ReplayRSpace.
These metrics are published by Kamon in a Prometheus format so they can be scraped by the latter. Prometheus is configured as the data source in Grafana, allowing us to query the time series using the built-in expression language and visualize them.
To find the number of COMM events per second triggered by produce operations use: rate(rspace_comm_produce_total[1m])
"rspace_comm_produce_total[1m]" - converts the time series to a range vector containing data points gathered over the last minute
The "rate" function calculates the per second average rate of increase of the time series in the range vector
Number of COMM events per second triggered by consume operations is defined analogously.