From 37afdd1a6544db4f74d7a15c7601f7532f6b6414 Mon Sep 17 00:00:00 2001
From: Yueh-Hsuan Chiang <93241502+yhchiang-sol@users.noreply.github.com>
Date: Sun, 6 Feb 2022 21:56:23 -0800
Subject: [PATCH] (Ledger Store) Improve comments for blockstore_purge (#22808)

---
 ledger/src/blockstore.rs                  |  7 +++++
 ledger/src/blockstore/blockstore_purge.rs | 35 ++++++++++++++++-------
 2 files changed, 32 insertions(+), 10 deletions(-)

diff --git a/ledger/src/blockstore.rs b/ledger/src/blockstore.rs
index c8dc170800..b36e802849 100644
--- a/ledger/src/blockstore.rs
+++ b/ledger/src/blockstore.rs
@@ -104,9 +104,16 @@ pub struct SignatureInfosForAddress {
 }
 
 #[derive(Clone, Copy)]
+/// Controls how `blockstore::purge_slots` purges the data.
 pub enum PurgeType {
+    /// A slower but more accurate way to purge slots by also ensuring higher
+    /// level of consistency between data during the clean up process.
     Exact,
+    /// A faster approximation of `Exact` where the purge process only takes
+    /// care of the primary index and does not update the associated entries.
     PrimaryIndex,
+    /// The fastest purge mode that relies on the slot-id based TTL
+    /// compaction filter to do the cleanup.
     CompactionFilter,
 }
 
diff --git a/ledger/src/blockstore/blockstore_purge.rs b/ledger/src/blockstore/blockstore_purge.rs
index 83bf6cbbab..389bc54c8a 100644
--- a/ledger/src/blockstore/blockstore_purge.rs
+++ b/ledger/src/blockstore/blockstore_purge.rs
@@ -7,10 +7,21 @@ pub struct PurgeStats {
 }
 
 impl Blockstore {
-    /// Silently deletes all blockstore column families in the range \[from_slot,to_slot\]
-    /// Dangerous; Use with care:
-    /// Does not check for integrity and does not update slot metas that refer to deleted slots
-    /// Modifies multiple column families simultaneously
+    /// Performs cleanup based on the specified deletion range.  After this
+    /// function call, entries within \[`from_slot`, `to_slot`\] will become
+    /// unavailable to the reader immediately, while its disk space occupied
+    /// by the deletion entries are reclaimed later via RocksDB's background
+    /// compaction.
+    ///
+    /// Note that this function modifies multiple column families at the same
+    /// time and might break the consistency between different column families
+    /// as it does not update the associated slot-meta entries that refer to
+    /// the deleted entries.
+    ///
+    /// For slot-id based column families, the purge is done by range deletion,
+    /// while the non-slot-id based column families, `cf::TransactionStatus`,
+    /// `AddressSignature`, and `cf::TransactionStatusIndex`, are cleaned-up
+    /// based on the `purge_type` setting.
     pub fn purge_slots(&self, from_slot: Slot, to_slot: Slot, purge_type: PurgeType) {
         let mut purge_stats = PurgeStats::default();
         let purge_result =
@@ -114,7 +125,8 @@ impl Blockstore {
         self.run_purge_with_stats(from_slot, to_slot, purge_type, &mut PurgeStats::default())
     }
 
-    // Returns whether or not all columns successfully purged the slot range
+    /// A helper function to `purge_slots` that executes the ledger clean up
+    /// from `from_slot` to `to_slot`.
     pub(crate) fn run_purge_with_stats(
         &self,
         from_slot: Slot,
@@ -314,9 +326,11 @@ impl Blockstore {
         Ok(result)
     }
 
-    /// Purges special columns (using a non-Slot primary-index) exactly, by deserializing each slot
-    /// being purged and iterating through all transactions to determine the keys of individual
-    /// records. **This method is very slow.**
+    /// Purges special columns (using a non-Slot primary-index) exactly, by
+    /// deserializing each slot being purged and iterating through all
+    /// transactions to determine the keys of individual records.
+    ///
+    /// **This method is very slow.**
     fn purge_special_columns_exact(
         &self,
         batch: &mut WriteBatch,
@@ -360,8 +374,9 @@ impl Blockstore {
         Ok(())
     }
 
-    /// Purges special columns (using a non-Slot primary-index) by range. Purge occurs if frozen
-    /// primary index has a max-slot less than the highest slot being purged.
+    /// Purges special columns (using a non-Slot primary-index) by range. Purge
+    /// occurs if frozen primary index has a max-slot less than the highest slot
+    /// being purged.
     fn purge_special_columns_with_primary_index(
         &self,
         write_batch: &mut WriteBatch,