In-memory implementation of interface and status_interface. More...

#include <locking_shard.hpp>

Inheritance diagram for cbdc::locking_shard::locking_shard:

[legend]

Collaboration diagram for cbdc::locking_shard::locking_shard:

[legend]

Public Member Functions
	locking_shard (const std::pair< uint8_t, uint8_t > &output_range, std::shared_ptr< logging::log > logger, size_t completed_txs_cache_size, const std::string &preseed_file, config::options opts)
	Constructor.

	locking_shard ()=delete

auto	lock_outputs (std::vector< tx > &&txs, const hash_t &dtx_id) -> std::optional< std::vector< bool > > final
	Attempts to lock the input hashes for the given batch of transactions.

auto	apply_outputs (std::vector< bool > &&complete_txs, const hash_t &dtx_id) -> bool final
	Selectively applies the transactions from a previous lock operation.

auto	discard_dtx (const hash_t &dtx_id) -> bool final
	Discards any cached information about a given distributed transaction.

void	stop () final
	Stops the locking shard from processing further commands.

auto	check_unspent (const hash_t &uhs_id) -> std::optional< bool > final
	Queries whether the shard's UHS contains the given UHS ID.

auto	check_tx_id (const hash_t &tx_id) -> std::optional< bool > final
	Queries whether the given TX ID is confirmed in the cache of recently confirmed TX IDs.

Public Member Functions inherited from cbdc::locking_shard::interface
	interface (std::pair< uint8_t, uint8_t > output_range)
	Constructor.

virtual	~interface ()=default

	interface ()=delete

	interface (const interface &)=delete

auto	operator= (const interface &) -> interface &=delete

	interface (interface &&)=delete

auto	operator= (interface &&) -> interface &=delete

virtual auto	hash_in_shard_range (const hash_t &h) const -> bool
	Returns whether a given hash is within the shard's range.

Public Member Functions inherited from cbdc::locking_shard::status_interface
	status_interface ()=default

virtual	~status_interface ()=default

	status_interface (const status_interface &)=default

auto	operator= (const status_interface &) -> status_interface &=default

	status_interface (status_interface &&)=default

auto	operator= (status_interface &&) -> status_interface &=default

Detailed Description

In-memory implementation of interface and status_interface.

Warning: Not thread safe. Implements a UHS through conservative two-phase locking. Callers atomically check a batch of prospective transactions for spendable input UHS IDs in this shard's range, and lock those UHS IDs. Based on confirming responses from other shards, callers specify which transactions to complete and which to abort. Shards use a unique batch ID to track each batch across lock and apply (completion) operations to allow for parallel batch processing. The completed transactions cache allows users to determine whether a given transaction ID has been recently applied in the system. This is useful for recipients in a transaction to verify that the transaction has completed, or if the sender disconnects from the sentinel before receiving a response.

Definition at line 44 of file locking_shard.hpp.

Constructor & Destructor Documentation

◆ locking_shard() [1/2]

cbdc::locking_shard::locking_shard::locking_shard	(	const std::pair< uint8_t, uint8_t > &	output_range,
		std::shared_ptr< logging::log >	logger,
		size_t	completed_txs_cache_size,
		const std::string &	preseed_file,
		config::options	opts )

Constructor.

Parameters

output_range	inclusive range of hash prefixes this shard is responsible for.
logger	log instance.
completed_txs_cache_size	number of confirmed TX IDs to keep before evicting the oldest TX ID.
preseed_file	path to file containing shard pre-seeding data or empty string to disable pre-seeding.
opts	configuration options.

Definition at line 24 of file locking_shard.cpp.

◆ locking_shard() [2/2]

cbdc::locking_shard::locking_shard::locking_shard ( )

delete

Member Function Documentation

◆ apply_outputs()

auto cbdc::locking_shard::locking_shard::apply_outputs	(	std::vector< bool > &&	complete_txs,
		const hash_t &	dtx_id ) -> bool

finalvirtual

Selectively applies the transactions from a previous lock operation.

Follows confirmation from other shards via the coordinator. Completes a previous lock operation by deleting the input hashes and adding the output hashes of confirmed transactions, and unlocking the input hashes of aborted transactions. Preceded by a lock operation with the same dtx_id.

Parameters

complete_txs	vector of truth values indicating which txs from the previous lock operation the shard should apply (`true`), and which it should cancel (`false`). Must have the same size and order as txs from lock.
dtx_id	distributed transaction ID of the previous lock operation.

Returns: true if the apply operation succeeded.

Implements cbdc::locking_shard::interface.

Definition at line 135 of file locking_shard.cpp.

References cbdc::transaction::compact_tx::m_id, cbdc::transaction::compact_tx::m_inputs, cbdc::locking_shard::tx::m_tx, cbdc::transaction::compact_tx::m_uhs_outputs, and cbdc::to_string().

Here is the call graph for this function:

◆ check_tx_id()

auto cbdc::locking_shard::locking_shard::check_tx_id ( const hash_t & tx_id ) -> std::optional<bool>

nodiscardfinalvirtual

Queries whether the given TX ID is confirmed in the cache of recently confirmed TX IDs.

Parameters

tx_id TX ID to query.

Returns: true if cache contains TX ID, or false if not. std::nullopt if the query failed.

Implements cbdc::locking_shard::status_interface.

Definition at line 195 of file locking_shard.cpp.

◆ check_unspent()

auto cbdc::locking_shard::locking_shard::check_unspent ( const hash_t & uhs_id ) -> std::optional<bool>

nodiscardfinalvirtual

Queries whether the shard's UHS contains the given UHS ID.

Parameters

uhs_id UHS ID to query.

Returns: true if the UHS ID is unspent, false if not. std::nullopt if the query failed.

Implements cbdc::locking_shard::status_interface.

Definition at line 188 of file locking_shard.cpp.

◆ discard_dtx()

auto cbdc::locking_shard::locking_shard::discard_dtx ( const hash_t & dtx_id ) -> bool

finalvirtual

Discards any cached information about a given distributed transaction.

Called as the final step of a distributed transaction once all other participating shards have finished processing apply_outputs.

Parameters

dtx_id distributed transaction ID of a previous apply command.

Returns: true if the discard operation succeeded.

Implements cbdc::locking_shard::interface.

Definition at line 15 of file locking_shard.cpp.

◆ lock_outputs()

auto cbdc::locking_shard::locking_shard::lock_outputs	(	std::vector< tx > &&	txs,
		const hash_t &	dtx_id ) -> std::optional<std::vector<bool>>

finalvirtual

Attempts to lock the input hashes for the given batch of transactions.

Only considers input hashes within this shard's range. The batch of transactions is a single distributed transaction, or 'dtx'. The coordinator that communicates with instances of this class provides a globally unique dtx ID along for each dtx. The provided vector of transactions may be a subset of the overall batch only including transactions relevant to this shard.

Parameters

txs	list of txs to attempt to lock.
dtx_id	distributed tx ID for lock operation.

Returns: if lock succeeds, return a vector of flags corresponding to the txs in the input which had their relevant input hashes locked by the shard. Otherwise std::nullopt.

Implements cbdc::locking_shard::interface.

Definition at line 78 of file locking_shard.cpp.

◆ stop()

void cbdc::locking_shard::locking_shard::stop ( )

finalvirtual

Stops the locking shard from processing further commands.

Any future calls to methods of this class will return a failure result.

Implements cbdc::locking_shard::interface.

Definition at line 184 of file locking_shard.cpp.

The documentation for this class was generated from the following files:

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ locking_shard() [1/2]

◆ locking_shard() [2/2]

Member Function Documentation

◆ apply_outputs()

◆ check_tx_id()

◆ check_unspent()

◆ discard_dtx()

◆ lock_outputs()

◆ stop()