OpenCBDC Transaction Processor
Loading...
Searching...
No Matches
cbdc::parsec::runtime_locking_shard::interface Class Referenceabstract

Interface for a runtime locking shard. More...

#include <interface.hpp>

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

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

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

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

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

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

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

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

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

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

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

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

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

Function type for try lock operation results.

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

◆ try_lock_return_type

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_numberticket to commit.
result_callbackfunction 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_numberticket to finish.
result_callbackfunction 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_idbroker ID.
result_callbackfunction 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_numberticket to prepare.
broker_idbroker ID managing the ticket.
state_updatestate changes to apply if ticket is committed.
result_callbackfunction 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_numberticket to roll back.
result_callbackfunction 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_numberticket number requesting the lock.
broker_idbroker ID managing the ticket.
keykey to lock.
locktypetype of lock to acquire.
first_locktrue if this is the first lock.
result_callbackfunction 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: