Collaboration diagram for ripple::TxQ:

[legend]

Classes
struct	FeeAndSeq

class	FeeMetrics
	Track and use the fee escalation metrics of the current open ledger. More...

class	MaybeTx
	Represents a transaction in the queue which may be applied later to the open ledger. More...

struct	Metrics
	Structure returned by TxQ::getMetrics, expressed in reference fee level units. More...

class	OrderCandidates
	Used for sorting MaybeTx. More...

struct	Setup
	Structure used to customize TxQ behavior. More...

struct	TxDetails
	Structure that describes a transaction in the queue waiting to be applied to the current open ledger. More...

class	TxQAccount
	Used to represent an account to the queue, and stores the transactions queued for that account by SeqProxy. More...

Public Member Functions
	TxQ (Setup const &setup, beast::Journal j)
	Constructor. More...

virtual	~TxQ ()
	Destructor. More...

std::pair< TER, bool >	apply (Application &app, OpenView &view, std::shared_ptr< STTx const > const &tx, ApplyFlags flags, beast::Journal j)
	Add a new transaction to the open ledger, hold it in the queue, or reject it. More...

bool	accept (Application &app, OpenView &view)
	Fill the new open ledger with transactions from the queue. More...

void	processClosedLedger (Application &app, ReadView const &view, bool timeLeap)
	Update fee metrics and clean up the queue in preparation for the next ledger. More...

SeqProxy	nextQueuableSeq (std::shared_ptr< SLE const > const &sleAccount) const
	Return the next sequence that would go in the TxQ for an account. More...

Metrics	getMetrics (OpenView const &view) const
	Returns fee metrics in reference fee level units. More...

FeeAndSeq	getTxRequiredFeeAndSeq (OpenView const &view, std::shared_ptr< STTx const > const &tx) const
	Returns minimum required fee for tx and two sequences: first vaild sequence for this account in current ledger and first available sequence for transaction. More...

std::vector< TxDetails >	getAccountTxs (AccountID const &account) const
	Returns information about the transactions currently in the queue for the account. More...

std::vector< TxDetails >	getTxs () const
	Returns information about all transactions currently in the queue. More...

Json::Value	doRPC (Application &app) const
	Summarize current fee metrics for the `fee` RPC command. More...

Static Public Attributes
static constexpr FeeLevel64	baseLevel {256}
	Fee level for single-signed reference transaction. More...

Private Types
using	FeeHook = boost::intrusive::member_hook< MaybeTx, boost::intrusive::set_member_hook<>, &MaybeTx::byFeeListHook >

using	FeeMultiSet = boost::intrusive::multiset< MaybeTx, FeeHook, boost::intrusive::compare< OrderCandidates > >

using	AccountMap = std::map< AccountID, TxQAccount >

Private Member Functions
SeqProxy	nextQueuableSeqImpl (std::shared_ptr< SLE const > const &sleAccount, std::lock_guard< std::mutex > const &) const

FeeLevel64	getRequiredFeeLevel (OpenView &view, ApplyFlags flags, FeeMetrics::Snapshot const &metricsSnapshot, std::lock_guard< std::mutex > const &lock) const

std::optional< std::pair< TER, bool > >	tryDirectApply (Application &app, OpenView &view, std::shared_ptr< STTx const > const &tx, ApplyFlags flags, beast::Journal j)

std::optional< TxQAccount::TxMap::iterator >	removeFromByFee (std::optional< TxQAccount::TxMap::iterator > const &replacedTxIter, std::shared_ptr< STTx const > const &tx)

template<size_t fillPercentage = 100>
bool	isFull () const
	Is the queue at least `fillPercentage` full? More...

TER	canBeHeld (STTx const &, ApplyFlags const, OpenView const &, std::shared_ptr< SLE const > const &sleAccount, AccountMap::iterator const &, std::optional< TxQAccount::TxMap::iterator > const &, std::lock_guard< std::mutex > const &lock)
	Checks if the indicated transaction fits the conditions for being stored in the queue. More...

FeeMultiSet::iterator_type	erase (FeeMultiSet::const_iterator_type)
	Erase and return the next entry in byFee_ (lower fee level) More...

FeeMultiSet::iterator_type	eraseAndAdvance (FeeMultiSet::const_iterator_type)
	Erase and return the next entry for the account (if fee level is higher), or next entry in byFee_ (lower fee level). More...

TxQAccount::TxMap::iterator	erase (TxQAccount &txQAccount, TxQAccount::TxMap::const_iterator begin, TxQAccount::TxMap::const_iterator end)
	Erase a range of items, based on TxQAccount::TxMap iterators. More...

std::pair< TER, bool >	tryClearAccountQueueUpThruTx (Application &app, OpenView &view, STTx const &tx, AccountMap::iterator const &accountIter, TxQAccount::TxMap::iterator, FeeLevel64 feeLevelPaid, PreflightResult const &pfresult, std::size_t const txExtraCount, ApplyFlags flags, FeeMetrics::Snapshot const &metricsSnapshot, beast::Journal j)
	All-or-nothing attempt to try to apply the queued txs for `accountIter` up to and including `tx`. More...

Private Attributes
const Setup	setup_
	Setup parameters used to control the behavior of the queue. More...

const beast::Journal	j_
	Journal. More...

FeeMetrics	feeMetrics_
	Tracks the current state of the queue. More...

FeeMultiSet	byFee_
	The queue itself: the collection of transactions ordered by fee level. More...

AccountMap	byAccount_
	All of the accounts which currently have any transactions in the queue. More...

std::optional< size_t >	maxSize_
	Maximum number of transactions allowed in the queue based on the current metrics. More...

LedgerHash	parentHash_ {beast::zero}
	parentHash_ checks that no unexpected ledger transitions happen, and is only checked via debug asserts. More...

std::mutex	mutex_
	Most queue operations are done under the master lock, but use this mutex for the RPC "fee" command, which isn't. More...

Detailed Description

Transaction Queue.

Used to manage transactions in conjunction with fee escalation.

Once enough transactions are added to the open ledger, the required fee will jump dramatically. If additional transactions are added, the fee will grow exponentially from there.

Transactions that don't have a high enough fee to be applied to the ledger are added to the queue in order from highest fee level to lowest. Whenever a new ledger is accepted as validated, transactions are first applied from the queue to the open ledger in fee level order until either all transactions are applied or the fee again jumps too high for the remaining transactions.

For further information and a high-level overview of how transactions are processed with the TxQ, see FeeEscalation.md

Definition at line 57 of file TxQ.h.

Member Typedef Documentation

◆ FeeHook

using ripple::TxQ::FeeHook = boost::intrusive::member_hook< MaybeTx, boost::intrusive::set_member_hook<>, &MaybeTx::byFeeListHook>

private

Definition at line 750 of file TxQ.h.

◆ FeeMultiSet

using ripple::TxQ::FeeMultiSet = boost::intrusive:: multiset<MaybeTx, FeeHook, boost::intrusive::compare<OrderCandidates> >

private

Definition at line 753 of file TxQ.h.

◆ AccountMap

using ripple::TxQ::AccountMap = std::map<AccountID, TxQAccount>

private

Definition at line 755 of file TxQ.h.

Constructor & Destructor Documentation

◆ TxQ()

ripple::TxQ::TxQ	(	Setup const &	setup,
		beast::Journal	j
	)

Constructor.

Definition at line 353 of file TxQ.cpp.

◆ ~TxQ()

ripple::TxQ::~TxQ ( )

virtual

Destructor.

Definition at line 358 of file TxQ.cpp.

Member Function Documentation

◆ apply()

std::pair< TER, bool > ripple::TxQ::apply	(	Application &	app,
		OpenView &	view,
		std::shared_ptr< STTx const > const &	tx,
		ApplyFlags	flags,
		beast::Journal	j
	)

Add a new transaction to the open ledger, hold it in the queue, or reject it.

Returns: A pair with the TER and a bool indicating whether or not the transaction was applied to the open ledger. If the transaction is queued, will return { terQUEUED, false }.

Definition at line 713 of file TxQ.cpp.

◆ accept()

bool ripple::TxQ::accept	(	Application &	app,
		OpenView &	view
	)

Fill the new open ledger with transactions from the queue.

Note: As more transactions are applied to the ledger, the required fee may increase. The required fee may rise above the fee level of the queued items before the queue is emptied, which will end the process, leaving those in the queue for the next open ledger.

Returns: Whether any transactions were added to the view.

Definition at line 1415 of file TxQ.cpp.

◆ processClosedLedger()

void ripple::TxQ::processClosedLedger	(	Application &	app,
		ReadView const &	view,
		bool	timeLeap
	)

Update fee metrics and clean up the queue in preparation for the next ledger.

Note: Fee metrics are updated based on the fee levels of the txs in the validated ledger and whether consensus is slow. Maximum queue size is adjusted to be enough to hold ledgersInQueue ledgers or queueSizeMin transactions. Any transactions for which the LastLedgerSequence has passed are removed from the queue, and any account objects that have no candidates under them are removed.

Definition at line 1346 of file TxQ.cpp.

◆ nextQueuableSeq()

SeqProxy ripple::TxQ::nextQueuableSeq ( std::shared_ptr< SLE const > const & sleAccount ) const

Return the next sequence that would go in the TxQ for an account.

Definition at line 1586 of file TxQ.cpp.

◆ getMetrics()

TxQ::Metrics ripple::TxQ::getMetrics ( OpenView const & view ) const

Returns fee metrics in reference fee level units.

Definition at line 1747 of file TxQ.cpp.

◆ getTxRequiredFeeAndSeq()

TxQ::FeeAndSeq ripple::TxQ::getTxRequiredFeeAndSeq	(	OpenView const &	view,
		std::shared_ptr< STTx const > const &	tx
	)		const

Returns minimum required fee for tx and two sequences: first vaild sequence for this account in current ledger and first available sequence for transaction.

Parameters

view	current open ledger
tx	the transaction

Returns: minimum required fee, first sequence in the ledger and first available sequence

Definition at line 1769 of file TxQ.cpp.

◆ getAccountTxs()

std::vector< TxQ::TxDetails > ripple::TxQ::getAccountTxs ( AccountID const & account ) const

Returns information about the transactions currently in the queue for the account.

Returns: Empty vector if the account has no transactions in the queue.

Definition at line 1790 of file TxQ.cpp.

◆ getTxs()

std::vector< TxQ::TxDetails > ripple::TxQ::getTxs ( ) const

Returns information about all transactions currently in the queue.

Returns: Empty vector if there are no transactions in the queue.

Definition at line 1811 of file TxQ.cpp.

◆ doRPC()

Json::Value ripple::TxQ::doRPC ( Application & app ) const

Summarize current fee metrics for the fee RPC command.

Returns: a Json objectvalue

Definition at line 1826 of file TxQ.cpp.

◆ nextQueuableSeqImpl()

SeqProxy ripple::TxQ::nextQueuableSeqImpl	(	std::shared_ptr< SLE const > const &	sleAccount,
		std::lock_guard< std::mutex > const &
	)		const

private

Definition at line 1599 of file TxQ.cpp.

◆ getRequiredFeeLevel()

FeeLevel64 ripple::TxQ::getRequiredFeeLevel	(	OpenView &	view,
		ApplyFlags	flags,
		FeeMetrics::Snapshot const &	metricsSnapshot,
		std::lock_guard< std::mutex > const &	lock
	)		const

private

Definition at line 1646 of file TxQ.cpp.

◆ tryDirectApply()

std::optional< std::pair< TER, bool > > ripple::TxQ::tryDirectApply	(	Application &	app,
		OpenView &	view,
		std::shared_ptr< STTx const > const &	tx,
		ApplyFlags	flags,
		beast::Journal	j
	)

private

Definition at line 1656 of file TxQ.cpp.

◆ removeFromByFee()

std::optional< TxQ::TxQAccount::TxMap::iterator > ripple::TxQ::removeFromByFee	(	std::optional< TxQAccount::TxMap::iterator > const &	replacedTxIter,
		std::shared_ptr< STTx const > const &	tx
	)

private

Definition at line 1727 of file TxQ.cpp.

◆ isFull()

template<size_t fillPercentage>

bool ripple::TxQ::isFull

private

Is the queue at least fillPercentage full?

Definition at line 365 of file TxQ.cpp.

◆ canBeHeld()

TER ripple::TxQ::canBeHeld	(	STTx const &	tx,
		ApplyFlags const	flags,
		OpenView const &	view,
		std::shared_ptr< SLE const > const &	sleAccount,
		AccountMap::iterator const &	accountIter,
		std::optional< TxQAccount::TxMap::iterator > const &	replacementIter,
		std::lock_guard< std::mutex > const &	lock
	)

private

Checks if the indicated transaction fits the conditions for being stored in the queue.

Definition at line 373 of file TxQ.cpp.

◆ erase() [1/2]

FeeMultiSet::iterator_type ripple::TxQ::erase ( FeeMultiSet::const_iterator_type )

private

Erase and return the next entry in byFee_ (lower fee level)

◆ eraseAndAdvance()

auto ripple::TxQ::eraseAndAdvance ( FeeMultiSet::const_iterator_type )

private

Erase and return the next entry for the account (if fee level is higher), or next entry in byFee_ (lower fee level).

Used to get the next "applyable" MaybeTx for accept().

Definition at line 456 of file TxQ.cpp.

◆ erase() [2/2]

TxQAccount::TxMap::iterator ripple::TxQ::erase	(	TxQAccount &	txQAccount,
		TxQAccount::TxMap::const_iterator	begin,
		TxQAccount::TxMap::const_iterator	end
	)

private

Erase a range of items, based on TxQAccount::TxMap iterators.

◆ tryClearAccountQueueUpThruTx()

std::pair< TER, bool > ripple::TxQ::tryClearAccountQueueUpThruTx	(	Application &	app,
		OpenView &	view,
		STTx const &	tx,
		AccountMap::iterator const &	accountIter,
		TxQAccount::TxMap::iterator	,
		FeeLevel64	feeLevelPaid,
		PreflightResult const &	pfresult,
		std::size_t const	txExtraCount,
		ApplyFlags	flags,
		FeeMetrics::Snapshot const &	metricsSnapshot,
		beast::Journal	j
	)

private

All-or-nothing attempt to try to apply the queued txs for accountIter up to and including tx.

Transactions following tx are not cleared.

Definition at line 503 of file TxQ.cpp.

Member Data Documentation

◆ baseLevel

constexpr FeeLevel64 ripple::TxQ::baseLevel {256}

staticconstexpr

Fee level for single-signed reference transaction.

Definition at line 61 of file TxQ.h.

◆ setup_

const Setup ripple::TxQ::setup_

private

Setup parameters used to control the behavior of the queue.

Definition at line 758 of file TxQ.h.

◆ j_

const beast::Journal ripple::TxQ::j_

private

Journal.

Definition at line 760 of file TxQ.h.

◆ feeMetrics_

FeeMetrics ripple::TxQ::feeMetrics_

private

Tracks the current state of the queue.

Note: This member must always and only be accessed under locked mutex_

Definition at line 766 of file TxQ.h.

◆ byFee_

FeeMultiSet ripple::TxQ::byFee_

private

The queue itself: the collection of transactions ordered by fee level.

Note: This member must always and only be accessed under locked mutex_

Definition at line 772 of file TxQ.h.

◆ byAccount_

AccountMap ripple::TxQ::byAccount_

private

All of the accounts which currently have any transactions in the queue.

Entries are created and destroyed dynamically as transactions are added and removed.

Note: This member must always and only be accessed under locked mutex_

Definition at line 779 of file TxQ.h.

◆ maxSize_

std::optional<size_t> ripple::TxQ::maxSize_

private

Maximum number of transactions allowed in the queue based on the current metrics.

If uninitialized, there is no limit, but that condition cannot last for long in practice.

Note: This member must always and only be accessed under locked mutex_

Definition at line 786 of file TxQ.h.

◆ parentHash_

LedgerHash ripple::TxQ::parentHash_ {beast::zero}

private

parentHash_ checks that no unexpected ledger transitions happen, and is only checked via debug asserts.

Definition at line 793 of file TxQ.h.

◆ mutex_

std::mutex ripple::TxQ::mutex_

mutableprivate

Most queue operations are done under the master lock, but use this mutex for the RPC "fee" command, which isn't.

Definition at line 799 of file TxQ.h.

Classes

Public Member Functions

Static Public Attributes

Private Types

Private Member Functions

Private Attributes

Detailed Description

Member Typedef Documentation

◆ FeeHook

◆ FeeMultiSet

◆ AccountMap

Constructor & Destructor Documentation

◆ TxQ()

◆ ~TxQ()

Member Function Documentation

◆ apply()

◆ accept()

◆ processClosedLedger()

◆ nextQueuableSeq()

◆ getMetrics()

◆ getTxRequiredFeeAndSeq()

◆ getAccountTxs()

◆ getTxs()

◆ doRPC()

◆ nextQueuableSeqImpl()

◆ getRequiredFeeLevel()

◆ tryDirectApply()

◆ removeFromByFee()

◆ isFull()

◆ canBeHeld()

◆ erase() [1/2]

◆ eraseAndAdvance()

◆ erase() [2/2]

◆ tryClearAccountQueueUpThruTx()

Member Data Documentation

◆ baseLevel

◆ setup_

◆ j_

◆ feeMetrics_

◆ byFee_

◆ byAccount_

◆ maxSize_

◆ parentHash_

◆ mutex_