Interface for a runtime locking shard. More...

#include <interface.hpp>

Inheritance diagram for cbdc::parsec::runtime_locking_shard::interface:

[legend]

Public Types
using	try_lock_return_type = std::variant<value_type, shard_error>
	Return type from a try lock operation.

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

using	prepare_return_type = std::optional<shard_error>
	Return type from a prepare operation. An error, if applicable.

using	prepare_callback_type = std::function<void(prepare_return_type)>
	Callback function type for the result of a prepare operation.

using	commit_return_type = std::optional<shard_error>
	Return type from a commit operation. An error code, if applicable.

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

using	rollback_return_type = std::optional<shard_error>
	Return type from a rollback operation.

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

using	finish_return_type = std::optional<shard_error>
	Return type from a finish operation. An error code, if applicable.

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

using	get_tickets_success_type = std::unordered_map<ticket_number_type, ticket_state>
	Return type from a successful get tickets operation.

using	get_tickets_return_type = std::variant<get_tickets_success_type, error_code>
	Return type from a get tickets operation.

using	get_tickets_callback_type = std::function<void(get_tickets_return_type)>
	Callback function type for the result of a get tickets 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	try_lock (ticket_number_type ticket_number, broker_id_type broker_id, key_type key, lock_type locktype, bool first_lock, try_lock_callback_type result_callback) -> bool=0
	Requests a lock on the given key and returns the value associated with the key.

virtual auto	prepare (ticket_number_type ticket_number, broker_id_type broker_id, state_update_type state_update, prepare_callback_type result_callback) -> bool=0
	Prepares a ticket with the given state updates to be applied if the ticket is subsequently committed.

virtual auto	commit (ticket_number_type ticket_number, commit_callback_type result_callback) -> bool=0
	Commits the state updates from a previously prepared ticket.

virtual auto	rollback (ticket_number_type ticket_number, rollback_callback_type result_callback) -> bool=0
	Releases any locks held by a ticket and returns it to a clean state.

virtual auto	finish (ticket_number_type ticket_number, finish_callback_type result_callback) -> bool=0
	Removes a ticket from the shard's internal state.

virtual auto	get_tickets (broker_id_type broker_id, get_tickets_callback_type result_callback) -> bool=0
	Returns all unfinished tickets managed with the given broker ID.

Detailed Description

Interface for a runtime locking shard.

Shard implements the three-phase commit protocol and two-phase locking. Deadlocks are avoided by assigning each transaction a monotonically increasing ticket number. Older tickets always receive higher priority than younger tickets. If an older ticket requests a lock on a key held by a younger ticket, the younger ticket is "wounded" (all its locks are revoked), and the lock is assigned to the older ticket. Once prepared, tickets are protected from being wounded until they are committed when their locks are released. Locks queue until they are asynchronously assigned to a ticket. The shard supports both read and write locks. Multiple readers are given the lock on a key at the same time, unless there is a write lock in the queue, in which case the write lock gets priority over new readers.

Definition at line 109 of file parsec/runtime_locking_shard/interface.hpp.

Member Typedef Documentation

◆ commit_callback_type

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

Callback function type for the result of a commit operation.

Definition at line 168 of file parsec/runtime_locking_shard/interface.hpp.

◆ commit_return_type

using cbdc::parsec::runtime_locking_shard::interface::commit_return_type = std::optional<shard_error>

Return type from a commit operation. An error code, if applicable.

Definition at line 166 of file parsec/runtime_locking_shard/interface.hpp.

◆ finish_callback_type

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

Callback function type for the result of a finish operation.

Definition at line 200 of file parsec/runtime_locking_shard/interface.hpp.

◆ finish_return_type

using cbdc::parsec::runtime_locking_shard::interface::finish_return_type = std::optional<shard_error>

Return type from a finish operation. An error code, if applicable.

Definition at line 198 of file parsec/runtime_locking_shard/interface.hpp.

◆ get_tickets_callback_type

using cbdc::parsec::runtime_locking_shard::interface::get_tickets_callback_type = std::function<void(get_tickets_return_type)>

Callback function type for the result of a get tickets operation.

Definition at line 220 of file parsec/runtime_locking_shard/interface.hpp.

◆ get_tickets_return_type

using cbdc::parsec::runtime_locking_shard::interface::get_tickets_return_type = std::variant<get_tickets_success_type, error_code>

Return type from a get tickets operation.

Either a map of ticket states or an error code.

Definition at line 218 of file parsec/runtime_locking_shard/interface.hpp.

◆ get_tickets_success_type

using cbdc::parsec::runtime_locking_shard::interface::get_tickets_success_type = std::unordered_map<ticket_number_type, ticket_state>

Return type from a successful get tickets operation.

A map of ticket numbers to their state.

Definition at line 215 of file parsec/runtime_locking_shard/interface.hpp.

◆ prepare_callback_type

using cbdc::parsec::runtime_locking_shard::interface::prepare_callback_type = std::function<void(prepare_return_type)>

Callback function type for the result of a prepare operation.

Definition at line 149 of file parsec/runtime_locking_shard/interface.hpp.

◆ prepare_return_type

using cbdc::parsec::runtime_locking_shard::interface::prepare_return_type = std::optional<shard_error>

Return type from a prepare operation. An error, if applicable.

Definition at line 147 of file parsec/runtime_locking_shard/interface.hpp.

◆ rollback_callback_type

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

Callback function type for the result of a rollback operation.

Definition at line 184 of file parsec/runtime_locking_shard/interface.hpp.

◆ rollback_return_type

using cbdc::parsec::runtime_locking_shard::interface::rollback_return_type = std::optional<shard_error>

Return type from a rollback operation.

An error code, if applicable.

Definition at line 182 of file parsec/runtime_locking_shard/interface.hpp.

◆ try_lock_callback_type

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

Function type for try lock operation results.

Definition at line 123 of file parsec/runtime_locking_shard/interface.hpp.

◆ try_lock_return_type

using cbdc::parsec::runtime_locking_shard::interface::try_lock_return_type = std::variant<value_type, shard_error>

Return type from a try lock operation.

Either the value at the requested key or an error code.

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

Constructor & Destructor Documentation

◆ ~interface()

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

virtualdefault

◆ interface() [1/3]

cbdc::parsec::runtime_locking_shard::interface::interface ( )

default

◆ interface() [2/3]

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

delete

◆ interface() [3/3]

cbdc::parsec::runtime_locking_shard::interface::interface ( interface && )

delete

Member Function Documentation

◆ commit()

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

pure virtual

Commits the state updates from a previously prepared ticket.

Writes the changes from the state update and unlocks any locks held by the ticket.

Parameters

ticket_number	ticket to commit.
result_callback	function to call with the commit result.

Returns: true if the operation was initiated successfully.

Implemented in cbdc::parsec::runtime_locking_shard::impl, and cbdc::parsec::runtime_locking_shard::rpc::client.

◆ finish()

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

pure virtual

Removes a ticket from the shard's internal state.

Called after a commit or rollback operation to permanently complete a ticket. No further operations should be performed on the ticket after a successful finish operation.

Parameters

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

Returns: true if the operation was initiated successfully.

Implemented in cbdc::parsec::runtime_locking_shard::impl, and cbdc::parsec::runtime_locking_shard::rpc::client.

◆ get_tickets()

virtual auto cbdc::parsec::runtime_locking_shard::interface::get_tickets	(	broker_id_type	broker_id,
		get_tickets_callback_type	result_callback ) -> bool

pure virtual

Returns all unfinished tickets managed with the given broker ID.

Parameters

broker_id	broker ID.
result_callback	function to call with get tickets result.

Returns: true if the operation was initiated successfully.

Implemented in cbdc::parsec::runtime_locking_shard::impl, and cbdc::parsec::runtime_locking_shard::rpc::client.

◆ operator=() [1/2]

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

delete

◆ operator=() [2/2]

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

delete

◆ prepare()

virtual auto cbdc::parsec::runtime_locking_shard::interface::prepare	(	ticket_number_type	ticket_number,
		broker_id_type	broker_id,
		state_update_type	state_update,
		prepare_callback_type	result_callback ) -> bool

pure virtual

Prepares a ticket with the given state updates to be applied if the ticket is subsequently committed.

Protects the ticket from being wounded by other tickets requesting locks.

Parameters

ticket_number	ticket to prepare.
broker_id	broker ID managing the ticket.
state_update	state changes to apply if ticket is committed.
result_callback	function to call with prepare result.

Returns: true if the operation was initiated successfully.

Implemented in cbdc::parsec::runtime_locking_shard::impl, and cbdc::parsec::runtime_locking_shard::rpc::client.

◆ rollback()

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

pure virtual

Releases any locks held by a ticket and returns it to a clean state.

Used to abort a wounded ticket, a ticket which experienced an irrecoverable error during execution, or cancel a prepared ticket. Cannot be used after a ticket is committed.

Parameters

ticket_number	ticket to roll back.
result_callback	function to call with rollback result.

Returns: true if the operation was initiated successfully.

Implemented in cbdc::parsec::runtime_locking_shard::impl, and cbdc::parsec::runtime_locking_shard::rpc::client.

◆ try_lock()

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

pure virtual

Requests a lock on the given key and returns the value associated with the key.

Lock may not be acquired immediately if another ticket already holds the write lock. May cause other tickets to be wounded if the requested lock is already held by a younger ticket. Cannot be used once a ticket is prepared or committed.

Parameters

ticket_number	ticket number requesting the lock.
broker_id	broker ID managing the ticket.
key	key to lock.
locktype	type of lock to acquire.
first_lock	true if this is the first lock.
result_callback	function to call with the value or error code.

Returns: true if the operation was initiated successfully.

Implemented in cbdc::parsec::runtime_locking_shard::impl, and cbdc::parsec::runtime_locking_shard::rpc::client.

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

parsec/runtime_locking_shard/interface.hpp

Public Types

Public Member Functions

Detailed Description

Member Typedef Documentation

◆ commit_callback_type

◆ commit_return_type

◆ finish_callback_type

◆ finish_return_type

◆ get_tickets_callback_type

◆ get_tickets_return_type

◆ get_tickets_success_type

◆ prepare_callback_type

◆ prepare_return_type

◆ rollback_callback_type

◆ rollback_return_type

◆ try_lock_callback_type

◆ try_lock_return_type

Constructor & Destructor Documentation

◆ ~interface()

◆ interface() [1/3]

◆ interface() [2/3]

◆ interface() [3/3]

Member Function Documentation

◆ commit()

◆ finish()

◆ get_tickets()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ prepare()

◆ rollback()

◆ try_lock()