@nxtedition/rocksdb 15.4.0 → 15.5.0

package/deps/rocksdb/rocksdb/utilities/transactions/optimistic_transaction_db_impl.cc

@@ -73,7 +73,7 @@ Status OptimisticTransactionDB::Open(
     std::vector<ColumnFamilyHandle*>* handles,
     OptimisticTransactionDB** dbptr) {
   Status s;
-  DB* db;
+  std::unique_ptr<DB> db;
 
   std::vector<ColumnFamilyDescriptor> column_families_copy = column_families;
 
@@ -91,7 +91,7 @@ Status OptimisticTransactionDB::Open(
   s = DB::Open(db_options, dbname, column_families_copy, handles, &db);
 
   if (s.ok()) {
-    *dbptr = new OptimisticTransactionDBImpl(db, occ_options);
+    *dbptr = new OptimisticTransactionDBImpl(std::move(db), occ_options);
   }
 
   return s;

package/deps/rocksdb/rocksdb/utilities/transactions/optimistic_transaction_db_impl.h

@@ -44,10 +44,9 @@ class OccLockBucketsImpl : public OccLockBucketsImplBase {
 class OptimisticTransactionDBImpl : public OptimisticTransactionDB {
  public:
   explicit OptimisticTransactionDBImpl(
-      DB* db, const OptimisticTransactionDBOptions& occ_options,
-      bool take_ownership = true)
-      : OptimisticTransactionDB(db),
-        db_owner_(take_ownership),
+      std::unique_ptr<DB>&& db,
+      const OptimisticTransactionDBOptions& occ_options)
+      : OptimisticTransactionDB(std::move(db)),
         validate_policy_(occ_options.validate_policy) {
     if (validate_policy_ == OccValidationPolicy::kValidateParallel) {
       auto bucketed_locks = occ_options.shared_lock_buckets;
@@ -60,13 +59,7 @@ class OptimisticTransactionDBImpl : public OptimisticTransactionDB {
     }
   }
 
-  ~OptimisticTransactionDBImpl() {
-    // Prevent this stackable from destroying
-    // base db
-    if (!db_owner_) {
-      db_ = nullptr;
-    }
-  }
+  ~OptimisticTransactionDBImpl() override = default;
 
   Transaction* BeginTransaction(const WriteOptions& write_options,
                                 const OptimisticTransactionOptions& txn_options,
@@ -97,8 +90,6 @@ class OptimisticTransactionDBImpl : public OptimisticTransactionDB {
  private:
   std::shared_ptr<OccLockBucketsImplBase> bucketed_locks_;
 
-  bool db_owner_;
-
   const OccValidationPolicy validate_policy_;
 
   void ReinitializeTransaction(Transaction* txn,

package/deps/rocksdb/rocksdb/utilities/transactions/transaction_test.cc

@@ -9005,7 +9005,7 @@ class CommitBypassMemtableTest
     txn_db_opts.use_per_key_point_lock_mgr = std::get<1>(GetParam());
     ASSERT_OK(TransactionDB::Open(options, txn_db_opts, dbname_, &txn_db));
     ASSERT_NE(txn_db, nullptr);
-    db_ = txn_db;
+    db_.reset(txn_db);
   }
 };
 
@@ -9453,9 +9453,9 @@ TEST_P(CommitBypassMemtableTest, Recovery) {
   VerifyDBFromMap(expected);
 
   ASSERT_OK(txn_db->Close());
-  delete txn_db;
+  db_.reset();  // destroys txn_db (owned by db_)
   ASSERT_OK(TransactionDB::Open(options, txn_db_opts, dbname_, &txn_db));
-  db_ = txn_db;
+  db_.reset(txn_db);
 
   VerifyDBFromMap(expected);
 }

package/deps/rocksdb/rocksdb/utilities/transactions/transaction_test.h

@@ -82,6 +82,12 @@ class TransactionTestBase : public ::testing::Test {
     txn_db_options.write_policy = write_policy;
     txn_db_options.rollback_merge_operands = true;
     txn_db_options.use_per_key_point_lock_mgr = use_per_key_point_lock_mgr;
+    // Reduce commit cache size from the default 2^23 (64MB) to 2^13 (64KB).
+    // The default is sized for production workloads but makes TSAN builds
+    // very slow because value-initializing 8M atomics triggers __tsan_memset,
+    // which updates shadow memory for every 8-byte cell.  Tests that need
+    // specific cache sizes (e.g., for wrapping/eviction) override this.
+    txn_db_options.wp_commit_cache_bits = 13;
     // This will stress write unprepared, by forcing write batch flush on every
     // write.
     txn_db_options.default_write_batch_flush_threshold = 1;

package/deps/rocksdb/rocksdb/utilities/transactions/write_prepared_transaction_seqno_test.cc

@@ -0,0 +1,431 @@
+//  Copyright (c) 2011-present, Facebook, Inc.  All rights reserved.
+//  This source code is licensed under both the GPLv2 (found in the
+//  COPYING file in the root directory) and Apache 2.0 License
+//  (found in the LICENSE.Apache file in the root directory).
+
+// Test to verify that sequence numbers remain consistent during error recovery
+// with WritePrepared TransactionDB and two_write_queues=true.
+//
+// The fix: SyncLastSequenceWithAllocated() is called during ResumeImpl to
+// ensure that allocated-but-not-published sequence numbers are accounted for
+// before creating new memtables/WALs, preventing "sequence number going
+// backwards" corruption on subsequent recovery.
+
+#include <atomic>
+#include <memory>
+#include <string>
+
+#include "db/db_impl/db_impl.h"
+#include "db/db_test_util.h"
+#include "db/version_set.h"
+#include "port/stack_trace.h"
+#include "rocksdb/utilities/transaction_db.h"
+#include "test_util/sync_point.h"
+#include "test_util/testharness.h"
+#include "test_util/testutil.h"
+#include "utilities/fault_injection_fs.h"
+
+namespace ROCKSDB_NAMESPACE {
+
+class WritePreparedTransactionSeqnoTest : public ::testing::Test {
+ public:
+  WritePreparedTransactionSeqnoTest()
+      : db_(nullptr),
+        special_env_(Env::Default()),
+        fault_fs_(new FaultInjectionTestFS(FileSystem::Default())),
+        env_(new CompositeEnvWrapper(&special_env_, fault_fs_)) {
+    options_.create_if_missing = true;
+    options_.max_write_buffer_number = 2;
+    options_.write_buffer_size = 4 * 1024;
+    options_.level0_file_num_compaction_trigger = 2;
+    options_.env = env_.get();
+    // Use two_write_queues which is typical for WritePrepared
+    options_.two_write_queues = true;
+    // Enable auto recovery from retryable errors
+    options_.max_bgerror_resume_count = 2;
+    options_.bgerror_resume_retry_interval = 100000;  // 100ms
+
+    dbname_ = test::PerThreadDBPath("write_prepared_seqno_test");
+    EXPECT_OK(DestroyDB(dbname_, options_));
+
+    txn_db_options_.transaction_lock_timeout = 0;
+    txn_db_options_.default_lock_timeout = 0;
+    txn_db_options_.write_policy = TxnDBWritePolicy::WRITE_PREPARED;
+  }
+
+  ~WritePreparedTransactionSeqnoTest() {
+    SyncPoint::GetInstance()->DisableProcessing();
+    SyncPoint::GetInstance()->ClearAllCallBacks();
+    if (db_) {
+      for (auto h : handles_) {
+        if (h) {
+          EXPECT_OK(db_->DestroyColumnFamilyHandle(h));
+        }
+      }
+      handles_.clear();
+      delete db_;
+      db_ = nullptr;
+    }
+  }
+
+  Status Open() {
+    return TransactionDB::Open(options_, txn_db_options_, dbname_, &db_);
+  }
+
+  void Close() {
+    for (auto h : handles_) {
+      if (h) {
+        EXPECT_OK(db_->DestroyColumnFamilyHandle(h));
+      }
+    }
+    handles_.clear();
+    delete db_;
+    db_ = nullptr;
+  }
+
+  DBImpl* dbimpl() { return static_cast_with_check<DBImpl>(db_->GetRootDB()); }
+
+ protected:
+  TransactionDB* db_;
+  SpecialEnv special_env_;
+  std::shared_ptr<FaultInjectionTestFS> fault_fs_;
+  std::unique_ptr<Env> env_;
+  std::string dbname_;
+  Options options_;
+  TransactionDBOptions txn_db_options_;
+  std::vector<ColumnFamilyHandle*> handles_;
+};
+
+// Regression test: verify that after error recovery with two_write_queues,
+// the DB can be closed and reopened without sequence number corruption.
+TEST_F(WritePreparedTransactionSeqnoTest,
+       SeqnoGoesBackwardsDuringErrorRecovery) {
+  ASSERT_OK(Open());
+
+  // Write some initial data and flush to establish baseline
+  WriteOptions write_opts;
+  TransactionOptions txn_opts;
+  for (int i = 0; i < 10; i++) {
+    Transaction* txn = db_->BeginTransaction(write_opts, txn_opts);
+    ASSERT_NE(txn, nullptr);
+    ASSERT_OK(txn->SetName("txn" + std::to_string(i)));
+    ASSERT_OK(txn->Put("key" + std::to_string(i), "value" + std::to_string(i)));
+    ASSERT_OK(txn->Prepare());
+    ASSERT_OK(txn->Commit());
+    delete txn;
+  }
+  ASSERT_OK(db_->Flush(FlushOptions()));
+
+  // Write more data - these will allocate sequence numbers
+  for (int i = 10; i < 20; i++) {
+    Transaction* txn = db_->BeginTransaction(write_opts, txn_opts);
+    ASSERT_NE(txn, nullptr);
+    ASSERT_OK(txn->SetName("txn" + std::to_string(i)));
+    ASSERT_OK(txn->Put("key" + std::to_string(i), "value" + std::to_string(i)));
+    ASSERT_OK(txn->Prepare());
+    ASSERT_OK(txn->Commit());
+    delete txn;
+  }
+
+  // Set up sync point dependency chain for deterministic recovery
+  // synchronization, following the pattern from
+  // ManifestWriteRetryableErrorAutoRecover in error_handler_fs_test.cc.
+  ROCKSDB_NAMESPACE::SyncPoint::GetInstance()->LoadDependency(
+      {{"RecoverFromRetryableBGIOError:BeforeStart",
+        "SeqnoGoesBackwardsDuringErrorRecovery:0"},
+       {"SeqnoGoesBackwardsDuringErrorRecovery:1",
+        "RecoverFromRetryableBGIOError:BeforeWait1"},
+       {"RecoverFromRetryableBGIOError:RecoverSuccess",
+        "SeqnoGoesBackwardsDuringErrorRecovery:2"}});
+
+  // Inject a retryable MANIFEST write error on the next flush
+  IOStatus error_to_inject = IOStatus::IOError("Injected MANIFEST error");
+  error_to_inject.SetRetryable(true);
+  SyncPoint::GetInstance()->SetCallBack(
+      "VersionSet::LogAndApply:WriteManifest",
+      [&](void*) { fault_fs_->SetFilesystemActive(false, error_to_inject); });
+  SyncPoint::GetInstance()->EnableProcessing();
+
+  // Trigger a flush that will fail due to MANIFEST write error
+  Status s = db_->Flush(FlushOptions());
+  ASSERT_NOK(s);
+
+  // Wait for recovery to start, then re-enable filesystem and let it proceed.
+  // Clear the callback first to prevent it from re-disabling the filesystem
+  // if recovery's ResumeImpl triggers WriteManifest before we re-enable.
+  TEST_SYNC_POINT("SeqnoGoesBackwardsDuringErrorRecovery:0");
+  SyncPoint::GetInstance()->ClearCallBack(
+      "VersionSet::LogAndApply:WriteManifest");
+  fault_fs_->SetFilesystemActive(true);
+  TEST_SYNC_POINT("SeqnoGoesBackwardsDuringErrorRecovery:1");
+
+  // Wait for recovery to complete
+  TEST_SYNC_POINT("SeqnoGoesBackwardsDuringErrorRecovery:2");
+  SyncPoint::GetInstance()->DisableProcessing();
+
+  // Write some more data after recovery
+  for (int i = 20; i < 30; i++) {
+    Transaction* txn = db_->BeginTransaction(write_opts, txn_opts);
+    ASSERT_NE(txn, nullptr);
+    ASSERT_OK(txn->SetName("txn_after_" + std::to_string(i)));
+    ASSERT_OK(txn->Put("key" + std::to_string(i), "value" + std::to_string(i)));
+    ASSERT_OK(txn->Prepare());
+    ASSERT_OK(txn->Commit());
+    delete txn;
+  }
+
+  // Close and reopen - this would fail with "sequence number going backwards"
+  // before the fix.
+  Close();
+
+  Status reopen_s = Open();
+  ASSERT_OK(reopen_s);
+
+  // Verify data integrity
+  ReadOptions read_opts;
+  for (int i = 0; i < 20; i++) {
+    std::string value;
+    ASSERT_OK(db_->Get(read_opts, "key" + std::to_string(i), &value));
+    ASSERT_EQ(value, "value" + std::to_string(i));
+  }
+
+  Close();
+}
+
+// Test that verifies the sequence number discrepancy is resolved by checking
+// that LastSequence >= LastAllocatedSequence after recovery completes.
+TEST_F(WritePreparedTransactionSeqnoTest, SeqnoDiscrepancyDuringErrorRecovery) {
+  ASSERT_OK(Open());
+
+  WriteOptions write_opts;
+  TransactionOptions txn_opts;
+
+  // Write initial data and flush
+  for (int i = 0; i < 5; i++) {
+    Transaction* txn = db_->BeginTransaction(write_opts, txn_opts);
+    ASSERT_NE(txn, nullptr);
+    ASSERT_OK(txn->SetName("init_txn" + std::to_string(i)));
+    ASSERT_OK(txn->Put("key" + std::to_string(i), "value" + std::to_string(i)));
+    ASSERT_OK(txn->Prepare());
+    ASSERT_OK(txn->Commit());
+    delete txn;
+  }
+  ASSERT_OK(db_->Flush(FlushOptions()));
+
+  // Write more transactions with two_write_queues to potentially create a gap
+  // between allocated and published sequence numbers. These must be written
+  // before installing the error injection callback, since the small write
+  // buffer (4KB) could trigger an automatic flush during these writes.
+  for (int i = 5; i < 10; i++) {
+    Transaction* txn = db_->BeginTransaction(write_opts, txn_opts);
+    ASSERT_NE(txn, nullptr);
+    ASSERT_OK(txn->SetName("txn" + std::to_string(i)));
+    ASSERT_OK(txn->Put("key" + std::to_string(i), "value" + std::to_string(i)));
+    ASSERT_OK(txn->Prepare());
+    ASSERT_OK(txn->Commit());
+    delete txn;
+  }
+
+  // Track sequence numbers at key points
+  std::atomic<uint64_t> last_seq_after_recovery{0};
+  std::atomic<uint64_t> last_allocated_seq_after_recovery{0};
+  std::atomic<bool> captured_seqs_after{false};
+
+  IOStatus error_to_inject = IOStatus::IOError("Injected error");
+  error_to_inject.SetRetryable(true);
+
+  // Set up sync point dependency chain for deterministic synchronization
+  ROCKSDB_NAMESPACE::SyncPoint::GetInstance()->LoadDependency(
+      {{"RecoverFromRetryableBGIOError:BeforeStart",
+        "SeqnoDiscrepancyDuringErrorRecovery:0"},
+       {"SeqnoDiscrepancyDuringErrorRecovery:1",
+        "RecoverFromRetryableBGIOError:BeforeWait1"},
+       {"RecoverFromRetryableBGIOError:RecoverSuccess",
+        "SeqnoDiscrepancyDuringErrorRecovery:2"}});
+
+  SyncPoint::GetInstance()->SetCallBack(
+      "VersionSet::LogAndApply:WriteManifest",
+      [&](void*) { fault_fs_->SetFilesystemActive(false, error_to_inject); });
+
+  // Capture sequence numbers after recovery completes to verify the fix
+  SyncPoint::GetInstance()->SetCallBack(
+      "RecoverFromRetryableBGIOError:RecoverSuccess", [&](void*) {
+        DBImpl* db_impl = dbimpl();
+        if (db_impl) {
+          VersionSet* vs = db_impl->GetVersionSet();
+          if (vs) {
+            last_seq_after_recovery.store(vs->LastSequence());
+            last_allocated_seq_after_recovery.store(
+                vs->LastAllocatedSequence());
+            captured_seqs_after.store(true);
+          }
+        }
+      });
+
+  SyncPoint::GetInstance()->EnableProcessing();
+
+  // Trigger a flush that will fail
+  Status flush_s = db_->Flush(FlushOptions());
+  ASSERT_NOK(flush_s);
+
+  // Wait for recovery to start, re-enable filesystem, let it proceed.
+  // Clear the callback first to prevent it from re-disabling the filesystem
+  // if recovery's ResumeImpl triggers WriteManifest before we re-enable.
+  TEST_SYNC_POINT("SeqnoDiscrepancyDuringErrorRecovery:0");
+  SyncPoint::GetInstance()->ClearCallBack(
+      "VersionSet::LogAndApply:WriteManifest");
+  fault_fs_->SetFilesystemActive(true);
+  TEST_SYNC_POINT("SeqnoDiscrepancyDuringErrorRecovery:1");
+
+  // Wait for recovery to complete
+  TEST_SYNC_POINT("SeqnoDiscrepancyDuringErrorRecovery:2");
+  SyncPoint::GetInstance()->DisableProcessing();
+
+  // Verify that sequences were captured and are in sync after recovery
+  ASSERT_TRUE(captured_seqs_after.load());
+  ASSERT_GE(last_seq_after_recovery.load(),
+            last_allocated_seq_after_recovery.load())
+      << "LastSequence should be >= LastAllocatedSequence after recovery";
+
+  // Close and reopen should succeed without corruption
+  Close();
+  ASSERT_OK(Open());
+
+  // Verify data integrity
+  ReadOptions read_opts;
+  for (int i = 0; i < 10; i++) {
+    std::string value;
+    ASSERT_OK(db_->Get(read_opts, "key" + std::to_string(i), &value));
+    ASSERT_EQ(value, "value" + std::to_string(i));
+  }
+
+  Close();
+}
+
+// Test that verifies SyncLastSequenceWithAllocated is called during ResumeImpl
+// by checking sequence numbers before and after the sync point.
+TEST_F(WritePreparedTransactionSeqnoTest, ConcurrentWritesDuringErrorRecovery) {
+  ASSERT_OK(Open());
+
+  WriteOptions write_opts;
+  TransactionOptions txn_opts;
+
+  // Write initial data and flush
+  for (int i = 0; i < 5; i++) {
+    Transaction* txn = db_->BeginTransaction(write_opts, txn_opts);
+    ASSERT_NE(txn, nullptr);
+    ASSERT_OK(txn->SetName("init_txn" + std::to_string(i)));
+    ASSERT_OK(txn->Put("key" + std::to_string(i), "value" + std::to_string(i)));
+    ASSERT_OK(txn->Prepare());
+    ASSERT_OK(txn->Commit());
+    delete txn;
+  }
+  ASSERT_OK(db_->Flush(FlushOptions()));
+
+  // Write more transactions. These must be written before installing the error
+  // injection callback, since the small write buffer (4KB) could trigger an
+  // automatic flush during these writes.
+  for (int i = 5; i < 10; i++) {
+    Transaction* txn = db_->BeginTransaction(write_opts, txn_opts);
+    ASSERT_NE(txn, nullptr);
+    ASSERT_OK(txn->SetName("txn" + std::to_string(i)));
+    ASSERT_OK(txn->Put("key" + std::to_string(i), "value" + std::to_string(i)));
+    ASSERT_OK(txn->Prepare());
+    ASSERT_OK(txn->Commit());
+    delete txn;
+  }
+
+  // Track sequence numbers at key points during recovery
+  std::atomic<uint64_t> seq_before_resume{0};
+  std::atomic<uint64_t> alloc_seq_before_resume{0};
+  std::atomic<uint64_t> seq_after_resume{0};
+  std::atomic<uint64_t> alloc_seq_after_resume{0};
+
+  IOStatus error_to_inject = IOStatus::IOError("Injected error");
+  error_to_inject.SetRetryable(true);
+
+  // Set up sync point dependency chain for deterministic synchronization
+  ROCKSDB_NAMESPACE::SyncPoint::GetInstance()->LoadDependency(
+      {{"RecoverFromRetryableBGIOError:BeforeStart",
+        "ConcurrentWritesDuringErrorRecovery:0"},
+       {"ConcurrentWritesDuringErrorRecovery:1",
+        "RecoverFromRetryableBGIOError:BeforeWait1"},
+       {"RecoverFromRetryableBGIOError:RecoverSuccess",
+        "ConcurrentWritesDuringErrorRecovery:2"}});
+
+  SyncPoint::GetInstance()->SetCallBack(
+      "VersionSet::LogAndApply:WriteManifest",
+      [&](void*) { fault_fs_->SetFilesystemActive(false, error_to_inject); });
+
+  // Capture sequences right before ResumeImpl runs the sync
+  SyncPoint::GetInstance()->SetCallBack("DBImpl::ResumeImpl:Start", [&](void*) {
+    DBImpl* db_impl = dbimpl();
+    if (db_impl) {
+      VersionSet* vs = db_impl->GetVersionSet();
+      if (vs) {
+        seq_before_resume.store(vs->LastSequence());
+        alloc_seq_before_resume.store(vs->LastAllocatedSequence());
+      }
+    }
+  });
+
+  // Capture sequences right after ResumeImpl syncs them
+  SyncPoint::GetInstance()->SetCallBack(
+      "DBImpl::ResumeImpl:AfterSyncSeq", [&](void*) {
+        DBImpl* db_impl = dbimpl();
+        if (db_impl) {
+          VersionSet* vs = db_impl->GetVersionSet();
+          if (vs) {
+            seq_after_resume.store(vs->LastSequence());
+            alloc_seq_after_resume.store(vs->LastAllocatedSequence());
+          }
+        }
+      });
+
+  SyncPoint::GetInstance()->EnableProcessing();
+
+  // Trigger a flush that will fail
+  Status flush_s = db_->Flush(FlushOptions());
+  ASSERT_NOK(flush_s);
+
+  // Wait for recovery to start, re-enable filesystem, let it proceed.
+  // Clear the callback first to prevent it from re-disabling the filesystem
+  // if recovery's ResumeImpl triggers WriteManifest before we re-enable.
+  TEST_SYNC_POINT("ConcurrentWritesDuringErrorRecovery:0");
+  SyncPoint::GetInstance()->ClearCallBack(
+      "VersionSet::LogAndApply:WriteManifest");
+  fault_fs_->SetFilesystemActive(true);
+  TEST_SYNC_POINT("ConcurrentWritesDuringErrorRecovery:1");
+
+  // Wait for recovery to complete
+  TEST_SYNC_POINT("ConcurrentWritesDuringErrorRecovery:2");
+  SyncPoint::GetInstance()->DisableProcessing();
+
+  // Verify that the AfterSyncSeq callback fired and sequences are in sync
+  ASSERT_GT(seq_after_resume.load(), 0u)
+      << "DBImpl::ResumeImpl:AfterSyncSeq callback should have fired";
+  ASSERT_EQ(seq_after_resume.load(), alloc_seq_after_resume.load())
+      << "Fix should have synced sequences";
+
+  // Close and reopen
+  Close();
+  ASSERT_OK(Open());
+
+  // Verify data integrity
+  ReadOptions read_opts;
+  for (int i = 0; i < 10; i++) {
+    std::string value;
+    ASSERT_OK(db_->Get(read_opts, "key" + std::to_string(i), &value));
+    ASSERT_EQ(value, "value" + std::to_string(i));
+  }
+
+  Close();
+}
+
+}  // namespace ROCKSDB_NAMESPACE
+
+int main(int argc, char** argv) {
+  ROCKSDB_NAMESPACE::port::InstallStackTraceHandler();
+  ::testing::InitGoogleTest(&argc, argv);
+  return RUN_ALL_TESTS();
+}

package/deps/rocksdb/rocksdb/utilities/transactions/write_prepared_transaction_test.cc

@@ -196,7 +196,7 @@ TEST(PreparedHeap, Concurrent) {
 TEST(WriteBatchWithIndex, SubBatchCnt) {
   ColumnFamilyOptions cf_options;
   std::string cf_name = "two";
-  DB* db;
+  std::unique_ptr<DB> db;
   Options options;
   options.create_if_missing = true;
   const std::string dbname = test::PerThreadDBPath("transaction_testdb");
@@ -285,7 +285,6 @@ TEST(WriteBatchWithIndex, SubBatchCnt) {
   }
 
   delete cf_handle;
-  delete db;
 }
 
 TEST(CommitEntry64b, BasicTest) {

package/deps/rocksdb/rocksdb/utilities/transactions/write_prepared_txn.h

@@ -36,6 +36,97 @@ class WritePreparedTxnDB;
 // committed data from uncommitted data. Uncommitted data could be after the
 // Prepare phase in 2PC (WritePreparedTxn) or before that
 // (WriteUnpreparedTxnImpl).
+//
+// == Concrete example: WritePrepared 2PC transaction ==
+//
+// User code:
+//
+//   Transaction* txn = db->BeginTransaction(write_opts, txn_opts);
+//   txn->SetName("txn1");
+//   txn->Put("key1", "value1");   // buffered in WriteBatch, nothing written
+//   yet txn->Prepare();               // Phase 1 txn->Commit(); // Phase 2
+//
+// -- Phase 1: Prepare (PrepareInternal) --
+//
+// The Prepare call (write_prepared_txn.cc PrepareInternal) calls:
+//
+//   db_impl_->WriteImpl(write_options, GetWriteBatch(),
+//                       ..., !DISABLE_MEMTABLE, ...);
+//
+// !DISABLE_MEMTABLE is false — memtable is enabled. This is the defining
+// characteristic of "WritePrepared": the actual data (Put("key1", "value1"))
+// is written to the memtable at Prepare time.
+//
+// Because disable_memtable == false, the routing check at
+// db_impl_write.cc:502 is not taken. The write goes through the main write
+// queue (write_thread_), which handles both WAL and memtable:
+//
+//   Destination | What gets written                          | Sequence
+//   ------------|--------------------------------------------|-----------
+//   WAL         | Put(key1, value1) + EndPrepare(txn1)       | prepare_seq
+//   Memtable    | Put(key1, value1)                          | prepare_seq
+//
+// The data is now durable (WAL) and in the memtable, but not yet visible
+// to readers. Readers use GetLastPublishedSequence() which consults a
+// commit map — since prepare_seq is in the PreparedHeap but not yet in the
+// CommitCache, readers know this data is uncommitted and skip it.
+//
+// -- Phase 2: Commit (CommitInternal) --
+//
+// The Commit call (write_prepared_txn.cc CommitInternal) calls:
+//
+//   db_impl_->WriteImpl(write_options_, working_batch,
+//                       ..., disable_memtable, ...);
+//
+// In the typical case (do_one_write == true, i.e., the commit-time batch
+// is empty or has no data), disable_memtable is true. Now the routing
+// check at db_impl_write.cc:502 is taken:
+//
+//   if (two_write_queues_ && disable_memtable) {
+//       return WriteImplWALOnly(&nonmem_write_thread_, ...);
+//   }
+//
+// The commit goes through the second write queue (nonmem_write_thread_),
+// WAL only:
+//
+//   Destination | What gets written   | Sequence
+//   ------------|---------------------|-----------
+//   WAL         | Commit(txn1) marker | commit_seq
+//   Memtable    | Nothing             | —
+//
+// The PreReleaseCallback (WritePreparedCommitEntryPreReleaseCallback)
+// updates the CommitCache to record that prepare_seq was committed at
+// commit_seq. After this, readers consulting the commit map will see that
+// the data at prepare_seq is committed and therefore visible.
+//
+// -- Why two queues help --
+//
+// The Commit phase doesn't touch the memtable — it only writes a small
+// marker to WAL and updates an in-memory commit map. By routing this
+// through a separate queue, Commit writes don't have to wait behind other
+// transactions' Prepare writes (which do the expensive memtable insertion
+// on the main queue). This is the optimization mentioned in the options
+// comment about MySQL 2PC where commits are serial.
+//
+// -- Sequence number flow --
+//
+//                            last_sequence_ | last_allocated_seq |
+//                            last_published_seq
+//                            ---------------|--------------------|-------------------
+//   Before Prepare:                  9      |         9          |        9
+//
+//   Prepare (main queue):
+//     FetchAdd alloc seq             9      |        10          |        9
+//     Write WAL + memtable
+//     SetLastSequence               10      |        10          |        9
+//     (published_seq not advanced yet — data is uncommitted)
+//
+//   Commit (2nd queue):
+//     FetchAdd alloc seq            10      |        11          |        9
+//     Write WAL only
+//     Update CommitCache
+//     SetLastPublishedSeq           10      |        11          |       11
+//
 class WritePreparedTxn : public PessimisticTransaction {
  public:
   WritePreparedTxn(WritePreparedTxnDB* db, const WriteOptions& write_options,