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