Class to manage a single distributed transaction (dtx) batch between shards. More...

#include <distributed_tx.hpp>

Public Types
enum class	dtx_state { start , prepare , commit , discard , done , failed }

using	discard_cb_t = std::function<bool(const hash_t&)>

using	done_cb_t = std::function<bool(const hash_t&)>

using	commit_cb_t

using	prepare_cb_t

Public Member Functions
	distributed_tx (const hash_t &dtx_id, std::vector< std::shared_ptr< locking_shard::interface > > shards, std::shared_ptr< logging::log > logger)
	Constructs a new transaction coordinator instance.

auto	execute () -> std::optional< std::vector< bool > >
	Executes the dtx batch to completion or failure, either from start, or an intermediate state if one of the recover functions were used.

auto	add_tx (const transaction::compact_tx &tx) -> size_t
	Adds a TX to the batch managed by this coordinator and dtx ID.

auto	get_id () const -> hash_t
	Returns the dtx ID associated with this coordinator instance.

void	set_prepare_cb (const prepare_cb_t &cb)
	Registers a callback to be called before starting the prepare phase of the dtx.

void	set_commit_cb (const commit_cb_t &cb)
	Registers a callback to be called before starting the commit phase of the dtx.

void	set_discard_cb (const discard_cb_t &cb)
	Registers a callback to be called before the discard phase of the dtx is started.

void	set_done_cb (const done_cb_t &cb)
	Registers a callback to be called before the done phase of the dtx is started.

void	recover_prepare (const std::vector< transaction::compact_tx > &txs)
	Sets the state of the dtx to prepare and re-adds all the txs included in the batch.

void	recover_commit (const std::vector< bool > &complete_txs, const std::vector< std::vector< uint64_t > > &tx_idxs)
	Sets the state of the dtx to commit and sets the state from the end of the prepare phase so that execute() will continue the commit phase.

void	recover_discard ()
	Sets the state of the dtx to discard so that execute() will start from the discard phase.

auto	size () const -> size_t
	Returns the number of transactions in the dtx.

auto	get_state () const -> dtx_state
	Returns the current state of the dtx.

Detailed Description

Class to manage a single distributed transaction (dtx) batch between shards.

Capable of recovering previously failed dtxs and sharing the results of each dtx phase with callback functions (usually for replication).

Definition at line 23 of file distributed_tx.hpp.

Member Typedef Documentation

◆ commit_cb_t

using cbdc::coordinator::distributed_tx::commit_cb_t

Initial value:

 std::function<bool(const hash_t&,
                                 const std::vector<bool>&,
                                 const std::vector<std::vector<uint64_t>>&)>

Definition at line 55 of file distributed_tx.hpp.

◆ discard_cb_t

using cbdc::coordinator::distributed_tx::discard_cb_t = std::function<bool(const hash_t&)>

Definition at line 53 of file distributed_tx.hpp.

◆ done_cb_t

using cbdc::coordinator::distributed_tx::done_cb_t = std::function<bool(const hash_t&)>

Definition at line 54 of file distributed_tx.hpp.

◆ prepare_cb_t

using cbdc::coordinator::distributed_tx::prepare_cb_t

Initial value:

std::function<bool(const hash_t&,

const std::vector<transaction::compact_tx>&)>

Definition at line 58 of file distributed_tx.hpp.

Member Enumeration Documentation

◆ dtx_state

enum class cbdc::coordinator::distributed_tx::dtx_state

strong

Enumerator
start	dtx initial state, no action has been performed yet
prepare	dtx is calling prepare on shards
commit	dtx is calling commit on shards
discard	dtx is calling discard on shards
done	dtx has completed fully
failed	dtx was interrupted and needs recovery. Shards will be left somewhere between states. For example, if the prepare phase has completed and the coordinator has started the commit phase, some shards will be committed and others could still be in the prepare phase. The dtx will need to be recovered from the start of the commit phase to ensure all shards are committed.

Definition at line 121 of file distributed_tx.hpp.

Constructor & Destructor Documentation

◆ distributed_tx()

cbdc::coordinator::distributed_tx::distributed_tx	(	const hash_t &	dtx_id,
		std::vector< std::shared_ptr< locking_shard::interface > >	shards,
		std::shared_ptr< logging::log >	logger )

Constructs a new transaction coordinator instance.

Parameters

dtx_id	dtx ID for this transaction batch
shards	vector of locking shards that will participate in the dtx. If recovering a previous dtx, the list must refer to the same shards in the same order.
logger	logger for messages.

Definition at line 11 of file distributed_tx.cpp.

Member Function Documentation

◆ add_tx()

auto cbdc::coordinator::distributed_tx::add_tx ( const transaction::compact_tx & tx ) -> size_t

Adds a TX to the batch managed by this coordinator and dtx ID.

Should not be used after calling execute().

Parameters

tx	compact transaction to add

Returns: the index of the transaction withing the dtx batch

Definition at line 147 of file distributed_tx.cpp.

Referenced by recover_prepare().

◆ execute()

auto cbdc::coordinator::distributed_tx::execute ( ) -> std::optional<std::vector<bool>>

nodiscard

Executes the dtx batch to completion or failure, either from start, or an intermediate state if one of the recover functions were used.

Returns: empty optional if the dtx failed, or a vector of flags indicating which constituent transactions settled and which were rolled back by the transaction's index in the batch.

Definition at line 109 of file distributed_tx.cpp.

References cbdc::to_string().

Here is the call graph for this function:

◆ get_id()

auto cbdc::coordinator::distributed_tx::get_id ( ) const -> hash_t

nodiscard

Returns the dtx ID associated with this coordinator instance.

Returns: dtx ID for this coordinator

Definition at line 218 of file distributed_tx.cpp.

◆ get_state()

auto cbdc::coordinator::distributed_tx::get_state ( ) const -> dtx_state

nodiscard

Returns the current state of the dtx.

Returns: state of the dtx

Definition at line 262 of file distributed_tx.cpp.

◆ recover_commit()

void cbdc::coordinator::distributed_tx::recover_commit	(	const std::vector< bool > &	complete_txs,
		const std::vector< std::vector< uint64_t > > &	tx_idxs )

Sets the state of the dtx to commit and sets the state from the end of the prepare phase so that execute() will continue the commit phase.

Parameters

complete_txs	vector of flags indicating which transactions in the batch to complete or cancel. The return value from the prepare phase.
tx_idxs	vector for each shard indicating which txs in the complete_txs vector apply to each shard. Generated before the prepare phase.

Definition at line 246 of file distributed_tx.cpp.

References commit.

◆ recover_discard()

void cbdc::coordinator::distributed_tx::recover_discard ( )

Sets the state of the dtx to discard so that execute() will start from the discard phase.

Definition at line 254 of file distributed_tx.cpp.

References discard.

◆ recover_prepare()

void cbdc::coordinator::distributed_tx::recover_prepare ( const std::vector< transaction::compact_tx > & txs )

Sets the state of the dtx to prepare and re-adds all the txs included in the batch.

Parameters

txs	list of txs included in the dtx batch

Definition at line 238 of file distributed_tx.cpp.

References add_tx(), and prepare.

Here is the call graph for this function:

◆ set_commit_cb()

void cbdc::coordinator::distributed_tx::set_commit_cb ( const commit_cb_t & cb )

Registers a callback to be called before starting the commit phase of the dtx.

Parameters

cb callback function taking the dtx ID, a vector of flags indicating which transactions to complete, and a vector of vectors indicating the indexes for each shard included in the complete transactions vector. Returns true if the callback operation was successful. Returning false halts further execution of the dtx and sets the dtx state to failed.

Definition at line 226 of file distributed_tx.cpp.

◆ set_discard_cb()

void cbdc::coordinator::distributed_tx::set_discard_cb ( const discard_cb_t & cb )

Registers a callback to be called before the discard phase of the dtx is started.

Parameters

cb	callback function taking the dtx ID as argument and returning true if the callback operation was successful. Returning false halts further execution of the dtx and sets the dtx state to failed.

Definition at line 230 of file distributed_tx.cpp.

◆ set_done_cb()

void cbdc::coordinator::distributed_tx::set_done_cb ( const done_cb_t & cb )

Registers a callback to be called before the done phase of the dtx is started.

Parameters

cb	callback function taking the dtx ID as argument and returning true if the callback operation was successful. Returning false halts further execution of the dtx and sets the dtx state to failed.

Definition at line 234 of file distributed_tx.cpp.

◆ set_prepare_cb()

void cbdc::coordinator::distributed_tx::set_prepare_cb ( const prepare_cb_t & cb )

Registers a callback to be called before starting the prepare phase of the dtx.

Parameters

cb	callback function taking the dtx ID and a vector of transactions in the dtx. Returns true if the callback operation was successful. Returning false halts further execution of the dtx and sets the dtx state to failed.

Definition at line 222 of file distributed_tx.cpp.

◆ size()

auto cbdc::coordinator::distributed_tx::size ( ) const -> size_t

nodiscard

Returns the number of transactions in the dtx.

Returns: number of transactions in the batch

Definition at line 258 of file distributed_tx.cpp.

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

Public Types

Public Member Functions

Detailed Description

Member Typedef Documentation

◆ commit_cb_t

◆ discard_cb_t

◆ done_cb_t

◆ prepare_cb_t

Member Enumeration Documentation

◆ dtx_state

Constructor & Destructor Documentation

◆ distributed_tx()

Member Function Documentation

◆ add_tx()

◆ execute()

◆ get_id()

◆ get_state()

◆ recover_commit()

◆ recover_discard()

◆ recover_prepare()

◆ set_commit_cb()

◆ set_discard_cb()

◆ set_done_cb()

◆ set_prepare_cb()

◆ size()