Skip to content

sgns::crdt::GlobalDB

#include <globaldb.hpp>

Inherits from std::enable_shared_from_this< GlobalDB >

Public Classes

Name
struct BackupOptions

Public Types

Name
enum class uint8_t Error { ROCKSDB_IO = 0, IPFS_DB_NOT_CREATED, DAG_SYNCHER_NOT_LISTENING, CRDT_DATASTORE_NOT_CREATED, PUBSUB_BROADCASTER_NOT_CREATED, INVALID_PARAMETERS, GLOBALDB_NOT_STARTED}
Enumeration of error codes used in the proof classes.
using base::Buffer Buffer
using CrdtDatastore::QueryResult QueryResult
using storage::rocksdb RocksDB
using CrdtHeads::CRDTListResult CRDTHeadListResult
using std::pair< HierarchicalKey, Buffer > DataPair
Pair of key and value to be stored in CRDT.
using CrdtDatastore::CRDTElementFilterCallback GlobalDBFilterCallback
CRDT Filter callback type.
using CrdtDatastore::CRDTNewElementCallback GlobalDBNewElementCallback
using CrdtDatastore::CRDTDeletedElementCallback GlobalDBDeletedElementCallback

Public Functions

Name
outcome::result< std::shared_ptr< GlobalDB > > New(std::shared_ptr< boost::asio::io_context > context, std::string databasePath, std::shared_ptr< sgns::ipfs_pubsub::GossipPubSub > pubsub, std::shared_ptr< CrdtOptions > crdtOptions, std::shared_ptr< sgns::ipfs_lite::ipfs::graphsync::Network > graphsyncnetwork, std::shared_ptr< libp2p::basic::Scheduler > scheduler, std::shared_ptr< sgns::ipfs_lite::ipfs::graphsync::RequestIdGenerator > generator, std::shared_ptr< RocksDB > datastore =nullptr, BackupOptions backup_options =BackupOptions)
Factory method to create a GlobalDB instance.
~GlobalDB()
Destructor or GlobalDB.
outcome::result< CID > Put(const HierarchicalKey & key, const Buffer & value, const std::unordered_set< std::string > & topics)
Puts key-value pair to the CRDT store, optionally specifying a broadcast topic.
outcome::result< CID > Put(const std::vector< DataPair > & data_vector, const std::unordered_set< std::string > & topics)
Writes a batch of CRDT data all at once.
outcome::result< Buffer > Get(const HierarchicalKey & key)
outcome::result< CID > Remove(const HierarchicalKey & key, const std::unordered_set< std::string > & topics)
outcome::result< QueryResult > QueryKeyValues(std::string_view keyPrefix)
outcome::result< QueryResult > QueryKeyValues(const std::string & prefix_base, const std::string & middle_part, const std::string & remainder_prefix)
Queries with a middle part that can be a wildcard, negated string or normal string.
outcome::result< std::string > KeyToString(const Buffer & key) const
std::shared_ptr< AtomicTransaction > BeginTransaction()
outcome::result< void > AddBroadcastTopic(const std::string & topicName)
void AddTopicName(const std::string & topicName)
void AddListenTopic(const std::string & topicName)
void PrintDataStore()
std::shared_ptr< RocksDB > GetDataStore()
std::shared_ptr< sgns::crdt::PubSubBroadcasterExt > GetBroadcaster()
std::shared_ptr< CRDTWorkJournal > GetWorkJournal() const
bool RegisterElementFilter(const std::string & pattern, GlobalDBFilterCallback filter)
bool RegisterNewElementCallback(const std::string & pattern, GlobalDBNewElementCallback callback)
bool RegisterDeletedElementCallback(const std::string & pattern, GlobalDBDeletedElementCallback callback)
void UnregisterElementFilter(const std::string & pattern)
void UnregisterNewElementCallback(const std::string & pattern)
Unregisters the new element callback for a pattern.
void UnregisterDeletedElementCallback(const std::string & pattern)
Unregisters the deleted element callback for a pattern.
void Start()
Starts the GlobalDB instance.
void ShutdownNow()
Immediately quiesce and shut down CRDT intake and workers. Safe to call multiple times.
void StartCIDReceiving()
Starts receiving CIDs.
void StartCICSync()
Starts CIC synchronization.
void StartRebroadcastHeads()
Starts rebroadcasting heads.
outcome::result< CRDTHeadListResult > GetCRDTHeadList()
outcome::result< uint64_t > GetCRDTHeadHeight(const CID & aCid, const std::string & topic)
outcome::result< void > CRDTHeadRemove(const CID & aCid, const std::string & topic)
outcome::result< void > CRDTHeadAdd(const CID & aCid, const std::string & topic, uint64_t priority)
outcome::result< crdt::CrdtDatastore::JobStatus > GetCIDJobStatus(const CID & cid) const
outcome::result< void > RequestHeadBroadcast(const std::set< std::string > & topics)
Request head broadcast for specified topics.
outcome::result< std::unordered_set< std::string > > GetMonitoredTopics() const
Get the topics that are being listened to.
std::shared_ptr< crdt::CrdtDatastore > GetCRDTDataStore()
outcome::result< std::vector< std::pair< std::string, base::Buffer > > > GetCIDContent(const std::string & cid_string)

Public Types Documentation

enum Error

Enumerator Value Description
ROCKSDB_IO 0 RocksDB wasn't opened.
IPFS_DB_NOT_CREATED IPFS datastore not created.
DAG_SYNCHER_NOT_LISTENING DAG Syncher listen error.
CRDT_DATASTORE_NOT_CREATED CRDT DataStore not created.
PUBSUB_BROADCASTER_NOT_CREATED CRDT DataStore not created.
INVALID_PARAMETERS Invalid parameters.
GLOBALDB_NOT_STARTED Start wasn't called.

Enumeration of error codes used in the proof classes.

using Buffer

using sgns::crdt::GlobalDB::Buffer = base::Buffer;

using QueryResult

using sgns::crdt::GlobalDB::QueryResult = CrdtDatastore::QueryResult;

using RocksDB

using sgns::crdt::GlobalDB::RocksDB = storage::rocksdb;

using CRDTHeadListResult

using sgns::crdt::GlobalDB::CRDTHeadListResult = CrdtHeads::CRDTListResult;

using DataPair

using sgns::crdt::GlobalDB::DataPair = std::pair<HierarchicalKey, Buffer>;

Pair of key and value to be stored in CRDT.

using GlobalDBFilterCallback

using sgns::crdt::GlobalDB::GlobalDBFilterCallback = CrdtDatastore::CRDTElementFilterCallback;

CRDT Filter callback type.

using GlobalDBNewElementCallback

using sgns::crdt::GlobalDB::GlobalDBNewElementCallback = CrdtDatastore::CRDTNewElementCallback;

using GlobalDBDeletedElementCallback

using sgns::crdt::GlobalDB::GlobalDBDeletedElementCallback = CrdtDatastore::CRDTDeletedElementCallback;

Public Functions Documentation

function New

static outcome::result< std::shared_ptr< GlobalDB > > New(
    std::shared_ptr< boost::asio::io_context > context,
    std::string databasePath,
    std::shared_ptr< sgns::ipfs_pubsub::GossipPubSub > pubsub,
    std::shared_ptr< CrdtOptions > crdtOptions,
    std::shared_ptr< sgns::ipfs_lite::ipfs::graphsync::Network > graphsyncnetwork,
    std::shared_ptr< libp2p::basic::Scheduler > scheduler,
    std::shared_ptr< sgns::ipfs_lite::ipfs::graphsync::RequestIdGenerator > generator,
    std::shared_ptr< RocksDB > datastore =nullptr,
    BackupOptions backup_options =BackupOptions{ false, 15, 12, true }
)

Factory method to create a GlobalDB instance.

Parameters:

  • context The io context used to run its inner methods
  • databasePath Local system's path where data will be stored, not used if datastore is not nullptr
  • pubsub The pubsub instance used to communicate
  • crdtOptions CRDT options
  • graphsyncnetwork The graphsync networks used
  • scheduler libp2p scheduler
  • generator The request ID generator from graphsync
  • datastore datastore to be used. If not defined, created using databasePath
  • backup_options configuration for automatic backups of the CRDT data

Return: Instance of the GlobalDB initialized or Error

function ~GlobalDB

~GlobalDB()

Destructor or GlobalDB.

function Put

outcome::result< CID > Put(
    const HierarchicalKey & key,
    const Buffer & value,
    const std::unordered_set< std::string > & topics
)

Puts key-value pair to the CRDT store, optionally specifying a broadcast topic.

Parameters:

  • key The hierarchical key where the value should be stored.
  • value The value to store.
  • topics Topics to publish to.

Return: outcome::success on success, or outcome::failure otherwise.

function Put

outcome::result< CID > Put(
    const std::vector< DataPair > & data_vector,
    const std::unordered_set< std::string > & topics
)

Writes a batch of CRDT data all at once.

Parameters:

  • data_vector A set of crdt to be written in a single transaction
  • topics Topics to publish to.

Return: outcome::failure on error or success otherwise

function Get

outcome::result< Buffer > Get(
    const HierarchicalKey & key
)

Parameters:

  • key - value key

Return: value as a Buffer

Gets a value that corresponds to specified key.

function Remove

outcome::result< CID > Remove(
    const HierarchicalKey & key,
    const std::unordered_set< std::string > & topics
)

Parameters:

  • key to remove from storage
  • topics Topics to publish to

Return: outcome::failure on error or success otherwise

Removes value for a given key.

function QueryKeyValues

outcome::result< QueryResult > QueryKeyValues(
    std::string_view keyPrefix
)

Parameters:

  • keyPrefix - keys prefix to match. An empty prefix matches any key.

Return: list of key-value pairs matches prefix

Queries CRDT key-value pairs by prefix. If the prefix is empty returns all elements that were not tombstoned

function QueryKeyValues

outcome::result< QueryResult > QueryKeyValues(
    const std::string & prefix_base,
    const std::string & middle_part,
    const std::string & remainder_prefix
)

Queries with a middle part that can be a wildcard, negated string or normal string.

Parameters:

  • prefix_base The base prefix to query
  • middle_part Either a string (normal query), '*' or !string
  • remainder_prefix The remainder part of the query prefix

Return: A list of key value pairs

function KeyToString

outcome::result< std::string > KeyToString(
    const Buffer & key
) const

Parameters:

  • key - binary key to convert

Return: string represenation of a unique key part

Converts a unique key part to a string representation

function BeginTransaction

std::shared_ptr< AtomicTransaction > BeginTransaction()

Return: new transaction

Create a transaction object

function AddBroadcastTopic

outcome::result< void > AddBroadcastTopic(
    const std::string & topicName
)

function AddTopicName

void AddTopicName(
    const std::string & topicName
)

function AddListenTopic

void AddListenTopic(
    const std::string & topicName
)

function PrintDataStore

void PrintDataStore()

function GetDataStore

std::shared_ptr< RocksDB > GetDataStore()

function GetBroadcaster

std::shared_ptr< sgns::crdt::PubSubBroadcasterExt > GetBroadcaster()

function GetWorkJournal

std::shared_ptr< CRDTWorkJournal > GetWorkJournal() const

function RegisterElementFilter

bool RegisterElementFilter(
    const std::string & pattern,
    GlobalDBFilterCallback filter
)

Parameters:

  • pattern The pattern to match elements against.
  • filter The callback to invoke for matching elements.

Return: true if the filter was successfully registered, false otherwise.

Registers a filter callback for elements matching a pattern.

function RegisterNewElementCallback

bool RegisterNewElementCallback(
    const std::string & pattern,
    GlobalDBNewElementCallback callback
)

Parameters:

  • pattern The pattern to match new elements against.
  • callback The callback to invoke for matching new elements.

Return: true if the callback was successfully registered, false otherwise.

Registers a callback for new elements matching a pattern.

function RegisterDeletedElementCallback

bool RegisterDeletedElementCallback(
    const std::string & pattern,
    GlobalDBDeletedElementCallback callback
)

Parameters:

  • pattern The pattern to match deleted elements against.
  • callback The callback to invoke for matching deleted elements.

Return: true if the callback was successfully registered, false otherwise.

Registers a callback for deleted elements matching a pattern.

function UnregisterElementFilter

void UnregisterElementFilter(
    const std::string & pattern
)

Parameters:

  • pattern The pattern to unregister the filter for.

Unregisters the filter callback for a pattern.

function UnregisterNewElementCallback

void UnregisterNewElementCallback(
    const std::string & pattern
)

Unregisters the new element callback for a pattern.

Parameters:

  • pattern The pattern to unregister the new element callback for.

function UnregisterDeletedElementCallback

void UnregisterDeletedElementCallback(
    const std::string & pattern
)

Unregisters the deleted element callback for a pattern.

Parameters:

  • pattern The pattern to unregister the deleted element callback for.

function Start

void Start()

Starts the GlobalDB instance.

function ShutdownNow

void ShutdownNow()

Immediately quiesce and shut down CRDT intake and workers. Safe to call multiple times.

function StartCIDReceiving

void StartCIDReceiving()

Starts receiving CIDs.

function StartCICSync

void StartCICSync()

Starts CIC synchronization.

function StartRebroadcastHeads

void StartRebroadcastHeads()

Starts rebroadcasting heads.

function GetCRDTHeadList

outcome::result< CRDTHeadListResult > GetCRDTHeadList()

function GetCRDTHeadHeight

outcome::result< uint64_t > GetCRDTHeadHeight(
    const CID & aCid,
    const std::string & topic
)

function CRDTHeadRemove

outcome::result< void > CRDTHeadRemove(
    const CID & aCid,
    const std::string & topic
)

function CRDTHeadAdd

outcome::result< void > CRDTHeadAdd(
    const CID & aCid,
    const std::string & topic,
    uint64_t priority
)

function GetCIDJobStatus

outcome::result< crdt::CrdtDatastore::JobStatus > GetCIDJobStatus(
    const CID & cid
) const

function RequestHeadBroadcast

outcome::result< void > RequestHeadBroadcast(
    const std::set< std::string > & topics
)

Request head broadcast for specified topics.

Parameters:

  • topics Vector of topic names to broadcast heads for

Return: outcome::success on success, or outcome::failure on error

function GetMonitoredTopics

outcome::result< std::unordered_set< std::string > > GetMonitoredTopics() const

Get the topics that are being listened to.

Return: A set of the monitored topic names

function GetCRDTDataStore

std::shared_ptr< crdt::CrdtDatastore > GetCRDTDataStore()

function GetCIDContent

outcome::result< std::vector< std::pair< std::string, base::Buffer > > > GetCIDContent(
    const std::string & cid_string
)

Updated on 2026-06-28 at 18:54:57 -0700