From ca8b85ac043fb066d6ff124729ef24b8c8ff02fc Mon Sep 17 00:00:00 2001
From: agiardullo <agiardullo@fb.com>
Date: Tue, 2 Jun 2015 21:24:19 -0700
Subject: [PATCH] better document max_write_buffer_number_to_maintain

Test Plan: compile

Reviewers: igor, sdong

Reviewed By: sdong

Subscribers: dhruba, leveldb

Differential Revision: https://reviews.facebook.net/D39285
---
 include/rocksdb/options.h                          |  6 +++++-
 .../transactions/optimistic_transaction_impl.cc    | 14 ++++++++++----
 2 files changed, 15 insertions(+), 5 deletions(-)

diff --git a/include/rocksdb/options.h b/include/rocksdb/options.h
index 66fe9e2b6..fcd044a6e 100644
--- a/include/rocksdb/options.h
+++ b/include/rocksdb/options.h
@@ -250,7 +250,11 @@ struct ColumnFamilyOptions {
   // after they are flushed.
   // If this value is set to -1, 'max_write_buffer_number' will be used.
   //
-  // Default: 0
+  // Default:
+  // If using an OptimisticTransactionDB, the default value will be set to the
+  // value
+  // of 'max_write_buffer_number' if it is not explicitly set by the user.
+  // Otherwise, the default is 0.
   int max_write_buffer_number_to_maintain;
 
   // Compress blocks using the specified compression algorithm.  This
diff --git a/utilities/transactions/optimistic_transaction_impl.cc b/utilities/transactions/optimistic_transaction_impl.cc
index cfb9fa660..d45117236 100644
--- a/utilities/transactions/optimistic_transaction_impl.cc
+++ b/utilities/transactions/optimistic_transaction_impl.cc
@@ -292,12 +292,14 @@ Status OptimisticTransactionImpl::CheckTransactionForConflicts(DB* db) {
       // Since it would be too slow to check the SST files, we will only use
       // the memtables to check whether there have been any recent writes
       // to this key after it was accessed in this transaction.  But if the
-      // memtables have been flushed recently, we cannot rely on them to tell
-      // whether there have been any recent writes and must fail this
+      // Memtables do not contain a long enough history, we must fail the
       // transaction.
       if (earliest_seq == kMaxSequenceNumber) {
         // The age of this memtable is unknown.  Cannot rely on it to check
-        // for recent writes.
+        // for recent writes.  This error shouldn't happen often in practice as
+        // the
+        // Memtable should have a valid earliest sequence number except in some
+        // corner cases (such as error cases during recovery).
         result = Status::Busy(
             "Could not commit transaction with as the MemTable does not "
             "countain a long enough history to check write at SequenceNumber: ",
@@ -311,7 +313,11 @@ Status OptimisticTransactionImpl::CheckTransactionForConflicts(DB* db) {
             msg, sizeof(msg),
             "Could not commit transaction with write at SequenceNumber %" PRIu64
             " as the MemTable only contains changes newer than SequenceNumber "
-            "%" PRIu64 ".",
+            "%" PRIu64
+            ".  Increasing the value of the "
+            "max_write_buffer_number_to_maintain option could reduce the "
+            "frequency "
+            "of this error.",
             key_seq, earliest_seq);
         result = Status::Busy(msg);
       } else {