rocksdb-native 2.2.0 → 2.3.0

package/vendor/librocksdb/vendor/rocksdb/file/file_util.h

@@ -46,10 +46,25 @@ inline IOStatus CreateFile(const std::shared_ptr<FileSystem>& fs,
   return CreateFile(fs.get(), destination, contents, use_fsync);
 }
 
+// Delete a DB file, if this file is a SST file or Blob file and SstFileManager
+// is used, it should have already been tracked by SstFileManager via its
+// `OnFileAdd` API before passing to this API to be deleted, to ensure
+// SstFileManager and its DeleteScheduler are tracking DB size and trash size
+// properly.
 Status DeleteDBFile(const ImmutableDBOptions* db_options,
                     const std::string& fname, const std::string& path_to_sync,
                     const bool force_bg, const bool force_fg);
 
+// Delete an unaccounted DB file that is not tracked by SstFileManager and will
+// not be tracked by its DeleteScheduler when getting deleted.
+// If a legitimate bucket is provided and this file is scheduled for slow
+// deletion, it will be assigned to the specified trash bucket.
+Status DeleteUnaccountedDBFile(const ImmutableDBOptions* db_options,
+                               const std::string& fname,
+                               const std::string& dir_to_sync,
+                               const bool force_bg, const bool force_fg,
+                               std::optional<int32_t> bucket);
+
 // TODO(hx235): pass the whole DBOptions intead of its individual fields
 IOStatus GenerateOneFileChecksum(
     FileSystem* fs, const std::string& file_path,

package/vendor/librocksdb/vendor/rocksdb/file/sequence_file_reader.cc

@@ -41,6 +41,7 @@ IOStatus SequentialFileReader::Read(size_t n, Slice* result, char* scratch,
   IOStatus io_s;
   IOOptions io_opts;
   io_opts.rate_limiter_priority = rate_limiter_priority;
+  io_opts.verify_and_reconstruct_read = verify_and_reconstruct_read_;
   if (use_direct_io()) {
     //
     //    |-offset_advance-|---bytes returned--|

package/vendor/librocksdb/vendor/rocksdb/file/sequence_file_reader.h

@@ -56,6 +56,7 @@ class SequentialFileReader {
   std::atomic<size_t> offset_{0};  // read offset
   std::vector<std::shared_ptr<EventListener>> listeners_{};
   RateLimiter* rate_limiter_;
+  bool verify_and_reconstruct_read_;
 
  public:
   explicit SequentialFileReader(
@@ -63,11 +64,13 @@ class SequentialFileReader {
       const std::shared_ptr<IOTracer>& io_tracer = nullptr,
       const std::vector<std::shared_ptr<EventListener>>& listeners = {},
       RateLimiter* rate_limiter =
-          nullptr)  // TODO: migrate call sites to provide rate limiter
+          nullptr,  // TODO: migrate call sites to provide rate limiter
+      bool verify_and_reconstruct_read = false)
       : file_name_(_file_name),
         file_(std::move(_file), io_tracer, _file_name),
         listeners_(),
-        rate_limiter_(rate_limiter) {
+        rate_limiter_(rate_limiter),
+        verify_and_reconstruct_read_(verify_and_reconstruct_read) {
     AddFileIOListeners(listeners);
   }
 
@@ -77,12 +80,14 @@ class SequentialFileReader {
       const std::shared_ptr<IOTracer>& io_tracer = nullptr,
       const std::vector<std::shared_ptr<EventListener>>& listeners = {},
       RateLimiter* rate_limiter =
-          nullptr)  // TODO: migrate call sites to provide rate limiter
+          nullptr,  // TODO: migrate call sites to provide rate limiter
+      bool verify_and_reconstruct_read = false)
       : file_name_(_file_name),
         file_(NewReadaheadSequentialFile(std::move(_file), _readahead_size),
               io_tracer, _file_name),
         listeners_(),
-        rate_limiter_(rate_limiter) {
+        rate_limiter_(rate_limiter),
+        verify_and_reconstruct_read_(verify_and_reconstruct_read) {
     AddFileIOListeners(listeners);
   }
   static IOStatus Create(const std::shared_ptr<FileSystem>& fs,

package/vendor/librocksdb/vendor/rocksdb/file/sst_file_manager_impl.cc

@@ -421,10 +421,28 @@ Status SstFileManagerImpl::ScheduleFileDeletion(const std::string& file_path,
   return delete_scheduler_.DeleteFile(file_path, path_to_sync, force_bg);
 }
 
+Status SstFileManagerImpl::ScheduleUnaccountedFileDeletion(
+    const std::string& file_path, const std::string& dir_to_sync,
+    const bool force_bg, std::optional<int32_t> bucket) {
+  TEST_SYNC_POINT_CALLBACK(
+      "SstFileManagerImpl::ScheduleUnaccountedFileDeletion",
+      const_cast<std::string*>(&file_path));
+  return delete_scheduler_.DeleteUnaccountedFile(file_path, dir_to_sync,
+                                                 force_bg, bucket);
+}
+
 void SstFileManagerImpl::WaitForEmptyTrash() {
   delete_scheduler_.WaitForEmptyTrash();
 }
 
+std::optional<int32_t> SstFileManagerImpl::NewTrashBucket() {
+  return delete_scheduler_.NewTrashBucket();
+}
+
+void SstFileManagerImpl::WaitForEmptyTrashBucket(int32_t bucket) {
+  delete_scheduler_.WaitForEmptyTrashBucket(bucket);
+}
+
 void SstFileManagerImpl::OnAddFileImpl(const std::string& file_path,
                                        uint64_t file_size) {
   auto tracked_file = tracked_files_.find(file_path);

package/vendor/librocksdb/vendor/rocksdb/file/sst_file_manager_impl.h

@@ -5,7 +5,7 @@
 
 #pragma once
 
-
+#include <optional>
 #include <string>
 
 #include "db/compaction/compaction.h"
@@ -30,6 +30,10 @@ class SstFileManagerImpl : public SstFileManager {
                               double max_trash_db_ratio,
                               uint64_t bytes_max_delete_chunk);
 
+  // No copy
+  SstFileManagerImpl(const SstFileManagerImpl& sfm) = delete;
+  SstFileManagerImpl& operator=(const SstFileManagerImpl& sfm) = delete;
+
   ~SstFileManagerImpl();
 
   // DB will call OnAddFile whenever a new sst/blob file is added.
@@ -114,17 +118,40 @@ class SstFileManagerImpl : public SstFileManager {
   // not guaranteed
   bool CancelErrorRecovery(ErrorHandler* db);
 
-  // Mark file as trash and schedule it's deletion. If force_bg is set, it
+  // Mark a file as trash and schedule its deletion. If force_bg is set, it
   // forces the file to be deleting in the background regardless of DB size,
-  // except when rate limited delete is disabled
+  // except when rate limited delete is disabled.
   virtual Status ScheduleFileDeletion(const std::string& file_path,
                                       const std::string& dir_to_sync,
                                       const bool force_bg = false);
 
-  // Wait for all files being deleteing in the background to finish or for
+  // Delete an unaccounted file. The file is deleted immediately if slow
+  // deletion is disabled. A file with more than 1 hard links will be deleted
+  // immediately unless force_bg is set. In other cases, files will be scheduled
+  // for slow deletion, and assigned to the specified bucket if a legitimate one
+  // is provided. A legitimate bucket is one that is created with the
+  // `NewTrashBucket` API, and for which `WaitForEmptyTrashBucket` hasn't been
+  // called yet.
+  virtual Status ScheduleUnaccountedFileDeletion(
+      const std::string& file_path, const std::string& dir_to_sync,
+      const bool force_bg = false,
+      std::optional<int32_t> bucket = std::nullopt);
+
+  // Wait for all files being deleted in the background to finish or for
   // destructor to be called.
   virtual void WaitForEmptyTrash();
 
+  // Creates a new trash bucket. A legitimate bucket is only created and
+  // returned when slow deletion is enabled.
+  // For each bucket that is created and used, the user should also call
+  // `WaitForEmptyTrashBucket` after scheduling file deletions to make sure all
+  // the trash files are cleared.
+  std::optional<int32_t> NewTrashBucket();
+
+  // Wait for all the files in the specified bucket to be deleted in the
+  // background or for destructor to be called.
+  virtual void WaitForEmptyTrashBucket(int32_t bucket);
+
   DeleteScheduler* delete_scheduler() { return &delete_scheduler_; }
 
   // Stop the error recovery background thread. This should be called only

package/vendor/librocksdb/vendor/rocksdb/file/writable_file_writer.cc

@@ -64,7 +64,7 @@ IOStatus WritableFileWriter::Create(const std::shared_ptr<FileSystem>& fs,
 IOStatus WritableFileWriter::Append(const IOOptions& opts, const Slice& data,
                                     uint32_t crc32c_checksum) {
   if (seen_error()) {
-    return AssertFalseAndGetStatusForPrevError();
+    return GetWriterHasPreviousErrorStatus();
   }
 
   StopWatch sw(clock_, stats_, hist_type_,
@@ -109,7 +109,7 @@ IOStatus WritableFileWriter::Append(const IOOptions& opts, const Slice& data,
     if (buf_.CurrentSize() > 0) {
       s = Flush(io_options);
       if (!s.ok()) {
-        set_seen_error();
+        set_seen_error(s);
         return s;
       }
     }
@@ -191,7 +191,7 @@ IOStatus WritableFileWriter::Append(const IOOptions& opts, const Slice& data,
     uint64_t cur_size = filesize_.load(std::memory_order_acquire);
     filesize_.store(cur_size + data.size(), std::memory_order_release);
   } else {
-    set_seen_error();
+    set_seen_error(s);
   }
   return s;
 }
@@ -199,13 +199,12 @@ IOStatus WritableFileWriter::Append(const IOOptions& opts, const Slice& data,
 IOStatus WritableFileWriter::Pad(const IOOptions& opts,
                                  const size_t pad_bytes) {
   if (seen_error()) {
-    return AssertFalseAndGetStatusForPrevError();
+    return GetWriterHasPreviousErrorStatus();
   }
   const IOOptions io_options = FinalizeIOOptions(opts);
   assert(pad_bytes < kDefaultPageSize);
   size_t left = pad_bytes;
   size_t cap = buf_.Capacity() - buf_.CurrentSize();
-  size_t pad_start = buf_.CurrentSize();
 
   // Assume pad_bytes is small compared to buf_ capacity. So we always
   // use buf_ rather than write directly to file in certain cases like
@@ -214,10 +213,20 @@ IOStatus WritableFileWriter::Pad(const IOOptions& opts,
     size_t append_bytes = std::min(cap, left);
     buf_.PadWith(append_bytes, 0);
     left -= append_bytes;
+
+    Slice data(buf_.BufferStart() + buf_.CurrentSize() - append_bytes,
+               append_bytes);
+    UpdateFileChecksum(data);
+    if (perform_data_verification_) {
+      buffered_data_crc32c_checksum_ = crc32c::Extend(
+          buffered_data_crc32c_checksum_,
+          buf_.BufferStart() + buf_.CurrentSize() - append_bytes, append_bytes);
+    }
+
     if (left > 0) {
       IOStatus s = Flush(io_options);
       if (!s.ok()) {
-        set_seen_error();
+        set_seen_error(s);
         return s;
       }
     }
@@ -226,11 +235,7 @@ IOStatus WritableFileWriter::Pad(const IOOptions& opts,
   pending_sync_ = true;
   uint64_t cur_size = filesize_.load(std::memory_order_acquire);
   filesize_.store(cur_size + pad_bytes, std::memory_order_release);
-  if (perform_data_verification_) {
-    buffered_data_crc32c_checksum_ =
-        crc32c::Extend(buffered_data_crc32c_checksum_,
-                       buf_.BufferStart() + pad_start, pad_bytes);
-  }
+
   return IOStatus::OK();
 }
 
@@ -333,7 +338,7 @@ IOStatus WritableFileWriter::Close(const IOOptions& opts) {
       checksum_finalized_ = true;
     }
   } else {
-    set_seen_error();
+    set_seen_error(s);
   }
 
   return s;
@@ -343,7 +348,7 @@ IOStatus WritableFileWriter::Close(const IOOptions& opts) {
 // enabled
 IOStatus WritableFileWriter::Flush(const IOOptions& opts) {
   if (seen_error()) {
-    return AssertFalseAndGetStatusForPrevError();
+    return GetWriterHasPreviousErrorStatus();
   }
 
   const IOOptions io_options = FinalizeIOOptions(opts);
@@ -369,7 +374,7 @@ IOStatus WritableFileWriter::Flush(const IOOptions& opts) {
       }
     }
     if (!s.ok()) {
-      set_seen_error();
+      set_seen_error(s);
       return s;
     }
   }
@@ -390,7 +395,7 @@ IOStatus WritableFileWriter::Flush(const IOOptions& opts) {
   }
 
   if (!s.ok()) {
-    set_seen_error();
+    set_seen_error(s);
     return s;
   }
 
@@ -419,7 +424,7 @@ IOStatus WritableFileWriter::Flush(const IOOptions& opts) {
         s = RangeSync(io_options, last_sync_size_,
                       offset_sync_to - last_sync_size_);
         if (!s.ok()) {
-          set_seen_error();
+          set_seen_error(s);
         }
         last_sync_size_ = offset_sync_to;
       }
@@ -453,20 +458,20 @@ IOStatus WritableFileWriter::PrepareIOOptions(const WriteOptions& wo,
 
 IOStatus WritableFileWriter::Sync(const IOOptions& opts, bool use_fsync) {
   if (seen_error()) {
-    return AssertFalseAndGetStatusForPrevError();
+    return GetWriterHasPreviousErrorStatus();
   }
 
   IOOptions io_options = FinalizeIOOptions(opts);
   IOStatus s = Flush(io_options);
   if (!s.ok()) {
-    set_seen_error();
+    set_seen_error(s);
     return s;
   }
   TEST_KILL_RANDOM("WritableFileWriter::Sync:0");
   if (!use_direct_io() && pending_sync_) {
     s = SyncInternal(io_options, use_fsync);
     if (!s.ok()) {
-      set_seen_error();
+      set_seen_error(s);
       return s;
     }
   }
@@ -478,7 +483,7 @@ IOStatus WritableFileWriter::Sync(const IOOptions& opts, bool use_fsync) {
 IOStatus WritableFileWriter::SyncWithoutFlush(const IOOptions& opts,
                                               bool use_fsync) {
   if (seen_error()) {
-    return AssertFalseAndGetStatusForPrevError();
+    return GetWriterHasPreviousErrorStatus();
   }
   IOOptions io_options = FinalizeIOOptions(opts);
   if (!writable_file_->IsSyncThreadSafe()) {
@@ -490,10 +495,7 @@ IOStatus WritableFileWriter::SyncWithoutFlush(const IOOptions& opts,
   IOStatus s = SyncInternal(io_options, use_fsync);
   TEST_SYNC_POINT("WritableFileWriter::SyncWithoutFlush:2");
   if (!s.ok()) {
-#ifndef NDEBUG
-    sync_without_flush_called_ = true;
-#endif  // NDEBUG
-    set_seen_error();
+    set_seen_error(s);
   }
   return s;
 }
@@ -531,14 +533,14 @@ IOStatus WritableFileWriter::SyncInternal(const IOOptions& opts,
   }
   SetPerfLevel(prev_perf_level);
 
-  // The caller will be responsible to call set_seen_error() if s is not OK.
+  // The caller will be responsible to call set_seen_error(s) if s is not OK.
   return s;
 }
 
 IOStatus WritableFileWriter::RangeSync(const IOOptions& opts, uint64_t offset,
                                        uint64_t nbytes) {
   if (seen_error()) {
-    return AssertFalseAndGetStatusForPrevError();
+    return GetWriterHasPreviousErrorStatus();
   }
 
   IOSTATS_TIMER_GUARD(range_sync_nanos);
@@ -549,7 +551,7 @@ IOStatus WritableFileWriter::RangeSync(const IOOptions& opts, uint64_t offset,
   }
   IOStatus s = writable_file_->RangeSync(offset, nbytes, opts, nullptr);
   if (!s.ok()) {
-    set_seen_error();
+    set_seen_error(s);
   }
   if (ShouldNotifyListeners()) {
     auto finish_ts = std::chrono::steady_clock::now();
@@ -567,7 +569,7 @@ IOStatus WritableFileWriter::RangeSync(const IOOptions& opts, uint64_t offset,
 IOStatus WritableFileWriter::WriteBuffered(const IOOptions& opts,
                                            const char* data, size_t size) {
   if (seen_error()) {
-    return AssertFalseAndGetStatusForPrevError();
+    return GetWriterHasPreviousErrorStatus();
   }
 
   IOStatus s;
@@ -633,7 +635,7 @@ IOStatus WritableFileWriter::WriteBuffered(const IOOptions& opts,
         }
       }
       if (!s.ok()) {
-        set_seen_error();
+        set_seen_error(s);
         return s;
       }
     }
@@ -649,7 +651,7 @@ IOStatus WritableFileWriter::WriteBuffered(const IOOptions& opts,
   buf_.Size(0);
   buffered_data_crc32c_checksum_ = 0;
   if (!s.ok()) {
-    set_seen_error();
+    set_seen_error(s);
   }
   return s;
 }
@@ -658,7 +660,7 @@ IOStatus WritableFileWriter::WriteBufferedWithChecksum(const IOOptions& opts,
                                                        const char* data,
                                                        size_t size) {
   if (seen_error()) {
-    return AssertFalseAndGetStatusForPrevError();
+    return GetWriterHasPreviousErrorStatus();
   }
 
   IOStatus s;
@@ -724,7 +726,7 @@ IOStatus WritableFileWriter::WriteBufferedWithChecksum(const IOOptions& opts,
       // and let caller determine error handling.
       buf_.Size(0);
       buffered_data_crc32c_checksum_ = 0;
-      set_seen_error();
+      set_seen_error(s);
       return s;
     }
   }
@@ -739,7 +741,7 @@ IOStatus WritableFileWriter::WriteBufferedWithChecksum(const IOOptions& opts,
   uint64_t cur_size = flushed_size_.load(std::memory_order_acquire);
   flushed_size_.store(cur_size + left, std::memory_order_release);
   if (!s.ok()) {
-    set_seen_error();
+    set_seen_error(s);
   }
   return s;
 }
@@ -840,7 +842,7 @@ IOStatus WritableFileWriter::WriteDirect(const IOOptions& opts) {
       }
       if (!s.ok()) {
         buf_.Size(file_advance + leftover_tail);
-        set_seen_error();
+        set_seen_error(s);
         return s;
       }
     }
@@ -865,14 +867,14 @@ IOStatus WritableFileWriter::WriteDirect(const IOOptions& opts) {
     // behind
     next_write_offset_ += file_advance;
   } else {
-    set_seen_error();
+    set_seen_error(s);
   }
   return s;
 }
 
 IOStatus WritableFileWriter::WriteDirectWithChecksum(const IOOptions& opts) {
   if (seen_error()) {
-    return AssertFalseAndGetStatusForPrevError();
+    return GetWriterHasPreviousErrorStatus();
   }
 
   assert(use_direct_io());
@@ -948,7 +950,7 @@ IOStatus WritableFileWriter::WriteDirectWithChecksum(const IOOptions& opts) {
       buf_.Size(file_advance + leftover_tail);
       buffered_data_crc32c_checksum_ =
           crc32c::Value(buf_.BufferStart(), buf_.CurrentSize());
-      set_seen_error();
+      set_seen_error(s);
       return s;
     }
   }
@@ -973,7 +975,7 @@ IOStatus WritableFileWriter::WriteDirectWithChecksum(const IOOptions& opts) {
     // behind
     next_write_offset_ += file_advance;
   } else {
-    set_seen_error();
+    set_seen_error(s);
   }
   return s;
 }

package/vendor/librocksdb/vendor/rocksdb/file/writable_file_writer.h

@@ -22,6 +22,9 @@
 #include "rocksdb/rate_limiter.h"
 #include "test_util/sync_point.h"
 #include "util/aligned_buffer.h"
+#ifndef NDEBUG
+#include "utilities/fault_injection_fs.h"
+#endif  // NDEBUG
 
 namespace ROCKSDB_NAMESPACE {
 class Statistics;
@@ -150,11 +153,7 @@ class WritableFileWriter {
   bool pending_sync_;
   std::atomic<bool> seen_error_;
 #ifndef NDEBUG
-  // SyncWithoutFlush() is the function that is allowed to be called
-  // concurrently with other function. One of the concurrent call
-  // could set seen_error_, and the other one would hit assertion
-  // in debug mode.
-  std::atomic<bool> sync_without_flush_called_ = false;
+  std::atomic<bool> seen_injected_error_;
 #endif  // NDEBUG
   uint64_t last_sync_size_;
   uint64_t bytes_per_sync_;
@@ -190,6 +189,9 @@ class WritableFileWriter {
         next_write_offset_(0),
         pending_sync_(false),
         seen_error_(false),
+#ifndef NDEBUG
+        seen_injected_error_(false),
+#endif  // NDEBUG
         last_sync_size_(0),
         bytes_per_sync_(options.bytes_per_sync),
         rate_limiter_(options.rate_limiter),
@@ -234,13 +236,17 @@ class WritableFileWriter {
   WritableFileWriter& operator=(const WritableFileWriter&) = delete;
 
   ~WritableFileWriter() {
-    ThreadStatus::OperationType cur_op_type =
+    IOOptions io_options;
+#ifndef NDEBUG
+    // This is needed to pass the IOActivity related checks in stress test.
+    // See DbStressWritableFileWrapper.
+    ThreadStatus::OperationType op_type =
         ThreadStatusUtil::GetThreadOperation();
-    ThreadStatusUtil::SetThreadOperation(
-        ThreadStatus::OperationType::OP_UNKNOWN);
-    auto s = Close(IOOptions());
+    io_options.io_activity =
+        ThreadStatusUtil::TEST_GetExpectedIOActivity(op_type);
+#endif
+    auto s = Close(io_options);
     s.PermitUncheckedError();
-    ThreadStatusUtil::SetThreadOperation(cur_op_type);
   }
 
   std::string file_name() const { return file_name_; }
@@ -263,6 +269,8 @@ class WritableFileWriter {
   // returns NotSupported status.
   IOStatus SyncWithoutFlush(const IOOptions& opts, bool use_fsync);
 
+  // Size including unflushed data written to this writer. If the next op is
+  // a successful Close, the file size will be this.
   uint64_t GetFileSize() const {
     return filesize_.load(std::memory_order_acquire);
   }
@@ -283,7 +291,9 @@ class WritableFileWriter {
 
   bool use_direct_io() { return writable_file_->use_direct_io(); }
 
-  bool BufferIsEmpty() { return buf_.CurrentSize() == 0; }
+  bool BufferIsEmpty() const { return buf_.CurrentSize() == 0; }
+
+  bool IsClosed() const { return writable_file_.get() == nullptr; }
 
   void TEST_SetFileChecksumGenerator(
       FileChecksumGenerator* checksum_generator) {
@@ -301,12 +311,35 @@ class WritableFileWriter {
   // operating on the file after an error happens.
   void reset_seen_error() {
     seen_error_.store(false, std::memory_order_relaxed);
+#ifndef NDEBUG
+    seen_injected_error_.store(false, std::memory_order_relaxed);
+#endif  // NDEBUG
+  }
+  void set_seen_error(const Status& s) {
+    seen_error_.store(true, std::memory_order_relaxed);
+    (void)s;
+#ifndef NDEBUG
+    if (s.getState() && std::strstr(s.getState(), "inject")) {
+      seen_injected_error_.store(true, std::memory_order_relaxed);
+    }
+#endif  // NDEBUG
+  }
+#ifndef NDEBUG
+  bool seen_injected_error() const {
+    return seen_injected_error_.load(std::memory_order_relaxed);
   }
-  void set_seen_error() { seen_error_.store(true, std::memory_order_relaxed); }
+#endif  // NDEBUG
 
-  IOStatus AssertFalseAndGetStatusForPrevError() {
-    // This should only happen if SyncWithoutFlush() was called.
-    assert(sync_without_flush_called_);
+  // TODO(hx235): store the actual previous error status and return it here
+  IOStatus GetWriterHasPreviousErrorStatus() {
+#ifndef NDEBUG
+    if (seen_injected_error_.load(std::memory_order_relaxed)) {
+      std::stringstream msg;
+      msg << "Writer has previous " << FaultInjectionTestFS::kInjected
+          << " error.";
+      return IOStatus::IOError(msg.str());
+    }
+#endif  // NDEBUG
     return IOStatus::IOError("Writer has previous error.");
   }
 

package/vendor/librocksdb/vendor/rocksdb/include/rocksdb/advanced_options.h

@@ -229,11 +229,18 @@ struct AdvancedColumnFamilyOptions {
   // if it is not explicitly set by the user.  Otherwise, the default is 0.
   int64_t max_write_buffer_size_to_maintain = 0;
 
-  // Allows thread-safe inplace updates. If this is true, there is no way to
+  // Allows thread-safe inplace updates.
+  //
+  // If this is true, there is no way to
   // achieve point-in-time consistency using snapshot or iterator (assuming
   // concurrent updates). Hence iterator and multi-get will return results
   // which are not consistent as of any point-in-time.
+  //
   // Backward iteration on memtables will not work either.
+  //
+  // It is intended to work or be compatible with a limited set of features:
+  // (1) Non-snapshot Get()
+  //
   // If inplace_callback function is not set,
   //   Put(key, new_value) will update inplace the existing_value iff
   //   * key exists in current memtable
@@ -1030,8 +1037,10 @@ struct AdvancedColumnFamilyOptions {
   // When setting this flag to `false`, users should also call
   // `DB::IncreaseFullHistoryTsLow` to set a cutoff timestamp for flush. RocksDB
   // refrains from flushing a memtable with data still above
-  // the cutoff timestamp with best effort. If this cutoff timestamp is not set,
-  // flushing continues normally.
+  // the cutoff timestamp with best effort. One limitation of this best effort
+  // is that when `max_write_buffer_number` is equal to or smaller than 2,
+  // RocksDB will not attempt to retain user-defined timestamps, all flush jobs
+  // continue normally.
   //
   // Users can do user-defined
   // multi-versioned read above the cutoff timestamp. When users try to read