Interface for a broker. More...

#include <interface.hpp>

Inheritance diagram for cbdc::parsec::broker::interface:

Public Types
enum class	error_code : uint8_t { ticket_number_assignment , unknown_ticket , prepared , shard_unreachable , ticket_machine_unreachable , committed , not_prepared , begun , aborted , directory_unreachable , invalid_shard_state , waiting_for_locks , commit_error , rollback_error , prepare_error , finish_error , get_tickets_error , commit_hazard }
	Error codes returned by broker operations. More...

using	ticketnum_or_errcode_type = std::variant<ticket_number_type, error_code>
	Return type from a begin operation.

using	begin_callback_type = std::function<void(ticketnum_or_errcode_type)>
	Callback function type for a begin operation.

using	try_lock_return_type
	Return type from a try lock operation.

using	try_lock_callback_type = std::function<void(try_lock_return_type)>
	Callback function type for a try lock operation.

using	commit_return_type
	Return type from a commit operation.

using	commit_callback_type = std::function<void(commit_return_type)>
	Callback function type for a commit operation.

using	finish_return_type = std::optional<error_code>
	Return type from a finish operation.

using	finish_callback_type = std::function<void(finish_return_type)>
	Callback function type for a finish operation.

using	rollback_return_type
	Return type from a rollback operation.

using	rollback_callback_type = std::function<void(rollback_return_type)>
	Callback function type for a rollback operation.

using	recover_return_type = std::optional<error_code>
	Return type from a recover operation.

using	recover_callback_type = std::function<void(recover_return_type)>
	Callback function type for a recovery operation.

Public Member Functions
virtual	~interface ()=default

	interface ()=default

	interface (const interface &)=delete

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

	interface (interface &&)=delete

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

virtual auto	begin (begin_callback_type result_callback) -> bool=0
	Acquires a new ticket number to begin a transaction.

virtual auto	try_lock (ticket_number_type ticket_number, key_type key, lock_type locktype, try_lock_callback_type result_callback) -> bool=0
	Attempts to acquire the given lock on the appropriate shard.

virtual auto	commit (ticket_number_type ticket_number, state_update_type state_updates, commit_callback_type result_callback) -> bool=0
	Prepares and commits a ticket on all shards involved in the ticket.

virtual auto	finish (ticket_number_type ticket_number, finish_callback_type result_callback) -> bool=0
	Finishes a ticket on all shards involved in the ticket.

virtual auto	rollback (ticket_number_type ticket_number, rollback_callback_type result_callback) -> bool=0
	Rollback a ticket on all shards involved in the ticket.

virtual auto	recover (recover_callback_type result_callback) -> bool=0
	Retrieves tickets associated with this broker from all shards and completes partially committed tickets, and rolls back uncommitted tickets.

virtual auto	highest_ticket () -> ticket_number_type=0
	Get the highest ticket number that was used.

Detailed Description

Interface for a broker.

Abstracts and simplified the three-phase commit protocol between multiple shards so that they behave as if there is only one shard. Handles recovery of tickets managed by a particular broker instance if the instance fails while tickets are in flight.

Definition at line 31 of file parsec/broker/interface.hpp.

Member Typedef Documentation

◆ begin_callback_type

using cbdc::parsec::broker::interface::begin_callback_type = std::function<void(ticketnum_or_errcode_type)>

Callback function type for a begin operation.

Definition at line 89 of file parsec/broker/interface.hpp.

◆ commit_callback_type

using cbdc::parsec::broker::interface::commit_callback_type = std::function<void(commit_return_type)>

Callback function type for a commit operation.

Definition at line 124 of file parsec/broker/interface.hpp.

◆ commit_return_type

using cbdc::parsec::broker::interface::commit_return_type

Initial value:

std::optional<

std::variant<error_code, runtime_locking_shard::shard_error>>

Return type from a commit operation.

Broker or shard error code, if applicable.

Definition at line 121 of file parsec/broker/interface.hpp.

◆ finish_callback_type

using cbdc::parsec::broker::interface::finish_callback_type = std::function<void(finish_return_type)>

Callback function type for a finish operation.

Definition at line 141 of file parsec/broker/interface.hpp.

◆ finish_return_type

using cbdc::parsec::broker::interface::finish_return_type = std::optional<error_code>

Return type from a finish operation.

Broker error code, if applicable.

Definition at line 139 of file parsec/broker/interface.hpp.

◆ recover_callback_type

using cbdc::parsec::broker::interface::recover_callback_type = std::function<void(recover_return_type)>

Callback function type for a recovery operation.

Definition at line 172 of file parsec/broker/interface.hpp.

◆ recover_return_type

using cbdc::parsec::broker::interface::recover_return_type = std::optional<error_code>

Return type from a recover operation.

Broker error code, if applicable.

Definition at line 170 of file parsec/broker/interface.hpp.

◆ rollback_callback_type

using cbdc::parsec::broker::interface::rollback_callback_type = std::function<void(rollback_return_type)>

Callback function type for a rollback operation.

Definition at line 157 of file parsec/broker/interface.hpp.

◆ rollback_return_type

using cbdc::parsec::broker::interface::rollback_return_type

Initial value:

std::optional<

std::variant<error_code, runtime_locking_shard::error_code>>

Return type from a rollback operation.

Broker or shard error code, if applicable.

Definition at line 154 of file parsec/broker/interface.hpp.

◆ ticketnum_or_errcode_type

using cbdc::parsec::broker::interface::ticketnum_or_errcode_type = std::variant<ticket_number_type, error_code>

Return type from a begin operation.

Either a new ticket number or an error code.

Definition at line 87 of file parsec/broker/interface.hpp.

◆ try_lock_callback_type

using cbdc::parsec::broker::interface::try_lock_callback_type = std::function<void(try_lock_return_type)>

Callback function type for a try lock operation.

Definition at line 104 of file parsec/broker/interface.hpp.

◆ try_lock_return_type

using cbdc::parsec::broker::interface::try_lock_return_type

Initial value:

 std::variant<value_type,
                           error_code,
                           runtime_locking_shard::shard_error>

Return type from a try lock operation.

Either the value associated with the requested key, a broker error, or a shard error.

Definition at line 100 of file parsec/broker/interface.hpp.

Member Enumeration Documentation

◆ error_code

enum class cbdc::parsec::broker::interface::error_code : uint8_t

strong

Error codes returned by broker operations.

Enumerator
ticket_number_assignment	Error during ticket number assignment.
unknown_ticket	Request for an unknown ticket.
prepared	Request invalid because ticket is prepared.
shard_unreachable	Request failed because a shard was unreachable.
ticket_machine_unreachable	Request failed because the ticket machine was unreachable.
committed	Reqeust invalid because ticket is committed.
not_prepared	Request invalid because ticket is not prepared.
begun	Request invalid because ticket is not committed or rolled back.
aborted	Request invalid because ticket is rolled back.
directory_unreachable	Request failed because directory was unreachable.
invalid_shard_state	Request failed because shard was in an invalid state for the given ticket.
waiting_for_locks	Cannot prepare because ticket still waiting for locks to be acquired.
commit_error	Shard error during commit.
rollback_error	Shard error during rollback.
prepare_error	Shard error during prepare.
finish_error	Shard error during finish.
get_tickets_error	Shard error during get tickets.
commit_hazard	A commit is attempted without associating update keys with ticket.

Definition at line 42 of file parsec/broker/interface.hpp.

Constructor & Destructor Documentation

◆ ~interface()

virtual cbdc::parsec::broker::interface::~interface ( )

virtualdefault

◆ interface() [1/3]

cbdc::parsec::broker::interface::interface ( )

default

◆ interface() [2/3]

cbdc::parsec::broker::interface::interface ( const interface & )

delete

◆ interface() [3/3]

cbdc::parsec::broker::interface::interface ( interface && )

delete

Member Function Documentation

◆ begin()

virtual auto cbdc::parsec::broker::interface::begin ( begin_callback_type result_callback ) -> bool

nodiscardpure virtual

Acquires a new ticket number to begin a transaction.

Parameters

result_callback function to call with begin result.

Returns: true if the operation was initiated successfully.

Implemented in cbdc::parsec::broker::impl.

◆ commit()

virtual auto cbdc::parsec::broker::interface::commit	(	ticket_number_type	ticket_number,
		state_update_type	state_updates,
		commit_callback_type	result_callback ) -> bool

nodiscardpure virtual

Prepares and commits a ticket on all shards involved in the ticket.

Parameters

ticket_number	ticket number.
state_updates	state updates to commit.
result_callback	function to call with commit result.

Returns: true if the operation was initiated successfully.

Implemented in cbdc::parsec::broker::impl.

◆ finish()

virtual auto cbdc::parsec::broker::interface::finish	(	ticket_number_type	ticket_number,
		finish_callback_type	result_callback ) -> bool

nodiscardpure virtual

Finishes a ticket on all shards involved in the ticket.

Parameters

ticket_number	ticket number.
result_callback	function to call with finish result.

Returns: true if the operation was initiated successfully.

Implemented in cbdc::parsec::broker::impl.

◆ highest_ticket()

virtual auto cbdc::parsec::broker::interface::highest_ticket ( ) -> ticket_number_type

pure virtual

Get the highest ticket number that was used.

This is not to be used for calculating a next ticket number, but is used to calculate the pretend height of the chain in the evm runner, which is derived from ticket numbers

Returns: highest ticket number that was used

Implemented in cbdc::parsec::broker::impl.

◆ operator=() [1/2]

auto cbdc::parsec::broker::interface::operator= ( const interface & ) -> interface &=delete

delete

◆ operator=() [2/2]

auto cbdc::parsec::broker::interface::operator= ( interface && ) -> interface &=delete

delete

◆ recover()

virtual auto cbdc::parsec::broker::interface::recover ( recover_callback_type result_callback ) -> bool

nodiscardpure virtual

Retrieves tickets associated with this broker from all shards and completes partially committed tickets, and rolls back uncommitted tickets.

Finishes all tickets.

Parameters

result_callback function to call with recovery result.

Returns: true if the operation was initated successfully.

Implemented in cbdc::parsec::broker::impl.

◆ rollback()

virtual auto cbdc::parsec::broker::interface::rollback	(	ticket_number_type	ticket_number,
		rollback_callback_type	result_callback ) -> bool

nodiscardpure virtual

Rollback a ticket on all shards involved in the ticket.

Parameters

ticket_number	ticket number.
result_callback	function to call with rollback result.

Returns: true if the operation was initiated successfully.

Implemented in cbdc::parsec::broker::impl.

◆ try_lock()

virtual auto cbdc::parsec::broker::interface::try_lock	(	ticket_number_type	ticket_number,
		key_type	key,
		lock_type	locktype,
		try_lock_callback_type	result_callback ) -> bool

nodiscardpure virtual

Attempts to acquire the given lock on the appropriate shard.

Parameters

ticket_number	ticket number.
key	key to lock.
locktype	type of lock to acquire.
result_callback	function to call with try lock result.

Returns: true if the operation was initiated successfully.

Implemented in cbdc::parsec::broker::impl.

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

parsec/broker/interface.hpp

Public Types

Public Member Functions

Detailed Description

Member Typedef Documentation

◆ begin_callback_type

◆ commit_callback_type

◆ commit_return_type

◆ finish_callback_type

◆ finish_return_type

◆ recover_callback_type

◆ recover_return_type

◆ rollback_callback_type

◆ rollback_return_type

◆ ticketnum_or_errcode_type

◆ try_lock_callback_type

◆ try_lock_return_type

Member Enumeration Documentation

◆ error_code

Constructor & Destructor Documentation

◆ ~interface()

◆ interface() [1/3]

◆ interface() [2/3]

◆ interface() [3/3]

Member Function Documentation

◆ begin()

◆ commit()

◆ finish()

◆ highest_ticket()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ recover()

◆ rollback()

◆ try_lock()