[#CoinsViewOverlay]
= CoinsViewOverlay
:mrdocs:

CCoinsViewCache subclass that asynchronously fetches most block input prevouts in parallel during ConnectBlock without mutating the base cache&period;

== Synopsis

Declared in `&lt;coins&period;h&gt;`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
class CoinsViewOverlay
    : public xref:CCoinsViewCache.adoc[CCoinsViewCache]
----

== Description

Only used in ConnectBlock to pass as an ephemeral view that can be reset if the block is invalid&period; It provides the same interface as CCoinsViewCache&period; It adds an additional StartFetching method to provide the block&period;

When a block is passed to StartFetching, the inputs of the block are flattened into a vector of InputToFetch objects&period; StartFetching then submits worker tasks to a ThreadPool and keeps the returned futures alive until fetching is stopped&period;

ProcessInput() atomically fetches and increments m&lowbar;input&lowbar;head, so each thread can only access a single element of the m&lowbar;inputs vector at a time&period; Workers race to claim inputs, so they may fetch elements in any order&period; If the fetched index is greater than or equal to the size of m&lowbar;inputs, no more inputs can be fetched and false is returned&period;

The worker claims the InputToFetch at this index, fetches the coin from the base cache and moves it into the InputToFetch object&period; The ready flag is then set with a release memory order&period; This allows the ready flag to be used as a memory fence, guaranteeing the coin being written to the object will have happened before another thread tests the flag with an acquire memory order&period; This assumes all base&hyphen;&gt;PeekCoin() paths are safe for concurrent readers and do not mutate lower cache layers&period;

When a coin is requested from the cache on the main thread and is not already in cacheCoins map, FetchCoinFromBase checks whether the next unconsumed entry in m&lowbar;inputs has the requested outpoint&period; On a match, m&lowbar;input&lowbar;tail is advanced and the entry&apos;s ready flag is waited on with an acquire memory order until a worker has finished fetching it&period; The coin is then moved out and returned&period; Since the main thread is the only consumer of validation results, it blocks on the specific input it needs rather than racing workers for other inputs&period;

StopFetching() is called in Flush() and in Reset() (the per&hyphen;block teardown) so workers stop before the block they reference goes away&period; It stops fetching by moving m&lowbar;input&lowbar;head to the end of m&lowbar;inputs (so workers quickly exit), then waits for all futures to complete and clears the per&hyphen;block state (m&lowbar;inputs and the head&sol;tail counters)&period;

Workers advance m&lowbar;input&lowbar;head to fetch inputs&period; Main thread advances m&lowbar;input&lowbar;tail to consume&period;

Before workers start&colon;

m&lowbar;input&lowbar;head m&lowbar;input&lowbar;tail │ ▼ ┌─────────┬─────────┬─────────┬─────────┬─────────┬─────────┬─────────┬─────────┬─────────┐ m&lowbar;inputs&colon; │ waiting │ waiting │ waiting │ waiting │ waiting │ waiting │ waiting │ waiting │ waiting │ │ │ │ │ │ │ │ │ │ │ └─────────┴─────────┴─────────┴─────────┴─────────┴─────────┴─────────┴─────────┴─────────┘

After workers start&colon;

Worker 2 Worker 0 Worker 3 Worker 1 m&lowbar;input&lowbar;head │ │ │ │ │ ▼ ▼ ▼ ▼ ▼ ┌─────────┬─────────┬─────────┬─────────┬─────────┬─────────┬─────────┬─────────┬─────────┐ m&lowbar;inputs&colon; │ ready │ ready │fetching │ ready │fetching │fetching │fetching │ waiting │ waiting │ │consumed │ ✓ │ ● │ ✓ │ ● │ ● │ ● │ │ │ └─────────┴─────────┴─────────┴─────────┴─────────┴─────────┴─────────┴─────────┴─────────┘ ▲ │ m&lowbar;input&lowbar;tail

== Base Classes

[cols="1,4"]
|===
| Name| Description
| `xref:CCoinsViewCache.adoc[CCoinsViewCache]`
| CCoinsView that adds a memory cache for transactions to another CCoinsView
|===

== Types

[cols="1,4"]
|===
| Name| Description
| xref:CCoinsViewCache/ResetGuard.adoc[`ResetGuard`] 
| Scope guard that calls Reset() on its cache when it goes out of scope&period;
|===


== Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:CoinsViewOverlay/2constructor.adoc[`CoinsViewOverlay`]         [.small]#[constructor]#
| Construct an overlay that fetches block input prevouts in parallel&period;
| xref:CoinsViewOverlay/2destructor.adoc[`&#126;CoinsViewOverlay`] [.small]#[destructor]# [.small]#[virtual]#
| Stop fetching before the overlay is destroyed&period;
| xref:CCoinsViewCache/AccessCoin.adoc[`AccessCoin`] 
| Return a reference to Coin in the cache, or coinEmpty if not found&period; This is more efficient than GetCoin&period;
| xref:CCoinsViewCache/AddCoin.adoc[`AddCoin`] 
| Add a coin&period; Set possible&lowbar;overwrite to true if an unspent version may already exist in the cache&period;
| xref:CoinsViewOverlay/AllInputsConsumed.adoc[`AllInputsConsumed`] 
| Verify that all parallel fetched input prevouts have been consumed&period;
| xref:CCoinsViewCache/BatchWrite.adoc[`BatchWrite`]  [.small]#[virtual]#
| Write flagged coins from a cursor into this cache and update the best block&period;
| xref:CCoinsViewCache/CreateResetGuard.adoc[`CreateResetGuard`] 
| Create a scoped guard that will call `Reset()` on this cache when it goes out of scope&period;
| xref:CCoinsViewCache/DynamicMemoryUsage.adoc[`DynamicMemoryUsage`] 
| Calculate the size of the cache (in bytes)
| xref:CCoinsViewCache/EmplaceCoinInternalDANGER.adoc[`EmplaceCoinInternalDANGER`] 
| Emplace a coin into cacheCoins without performing any checks, marking the emplaced coin as dirty&period;
| xref:CCoinsViewBacked/EstimateSize.adoc[`EstimateSize`]  [.small]#[virtual]#
| Forward the size estimate to the backing view&period;
| xref:CoinsViewOverlay/Flush.adoc[`Flush`]  [.small]#[virtual]#
| Warn if prefetched inputs went unconsumed, stop fetching, then flush to the base cache&period;
| xref:CCoinsViewCache/GetBestBlock.adoc[`GetBestBlock`]  [.small]#[virtual]#
| Retrieve the best block hash this cache represents&period;
| xref:CCoinsViewCache/GetCacheSize.adoc[`GetCacheSize`] 
| Size of the cache (in number of transaction outputs)
| xref:CCoinsViewCache/GetCoin.adoc[`GetCoin`]  [.small]#[virtual]#
| Retrieve a coin, populating this cache on a hit&period;
| xref:CCoinsViewCache/GetDirtyCount.adoc[`GetDirtyCount`] 
| Number of dirty cache entries (transaction outputs)
| xref:CCoinsViewBacked/GetHeadBlocks.adoc[`GetHeadBlocks`]  [.small]#[virtual]#
| Forward the head&hyphen;blocks query to the backing view&period;
| xref:CCoinsViewCache/HaveCoin.adoc[`HaveCoin`]  [.small]#[virtual]#
| Check whether an outpoint is unspent, possibly populating this cache&period;
| xref:CCoinsViewCache/HaveCoinInCache.adoc[`HaveCoinInCache`] 
| Check if we have the given utxo already loaded in this cache&period; The semantics are the same as HaveCoin(), but no calls to the backing CCoinsView are made&period;
| xref:CCoinsViewCache/HaveInputs.adoc[`HaveInputs`] 
| Check whether all prevouts of the transaction are present in the UTXO set represented by this view
| xref:CCoinsViewCache/PeekCoin.adoc[`PeekCoin`]  [.small]#[virtual]#
| Retrieve a coin without populating this cache&period;
| xref:CCoinsViewCache/SanityCheck.adoc[`SanityCheck`] 
| Run an internal sanity check on the cache data structure&period; &ast;&sol;
| xref:CCoinsViewBacked/SetBackend.adoc[`SetBackend`] 
| Replace the backing view&period;
| xref:CCoinsViewCache/SetBestBlock.adoc[`SetBestBlock`] 
| Set the best block hash this cache represents&period;
| xref:CCoinsViewCache/SpendCoin.adoc[`SpendCoin`] 
| Spend a coin&period; Pass moveto in order to get the deleted data&period; If no unspent output exists for the passed outpoint, this call has no effect&period;
| xref:CoinsViewOverlay/StartFetching.adoc[`StartFetching`] 
| Start fetching inputs from block&period;
| xref:CCoinsViewCache/Sync.adoc[`Sync`] 
| Push the modifications applied to this cache to its base while retaining the contents of this cache (except for spent coins, which we erase)&period; Failure to call this method or Flush() before destruction will cause the changes to be forgotten&period;
| xref:CCoinsViewCache/Uncache.adoc[`Uncache`] 
| Removes the UTXO with the given outpoint from the cache, if it is not modified&period;
|===


== Protected Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:CCoinsViewCache/FetchCoinFromBase.adoc[`FetchCoinFromBase`]  [.small]#[virtual]#
| Fetch the coin from base&period; Used for cache misses in FetchCoin&period;
| xref:CoinsViewOverlay/Reset.adoc[`Reset`]  [.small]#[virtual]#
| Stop any in&hyphen;progress fetching, then discard this overlay&apos;s modifications&period;
|===


== Protected Data Members

[cols="1,4"]
|===
| Name| Description
| xref:CCoinsViewBacked/base.adoc[`base`] 
| The underlying view that all calls are forwarded to&period;
| xref:CCoinsViewCache/cacheCoins.adoc[`cacheCoins`] 
| The map of cached coins, keyed by outpoint&period;
| xref:CCoinsViewCache/cachedCoinsUsage.adoc[`cachedCoinsUsage`] 
| Cached dynamic memory usage for the inner Coin objects&period;
| xref:CCoinsViewCache/m_block_hash.adoc[`m&lowbar;block&lowbar;hash`] 
| Make mutable so that we can &quot;fill the cache&quot; even from Get&hyphen;methods declared as &quot;const&quot;&period;
| xref:CCoinsViewCache/m_cache_coins_memory_resource.adoc[`m&lowbar;cache&lowbar;coins&lowbar;memory&lowbar;resource`] 
| Memory resource that backs the pool allocator used by cacheCoins&period;
| xref:CCoinsViewCache/m_dirty_count.adoc[`m&lowbar;dirty&lowbar;count`] 
| Running count of dirty Coin cache entries&period;
| xref:CCoinsViewCache/m_sentinel.adoc[`m&lowbar;sentinel`] 
| The starting sentinel of the flagged entry circular doubly linked list&period;
|===


== Non-Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:AccessByTxid.adoc[`AccessByTxid`]
| Utility function to find any unspent output with a given txid&period; This function can be quite expensive because in the event of a transaction which is not found in the cache, it can cause up to MAX&lowbar;OUTPUTS&lowbar;PER&lowbar;BLOCK lookups to database, so it should be used with care&period;
| xref:AddCoins.adoc[`AddCoins`]
| Utility function to add all of a transaction&apos;s outputs to a cache&period; When check is false, this assumes that overwrites are only possible for coinbase transactions&period; When check is true, the underlying view may be queried to determine whether an addition is an overwrite&period;
|===


[.small]#Created with https://www.mrdocs.com[MrDocs]#
