validationinterface.h

Go to the documentation of this file.

// Copyright (c) 2009-2010 Satoshi Nakamoto
// Copyright (c) 2009-2022 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_VALIDATIONINTERFACE_H
#define BITCOIN_VALIDATIONINTERFACE_H

#include <kernel/chain.h>
#include <kernel/cs_main.h>
#include <primitives/transaction.h> // CTransaction(Ref)
#include <sync.h>

#include <cstddef>
#include <cstdint>
#include <functional>
#include <memory>
#include <vector>

namespace util {
class TaskRunnerInterface;
} // namespace util

class BlockValidationState;
class CBlock;
class CBlockIndex;
struct CBlockLocator;
enum class MemPoolRemovalReason;
struct RemovedMempoolTransactionInfo;
struct NewMempoolTransactionInfo;

class CValidationInterface {
protected:
    ~CValidationInterface() = default;
    virtual void UpdatedBlockTip(const CBlockIndex *pindexNew, const CBlockIndex *pindexFork, bool fInitialDownload) {}
    virtual void ActiveTipChange(const CBlockIndex& new_tip, bool is_ibd) {};
    virtual void TransactionAddedToMempool(const NewMempoolTransactionInfo& tx, uint64_t mempool_sequence) {}

    virtual void TransactionRemovedFromMempool(const CTransactionRef& tx, MemPoolRemovalReason reason, uint64_t mempool_sequence) {}
    /*
     * Notifies listeners of transactions removed from the mempool as
     * as a result of new block being connected.
     * MempoolTransactionsRemovedForBlock will be fired before BlockConnected.
     *
     * Called on a background thread.
     */
    virtual void MempoolTransactionsRemovedForBlock(const std::vector<RemovedMempoolTransactionInfo>& txs_removed_for_block, unsigned int nBlockHeight) {}
    virtual void BlockConnected(ChainstateRole role, const std::shared_ptr<const CBlock> &block, const CBlockIndex *pindex) {}
    virtual void BlockDisconnected(const std::shared_ptr<const CBlock> &block, const CBlockIndex* pindex) {}
    virtual void ChainStateFlushed(ChainstateRole role, const CBlockLocator &locator) {}
    virtual void BlockChecked(const CBlock&, const BlockValidationState&) {}
    virtual void NewPoWValidBlock(const CBlockIndex *pindex, const std::shared_ptr<const CBlock>& block) {};
    friend class ValidationSignals;
    friend class ValidationInterfaceTest;
};

class ValidationSignalsImpl;
class ValidationSignals {
private:
    std::unique_ptr<ValidationSignalsImpl> m_internals;

public:
    // The task runner will block validation if it calls its insert method's
    // func argument synchronously. In this class func contains a loop that
    // dispatches a single validation event to all subscribers sequentially.
    explicit ValidationSignals(std::unique_ptr<util::TaskRunnerInterface> task_runner);

    ~ValidationSignals();

    void FlushBackgroundCallbacks();

    size_t CallbacksPending();

    void RegisterValidationInterface(CValidationInterface* callbacks);
    void UnregisterValidationInterface(CValidationInterface* callbacks);
    void UnregisterAllValidationInterfaces();

    // Alternate registration functions that release a shared_ptr after the last
    // notification is sent. These are useful for race-free cleanup, since
    // unregistration is nonblocking and can return before the last notification is
    // processed.
    void RegisterSharedValidationInterface(std::shared_ptr<CValidationInterface> callbacks);
    void UnregisterSharedValidationInterface(std::shared_ptr<CValidationInterface> callbacks);

    void CallFunctionInValidationInterfaceQueue(std::function<void ()> func);

    void SyncWithValidationInterfaceQueue() LOCKS_EXCLUDED(cs_main);

    void UpdatedBlockTip(const CBlockIndex *, const CBlockIndex *, bool fInitialDownload);
    void ActiveTipChange(const CBlockIndex&, bool);
    void TransactionAddedToMempool(const NewMempoolTransactionInfo&, uint64_t mempool_sequence);
    void TransactionRemovedFromMempool(const CTransactionRef&, MemPoolRemovalReason, uint64_t mempool_sequence);
    void MempoolTransactionsRemovedForBlock(const std::vector<RemovedMempoolTransactionInfo>&, unsigned int nBlockHeight);
    void BlockConnected(ChainstateRole, const std::shared_ptr<const CBlock> &, const CBlockIndex *pindex);
    void BlockDisconnected(const std::shared_ptr<const CBlock> &, const CBlockIndex* pindex);
    void ChainStateFlushed(ChainstateRole, const CBlockLocator &);
    void BlockChecked(const CBlock&, const BlockValidationState&);
    void NewPoWValidBlock(const CBlockIndex *, const std::shared_ptr<const CBlock>&);
};

#endif // BITCOIN_VALIDATIONINTERFACE_H