Base class for indices of blockchain data. More...

#include <base.h>

Inheritance diagram for BaseIndex:

Collaboration diagram for BaseIndex:

Classes
class	DB
	The database stores a block locator of the chain the database is synced to so that the index can efficiently determine the point it last stopped at. More...

Public Member Functions
	BaseIndex (std::unique_ptr< interfaces::Chain > chain, std::string name, std::string thread_name)

virtual	~BaseIndex ()
	Destructor interrupts sync thread if running and blocks until it exits.

const std::string &	GetName () const LIFETIMEBOUND
	Get the name of the index for display in logs.

virtual interfaces::Chain::NotifyOptions	CustomOptions ()
	Return custom notification options for index.

bool BlockUntilSyncedToCurrentChain() const LOCKS_EXCLUDED(void	Interrupt ()
	Blocks the current thread until the index is caught up to the current state of the block chain.

bool	Init ()
	Initializes the sync state and registers the instance to the validation interface so that it stays in sync with blockchain updates.

bool	StartBackgroundSync ()
	Starts the initial sync process on a background thread.

void	Sync ()
	Sync the index with the block index starting from the current best block.

void	Stop ()
	Stops the instance from staying in sync with blockchain updates.

IndexSummary	GetSummary () const
	Get a summary of the index and its state.

Protected Member Functions
void	BlockConnected (const kernel::ChainstateRole &role, const std::shared_ptr< const CBlock > &block, const CBlockIndex *pindex) override
	Notifies listeners of a block being connected.

void	ChainStateFlushed (const kernel::ChainstateRole &role, const CBlockLocator &locator) override
	Notifies listeners of the new active block chain on-disk.

virtual bool	CustomInit (const std::optional< interfaces::BlockRef > &block)
	Initialize internal state from the database and block index.

virtual bool	CustomAppend (const interfaces::BlockInfo &block)
	Write update index entries for a newly connected block.

virtual bool	CustomCommit (CDBBatch &batch)
	Virtual method called internally by Commit that can be overridden to atomically commit more index state.

virtual bool	CustomRemove (const interfaces::BlockInfo &block)
	Rewind index by one block during a chain reorg.

virtual DB &	GetDB () const =0

void	SetBestBlockIndex (const CBlockIndex *block)
	Update the internal best block index as well as the prune lock.

Protected Member Functions inherited from CValidationInterface
	~CValidationInterface ()=default
	Protected destructor so that instances can only be deleted by derived classes.

virtual void	UpdatedBlockTip (const CBlockIndex pindexNew, const CBlockIndex pindexFork, bool fInitialDownload)
	Notifies listeners when the block chain tip advances.

virtual void	ActiveTipChange (const CBlockIndex &new_tip, bool is_ibd)
	Notifies listeners any time the block chain tip changes, synchronously.

virtual void	TransactionAddedToMempool (const NewMempoolTransactionInfo &tx, uint64_t mempool_sequence)
	Notifies listeners of a transaction having been added to mempool.

virtual void	TransactionRemovedFromMempool (const CTransactionRef &tx, MemPoolRemovalReason reason, uint64_t mempool_sequence)
	Notifies listeners of a transaction leaving mempool.

virtual void	MempoolTransactionsRemovedForBlock (const std::shared_ptr< const CBlock > &block, const std::vector< RemovedMempoolTransactionInfo > &txs_removed_for_block, unsigned int block_height)

virtual void	BlockDisconnected (const std::shared_ptr< const CBlock > &block, const CBlockIndex *pindex)
	Notifies listeners of a block being disconnected Provides the block that was disconnected.

virtual void	BlockChecked (const std::shared_ptr< const CBlock > &, const BlockValidationState &)
	Notifies listeners of a block validation result.

virtual void	NewPoWValidBlock (const CBlockIndex *pindex, const std::shared_ptr< const CBlock > &block)
	Notifies listeners that a block which builds directly on our current tip has been received and connected to the headers tree, though not validated yet.

Protected Attributes
std::unique_ptr< interfaces::Chain >	m_chain

Chainstate *	m_chainstate {nullptr}

const std::string	m_name

const std::string	m_thread_name

Private Member Functions
void	Commit ()
	Write the current index state (eg.

bool	Rewind (const CBlockIndex current_tip, const CBlockIndex new_tip)
	Loop over disconnected blocks and call CustomRemove.

bool	ProcessBlock (const CBlockIndex pindex, const CBlock block_data=nullptr)

virtual bool	AllowPrune () const =0

template<typename... Args>
void	FatalErrorf (util::log::FormatString< sizeof...(Args)> fmt, const Args &... args)

Private Attributes
std::atomic< bool >	m_init {false}
	Whether the index has been initialized or not.

std::atomic< bool >	m_synced {false}
	Whether the index is in sync with the main chain.

std::atomic< const CBlockIndex * >	m_best_block_index {nullptr}
	The last block in the chain that the index is in sync with.

std::thread	m_thread_sync

CThreadInterrupt	m_interrupt

Detailed Description

Base class for indices of blockchain data.

This implements CValidationInterface and ensures blocks are indexed sequentially according to their position in the active chain.

In the presence of multiple chainstates (i.e. if a UTXO snapshot is loaded), only the background "IBD" chainstate will be indexed to avoid building the index out of order. When the background chainstate completes validation, the index will be reinitialized and indexing will continue.

Definition at line 54 of file base.h.

Constructor & Destructor Documentation

◆ BaseIndex()

BaseIndex::BaseIndex	(	std::unique_ptr< interfaces::Chain >	chain,
		std::string	name,
		std::string	thread_name
	)

Definition at line 95 of file base.cpp.

◆ ~BaseIndex()

BaseIndex::~BaseIndex ( )

virtual

Destructor interrupts sync thread if running and blocks until it exits.

Definition at line 98 of file base.cpp.

Here is the call graph for this function:

Member Function Documentation

◆ AllowPrune()

virtual bool BaseIndex::AllowPrune ( ) const

privatepure virtual

Implemented in BlockFilterIndex, CoinStatsIndex, TxIndex, TxoSpenderIndex, and IndexReorgCrash.

Here is the caller graph for this function:

◆ BlockConnected()

void BaseIndex::BlockConnected	(	const kernel::ChainstateRole &	role,
		const std::shared_ptr< const CBlock > &	block,
		const CBlockIndex *	pindex
	)

overrideprotectedvirtual

Notifies listeners of a block being connected.

Called on a background thread.

Reimplemented from CValidationInterface.

Definition at line 343 of file base.cpp.

Here is the call graph for this function:

◆ ChainStateFlushed()

void BaseIndex::ChainStateFlushed	(	const kernel::ChainstateRole &	role,
		const CBlockLocator &	locator
	)

overrideprotectedvirtual

Notifies listeners of the new active block chain on-disk.

Prior to this callback, any updates are not guaranteed to persist on disk (ie clients need to handle shutdown/restart safety by being able to understand when some updates were lost due to unclean shutdown).

When this callback is invoked, the validation changes done by any prior callback are guaranteed to exist on disk and survive a restart, including an unclean shutdown.

Provides a locator describing the best chain, which is likely useful for storing current state on disk in client DBs.

Called on a background thread.

Reimplemented from CValidationInterface.

Definition at line 395 of file base.cpp.

Here is the call graph for this function:

◆ Commit()

void BaseIndex::Commit ( )

private

Write the current index state (eg.

chain block locator and subclass-specific items) to disk. Will skip the commit if no block has been indexed yet or if the index's best block is ahead of the chainstate's last flushed block. This avoids persisting state an unclean shutdown could not roll back from. A later call commits when the chainstate has flushed far enough.

Definition at line 276 of file base.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ CustomAppend()

virtual bool BaseIndex::CustomAppend ( const interfaces::BlockInfo & block )

inlineprotectedvirtual

Write update index entries for a newly connected block.

Reimplemented in BlockFilterIndex, CoinStatsIndex, TxIndex, TxoSpenderIndex, and IndexReorgCrash.

Definition at line 127 of file base.h.

Here is the caller graph for this function:

◆ CustomCommit()

virtual bool BaseIndex::CustomCommit ( CDBBatch & batch )

inlineprotectedvirtual

Virtual method called internally by Commit that can be overridden to atomically commit more index state.

Reimplemented in BlockFilterIndex, and CoinStatsIndex.

Definition at line 131 of file base.h.

Here is the caller graph for this function:

◆ CustomInit()

virtual bool BaseIndex::CustomInit ( const std::optional< interfaces::BlockRef > & block )

inlineprotectedvirtual

Initialize internal state from the database and block index.

Reimplemented in BlockFilterIndex, and CoinStatsIndex.

Definition at line 124 of file base.h.

Here is the caller graph for this function:

◆ CustomOptions()

virtual interfaces::Chain::NotifyOptions BaseIndex::CustomOptions ( )

inlinevirtual

Return custom notification options for index.

Reimplemented in BlockFilterIndex, CoinStatsIndex, and TxoSpenderIndex.

Definition at line 150 of file base.h.

Here is the caller graph for this function:

◆ CustomRemove()

virtual bool BaseIndex::CustomRemove ( const interfaces::BlockInfo & block )

inlineprotectedvirtual

Rewind index by one block during a chain reorg.

Reimplemented in BlockFilterIndex, CoinStatsIndex, and TxoSpenderIndex.

Definition at line 134 of file base.h.

Here is the caller graph for this function:

◆ FatalErrorf()

template<typename... Args>

void BaseIndex::FatalErrorf	(	util::log::FormatString< sizeof...(Args)>	fmt,
		const Args &...	args
	)

private

Definition at line 52 of file base.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ GetDB()

virtual DB & BaseIndex::GetDB ( ) const

protectedpure virtual

Implemented in BlockFilterIndex, CoinStatsIndex, TxIndex, TxoSpenderIndex, and IndexReorgCrash.

Here is the caller graph for this function:

◆ GetName()

const std::string & BaseIndex::GetName ( ) const

inline

Get the name of the index for display in logs.

Definition at line 147 of file base.h.

Here is the caller graph for this function:

◆ GetSummary()

IndexSummary BaseIndex::GetSummary ( ) const

Get a summary of the index and its state.

Definition at line 487 of file base.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ Init()

bool BaseIndex::Init ( )

Initializes the sync state and registers the instance to the validation interface so that it stays in sync with blockchain updates.

Definition at line 104 of file base.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ Interrupt()

void BaseIndex::Interrupt ( )

Blocks the current thread until the index is caught up to the current state of the block chain.

This only blocks if the index has gotten in sync once and only needs to process blocks in the ValidationInterface queue. If the index is catching up from far behind, this method does not block and immediately returns false.

Definition at line 463 of file base.cpp.

Here is the caller graph for this function:

◆ ProcessBlock()

bool BaseIndex::ProcessBlock	(	const CBlockIndex *	pindex,
		const CBlock *	block_data = `nullptr`
	)

private

Definition at line 174 of file base.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ Rewind()

bool BaseIndex::Rewind	(	const CBlockIndex *	current_tip,
		const CBlockIndex *	new_tip
	)

private

Loop over disconnected blocks and call CustomRemove.

Definition at line 305 of file base.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ SetBestBlockIndex()

void BaseIndex::SetBestBlockIndex ( const CBlockIndex * block )

protected

Update the internal best block index as well as the prune lock.

Definition at line 502 of file base.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ StartBackgroundSync()

bool BaseIndex::StartBackgroundSync ( )

Starts the initial sync process on a background thread.

Definition at line 468 of file base.cpp.

Here is the call graph for this function:

◆ Stop()

void BaseIndex::Stop ( )

Stops the instance from staying in sync with blockchain updates.

Definition at line 476 of file base.cpp.

Here is the caller graph for this function:

◆ Sync()

void BaseIndex::Sync ( )

Sync the index with the block index starting from the current best block.

Intended to be run in its own thread, m_thread_sync, and can be interrupted with m_interrupt. Once the index gets in sync, the m_synced flag is set and the BlockConnected ValidationInterface callback takes over and the sync thread exits.

Definition at line 207 of file base.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

Member Data Documentation

◆ m_best_block_index

std::atomic<const CBlockIndex*> BaseIndex::m_best_block_index {nullptr}

private

The last block in the chain that the index is in sync with.

Definition at line 92 of file base.h.

◆ m_chain

std::unique_ptr<interfaces::Chain> BaseIndex::m_chain

protected

Definition at line 114 of file base.h.

◆ m_chainstate

Chainstate* BaseIndex::m_chainstate {nullptr}

protected

Definition at line 115 of file base.h.

◆ m_init

std::atomic<bool> BaseIndex::m_init {false}

private

Whether the index has been initialized or not.

Definition at line 81 of file base.h.

◆ m_interrupt

CThreadInterrupt BaseIndex::m_interrupt

private

Definition at line 95 of file base.h.

◆ m_name

const std::string BaseIndex::m_name

protected

Definition at line 116 of file base.h.

◆ m_synced

std::atomic<bool> BaseIndex::m_synced {false}

private

Whether the index is in sync with the main chain.

The flag is flipped from false to true once, after which point this starts processing ValidationInterface notifications to stay in sync.

Note that this will latch to true immediately upon startup if m_chainstate->m_chain is empty, which will be the case upon startup with an empty datadir if, e.g., -txindex=1 is specified.

Definition at line 89 of file base.h.

◆ m_thread_name

const std::string BaseIndex::m_thread_name

protected

Definition at line 117 of file base.h.

◆ m_thread_sync

std::thread BaseIndex::m_thread_sync

private

Definition at line 94 of file base.h.

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

src/index/base.h
src/index/base.cpp

Classes

Public Member Functions

Protected Member Functions

Protected Attributes

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ BaseIndex()

◆ ~BaseIndex()

Member Function Documentation

◆ AllowPrune()

◆ BlockConnected()

◆ ChainStateFlushed()

◆ Commit()

◆ CustomAppend()

◆ CustomCommit()

◆ CustomInit()

◆ CustomOptions()

◆ CustomRemove()

◆ FatalErrorf()

◆ GetDB()

◆ GetName()

◆ GetSummary()

◆ Init()

◆ Interrupt()

◆ ProcessBlock()

◆ Rewind()

◆ SetBestBlockIndex()

◆ StartBackgroundSync()

◆ Stop()

◆ Sync()

Member Data Documentation

◆ m_best_block_index

◆ m_chain

◆ m_chainstate

◆ m_init

◆ m_interrupt

◆ m_name

◆ m_synced

◆ m_thread_name

◆ m_thread_sync