Add comment with rationale for using atomic value updates instead of tree thawing/freezing

1 files changed, 10 insertions, 0 deletions

diff --git a/storage/src/vespa/storage/bucketdb/generic_btree_bucket_database.h b/storage/src/vespa/storage/bucketdb/generic_btree_bucket_database.h
index ba99dad39c0..256a54b19b3 100644
--- a/storage/src/vespa/storage/bucketdb/generic_btree_bucket_database.h
+++ b/storage/src/vespa/storage/bucketdb/generic_btree_bucket_database.h
@@ -53,6 +53,16 @@ public:
         }
     };
 
+    // Rationale for using an atomic u64 value type:
+    // It is expected that the set of bucket keys is much less frequently updated than their
+    // corresponding values. Since values must be stable for concurrent readers, all written values
+    // are _immutable_ once created. Consequently, every single mutation of a bucket will replace its
+    // value with a new (immutable) entry. For distributors, this replaces an entire array of values.
+    // Instead of constantly thawing and freezing subtrees for each bucket update, we atomically
+    // replace the value to point to a new u32 EntryRef mangled together with an u32 timestamp.
+    // This means updates that don't change the set of buckets leave the B-tree node structure
+    // itself entirely untouched.
+    // This requires great care to be taken when writing and reading to ensure memory visibility.
     using BTree = vespalib::btree::BTree<uint64_t,
                                          vespalib::datastore::AtomicValueWrapper<uint64_t>,
                                          vespalib::btree::MinMaxAggregated,