From d5adb9d09b858d2ab61be52a4b8359cef7c65a0b Mon Sep 17 00:00:00 2001 From: Matthew Zipkin Date: Mon, 4 May 2026 10:37:18 -0400 Subject: [PATCH] doc: fix doxygen links to threads in developer-notes.md --- doc/developer-notes.md | 30 +++++++++++++++--------------- src/bitcoind.cpp | 1 + src/checkqueue.h | 1 + src/httpserver.cpp | 2 ++ src/index/base.h | 1 + src/init.cpp | 1 + src/mapport.cpp | 1 + src/net.h | 6 ++++++ src/scheduler.h | 1 + src/torcontrol.h | 3 ++- 10 files changed, 31 insertions(+), 16 deletions(-) diff --git a/doc/developer-notes.md b/doc/developer-notes.md index e79c14ad47f..22789d09743 100644 --- a/doc/developer-notes.md +++ b/doc/developer-notes.md @@ -672,55 +672,55 @@ and its `cs_KeyStore` lock for example). ## Threads -- [Main thread (`bitcoind`)](https://doxygen.bitcoincore.org/bitcoind_8cpp.html#a0ddf1224851353fc92bfbff6f499fa97) +- [Main thread (`bitcoind`)](https://doxygen.bitcoincore.org/bitcoind_8cpp.html#main) : Started from `main()` in `bitcoind.cpp`. Responsible for starting up and shutting down the application. -- [Init load (`b-initload`)](https://doxygen.bitcoincore.org/namespacenode.html#ab4305679079866f0f420f7dbf278381d) +- [Init load (`b-initload`)](https://doxygen.bitcoincore.org/init_8cpp.html#initload) : Performs various loading tasks that are part of init but shouldn't block the node from being started: external block import, reindex, reindex-chainstate, main chain activation, spawn indexes background sync threads and mempool load. -- [CCheckQueue::Loop (`b-scriptch.x`)](https://doxygen.bitcoincore.org/class_c_check_queue.html#a6e7fa51d3a25e7cb65446d4b50e6a987) +- [CCheckQueue::Loop (`b-scriptch.x`)](https://doxygen.bitcoincore.org/class_c_check_queue.html#checkqueue) : Parallel script validation threads for transactions in blocks. -- [ThreadHTTP (`b-http`)](https://doxygen.bitcoincore.org/httpserver_8cpp.html#abb9f6ea8819672bd9a62d3695070709c) +- [ThreadHTTP (`b-http`)](https://doxygen.bitcoincore.org/httpserver_8cpp.html#http) : Libevent thread to listen for RPC and REST connections. -- [HTTP worker threads (`b-http_pool_x`)](https://doxygen.bitcoincore.org/httpserver_8cpp.html#a2ad0a49dc9b5e8117c0dee98c24187d8) +- [HTTP worker threads (`b-http_pool_x`)](https://doxygen.bitcoincore.org/httpserver_8cpp.html#http_pool) : Threads to service RPC and REST requests. -- [Indexer threads (`b-txindex`, etc)](https://doxygen.bitcoincore.org/class_base_index.html#a96a7407421fbf877509248bbe64f8d87) +- [Indexer threads (`b-txindex`, etc)](https://doxygen.bitcoincore.org/class_base_index.html#index_sync) : One thread per indexer. -- [SchedulerThread (`b-scheduler`)](https://doxygen.bitcoincore.org/class_c_scheduler.html#a14d2800815da93577858ea078aed1fba) +- [SchedulerThread (`b-scheduler`)](https://doxygen.bitcoincore.org/class_c_scheduler.html#scheduler) : Does asynchronous background tasks like dumping wallet contents, dumping addrman and running asynchronous validationinterface callbacks. -- [TorControlThread (`b-torcontrol`)](https://doxygen.bitcoincore.org/torcontrol_8cpp.html#a52a3efff23634500bb42c6474f306091) +- [TorControlThread (`b-torcontrol`)](https://doxygen.bitcoincore.org/class_tor_controller.html#torcontrol) : Libevent thread for tor connections. - Net threads: - - [ThreadMessageHandler (`b-msghand`)](https://doxygen.bitcoincore.org/class_c_connman.html#aacdbb7148575a31bb33bc345e2bf22a9) + - [ThreadMessageHandler (`b-msghand`)](https://doxygen.bitcoincore.org/class_c_connman.html#msghand) : Application level message handling (sending and receiving). Almost all net_processing and validation logic runs on this thread. - - [ThreadDNSAddressSeed (`b-dnsseed`)](https://doxygen.bitcoincore.org/class_c_connman.html#aa7c6970ed98a4a7bafbc071d24897d13) + - [ThreadDNSAddressSeed (`b-dnsseed`)](https://doxygen.bitcoincore.org/class_c_connman.html#dnsseed) : Loads addresses of peers from the DNS. - - ThreadMapPort (`b-mapport`) + - [ThreadMapPort (`b-mapport`)](https://doxygen.bitcoincore.org/mapport_8cpp.html#mapport) : Universal plug-and-play startup/shutdown. - - [ThreadSocketHandler (`b-net`)](https://doxygen.bitcoincore.org/class_c_connman.html#a765597cbfe99c083d8fa3d61bb464e34) + - [ThreadSocketHandler (`b-net`)](https://doxygen.bitcoincore.org/class_c_connman.html#net) : Sends/Receives data from peers on port 8333. - - [ThreadOpenAddedConnections (`b-addcon`)](https://doxygen.bitcoincore.org/class_c_connman.html#a0b787caf95e52a346a2b31a580d60a62) + - [ThreadOpenAddedConnections (`b-addcon`)](https://doxygen.bitcoincore.org/class_c_connman.html#addcon) : Opens network connections to added nodes. - - [ThreadOpenConnections (`b-opencon`)](https://doxygen.bitcoincore.org/class_c_connman.html#a55e9feafc3bab78e5c9d408c207faa45) + - [ThreadOpenConnections (`b-opencon`)](https://doxygen.bitcoincore.org/class_c_connman.html#opencon) : Initiates new connections to peers. - - [ThreadI2PAcceptIncoming (`b-i2paccept`)](https://doxygen.bitcoincore.org/class_c_connman.html#a57787b4f9ac847d24065fbb0dd6e70f8) + - [ThreadI2PAcceptIncoming (`b-i2paccept`)](https://doxygen.bitcoincore.org/class_c_connman.html#i2paccept) : Listens for and accepts incoming I2P connections through the I2P SAM proxy. # Development guidelines diff --git a/src/bitcoind.cpp b/src/bitcoind.cpp index ac731587683..472ff381a82 100644 --- a/src/bitcoind.cpp +++ b/src/bitcoind.cpp @@ -258,6 +258,7 @@ static bool AppInit(NodeContext& node) return fRet; } +/// \anchor main MAIN_FUNCTION { NodeContext node; diff --git a/src/checkqueue.h b/src/checkqueue.h index 5258d7113e6..1e265525df8 100644 --- a/src/checkqueue.h +++ b/src/checkqueue.h @@ -68,6 +68,7 @@ private: std::vector m_worker_threads; bool m_request_stop GUARDED_BY(m_mutex){false}; + /// \anchor checkqueue /** Internal function that does bulk of the verification work. If fMaster, return the final result. */ std::optional Loop(bool fMaster) EXCLUSIVE_LOCKS_REQUIRED(!m_mutex) { diff --git a/src/httpserver.cpp b/src/httpserver.cpp index b84f0da08fd..2e42eb0bd1d 100644 --- a/src/httpserver.cpp +++ b/src/httpserver.cpp @@ -74,6 +74,7 @@ static GlobalMutex g_httppathhandlers_mutex; static std::vector pathHandlers GUARDED_BY(g_httppathhandlers_mutex); //! Bound listening sockets static std::vector boundSockets; +/// \anchor http_pool //! Http thread pool - future: encapsulate in HttpContext static ThreadPool g_threadpool_http("http"); static int g_max_queue_depth{100}; @@ -295,6 +296,7 @@ static void http_reject_request_cb(struct evhttp_request* req, void*) evhttp_send_error(req, HTTP_SERVUNAVAIL, nullptr); } +/// \anchor http /** Event dispatcher thread */ static void ThreadHTTP(struct event_base* base) { diff --git a/src/index/base.h b/src/index/base.h index 63f60be0349..761b6f56bc2 100644 --- a/src/index/base.h +++ b/src/index/base.h @@ -167,6 +167,7 @@ public: /// Starts the initial sync process on a background thread. [[nodiscard]] bool StartBackgroundSync(); + /// \anchor index_sync /// Sync the index with the block index starting from the current best block. /// Intended to be run in its own thread, m_thread_sync, and can be /// interrupted with m_interrupt. Once the index gets in sync, the m_synced diff --git a/src/init.cpp b/src/init.cpp index c53e5ed634c..7cdcb822bf5 100644 --- a/src/init.cpp +++ b/src/init.cpp @@ -2028,6 +2028,7 @@ bool AppInitMain(NodeContext& node, interfaces::BlockAndHeaderTipInfo* tip_info) vImportFiles.push_back(fs::PathFromString(strFile)); } + /// \anchor initload node.background_init_thread = std::thread(&util::TraceThread, "initload", [=, &chainman, &args, &node] { ScheduleBatchPriority(); // Import blocks and ActivateBestChain() diff --git a/src/mapport.cpp b/src/mapport.cpp index 43918ebf101..1b079fafea2 100644 --- a/src/mapport.cpp +++ b/src/mapport.cpp @@ -119,6 +119,7 @@ static void ProcessPCP() // we rather just choose a fairly short expiry time. } +/// \anchor mapport static void ThreadMapPort() { do { diff --git a/src/net.h b/src/net.h index d0171c5345f..a35d30a2d29 100644 --- a/src/net.h +++ b/src/net.h @@ -1425,6 +1425,7 @@ private: bool Bind(const CService& addr, unsigned int flags, NetPermissionFlags permissions); bool InitBinds(const Options& options); + /// \anchor addcon void ThreadOpenAddedConnections() EXCLUSIVE_LOCKS_REQUIRED(!m_added_nodes_mutex, !m_nodes_mutex, !m_reconnections_mutex, @@ -1436,6 +1437,7 @@ private: !m_nodes_mutex, !m_unused_i2p_sessions_mutex); + /// \anchor opencon void ThreadOpenConnections(std::vector connect, std::span seed_nodes) EXCLUSIVE_LOCKS_REQUIRED(!m_added_nodes_mutex, !m_addr_fetches_mutex, @@ -1443,7 +1445,9 @@ private: !m_reconnections_mutex, !m_unused_i2p_sessions_mutex); + /// \anchor msghand void ThreadMessageHandler() EXCLUSIVE_LOCKS_REQUIRED(!m_nodes_mutex, !mutexMsgProc); + /// \anchor i2paccept void ThreadI2PAcceptIncoming() EXCLUSIVE_LOCKS_REQUIRED(!m_nodes_mutex); void ThreadPrivateBroadcast() EXCLUSIVE_LOCKS_REQUIRED(!m_nodes_mutex, !m_unused_i2p_sessions_mutex); void AcceptConnection(const ListenSocket& hListenSocket) EXCLUSIVE_LOCKS_REQUIRED(!m_nodes_mutex); @@ -1495,7 +1499,9 @@ private: void SocketHandlerListening(const Sock::EventsPerSock& events_per_sock) EXCLUSIVE_LOCKS_REQUIRED(!m_nodes_mutex); + /// \anchor net void ThreadSocketHandler() EXCLUSIVE_LOCKS_REQUIRED(!m_total_bytes_sent_mutex, !mutexMsgProc, !m_nodes_mutex, !m_reconnections_mutex); + /// \anchor dnsseed void ThreadDNSAddressSeed() EXCLUSIVE_LOCKS_REQUIRED(!m_addr_fetches_mutex, !m_nodes_mutex); uint64_t CalculateKeyedNetGroup(const CNetAddr& ad) const; diff --git a/src/scheduler.h b/src/scheduler.h index 5d4affb0ab8..0a05f6cb71f 100644 --- a/src/scheduler.h +++ b/src/scheduler.h @@ -70,6 +70,7 @@ public: void MockForward(std::chrono::seconds delta_seconds) EXCLUSIVE_LOCKS_REQUIRED(!newTaskMutex); /** + * \anchor scheduler * Services the queue 'forever'. Should be run in a thread. */ void serviceQueue() EXCLUSIVE_LOCKS_REQUIRED(!newTaskMutex); diff --git a/src/torcontrol.h b/src/torcontrol.h index 75b81b87b2d..410cb0b368c 100644 --- a/src/torcontrol.h +++ b/src/torcontrol.h @@ -151,7 +151,8 @@ private: std::vector m_cookie; /** ClientNonce for SAFECOOKIE auth */ std::vector m_client_nonce; - /** Main control thread */ + + /// \anchor torcontrol void ThreadControl(); public: