OpenCBDC Transaction Processor
Loading...
Searching...
No Matches
cbdc::coordinator::distributed_tx Class Reference

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

Initial value:
std::function<bool(const hash_t&,
const std::vector<bool>&,
const std::vector<std::vector<uint64_t>>&)>
std::array< unsigned char, cbdc::hash_size > hash_t
SHA256 hash container.

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

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

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_iddtx ID for this transaction batch
shardsvector 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.
loggerlogger 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
txcompact 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_txsvector of flags indicating which transactions in the batch to complete or cancel. The return value from the prepare phase.
tx_idxsvector 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
txslist 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
cbcallback 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
cbcallback 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
cbcallback 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
cbcallback 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: