From ca7a7ad2f34fe3a34d1d64973961c2b3ed1b5dc3 Mon Sep 17 00:00:00 2001 From: "Jeff Washington (jwash)" Date: Fri, 4 Aug 2023 10:52:01 -0700 Subject: [PATCH] add some doc comments identified in audit (#32709) * add some doc comments identified in audit * Update runtime/src/bank.rs Co-authored-by: Brooks * Update runtime/src/accounts_db.rs Co-authored-by: Brooks * Update runtime/src/accounts_db.rs Co-authored-by: Brooks --------- Co-authored-by: Brooks --- runtime/src/accounts_db.rs | 5 +++++ runtime/src/bank.rs | 40 +++++++++++++++++++++++++++++++------- 2 files changed, 38 insertions(+), 7 deletions(-) diff --git a/runtime/src/accounts_db.rs b/runtime/src/accounts_db.rs index 85db478aab..fde155afc8 100644 --- a/runtime/src/accounts_db.rs +++ b/runtime/src/accounts_db.rs @@ -5008,6 +5008,8 @@ impl AccountsDb { account_accessor.account_matches_owners(owners) } + /// load the account with `pubkey` into the read only accounts cache. + /// The goal is to make subsequent loads (which caller expects to occur) to find the account quickly. pub fn load_account_into_read_cache(&self, ancestors: &Ancestors, pubkey: &Pubkey) { self.do_load_with_populate_read_cache( ancestors, @@ -6987,6 +6989,8 @@ impl AccountsDb { Ok((accounts_hash, total_lamports)) } + /// This is only valid to call from tests. + /// run the accounts hash calculation and store the results pub fn update_accounts_hash_for_tests( &self, slot: Slot, @@ -7311,6 +7315,7 @@ impl AccountsDb { Ok((accounts_hash, total_lamports)) } + /// run the accounts hash calculation and store the results #[allow(clippy::too_many_arguments)] pub fn update_accounts_hash( &self, diff --git a/runtime/src/bank.rs b/runtime/src/bank.rs index bd7ef823e5..e348a4548a 100644 --- a/runtime/src/bank.rs +++ b/runtime/src/bank.rs @@ -404,9 +404,13 @@ impl TransactionLogCollector { } } -// Bank's common fields shared by all supported snapshot versions for deserialization. -// Sync fields with BankFieldsToSerialize! This is paired with it. -// All members are made public to remain Bank's members private and to make versioned deserializer workable on this +/// Bank's common fields shared by all supported snapshot versions for deserialization. +/// Sync fields with BankFieldsToSerialize! This is paired with it. +/// All members are made public to remain Bank's members private and to make versioned deserializer workable on this +/// Note that some fields are missing from the serializer struct. This is because of fields added later. +/// Since it is difficult to insert fields to serialize/deserialize against existing code already deployed, +/// new fields can be optionally serialized and optionally deserialized. At some point, the serialization and +/// deserialization will use a new mechanism or otherwise be in sync more clearly. #[derive(Clone, Debug, Default, PartialEq)] pub struct BankFieldsToDeserialize { pub(crate) blockhash_queue: BlockhashQueue, @@ -445,10 +449,14 @@ pub struct BankFieldsToDeserialize { pub(crate) epoch_reward_status: EpochRewardStatus, } -// Bank's common fields shared by all supported snapshot versions for serialization. -// This is separated from BankFieldsToDeserialize to avoid cloning by using refs. -// So, sync fields with BankFieldsToDeserialize! -// all members are made public to keep Bank private and to make versioned serializer workable on this +/// Bank's common fields shared by all supported snapshot versions for serialization. +/// This is separated from BankFieldsToDeserialize to avoid cloning by using refs. +/// So, sync fields with BankFieldsToDeserialize! +/// all members are made public to keep Bank private and to make versioned serializer workable on this. +/// Note that some fields are missing from the serializer struct. This is because of fields added later. +/// Since it is difficult to insert fields to serialize/deserialize against existing code already deployed, +/// new fields can be optionally serialized and optionally deserialized. At some point, the serialization and +/// deserialization will use a new mechanism or otherwise be in sync more clearly. #[derive(Debug)] pub(crate) struct BankFieldsToSerialize<'a> { pub(crate) blockhash_queue: &'a RwLock, @@ -989,6 +997,8 @@ impl Bank { ) } + /// Intended for use by tests only. + /// create new bank with the given configs. pub fn new_with_runtime_config_for_tests( genesis_config: &GenesisConfig, runtime_config: Arc, @@ -1115,6 +1125,8 @@ impl Bank { ) } + /// Intended for use by benches only. + /// create new bank with the given config and paths. pub fn new_with_paths_for_benches(genesis_config: &GenesisConfig, paths: Vec) -> Self { Self::new_with_paths( genesis_config, @@ -3756,6 +3768,9 @@ impl Bank { /// squash the parent's state up into this Bank, /// this Bank becomes a root + /// Note that this function is not thread-safe. If it is called concurrently on the same bank + /// by multiple threads, the end result could be inconsistent. + /// Calling code does not currently call this concurrently. pub fn squash(&self) -> SquashTiming { self.freeze(); @@ -4028,6 +4043,7 @@ impl Bank { Some(self.get_fee_for_message_with_lamports_per_signature(message, lamports_per_signature)) } + /// Returns true when startup accounts hash verification has completed or never had to run in background. pub fn get_startup_verification_complete(&self) -> &Arc { &self .rc @@ -4037,6 +4053,9 @@ impl Bank { .verified } + /// return true if bg hash verification is complete + /// return false if bg hash verification has not completed yet + /// if hash verification failed, a panic will occur pub fn is_startup_verification_complete(&self) -> bool { self.rc .accounts @@ -6478,6 +6497,8 @@ impl Bank { parents } + /// fn store the single `account` with `pubkey`. + /// Uses `store_accounts`, which works on a vector of accounts. pub fn store_account( &self, pubkey: &Pubkey, @@ -7040,6 +7061,8 @@ impl Bank { epoch_accounts_hash } + /// Used by ledger tool to run a final hash calculation once all ledger replay has completed. + /// This should not be called by validator code. pub fn run_final_hash_calc(&self, on_halt_store_hash_raw_data_for_debug: bool) { self.force_flush_accounts_cache(); // note that this slot may not be a root @@ -7174,6 +7197,8 @@ impl Bank { .check_complete() } + /// This is only valid to call from tests. + /// block until initial accounts hash verification has completed pub fn wait_for_initial_accounts_hash_verification_completed_for_tests(&self) { self.rc .accounts @@ -7545,6 +7570,7 @@ impl Bank { *self.inflation.read().unwrap() } + /// Return the rent collector for this Bank pub fn rent_collector(&self) -> &RentCollector { &self.rent_collector }