Line data    Source code

       1             : // Copyright (c) 2009-2010 Satoshi Nakamoto
       2             : // Copyright (c) 2009-2015 The Bitcoin Core developers
       3             : // Copyright (c) 2017-2021 The PIVX Core developers
       4             : // Distributed under the MIT software license, see the accompanying
       5             : // file COPYING or http://www.opensource.org/licenses/mit-license.php.
       6             : 
       7             : #ifndef PIVX_VALIDATIONINTERFACE_H
       8             : #define PIVX_VALIDATIONINTERFACE_H
       9             : 
      10             : #include "optional.h"
      11             : #include "sapling/incrementalmerkletree.h"
      12             : #include "primitives/transaction.h"
      13             : 
      14             : #include <functional>
      15             : #include <memory>
      16             : 
      17             : class CBlock;
      18             : struct CBlockLocator;
      19             : class CBlockIndex;
      20             : class CConnman;
      21             : class CDeterministicMNList;
      22             : class CDeterministicMNListDiff;
      23             : class CValidationInterface;
      24             : class CValidationState;
      25             : class uint256;
      26             : class CScheduler;
      27             : enum class MemPoolRemovalReason;
      28             : 
      29             : // These functions dispatch to one or all registered wallets
      30             : 
      31             : /** Register a wallet to receive updates from core */
      32             : void RegisterValidationInterface(CValidationInterface* pwalletIn);
      33             : /** Unregister a wallet from core */
      34             : void UnregisterValidationInterface(CValidationInterface* pwalletIn);
      35             : /** Unregister all wallets from core */
      36             : void UnregisterAllValidationInterfaces();
      37             : 
      38             : // Alternate registration functions that release a shared_ptr after the last
      39             : // notification is sent. These are useful for race-free cleanup, since
      40             : // unregistration is nonblocking and can return before the last notification is
      41             : // processed.
      42             : void RegisterSharedValidationInterface(std::shared_ptr<CValidationInterface> pwalletIn);
      43             : void UnregisterSharedValidationInterface(std::shared_ptr<CValidationInterface> pwalletIn);
      44             : 
      45             : /**
      46             :  * Pushes a function to callback onto the notification queue, guaranteeing any
      47             :  * callbacks generated prior to now are finished when the function is called.
      48             :  *
      49             :  * Be very careful blocking on func to be called if any locks are held -
      50             :  * validation interface clients may not be able to make progress as they often
      51             :  * wait for things like cs_main, so blocking until func is called with cs_main
      52             :  * will result in a deadlock (that DEBUG_LOCKORDER will miss).
      53             :  */
      54             : void CallFunctionInValidationInterfaceQueue(std::function<void ()> func);
      55             : /**
      56             :  * This is a synonym for the following, which asserts certain locks are not
      57             :  * held:
      58             :  *     std::promise<void> promise;
      59             :  *     CallFunctionInValidationInterfaceQueue([&promise] {
      60             :  *         promise.set_value();
      61             :  *     });
      62             :  *     promise.get_future().wait();
      63             :  */
      64             : void SyncWithValidationInterfaceQueue();
      65             : 
      66             : /**
      67             :  * Implement this to subscribe to events generated in validation
      68             :  *
      69             :  * Each CValidationInterface() subscriber will receive event callbacks
      70             :  * in the order in which the events were generated by validation.
      71             :  * Furthermore, each ValidationInterface() subscriber may assume that
      72             :  * callbacks effectively run in a single thread with single-threaded
      73             :  * memory consistency. That is, for a given ValidationInterface()
      74             :  * instantiation, each callback will complete before the next one is
      75             :  * invoked. This means, for example when a block is connected that the
      76             :  * UpdatedBlockTip() callback may depend on an operation performed in
      77             :  * the BlockConnected() callback without worrying about explicit
      78             :  * synchronization. No ordering should be assumed across
      79             :  * ValidationInterface() subscribers.
      80             :  */
      81        5419 : class CValidationInterface {
      82             : public:
      83        1506 :     virtual ~CValidationInterface() = default;
      84      172699 :     virtual void AcceptedBlockHeader(const CBlockIndex* pindexNew) {}
      85             : 
      86             : protected:
      87             :     /**
      88             :      * Notifies listeners when the block chain tip advances.
      89             :      *
      90             :      * When multiple blocks are connected at once, UpdatedBlockTip will be called on the final tip
      91             :      * but may not be called on every intermediate tip. If the latter behavior is desired,
      92             :      * subscribe to BlockConnected() instead.
      93             :      *
      94             :      * Called on a background thread.
      95             :      */
      96        9764 :     virtual void UpdatedBlockTip(const CBlockIndex* pindexNew, const CBlockIndex* pindexFork, bool fInitialDownload) {}
      97             :     /**
      98             :      * Notifies listeners of a transaction having been added to mempool.
      99             :      *
     100             :      * Called on a background thread.
     101             :      */
     102      684470 :     virtual void TransactionAddedToMempool(const CTransactionRef &ptxn) {}
     103             :     /**
     104             :      * Notifies listeners of a transaction leaving mempool.
     105             :      *
     106             :      * This notification fires for transactions that are removed from the
     107             :      * mempool for the following reasons:
     108             :      *
     109             :      * - EXPIRY (expired from mempool after -mempoolexpiry hours)
     110             :      * - SIZELIMIT (removed in size limiting if the mempool exceeds -maxmempool megabytes)
     111             :      * - REORG (removed during a reorg)
     112             :      * - CONFLICT (removed because it conflicts with in-block transaction)
     113             :      * - REPLACED (removed due to RBF replacement) -- not supported yet --
     114             :      *
     115             :      * This does not fire for transactions that are removed from the mempool
     116             :      * because they have been included in a block. Any client that is interested
     117             :      * in transactions removed from the mempool for inclusion in a block can learn
     118             :      * about those transactions from the BlockConnected notification.
     119             :      *
     120             :      * Transactions that are removed from the mempool because they conflict
     121             :      * with a transaction in the new block will have
     122             :      * TransactionRemovedFromMempool events fired *before* the BlockConnected
     123             :      * event is fired. If multiple blocks are connected in one step, then the
     124             :      * ordering could be:
     125             :      *
     126             :      * - TransactionRemovedFromMempool(tx1 from block A)
     127             :      * - TransactionRemovedFromMempool(tx2 from block A)
     128             :      * - TransactionRemovedFromMempool(tx1 from block B)
     129             :      * - TransactionRemovedFromMempool(tx2 from block B)
     130             :      * - BlockConnected(A)
     131             :      * - BlockConnected(B)
     132             :      *
     133             :      * Called on a background thread.
     134             :      */
     135        5647 :     virtual void TransactionRemovedFromMempool(const CTransactionRef &ptx, MemPoolRemovalReason reason) {}
     136             :     /**
     137             :      * Notifies listeners of a block being connected.
     138             :      * Provides a vector of transactions evicted from the mempool as a result.
     139             :      *
     140             :      * Called on a background thread.
     141             :      */
     142      133214 :     virtual void BlockConnected(const std::shared_ptr<const CBlock> &block, const CBlockIndex *pindex) {}
     143             :     /**
     144             :      * Notifies listeners of a block being disconnected
     145             :      *
     146             :      * Called on a background thread.
     147             :      */
     148        1300 :     virtual void BlockDisconnected(const std::shared_ptr<const CBlock> &block, const uint256& blockHash, int nBlockHeight, int64_t blockTime) {}
     149             :     /**
     150             :      * Notifies listeners of the new active block chain on-disk.
     151             :      *
     152             :      * Called on a background thread.
     153             :      */
     154           0 :     virtual void SetBestChain(const CBlockLocator &locator) {}
     155             :     /** Tells listeners to broadcast their data. */
     156     7716420 :     virtual void ResendWalletTransactions(CConnman* connman) {}
     157      185656 :     virtual void BlockChecked(const CBlock&, const CValidationState&) {}
     158             :     friend void ::RegisterSharedValidationInterface(std::shared_ptr<CValidationInterface>);
     159             :     friend void ::UnregisterValidationInterface(CValidationInterface*);
     160             :     friend void ::UnregisterAllValidationInterfaces();
     161             :     /** Notifies listeners of updated deterministic masternode list */
     162       33591 :     virtual void NotifyMasternodeListChanged(bool undo, const CDeterministicMNList& oldMNList, const CDeterministicMNListDiff& diff) {}
     163             : };
     164             : 
     165             : struct MainSignalsInstance;
     166             : class CMainSignals {
     167             : private:
     168             :     std::unique_ptr<MainSignalsInstance> m_internals;
     169             : 
     170             :     friend void ::RegisterSharedValidationInterface(std::shared_ptr<CValidationInterface>);
     171             :     friend void ::UnregisterValidationInterface(CValidationInterface*);
     172             :     friend void ::UnregisterAllValidationInterfaces();
     173             :     friend void ::CallFunctionInValidationInterfaceQueue(std::function<void ()> func);
     174             : 
     175             : public:
     176             :     /** Register a CScheduler to give callbacks which should run in the background (may only be called once) */
     177             :     void RegisterBackgroundSignalScheduler(CScheduler& scheduler);
     178             :     /** Unregister a CScheduler to give callbacks which should run in the background - these callbacks will now be dropped! */
     179             :     void UnregisterBackgroundSignalScheduler();
     180             :     /** Call any remaining callbacks on the calling thread */
     181             :     void FlushBackgroundCallbacks();
     182             : 
     183             :     size_t CallbacksPending();
     184             : 
     185             :     void AcceptedBlockHeader(const CBlockIndex* pindexNew);
     186             :     void UpdatedBlockTip(const CBlockIndex *, const CBlockIndex *, bool fInitialDownload);
     187             :     void TransactionAddedToMempool(const CTransactionRef &ptxn);
     188             :     void TransactionRemovedFromMempool(const CTransactionRef&, MemPoolRemovalReason);
     189             :     void BlockConnected(const std::shared_ptr<const CBlock> &block, const CBlockIndex *pindex);
     190             :     void BlockDisconnected(const std::shared_ptr<const CBlock> &block, const uint256& blockHash, int nBlockHeight, int64_t blockTime);
     191             :     void SetBestChain(const CBlockLocator &);
     192             :     void Broadcast(CConnman* connman);
     193             :     void BlockChecked(const CBlock&, const CValidationState&);
     194             :     void NotifyMasternodeListChanged(bool undo, const CDeterministicMNList& oldMNList, const CDeterministicMNListDiff& diff);
     195             : };
     196             : 
     197             : CMainSignals& GetMainSignals();
     198             : 
     199             : #endif // PIVX_VALIDATIONINTERFACE_H