CCoinsCacheEntry Struct Reference

A Coin in one level of the coins database caching hierarchy. More...

#include <coins.h>

Collaboration diagram for CCoinsCacheEntry:

Public Types
enum	Flags { DIRTY = (1 << 0) , FRESH = (1 << 1) }

Public Member Functions
	CCoinsCacheEntry () noexcept=default
	CCoinsCacheEntry (Coin &&coin_) noexcept
	~CCoinsCacheEntry ()
void	SetClean () noexcept
bool	IsDirty () const noexcept
bool	IsFresh () const noexcept
CoinsCachePair *	Next () const noexcept
	Only call Next when this entry is DIRTY, FRESH, or both. More...
CoinsCachePair *	Prev () const noexcept
	Only call Prev when this entry is DIRTY, FRESH, or both. More...
void	SelfRef (CoinsCachePair &pair) noexcept
	Only use this for initializing the linked list sentinel. More...

Static Public Member Functions
static void	SetDirty (CoinsCachePair &pair, CoinsCachePair &sentinel) noexcept
static void	SetFresh (CoinsCachePair &pair, CoinsCachePair &sentinel) noexcept

Public Attributes
Coin	coin

Static Private Member Functions
static void	AddFlags (uint8_t flags, CoinsCachePair &pair, CoinsCachePair &sentinel) noexcept
	Adding a flag requires a reference to the sentinel of the flagged pair linked list. More...

Private Attributes
CoinsCachePair *	m_prev {nullptr}
	These are used to create a doubly linked list of flagged entries. More...
CoinsCachePair *	m_next {nullptr}
uint8_t	m_flags {0}

Detailed Description

A Coin in one level of the coins database caching hierarchy.

A coin can either be:

• unspent or spent (in which case the Coin object will be nulled out - see Coin.Clear())
• DIRTY or not DIRTY
• FRESH or not FRESH

Out of these 2^3 = 8 states, only some combinations are valid:

• unspent, FRESH, DIRTY (e.g. a new coin created in the cache)
• unspent, not FRESH, DIRTY (e.g. a coin changed in the cache during a reorg)
• unspent, not FRESH, not DIRTY (e.g. an unspent coin fetched from the parent cache)
• spent, FRESH, not DIRTY (e.g. a spent coin fetched from the parent cache)
• spent, not FRESH, DIRTY (e.g. a coin is spent and spentness needs to be flushed to the parent)

Definition at line 108 of file coins.h.

Member Enumeration Documentation

Flags

enum CCoinsCacheEntry::Flags

Enumerator
DIRTY	DIRTY means the CCoinsCacheEntry is potentially different from the version in the parent cache. Failure to mark a coin as DIRTY when it is potentially different from the parent cache will cause a consensus failure, since the coin's state won't get written to the parent when the cache is flushed.
FRESH	FRESH means the parent cache does not have this coin or that it is a spent coin in the parent cache. If a FRESH coin in the cache is later spent, it can be deleted entirely and doesn't ever need to be flushed to the parent. This is a performance optimization. Marking a coin as FRESH when it exists unspent in the parent cache will cause a consensus failure, since it might not be deleted from the parent when this cache is flushed.

Definition at line 149 of file coins.h.

Constructor & Destructor Documentation

CCoinsCacheEntry() [1/2]

CCoinsCacheEntry::CCoinsCacheEntry ( )

defaultnoexcept

CCoinsCacheEntry() [2/2]

CCoinsCacheEntry::CCoinsCacheEntry ( Coin &&  coin_ )

inlineexplicitnoexcept

Definition at line 171 of file coins.h.

~CCoinsCacheEntry()

CCoinsCacheEntry::~CCoinsCacheEntry ( )

inline

Definition at line 172 of file coins.h.

Here is the call graph for this function:

Member Function Documentation

AddFlags()

static void CCoinsCacheEntry::AddFlags ( uint8_t  flags, CoinsCachePair &  pair, CoinsCachePair &  sentinel  )

inlinestaticprivatenoexcept

Adding a flag requires a reference to the sentinel of the flagged pair linked list.

Definition at line 132 of file coins.h.

Here is the caller graph for this function:

IsDirty()

bool CCoinsCacheEntry::IsDirty ( ) const

inlinenoexcept

Definition at line 188 of file coins.h.

IsFresh()

bool CCoinsCacheEntry::IsFresh ( ) const

inlinenoexcept

Definition at line 189 of file coins.h.

Next()

CoinsCachePair * CCoinsCacheEntry::Next ( ) const

inlinenoexcept

Only call Next when this entry is DIRTY, FRESH, or both.

Definition at line 192 of file coins.h.

Prev()

CoinsCachePair * CCoinsCacheEntry::Prev ( ) const

inlinenoexcept

Only call Prev when this entry is DIRTY, FRESH, or both.

Definition at line 199 of file coins.h.

SelfRef()

void CCoinsCacheEntry::SelfRef ( CoinsCachePair &  pair )

inlinenoexcept

Only use this for initializing the linked list sentinel.

Definition at line 206 of file coins.h.

SetClean()

void CCoinsCacheEntry::SetClean ( )

inlinenoexcept

Definition at line 180 of file coins.h.

Here is the caller graph for this function:

SetDirty()

static void CCoinsCacheEntry::SetDirty ( CoinsCachePair &  pair, CoinsCachePair &  sentinel  )

inlinestaticnoexcept

Definition at line 177 of file coins.h.

Here is the call graph for this function:

Here is the caller graph for this function:

SetFresh()

static void CCoinsCacheEntry::SetFresh ( CoinsCachePair &  pair, CoinsCachePair &  sentinel  )

inlinestaticnoexcept

Definition at line 178 of file coins.h.

Here is the call graph for this function:

Here is the caller graph for this function:

Member Data Documentation

coin

Coin CCoinsCacheEntry::coin

Definition at line 147 of file coins.h.

m_flags

uint8_t CCoinsCacheEntry::m_flags {0}

private

Definition at line 129 of file coins.h.

m_next

CoinsCachePair* CCoinsCacheEntry::m_next {nullptr}

private

Definition at line 128 of file coins.h.

m_prev

CoinsCachePair* CCoinsCacheEntry::m_prev {nullptr}

private

These are used to create a doubly linked list of flagged entries.

They are set in SetDirty, SetFresh, and unset in SetClean. A flagged entry is any entry that is either DIRTY, FRESH, or both.

DIRTY entries are tracked so that only modified entries can be passed to the parent cache for batch writing. This is a performance optimization compared to giving all entries in the cache to the parent and having the parent scan for only modified entries.

FRESH-but-not-DIRTY coins can not occur in practice, since that would mean a spent coin exists in the parent CCoinsView and not in the child CCoinsViewCache. Nevertheless, if a spent coin is retrieved from the parent cache, the FRESH-but-not-DIRTY coin will be tracked by the linked list and deleted when Sync or Flush is called on the CCoinsViewCache.

Definition at line 127 of file coins.h.

---

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

• src/coins.h