coins.h

Go to the documentation of this file.

// Copyright (c) 2009-2010 Satoshi Nakamoto
// Copyright (c) 2009-2016 The Bitcoin Core developers
// Distributed under the MIT software license, see the accompanying
// file COPYING or http://www.opensource.org/licenses/mit-license.php.
 
#ifndef BITCOIN_COINS_H
#define BITCOIN_COINS_H
 
#include <attributes.h>
#include <compressor.h>
#include <memusage.h>
#include <primitives/blockhash.h>
#include <serialize.h>
#include <support/allocators/pool.h>
#include <util/check.h>
#include <util/hasher.h>
#include <util/overflow.h>
 
#include <cassert>
#include <cstdint>
#include <functional>
#include <unordered_map>
 
class Coin {
    CTxOut out;
 
    uint32_t nHeightAndIsCoinBase;
 
public:
    Coin() : nHeightAndIsCoinBase(0) {}
 
    Coin(CTxOut outIn, uint32_t nHeightIn, bool IsCoinbase)
        : out(std::move(outIn)),
          nHeightAndIsCoinBase((nHeightIn << 1) | IsCoinbase) {}
 
    uint32_t GetHeight() const { return nHeightAndIsCoinBase >> 1; }
    bool IsCoinBase() const { return nHeightAndIsCoinBase & 0x01; }
    bool IsSpent() const { return out.IsNull(); }
 
    CTxOut &GetTxOut() { return out; }
    const CTxOut &GetTxOut() const { return out; }
 
    void Clear() {
        out.SetNull();
        nHeightAndIsCoinBase = 0;
    }
 
    template <typename Stream> void Serialize(Stream &s) const {
        assert(!IsSpent());
        ::Serialize(s, VARINT(nHeightAndIsCoinBase));
        ::Serialize(s, Using<TxOutCompression>(out));
    }
 
    template <typename Stream> void Unserialize(Stream &s) {
        ::Unserialize(s, VARINT(nHeightAndIsCoinBase));
        ::Unserialize(s, Using<TxOutCompression>(out));
    }
 
    size_t DynamicMemoryUsage() const {
        return memusage::DynamicUsage(out.scriptPubKey);
    }
};
 
struct CCoinsCacheEntry;
using CoinsCachePair = std::pair<const COutPoint, CCoinsCacheEntry>;
 
struct CCoinsCacheEntry {
private:
    CoinsCachePair *m_prev{nullptr};
    CoinsCachePair *m_next{nullptr};
    uint8_t m_flags{0};
 
    static void AddFlags(uint8_t flags, CoinsCachePair &pair,
                         CoinsCachePair &sentinel) noexcept {
        Assume(flags & (DIRTY | FRESH));
        if (!pair.second.m_flags) {
            Assume(!pair.second.m_prev && !pair.second.m_next);
            pair.second.m_prev = sentinel.second.m_prev;
            pair.second.m_next = &sentinel;
            sentinel.second.m_prev = &pair;
            pair.second.m_prev->second.m_next = &pair;
        }
        Assume(pair.second.m_prev && pair.second.m_next);
        pair.second.m_flags |= flags;
    }
 
public:
    // The actual cached data.
    Coin coin;
 
    enum Flags {
        DIRTY = (1 << 0),
        FRESH = (1 << 1),
    };
 
    CCoinsCacheEntry() noexcept = default;
    explicit CCoinsCacheEntry(Coin &&coin_) : coin(std::move(coin_)) {}
    ~CCoinsCacheEntry() { SetClean(); }
 
    static void SetDirty(CoinsCachePair &pair,
                         CoinsCachePair &sentinel) noexcept {
        AddFlags(DIRTY, pair, sentinel);
    }
    static void SetFresh(CoinsCachePair &pair,
                         CoinsCachePair &sentinel) noexcept {
        AddFlags(FRESH, pair, sentinel);
    }
 
    void SetClean() noexcept {
        if (!m_flags) {
            return;
        }
        m_next->second.m_prev = m_prev;
        m_prev->second.m_next = m_next;
        m_flags = 0;
        m_prev = m_next = nullptr;
    }
    bool IsDirty() const noexcept { return m_flags & DIRTY; }
    bool IsFresh() const noexcept { return m_flags & FRESH; }
 
    CoinsCachePair *Next() const noexcept {
        Assume(m_flags);
        return m_next;
    }
 
    CoinsCachePair *Prev() const noexcept {
        Assume(m_flags);
        return m_prev;
    }
 
    void SelfRef(CoinsCachePair &pair) noexcept {
        Assume(&pair.second == this);
        m_prev = &pair;
        m_next = &pair;
        // Set sentinel to DIRTY so we can call Next on it
        m_flags = DIRTY;
    }
};
 
using CCoinsMap = std::unordered_map<
    COutPoint, CCoinsCacheEntry, SaltedOutpointHasher, std::equal_to<COutPoint>,
    PoolAllocator<CoinsCachePair, sizeof(CoinsCachePair) + sizeof(void *) * 4>>;
 
using CCoinsMapMemoryResource = CCoinsMap::allocator_type::ResourceType;
 
class CCoinsViewCursor {
public:
    CCoinsViewCursor(const BlockHash &hashBlockIn) : hashBlock(hashBlockIn) {}
    virtual ~CCoinsViewCursor() {}
 
    virtual bool GetKey(COutPoint &key) const = 0;
    virtual bool GetValue(Coin &coin) const = 0;
    virtual unsigned int GetValueSize() const = 0;
 
    virtual bool Valid() const = 0;
    virtual void Next() = 0;
 
    const BlockHash &GetBestBlock() const { return hashBlock; }
 
private:
    BlockHash hashBlock;
};
 
struct CoinsViewCacheCursor {
    CoinsViewCacheCursor(size_t &dirty_count LIFETIMEBOUND,
                         CoinsCachePair &sentinel LIFETIMEBOUND,
                         CCoinsMap &map LIFETIMEBOUND, bool will_erase) noexcept
        : m_dirty_count(dirty_count), m_sentinel(sentinel), m_map(map),
          m_will_erase(will_erase) {}
 
    inline CoinsCachePair *Begin() const noexcept {
        return m_sentinel.second.Next();
    }
    inline CoinsCachePair *End() const noexcept { return &m_sentinel; }
 
    inline CoinsCachePair *NextAndMaybeErase(CoinsCachePair &current) noexcept {
        const auto next_entry{current.second.Next()};
        Assume(TrySub(m_dirty_count, current.second.IsDirty()));
        // If we are not going to erase the cache, we must still erase spent
        // entries. Otherwise, clear the state of the entry.
        if (!m_will_erase) {
            if (current.second.coin.IsSpent()) {
                // scriptPubKey was already cleared in SpendCoin
                assert(current.second.coin.DynamicMemoryUsage() == 0);
                m_map.erase(current.first);
            } else {
                current.second.SetClean();
            }
        }
        return next_entry;
    }
 
    inline bool WillErase(CoinsCachePair &current) const noexcept {
        return m_will_erase || current.second.coin.IsSpent();
    }
    size_t GetDirtyCount() const noexcept { return m_dirty_count; }
    size_t GetTotalCount() const noexcept { return m_map.size(); }
 
private:
    size_t &m_dirty_count;
    CoinsCachePair &m_sentinel;
    CCoinsMap &m_map;
    bool m_will_erase;
};
 
class CCoinsView {
public:
    virtual std::optional<Coin> GetCoin(const COutPoint &outpoint) const;
 
    virtual bool HaveCoin(const COutPoint &outpoint) const;
 
    virtual BlockHash GetBestBlock() const;
 
    virtual std::vector<BlockHash> GetHeadBlocks() const;
 
    virtual void BatchWrite(CoinsViewCacheCursor &cursor,
                            const BlockHash &hashBlock);
 
    virtual CCoinsViewCursor *Cursor() const;
 
    virtual ~CCoinsView() {}
 
    virtual size_t EstimateSize() const { return 0; }
};
 
class CCoinsViewBacked : public CCoinsView {
protected:
    CCoinsView *base;
 
public:
    CCoinsViewBacked(CCoinsView *viewIn);
    std::optional<Coin> GetCoin(const COutPoint &outpoint) const override;
    bool HaveCoin(const COutPoint &outpoint) const override;
    BlockHash GetBestBlock() const override;
    std::vector<BlockHash> GetHeadBlocks() const override;
    void SetBackend(CCoinsView &viewIn);
    void BatchWrite(CoinsViewCacheCursor &cursor,
                    const BlockHash &hashBlock) override;
    CCoinsViewCursor *Cursor() const override;
    size_t EstimateSize() const override;
};
 
class CCoinsViewCache : public CCoinsViewBacked {
private:
    const bool m_deterministic;
 
protected:
    mutable BlockHash hashBlock;
    mutable CCoinsMapMemoryResource m_cache_coins_memory_resource{};
    mutable CoinsCachePair m_sentinel;
    mutable CCoinsMap cacheCoins;
 
    /* Cached dynamic memory usage for the inner Coin objects. */
    mutable size_t cachedCoinsUsage;
    /* Running count of dirty Coin cache entries. */
    mutable size_t m_dirty_count{0};
 
    void Reset() noexcept;
 
public:
    CCoinsViewCache(CCoinsView *baseIn, bool deterministic = false);
 
    CCoinsViewCache(const CCoinsViewCache &) = delete;
 
    // Standard CCoinsView methods
    std::optional<Coin> GetCoin(const COutPoint &outpoint) const override;
    bool HaveCoin(const COutPoint &outpoint) const override;
    BlockHash GetBestBlock() const override;
    void SetBestBlock(const BlockHash &hashBlock);
    void BatchWrite(CoinsViewCacheCursor &cursor,
                    const BlockHash &hashBlock) override;
    CCoinsViewCursor *Cursor() const override {
        throw std::logic_error(
            "CCoinsViewCache cursor iteration not supported.");
    }
 
    bool HaveCoinInCache(const COutPoint &outpoint) const;
 
    const Coin &AccessCoin(const COutPoint &output) const;
 
    void AddCoin(const COutPoint &outpoint, Coin coin, bool possible_overwrite);
 
    void EmplaceCoinInternalDANGER(COutPoint &&outpoint, Coin &&coin);
 
    bool SpendCoin(const COutPoint &outpoint, Coin *moveto = nullptr);
 
    void Flush(bool reallocate_cache = true);
 
    void Sync();
 
    void Uncache(const COutPoint &outpoint);
 
    unsigned int GetCacheSize() const;
 
    size_t GetDirtyCount() const noexcept { return m_dirty_count; }
 
    size_t DynamicMemoryUsage() const;
 
    bool HaveInputs(const CTransaction &tx) const;
 
    void ReallocateCache();
 
    void SanityCheck() const;
 
    class ResetGuard {
    private:
        friend CCoinsViewCache;
        CCoinsViewCache &m_cache;
        explicit ResetGuard(CCoinsViewCache &cache LIFETIMEBOUND) noexcept
            : m_cache{cache} {}
 
    public:
        ResetGuard(const ResetGuard &) = delete;
        ResetGuard &operator=(const ResetGuard &) = delete;
        ResetGuard(ResetGuard &&) = delete;
        ResetGuard &operator=(ResetGuard &&) = delete;
 
        ~ResetGuard() { m_cache.Reset(); }
    };
 
    [[nodiscard]] ResetGuard CreateResetGuard() noexcept {
        return ResetGuard{*this};
    }
 
private:
    CCoinsMap::iterator FetchCoin(const COutPoint &outpoint) const;
};
 
// TODO: pass in a boolean to limit these possible overwrites to known
// (pre-BIP34) cases.
void AddCoins(CCoinsViewCache &cache, const CTransaction &tx, int nHeight,
              bool check = false);
 
const Coin &AccessByTxid(const CCoinsViewCache &cache, const TxId &txid);
 
class CCoinsViewErrorCatcher final : public CCoinsViewBacked {
public:
    explicit CCoinsViewErrorCatcher(CCoinsView *view)
        : CCoinsViewBacked(view) {}
 
    void AddReadErrCallback(std::function<void()> f) {
        m_err_callbacks.emplace_back(std::move(f));
    }
 
    std::optional<Coin> GetCoin(const COutPoint &outpoint) const override;
    bool HaveCoin(const COutPoint &outpoint) const override;
 
private:
    std::vector<std::function<void()>> m_err_callbacks;
};
 
#endif // BITCOIN_COINS_H