src/validationinterface.h

   1 // Copyright (c) 2009-2010 Satoshi Nakamoto
   2 // Copyright (c) 2009-2017 The Bitcoin Core developers
   3 // Distributed under the MIT software license, see the accompanying
   4 // file COPYING or http://www.opensource.org/licenses/mit-license.php.
   5
   6 #ifndef BITCOIN_VALIDATIONINTERFACE_H
   7 #define BITCOIN_VALIDATIONINTERFACE_H
   8
   9 #include <primitives/transaction.h> // CTransaction(Ref)
  10
  11 #include <functional>
  12 #include <memory>
  13
  14 class CBlock;
  15 class CBlockIndex;
  16 struct CBlockLocator;
  17 class CBlockIndex;
  18 class CConnman;
  19 class CReserveScript;
  20 class CValidationInterface;
  21 class CValidationState;
  22 class uint256;
  23 class CScheduler;
  24 class CTxMemPool;
  25 enum class MemPoolRemovalReason;
  26
  27 // These functions dispatch to one or all registered wallets
  28
  29 /** Register a wallet to receive updates from core */
  30 void RegisterValidationInterface(CValidationInterface* pwalletIn);
  31 /** Unregister a wallet from core */
  32 void UnregisterValidationInterface(CValidationInterface* pwalletIn);
  33 /** Unregister all wallets from core */
  34 void UnregisterAllValidationInterfaces();
  35 /**
  36  * Pushes a function to callback onto the notification queue, guaranteeing any
  37  * callbacks generated prior to now are finished when the function is called.
  38  *
  39  * Be very careful blocking on func to be called if any locks are held -
  40  * validation interface clients may not be able to make progress as they often
  41  * wait for things like cs_main, so blocking until func is called with cs_main
  42  * will result in a deadlock (that DEBUG_LOCKORDER will miss).
  43  */
  44 void CallFunctionInValidationInterfaceQueue(std::function<void ()> func);
  45 /**
  46  * This is a synonym for the following, which asserts certain locks are not
  47  * held:
  48  *     std::promise<void> promise;
  49  *     CallFunctionInValidationInterfaceQueue([&promise] {
  50  *         promise.set_value();
  51  *     });
  52  *     promise.get_future().wait();
  53  */
  54 void SyncWithValidationInterfaceQueue();
  55
  56 class CValidationInterface {
  57 protected:
  58     /**
  59      * Notifies listeners of updated block chain tip
  60      *
  61      * Called on a background thread.
  62      */
  63     virtual void UpdatedBlockTip(const CBlockIndex *pindexNew, const CBlockIndex *pindexFork, bool fInitialDownload) {}
  64     /**
  65      * Notifies listeners of a transaction having been added to mempool.
  66      *
  67      * Called on a background thread.
  68      */
  69     virtual void TransactionAddedToMempool(const CTransactionRef &ptxn) {}
  70     /**
  71      * Notifies listeners of a transaction leaving mempool.
  72      *
  73      * This only fires for transactions which leave mempool because of expiry,
  74      * size limiting, reorg (changes in lock times/coinbase maturity), or
  75      * replacement. This does not include any transactions which are included
  76      * in BlockConnectedDisconnected either in block->vtx or in txnConflicted.
  77      *
  78      * Called on a background thread.
  79      */
  80     virtual void TransactionRemovedFromMempool(const CTransactionRef &ptx) {}
  81     /**
  82      * Notifies listeners of a block being connected.
  83      * Provides a vector of transactions evicted from the mempool as a result.
  84      *
  85      * Called on a background thread.
  86      */
  87     virtual void BlockConnected(const std::shared_ptr<const CBlock> &block, const CBlockIndex *pindex, const std::vector<CTransactionRef> &txnConflicted) {}
  88     /**
  89      * Notifies listeners of a block being disconnected
  90      *
  91      * Called on a background thread.
  92      */
  93     virtual void BlockDisconnected(const std::shared_ptr<const CBlock> &block) {}
  94     /**
  95      * Notifies listeners of the new active block chain on-disk.
  96      *
  97      * Called on a background thread.
  98      */
  99     virtual void SetBestChain(const CBlockLocator &locator) {}
 100     /**
 101      * Notifies listeners about an inventory item being seen on the network.
 102      *
 103      * Called on a background thread.
 104      */
 105     virtual void Inventory(const uint256 &hash) {}
 106     /** Tells listeners to broadcast their data. */
 107     virtual void ResendWalletTransactions(int64_t nBestBlockTime, CConnman* connman) {}
 108     /**
 109      * Notifies listeners of a block validation result.
 110      * If the provided CValidationState IsValid, the provided block
 111      * is guaranteed to be the current best block at the time the
 112      * callback was generated (not necessarily now)
 113      */
 114     virtual void BlockChecked(const CBlock&, const CValidationState&) {}
 115     /**
 116      * Notifies listeners that a block which builds directly on our current tip
 117      * has been received and connected to the headers tree, though not validated yet */
 118     virtual void NewPoWValidBlock(const CBlockIndex *pindex, const std::shared_ptr<const CBlock>& block) {};
 119     friend void ::RegisterValidationInterface(CValidationInterface*);
 120     friend void ::UnregisterValidationInterface(CValidationInterface*);
 121     friend void ::UnregisterAllValidationInterfaces();
 122 };
 123
 124 struct MainSignalsInstance;
 125 class CMainSignals {
 126 private:
 127     std::unique_ptr<MainSignalsInstance> m_internals;
 128
 129     friend void ::RegisterValidationInterface(CValidationInterface*);
 130     friend void ::UnregisterValidationInterface(CValidationInterface*);
 131     friend void ::UnregisterAllValidationInterfaces();
 132     friend void ::CallFunctionInValidationInterfaceQueue(std::function<void ()> func);
 133
 134     void MempoolEntryRemoved(CTransactionRef tx, MemPoolRemovalReason reason);
 135
 136 public:
 137     /** Register a CScheduler to give callbacks which should run in the background (may only be called once) */
 138     void RegisterBackgroundSignalScheduler(CScheduler& scheduler);
 139     /** Unregister a CScheduler to give callbacks which should run in the background - these callbacks will now be dropped! */
 140     void UnregisterBackgroundSignalScheduler();
 141     /** Call any remaining callbacks on the calling thread */
 142     void FlushBackgroundCallbacks();
 143
 144     size_t CallbacksPending();
 145
 146     /** Register with mempool to call TransactionRemovedFromMempool callbacks */
 147     void RegisterWithMempoolSignals(CTxMemPool& pool);
 148     /** Unregister with mempool */
 149     void UnregisterWithMempoolSignals(CTxMemPool& pool);
 150
 151     void UpdatedBlockTip(const CBlockIndex *, const CBlockIndex *, bool fInitialDownload);
 152     void TransactionAddedToMempool(const CTransactionRef &);
 153     void BlockConnected(const std::shared_ptr<const CBlock> &, const CBlockIndex *pindex, const std::shared_ptr<const std::vector<CTransactionRef>> &);
 154     void BlockDisconnected(const std::shared_ptr<const CBlock> &);
 155     void SetBestChain(const CBlockLocator &);
 156     void Inventory(const uint256 &);
 157     void Broadcast(int64_t nBestBlockTime, CConnman* connman);
 158     void BlockChecked(const CBlock&, const CValidationState&);
 159     void NewPoWValidBlock(const CBlockIndex *, const std::shared_ptr<const CBlock>&);
 160 };
 161
 162 CMainSignals& GetMainSignals();
 163
 164 #endif // BITCOIN_VALIDATIONINTERFACE_H