Line data    Source code

       1             : // Copyright (c) 2009-2010 Satoshi Nakamoto
       2             : // Copyright (c) 2009-2022 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 <kernel/cs_main.h>
      10             : #include <primitives/transaction.h> // CTransaction(Ref)
      11             : #include <sync.h>
      12             : 
      13             : #include <functional>
      14             : #include <memory>
      15             : 
      16             : class BlockValidationState;
      17             : class CBlock;
      18             : class CBlockIndex;
      19             : struct CBlockLocator;
      20             : class CValidationInterface;
      21             : class CScheduler;
      22             : enum class MemPoolRemovalReason;
      23             : 
      24             : /** Register subscriber */
      25             : void RegisterValidationInterface(CValidationInterface* callbacks);
      26             : /** Unregister subscriber. DEPRECATED. This is not safe to use when the RPC server or main message handler thread is running. */
      27             : void UnregisterValidationInterface(CValidationInterface* callbacks);
      28             : /** Unregister all subscribers */
      29             : void UnregisterAllValidationInterfaces();
      30             : 
      31             : // Alternate registration functions that release a shared_ptr after the last
      32             : // notification is sent. These are useful for race-free cleanup, since
      33             : // unregistration is nonblocking and can return before the last notification is
      34             : // processed.
      35             : /** Register subscriber */
      36             : void RegisterSharedValidationInterface(std::shared_ptr<CValidationInterface> callbacks);
      37             : /** Unregister subscriber */
      38             : void UnregisterSharedValidationInterface(std::shared_ptr<CValidationInterface> callbacks);
      39             : 
      40             : /**
      41             :  * Pushes a function to callback onto the notification queue, guaranteeing any
      42             :  * callbacks generated prior to now are finished when the function is called.
      43             :  *
      44             :  * Be very careful blocking on func to be called if any locks are held -
      45             :  * validation interface clients may not be able to make progress as they often
      46             :  * wait for things like cs_main, so blocking until func is called with cs_main
      47             :  * will result in a deadlock (that DEBUG_LOCKORDER will miss).
      48             :  */
      49             : void CallFunctionInValidationInterfaceQueue(std::function<void ()> func);
      50             : /**
      51             :  * This is a synonym for the following, which asserts certain locks are not
      52             :  * held:
      53             :  *     std::promise<void> promise;
      54             :  *     CallFunctionInValidationInterfaceQueue([&promise] {
      55             :  *         promise.set_value();
      56             :  *     });
      57             :  *     promise.get_future().wait();
      58             :  */
      59             : void SyncWithValidationInterfaceQueue() LOCKS_EXCLUDED(cs_main);
      60             : 
      61             : /**
      62             :  * Implement this to subscribe to events generated in validation
      63             :  *
      64             :  * Each CValidationInterface() subscriber will receive event callbacks
      65             :  * in the order in which the events were generated by validation.
      66             :  * Furthermore, each ValidationInterface() subscriber may assume that
      67             :  * callbacks effectively run in a single thread with single-threaded
      68             :  * memory consistency. That is, for a given ValidationInterface()
      69             :  * instantiation, each callback will complete before the next one is
      70             :  * invoked. This means, for example when a block is connected that the
      71             :  * UpdatedBlockTip() callback may depend on an operation performed in
      72             :  * the BlockConnected() callback without worrying about explicit
      73             :  * synchronization. No ordering should be assumed across
      74             :  * ValidationInterface() subscribers.
      75             :  */
      76             : class CValidationInterface {
      77             : protected:
      78             :     /**
      79             :      * Protected destructor so that instances can only be deleted by derived classes.
      80             :      * If that restriction is no longer desired, this should be made public and virtual.
      81             :      */
      82             :     ~CValidationInterface() = default;
      83             :     /**
      84             :      * Notifies listeners when the block chain tip advances.
      85             :      *
      86             :      * When multiple blocks are connected at once, UpdatedBlockTip will be called on the final tip
      87             :      * but may not be called on every intermediate tip. If the latter behavior is desired,
      88             :      * subscribe to BlockConnected() instead.
      89             :      *
      90             :      * Called on a background thread.
      91             :      */
      92         168 :     virtual void UpdatedBlockTip(const CBlockIndex *pindexNew, const CBlockIndex *pindexFork, bool fInitialDownload) {}
      93             :     /**
      94             :      * Notifies listeners of a transaction having been added to mempool.
      95             :      *
      96             :      * Called on a background thread.
      97             :      */
      98           0 :     virtual void TransactionAddedToMempool(const CTransactionRef& tx, uint64_t mempool_sequence) {}
      99             : 
     100             :     /**
     101             :      * Notifies listeners of a transaction leaving mempool.
     102             :      *
     103             :      * This notification fires for transactions that are removed from the
     104             :      * mempool for the following reasons:
     105             :      *
     106             :      * - EXPIRY (expired from mempool after -mempoolexpiry hours)
     107             :      * - SIZELIMIT (removed in size limiting if the mempool exceeds -maxmempool megabytes)
     108             :      * - REORG (removed during a reorg)
     109             :      * - CONFLICT (removed because it conflicts with in-block transaction)
     110             :      * - REPLACED (removed due to RBF replacement)
     111             :      *
     112             :      * This does not fire for transactions that are removed from the mempool
     113             :      * because they have been included in a block. Any client that is interested
     114             :      * in transactions removed from the mempool for inclusion in a block can learn
     115             :      * about those transactions from the BlockConnected notification.
     116             :      *
     117             :      * Transactions that are removed from the mempool because they conflict
     118             :      * with a transaction in the new block will have
     119             :      * TransactionRemovedFromMempool events fired *before* the BlockConnected
     120             :      * event is fired. If multiple blocks are connected in one step, then the
     121             :      * ordering could be:
     122             :      *
     123             :      * - TransactionRemovedFromMempool(tx1 from block A)
     124             :      * - TransactionRemovedFromMempool(tx2 from block A)
     125             :      * - TransactionRemovedFromMempool(tx1 from block B)
     126             :      * - TransactionRemovedFromMempool(tx2 from block B)
     127             :      * - BlockConnected(A)
     128             :      * - BlockConnected(B)
     129             :      *
     130             :      * Called on a background thread.
     131             :      */
     132           0 :     virtual void TransactionRemovedFromMempool(const CTransactionRef& tx, MemPoolRemovalReason reason, uint64_t mempool_sequence) {}
     133             :     /**
     134             :      * Notifies listeners of a block being connected.
     135             :      * Provides a vector of transactions evicted from the mempool as a result.
     136             :      *
     137             :      * Called on a background thread.
     138             :      */
     139         177 :     virtual void BlockConnected(const std::shared_ptr<const CBlock> &block, const CBlockIndex *pindex) {}
     140             :     /**
     141             :      * Notifies listeners of a block being disconnected
     142             :      *
     143             :      * Called on a background thread.
     144             :      */
     145           0 :     virtual void BlockDisconnected(const std::shared_ptr<const CBlock> &block, const CBlockIndex* pindex) {}
     146             :     /**
     147             :      * Notifies listeners of the new active block chain on-disk.
     148             :      *
     149             :      * Prior to this callback, any updates are not guaranteed to persist on disk
     150             :      * (ie clients need to handle shutdown/restart safety by being able to
     151             :      * understand when some updates were lost due to unclean shutdown).
     152             :      *
     153             :      * When this callback is invoked, the validation changes done by any prior
     154             :      * callback are guaranteed to exist on disk and survive a restart, including
     155             :      * an unclean shutdown.
     156             :      *
     157             :      * Provides a locator describing the best chain, which is likely useful for
     158             :      * storing current state on disk in client DBs.
     159             :      *
     160             :      * Called on a background thread.
     161             :      */
     162           0 :     virtual void ChainStateFlushed(const CBlockLocator &locator) {}
     163             :     /**
     164             :      * Notifies listeners of a block validation result.
     165             :      * If the provided BlockValidationState IsValid, the provided block
     166             :      * is guaranteed to be the current best block at the time the
     167             :      * callback was generated (not necessarily now)
     168             :      */
     169           0 :     virtual void BlockChecked(const CBlock&, const BlockValidationState&) {}
     170             :     /**
     171             :      * Notifies listeners that a block which builds directly on our current tip
     172             :      * has been received and connected to the headers tree, though not validated yet */
     173           0 :     virtual void NewPoWValidBlock(const CBlockIndex *pindex, const std::shared_ptr<const CBlock>& block) {};
     174             :     friend class CMainSignals;
     175             :     friend class ValidationInterfaceTest;
     176             : };
     177             : 
     178             : class MainSignalsImpl;
     179             : class CMainSignals {
     180             : private:
     181             :     std::unique_ptr<MainSignalsImpl> m_internals;
     182             : 
     183             :     friend void ::RegisterSharedValidationInterface(std::shared_ptr<CValidationInterface>);
     184             :     friend void ::UnregisterValidationInterface(CValidationInterface*);
     185             :     friend void ::UnregisterAllValidationInterfaces();
     186             :     friend void ::CallFunctionInValidationInterfaceQueue(std::function<void ()> func);
     187             : 
     188             : public:
     189             :     /** Register a CScheduler to give callbacks which should run in the background (may only be called once) */
     190             :     void RegisterBackgroundSignalScheduler(CScheduler& scheduler);
     191             :     /** Unregister a CScheduler to give callbacks which should run in the background - these callbacks will now be dropped! */
     192             :     void UnregisterBackgroundSignalScheduler();
     193             :     /** Call any remaining callbacks on the calling thread */
     194             :     void FlushBackgroundCallbacks();
     195             : 
     196             :     size_t CallbacksPending();
     197             : 
     198             : 
     199             :     void UpdatedBlockTip(const CBlockIndex *, const CBlockIndex *, bool fInitialDownload);
     200             :     void TransactionAddedToMempool(const CTransactionRef&, uint64_t mempool_sequence);
     201             :     void TransactionRemovedFromMempool(const CTransactionRef&, MemPoolRemovalReason, uint64_t mempool_sequence);
     202             :     void BlockConnected(const std::shared_ptr<const CBlock> &, const CBlockIndex *pindex);
     203             :     void BlockDisconnected(const std::shared_ptr<const CBlock> &, const CBlockIndex* pindex);
     204             :     void ChainStateFlushed(const CBlockLocator &);
     205             :     void BlockChecked(const CBlock&, const BlockValidationState&);
     206             :     void NewPoWValidBlock(const CBlockIndex *, const std::shared_ptr<const CBlock>&);
     207             : };
     208             : 
     209             : CMainSignals& GetMainSignals();
     210             : 
     211             : #endif // BITCOIN_VALIDATIONINTERFACE_H