From d67f7beb2f3d341d8e9c022be8d00872bbd70012 Mon Sep 17 00:00:00 2001 From: Thiago Silva <82097354+thsfs@users.noreply.github.com> Date: Wed, 9 Feb 2022 09:35:32 -0300 Subject: [PATCH] Add class description to mostly of bootstrap classes (#3725) --- nano/node/bootstrap/bootstrap.hpp | 12 ++++++++++++ nano/node/bootstrap/bootstrap_attempt.hpp | 4 ++++ nano/node/bootstrap/bootstrap_bulk_pull.hpp | 10 ++++++++++ nano/node/bootstrap/bootstrap_bulk_push.hpp | 8 ++++++++ nano/node/bootstrap/bootstrap_connections.hpp | 8 ++++++++ nano/node/bootstrap/bootstrap_frontier.hpp | 8 ++++++++ nano/node/bootstrap/bootstrap_lazy.hpp | 9 +++++++++ nano/node/bootstrap/bootstrap_legacy.hpp | 3 +++ nano/node/bootstrap/bootstrap_server.hpp | 8 ++++++++ 9 files changed, 70 insertions(+) diff --git a/nano/node/bootstrap/bootstrap.hpp b/nano/node/bootstrap/bootstrap.hpp index cedfc32a..e5ff75db 100644 --- a/nano/node/bootstrap/bootstrap.hpp +++ b/nano/node/bootstrap/bootstrap.hpp @@ -63,6 +63,10 @@ public: // clang-format on constexpr static std::size_t cache_size_max = 10000; }; + +/** + * Container for bootstrap sessions that are active. Owned by bootstrap_initiator. + */ class bootstrap_attempts final { public: @@ -76,6 +80,10 @@ public: std::map> attempts; }; +/** + * Client side portion to initiate bootstrap sessions. Prevents multiple legacy-type bootstrap sessions from being started at the same time. Does permit + * lazy/wallet bootstrap sessions to overlap with legacy sessions. + */ class bootstrap_initiator final { public: @@ -117,6 +125,10 @@ private: }; std::unique_ptr collect_container_info (bootstrap_initiator & bootstrap_initiator, std::string const & name); + +/** + * Defines the numeric values for the bootstrap feature. + */ class bootstrap_limits final { public: diff --git a/nano/node/bootstrap/bootstrap_attempt.hpp b/nano/node/bootstrap/bootstrap_attempt.hpp index 459df000..55c56781 100644 --- a/nano/node/bootstrap/bootstrap_attempt.hpp +++ b/nano/node/bootstrap/bootstrap_attempt.hpp @@ -11,6 +11,10 @@ class node; class frontier_req_client; class bulk_push_client; + +/** + * Polymorphic base class for bootstrap sessions. + */ class bootstrap_attempt : public std::enable_shared_from_this { public: diff --git a/nano/node/bootstrap/bootstrap_bulk_pull.hpp b/nano/node/bootstrap/bootstrap_bulk_pull.hpp index 1b488f4a..673db280 100644 --- a/nano/node/bootstrap/bootstrap_bulk_pull.hpp +++ b/nano/node/bootstrap/bootstrap_bulk_pull.hpp @@ -25,6 +25,10 @@ public: uint64_t bootstrap_id{ 0 }; }; class bootstrap_client; + +/** + * Client side of a bulk_pull request. Created when the bootstrap_attempt wants to make a bulk_pull request to the remote side. + */ class bulk_pull_client final : public std::enable_shared_from_this { public: @@ -59,6 +63,12 @@ public: }; class bootstrap_server; class bulk_pull; + +/** + * Server side of a bulk_pull request. Created when bootstrap_server receives a bulk_pull message and is exited after the contents + * have been sent. If the 'start' in the bulk_pull message is an account, send blocks for that account down to 'end'. If the 'start' + * is a block hash, send blocks for that chain down to 'end'. If end doesn't exist, send all accounts in the chain. + */ class bulk_pull_server final : public std::enable_shared_from_this { public: diff --git a/nano/node/bootstrap/bootstrap_bulk_push.hpp b/nano/node/bootstrap/bootstrap_bulk_push.hpp index f26ac684..c9f19d5c 100644 --- a/nano/node/bootstrap/bootstrap_bulk_push.hpp +++ b/nano/node/bootstrap/bootstrap_bulk_push.hpp @@ -8,6 +8,10 @@ namespace nano { class bootstrap_attempt; class bootstrap_client; + +/** + * Client side of a bulk_push request. Sends a sequence of blocks the other side did not report in their frontier_req response. + */ class bulk_push_client final : public std::enable_shared_from_this { public: @@ -23,6 +27,10 @@ public: std::pair current_target; }; class bootstrap_server; + +/** + * Server side of a bulk_push request. Receives blocks and puts them in the block processor to be processed. + */ class bulk_push_server final : public std::enable_shared_from_this { public: diff --git a/nano/node/bootstrap/bootstrap_connections.hpp b/nano/node/bootstrap/bootstrap_connections.hpp index fcebe55d..7a007f96 100644 --- a/nano/node/bootstrap/bootstrap_connections.hpp +++ b/nano/node/bootstrap/bootstrap_connections.hpp @@ -18,6 +18,10 @@ class bootstrap_attempt; class bootstrap_connections; class frontier_req_client; class pull_info; + +/** + * Owns the client side of the bootstrap connection. + */ class bootstrap_client final : public std::enable_shared_from_this { public: @@ -42,6 +46,10 @@ private: std::chrono::steady_clock::time_point start_time_m; }; +/** + * Container for bootstrap_client objects. Owned by bootstrap_initiator which pools open connections and makes them available + * for use by different bootstrap sessions. + */ class bootstrap_connections final : public std::enable_shared_from_this { public: diff --git a/nano/node/bootstrap/bootstrap_frontier.hpp b/nano/node/bootstrap/bootstrap_frontier.hpp index 2357abb7..bab0c238 100644 --- a/nano/node/bootstrap/bootstrap_frontier.hpp +++ b/nano/node/bootstrap/bootstrap_frontier.hpp @@ -9,6 +9,10 @@ namespace nano { class bootstrap_attempt; class bootstrap_client; + +/** + * Client side of a frontier request. Created to send and listen for frontier sequences from the server. + */ class frontier_req_client final : public std::enable_shared_from_this { public: @@ -36,6 +40,10 @@ public: }; class bootstrap_server; class frontier_req; + +/** + * Server side of a frontier request. Created when a bootstrap_server receives a frontier_req message and exited when end-of-list is reached. + */ class frontier_req_server final : public std::enable_shared_from_this { public: diff --git a/nano/node/bootstrap/bootstrap_lazy.hpp b/nano/node/bootstrap/bootstrap_lazy.hpp index 03ed15d9..bc34ce3f 100644 --- a/nano/node/bootstrap/bootstrap_lazy.hpp +++ b/nano/node/bootstrap/bootstrap_lazy.hpp @@ -23,6 +23,11 @@ public: nano::uint128_t balance{ 0 }; unsigned retry_limit{ 0 }; }; + +/** + * Lazy bootstrap session. Started with a block hash, this will "trace down" the blocks obtained to find a connection to the ledger. + * This attempts to quickly bootstrap a section of the ledger given a hash that's known to be confirmed. + */ class bootstrap_attempt_lazy final : public bootstrap_attempt { public: @@ -60,6 +65,10 @@ public: /** The maximum number of records to be read in while iterating over long lazy containers */ static uint64_t constexpr batch_read_size = 256; }; + +/** + * Wallet bootstrap session. This session will trace down accounts within local wallets to try and bootstrap those blocks first. + */ class bootstrap_attempt_wallet final : public bootstrap_attempt { public: diff --git a/nano/node/bootstrap/bootstrap_legacy.hpp b/nano/node/bootstrap/bootstrap_legacy.hpp index 7387556e..ae51c73d 100644 --- a/nano/node/bootstrap/bootstrap_legacy.hpp +++ b/nano/node/bootstrap/bootstrap_legacy.hpp @@ -13,6 +13,9 @@ namespace nano { class node; +/** + * Legacy bootstrap session. This is made up of 3 phases: frontier requests, bootstrap pulls, bootstrap pushes. + */ class bootstrap_attempt_legacy : public bootstrap_attempt { public: diff --git a/nano/node/bootstrap/bootstrap_server.hpp b/nano/node/bootstrap/bootstrap_server.hpp index 7634bf6c..0d055fe3 100644 --- a/nano/node/bootstrap/bootstrap_server.hpp +++ b/nano/node/bootstrap/bootstrap_server.hpp @@ -9,6 +9,10 @@ namespace nano { class bootstrap_server; + +/** + * Server side portion of bootstrap sessions. Listens for new socket connections and spawns bootstrap_server objects when connected. + */ class bootstrap_listener final { public: @@ -32,6 +36,10 @@ public: std::unique_ptr collect_container_info (bootstrap_listener & bootstrap_listener, std::string const & name); class message; + +/** + * Owns the server side of a bootstrap connection. Responds to bootstrap messages sent over the socket. + */ class bootstrap_server final : public std::enable_shared_from_this { public: