add rwlock rationale

Author: roberto-bayardo

storage/src/qmdb/current/batch.rs

@@ -679,6 +679,15 @@ where
 /// [`Db::prune`](super::db::Db::prune), and [`Db::rewind`](super::db::Db::rewind) can mutate
 /// the bitmap in place while live batches concurrently read through it.
 ///
+/// # Why in-place mutation under a lock
+///
+/// Snapshot-based alternatives (per-apply clone, page-level copy-on-write, etc.) all require
+/// cloning at least the bitmap's top-level pointer structure on every apply. For large DBs that
+/// cost grows linearly with the total bit count and every live batch retains its snapshot's
+/// memory until dropped, so memory use would grow with both bitmap size and batch lifetime.
+/// Mutating in place keeps memory bounded by the actual bitmap size regardless of how many
+/// batches are alive or how long they live. The per-call read lock is the cost we pay for that.
+///
 /// # Reading through invalid batches
 ///
 /// The bitmap behind this lock represents *committed* state. If a caller holds a

storage/src/qmdb/current/db.rs

@@ -186,8 +186,8 @@ where
     ) -> Result<OpsRootWitness<H::Digest>, Error<F>> {
         let storage = self.grafted_storage();
         let grafted_root =
-            compute_grafted_root::<F, H, _, _, N>(hasher, &self.status, &storage).await?;
-        let partial_chunk = partial_chunk::<_, N>(&self.status)
+            compute_grafted_root::<F, H, _, _, N>(hasher, self.status.as_ref(), &storage).await?;
+        let partial_chunk = partial_chunk::<_, N>(self.status.as_ref())
             .map(|(chunk, next_bit)| (next_bit, hasher.digest(&chunk)));
         Ok(OpsRootWitness {
             grafted_root,
@@ -1179,7 +1179,7 @@ mod tests {
             let mut next_idx = 0;
             populate_fixed_db::<mmr::Family, _>(&mut db, next_idx, 256).await;
             next_idx += 256;
-            while partial_chunk::<_, 32>(&db.status).is_some() {
+            while partial_chunk::<_, 32>(db.status.as_ref()).is_some() {
                 populate_fixed_db::<mmr::Family, _>(&mut db, next_idx, 1).await;
                 next_idx += 1;
             }