@nxtedition/rocksdb 8.2.7 → 9.0.0

package/deps/rocksdb/rocksdb/file/random_access_file_reader.cc

@@ -22,12 +22,37 @@
 #include "util/rate_limiter_impl.h"
 
 namespace ROCKSDB_NAMESPACE {
-const std::array<Histograms, std::size_t(Env::IOActivity::kUnknown)>
-    kReadHistograms{{
-        FILE_READ_FLUSH_MICROS,
-        FILE_READ_COMPACTION_MICROS,
-        FILE_READ_DB_OPEN_MICROS,
-    }};
+inline Histograms GetFileReadHistograms(Statistics* stats,
+                                        Env::IOActivity io_activity) {
+  switch (io_activity) {
+    case Env::IOActivity::kFlush:
+      return Histograms::FILE_READ_FLUSH_MICROS;
+    case Env::IOActivity::kCompaction:
+      return Histograms::FILE_READ_COMPACTION_MICROS;
+    case Env::IOActivity::kDBOpen:
+      return Histograms::FILE_READ_DB_OPEN_MICROS;
+    default:
+      break;
+  }
+
+  if (stats && stats->get_stats_level() > StatsLevel::kExceptDetailedTimers) {
+    switch (io_activity) {
+      case Env::IOActivity::kGet:
+        return Histograms::FILE_READ_GET_MICROS;
+      case Env::IOActivity::kMultiGet:
+        return Histograms::FILE_READ_MULTIGET_MICROS;
+      case Env::IOActivity::kDBIterator:
+        return Histograms::FILE_READ_DB_ITERATOR_MICROS;
+      case Env::IOActivity::kVerifyDBChecksum:
+        return Histograms::FILE_READ_VERIFY_DB_CHECKSUM_MICROS;
+      case Env::IOActivity::kVerifyFileChecksums:
+        return Histograms::FILE_READ_VERIFY_FILE_CHECKSUMS_MICROS;
+      default:
+        break;
+    }
+  }
+  return Histograms::HISTOGRAM_ENUM_MAX;
+}
 inline void RecordIOStats(Statistics* stats, Temperature file_temperature,
                           bool is_last_level, size_t size) {
   IOSTATS_ADD(bytes_read, size);
@@ -79,11 +104,11 @@ IOStatus RandomAccessFileReader::Create(
   return io_s;
 }
 
-IOStatus RandomAccessFileReader::Read(
-    const IOOptions& opts, uint64_t offset, size_t n, Slice* result,
-    char* scratch, AlignedBuf* aligned_buf,
-    Env::IOPriority rate_limiter_priority) const {
+IOStatus RandomAccessFileReader::Read(const IOOptions& opts, uint64_t offset,
+                                      size_t n, Slice* result, char* scratch,
+                                      AlignedBuf* aligned_buf) const {
   (void)aligned_buf;
+  const Env::IOPriority rate_limiter_priority = opts.rate_limiter_priority;
 
   TEST_SYNC_POINT_CALLBACK("RandomAccessFileReader::Read", nullptr);
 
@@ -97,17 +122,23 @@ IOStatus RandomAccessFileReader::Read(
 
   IOStatus io_s;
   uint64_t elapsed = 0;
+  size_t alignment = file_->GetRequiredBufferAlignment();
+  bool is_aligned = false;
+  if (scratch != nullptr) {
+    // Check if offset, length and buffer are aligned.
+    is_aligned = (offset & (alignment - 1)) == 0 &&
+                 (n & (alignment - 1)) == 0 &&
+                 (uintptr_t(scratch) & (alignment - 1)) == 0;
+  }
+
   {
     StopWatch sw(clock_, stats_, hist_type_,
-                 (opts.io_activity != Env::IOActivity::kUnknown)
-                     ? kReadHistograms[(std::size_t)(opts.io_activity)]
-                     : Histograms::HISTOGRAM_ENUM_MAX,
+                 GetFileReadHistograms(stats_, opts.io_activity),
                  (stats_ != nullptr) ? &elapsed : nullptr, true /*overwrite*/,
                  true /*delay_enabled*/);
     auto prev_perf_level = GetPerfLevel();
     IOSTATS_TIMER_GUARD(read_nanos);
-    if (use_direct_io()) {
-      size_t alignment = file_->GetRequiredBufferAlignment();
+    if (use_direct_io() && is_aligned == false) {
       size_t aligned_offset =
           TruncateToPageBoundary(alignment, static_cast<size_t>(offset));
       size_t offset_advance = static_cast<size_t>(offset) - aligned_offset;
@@ -182,9 +213,9 @@ IOStatus RandomAccessFileReader::Read(
           if (rate_limiter_->IsRateLimited(RateLimiter::OpType::kRead)) {
             sw.DelayStart();
           }
-          allowed = rate_limiter_->RequestToken(n - pos, 0 /* alignment */,
-                                                rate_limiter_priority, stats_,
-                                                RateLimiter::OpType::kRead);
+          allowed = rate_limiter_->RequestToken(
+              n - pos, (use_direct_io() ? alignment : 0), rate_limiter_priority,
+              stats_, RateLimiter::OpType::kRead);
           if (rate_limiter_->IsRateLimited(RateLimiter::OpType::kRead)) {
             sw.DelayStop();
           }
@@ -269,9 +300,10 @@ bool TryMerge(FSReadRequest* dest, const FSReadRequest& src) {
   return true;
 }
 
-IOStatus RandomAccessFileReader::MultiRead(
-    const IOOptions& opts, FSReadRequest* read_reqs, size_t num_reqs,
-    AlignedBuf* aligned_buf, Env::IOPriority rate_limiter_priority) const {
+IOStatus RandomAccessFileReader::MultiRead(const IOOptions& opts,
+                                           FSReadRequest* read_reqs,
+                                           size_t num_reqs,
+                                           AlignedBuf* aligned_buf) const {
   (void)aligned_buf;  // suppress warning of unused variable in LITE mode
   assert(num_reqs > 0);
 
@@ -280,6 +312,7 @@ IOStatus RandomAccessFileReader::MultiRead(
     assert(read_reqs[i].offset <= read_reqs[i + 1].offset);
   }
 #endif  // !NDEBUG
+  const Env::IOPriority rate_limiter_priority = opts.rate_limiter_priority;
 
   // To be paranoid modify scratch a little bit, so in case underlying
   // FileSystem doesn't fill the buffer but return success and `scratch` returns
@@ -296,9 +329,7 @@ IOStatus RandomAccessFileReader::MultiRead(
   uint64_t elapsed = 0;
   {
     StopWatch sw(clock_, stats_, hist_type_,
-                 (opts.io_activity != Env::IOActivity::kUnknown)
-                     ? kReadHistograms[(std::size_t)(opts.io_activity)]
-                     : Histograms::HISTOGRAM_ENUM_MAX,
+                 GetFileReadHistograms(stats_, opts.io_activity),
                  (stats_ != nullptr) ? &elapsed : nullptr, true /*overwrite*/,
                  true /*delay_enabled*/);
     auto prev_perf_level = GetPerfLevel();
@@ -314,14 +345,14 @@ IOStatus RandomAccessFileReader::MultiRead(
       // Align and merge the read requests.
       size_t alignment = file_->GetRequiredBufferAlignment();
       for (size_t i = 0; i < num_reqs; i++) {
-        const auto& r = Align(read_reqs[i], alignment);
+        FSReadRequest r = Align(read_reqs[i], alignment);
         if (i == 0) {
           // head
-          aligned_reqs.push_back(r);
+          aligned_reqs.push_back(std::move(r));
 
         } else if (!TryMerge(&aligned_reqs.back(), r)) {
           // head + n
-          aligned_reqs.push_back(r);
+          aligned_reqs.push_back(std::move(r));
 
         } else {
           // unused
@@ -487,16 +518,16 @@ IOStatus RandomAccessFileReader::ReadAsync(
 
     assert(read_async_info->buf_.CurrentSize() == 0);
 
-    StopWatch sw(clock_, nullptr /*stats*/,
-                 Histograms::HISTOGRAM_ENUM_MAX /*hist_type*/,
-                 Histograms::HISTOGRAM_ENUM_MAX, &elapsed, true /*overwrite*/,
+    StopWatch sw(clock_, stats_, hist_type_,
+                 GetFileReadHistograms(stats_, opts.io_activity),
+                 (stats_ != nullptr) ? &elapsed : nullptr, true /*overwrite*/,
                  true /*delay_enabled*/);
     s = file_->ReadAsync(aligned_req, opts, read_async_callback,
                          read_async_info, io_handle, del_fn, nullptr /*dbg*/);
   } else {
-    StopWatch sw(clock_, nullptr /*stats*/,
-                 Histograms::HISTOGRAM_ENUM_MAX /*hist_type*/,
-                 Histograms::HISTOGRAM_ENUM_MAX, &elapsed, true /*overwrite*/,
+    StopWatch sw(clock_, stats_, hist_type_,
+                 GetFileReadHistograms(stats_, opts.io_activity),
+                 (stats_ != nullptr) ? &elapsed : nullptr, true /*overwrite*/,
                  true /*delay_enabled*/);
     s = file_->ReadAsync(req, opts, read_async_callback, read_async_info,
                          io_handle, del_fn, nullptr /*dbg*/);

package/deps/rocksdb/rocksdb/file/random_access_file_reader.h

@@ -164,31 +164,18 @@ class RandomAccessFileReader {
   // 2. Otherwise, scratch is not used and can be null, the aligned_buf owns
   // the internally allocated buffer on return, and the result refers to a
   // region in aligned_buf.
-  //
-  // `rate_limiter_priority` is used to charge the internal rate limiter when
-  // enabled. The special value `Env::IO_TOTAL` makes this operation bypass the
-  // rate limiter.
   IOStatus Read(const IOOptions& opts, uint64_t offset, size_t n, Slice* result,
-                char* scratch, AlignedBuf* aligned_buf,
-                Env::IOPriority rate_limiter_priority) const;
+                char* scratch, AlignedBuf* aligned_buf) const;
 
   // REQUIRES:
   // num_reqs > 0, reqs do not overlap, and offsets in reqs are increasing.
   // In non-direct IO mode, aligned_buf should be null;
   // In direct IO mode, aligned_buf stores the aligned buffer allocated inside
   // MultiRead, the result Slices in reqs refer to aligned_buf.
-  //
-  // `rate_limiter_priority` will be used to charge the internal rate limiter.
-  // It is not yet supported so the client must provide the special value
-  // `Env::IO_TOTAL` to bypass the rate limiter.
   IOStatus MultiRead(const IOOptions& opts, FSReadRequest* reqs,
-                     size_t num_reqs, AlignedBuf* aligned_buf,
-                     Env::IOPriority rate_limiter_priority) const;
+                     size_t num_reqs, AlignedBuf* aligned_buf) const;
 
-  IOStatus Prefetch(uint64_t offset, size_t n,
-                    const Env::IOPriority rate_limiter_priority) const {
-    IOOptions opts;
-    opts.rate_limiter_priority = rate_limiter_priority;
+  IOStatus Prefetch(const IOOptions& opts, uint64_t offset, size_t n) const {
     return file_->Prefetch(offset, n, opts, nullptr);
   }
 

package/deps/rocksdb/rocksdb/file/random_access_file_reader_test.cc

@@ -83,8 +83,9 @@ TEST_F(RandomAccessFileReaderTest, ReadDirectIO) {
   Slice result;
   AlignedBuf buf;
   for (Env::IOPriority rate_limiter_priority : {Env::IO_LOW, Env::IO_TOTAL}) {
-    ASSERT_OK(r->Read(IOOptions(), offset, len, &result, nullptr, &buf,
-                      rate_limiter_priority));
+    IOOptions io_opts;
+    io_opts.rate_limiter_priority = rate_limiter_priority;
+    ASSERT_OK(r->Read(io_opts, offset, len, &result, nullptr, &buf));
     ASSERT_EQ(result.ToString(), content.substr(offset, len));
   }
 }
@@ -95,7 +96,18 @@ TEST_F(RandomAccessFileReaderTest, MultiReadDirectIO) {
       "RandomAccessFileReader::MultiRead:AlignedReqs", [&](void* reqs) {
         // Copy reqs, since it's allocated on stack inside MultiRead, which will
         // be deallocated after MultiRead returns.
-        aligned_reqs = *reinterpret_cast<std::vector<FSReadRequest>*>(reqs);
+        size_t i = 0;
+        aligned_reqs.resize(
+            (*reinterpret_cast<std::vector<FSReadRequest>*>(reqs)).size());
+        for (auto& req :
+             (*reinterpret_cast<std::vector<FSReadRequest>*>(reqs))) {
+          aligned_reqs[i].offset = req.offset;
+          aligned_reqs[i].len = req.len;
+          aligned_reqs[i].result = req.result;
+          aligned_reqs[i].status = req.status;
+          aligned_reqs[i].scratch = req.scratch;
+          i++;
+        }
       });
   ROCKSDB_NAMESPACE::SyncPoint::GetInstance()->EnableProcessing();
 
@@ -135,8 +147,8 @@ TEST_F(RandomAccessFileReaderTest, MultiReadDirectIO) {
     reqs.push_back(std::move(r0));
     reqs.push_back(std::move(r1));
     AlignedBuf aligned_buf;
-    ASSERT_OK(r->MultiRead(IOOptions(), reqs.data(), reqs.size(), &aligned_buf,
-                           Env::IO_TOTAL /* rate_limiter_priority */));
+    ASSERT_OK(
+        r->MultiRead(IOOptions(), reqs.data(), reqs.size(), &aligned_buf));
 
     AssertResult(content, reqs);
 
@@ -180,8 +192,8 @@ TEST_F(RandomAccessFileReaderTest, MultiReadDirectIO) {
     reqs.push_back(std::move(r1));
     reqs.push_back(std::move(r2));
     AlignedBuf aligned_buf;
-    ASSERT_OK(r->MultiRead(IOOptions(), reqs.data(), reqs.size(), &aligned_buf,
-                           Env::IO_TOTAL /* rate_limiter_priority */));
+    ASSERT_OK(
+        r->MultiRead(IOOptions(), reqs.data(), reqs.size(), &aligned_buf));
 
     AssertResult(content, reqs);
 
@@ -225,8 +237,8 @@ TEST_F(RandomAccessFileReaderTest, MultiReadDirectIO) {
     reqs.push_back(std::move(r1));
     reqs.push_back(std::move(r2));
     AlignedBuf aligned_buf;
-    ASSERT_OK(r->MultiRead(IOOptions(), reqs.data(), reqs.size(), &aligned_buf,
-                           Env::IO_TOTAL /* rate_limiter_priority */));
+    ASSERT_OK(
+        r->MultiRead(IOOptions(), reqs.data(), reqs.size(), &aligned_buf));
 
     AssertResult(content, reqs);
 
@@ -262,8 +274,8 @@ TEST_F(RandomAccessFileReaderTest, MultiReadDirectIO) {
     reqs.push_back(std::move(r0));
     reqs.push_back(std::move(r1));
     AlignedBuf aligned_buf;
-    ASSERT_OK(r->MultiRead(IOOptions(), reqs.data(), reqs.size(), &aligned_buf,
-                           Env::IO_TOTAL /* rate_limiter_priority */));
+    ASSERT_OK(
+        r->MultiRead(IOOptions(), reqs.data(), reqs.size(), &aligned_buf));
 
     AssertResult(content, reqs);
 
@@ -283,7 +295,6 @@ TEST_F(RandomAccessFileReaderTest, MultiReadDirectIO) {
   ROCKSDB_NAMESPACE::SyncPoint::GetInstance()->ClearAllCallBacks();
 }
 
-
 TEST(FSReadRequest, Align) {
   FSReadRequest r;
   r.offset = 2000;

package/deps/rocksdb/rocksdb/file/sequence_file_reader.h

@@ -99,6 +99,9 @@ class SequentialFileReader {
   // when less than n bytes are actually read (e.g. at end of file). To avoid
   // overcharging the rate limiter, the caller can use file size to cap n to
   // read until end of file.
+  //
+  // TODO(hx235): accept parameter `IOOptions` containing
+  // `rate_limiter_priority` like RandomAccessFileReader::Read()
   IOStatus Read(size_t n, Slice* result, char* scratch,
                 Env::IOPriority rate_limiter_priority);
 

package/deps/rocksdb/rocksdb/include/rocksdb/advanced_cache.h

@@ -514,7 +514,8 @@ class Cache {
   // returns `true` if it has taken ownership of the Value (object), or
   // `false` if the cache should destroy it as usual. Regardless, Ref() and
   // Release() cannot be called on this Handle that is poised for eviction.
-  using EvictionCallback = std::function<bool(const Slice& key, Handle* h)>;
+  using EvictionCallback =
+      std::function<bool(const Slice& key, Handle* h, bool was_hit)>;
   // Sets an eviction callback for this Cache. Not thread safe and only
   // supports being set once, so should only be used during initialization
   // or destruction, guaranteed before or after any thread-shared operations.

package/deps/rocksdb/rocksdb/include/rocksdb/advanced_options.h

@@ -181,6 +181,14 @@ struct CompressionOptions {
   // compressed by less than 12.5% (minimum ratio of 1.143:1).
   int max_compressed_bytes_per_kb = 1024 * 7 / 8;
 
+  // ZSTD only.
+  // Enable compression algorithm's checksum feature.
+  // (https://github.com/facebook/zstd/blob/d857369028d997c92ff1f1861a4d7f679a125464/lib/zstd.h#L428)
+  // Each compressed frame will have a 32-bit checksum attached. The checksum
+  // computed from the uncompressed data and can be verified during
+  // decompression.
+  bool checksum = false;
+
   // A convenience function for setting max_compressed_bytes_per_kb based on a
   // minimum acceptable compression ratio (uncompressed size over compressed
   // size).
@@ -600,11 +608,11 @@ struct AdvancedColumnFamilyOptions {
   // 1. target size is in the range of
   //   (max_bytes_for_level_base / max_bytes_for_level_multiplier,
   //    max_bytes_for_level_base]
-  // 2. target size of the last level (level num_levels-1) equals to extra size
-  //    of the level.
-  // At the same time max_bytes_for_level_multiplier and
-  // max_bytes_for_level_multiplier_additional are still satisfied.
-  // (When L0 is too large, we make some adjustment. See below.)
+  // 2. target size of the last level (level num_levels-1) equals to the max
+  //    size of a level in the LSM (typically the last level).
+  // At the same time max_bytes_for_level_multiplier is still satisfied.
+  // Note that max_bytes_for_level_multiplier_additional is ignored with this
+  // flag on.
   //
   // With this option on, from an empty DB, we make last level the base level,
   // which means merging L0 data into the last level, until it exceeds
@@ -642,60 +650,37 @@ struct AdvancedColumnFamilyOptions {
   // By doing it, we give max_bytes_for_level_multiplier a priority against
   // max_bytes_for_level_base, for a more predictable LSM tree shape. It is
   // useful to limit worse case space amplification.
-  //
-  //
-  // If the compaction from L0 is lagged behind, a special mode will be turned
-  // on to prioritize write amplification against max_bytes_for_level_multiplier
-  // or max_bytes_for_level_base. The L0 compaction is lagged behind by looking
-  // at number of L0 files and total L0 size. If number of L0 files is at least
-  // the double of level0_file_num_compaction_trigger, or the total size is
-  // at least max_bytes_for_level_base, this mode is on. The target of L1 grows
-  // to the actual data size in L0, and then determine the target for each level
-  // so that each level will have the same level multiplier.
-  //
-  // For example, when L0 size is 100MB, the size of last level is 1600MB,
-  // max_bytes_for_level_base = 80MB, and max_bytes_for_level_multiplier = 10.
-  // Since L0 size is larger than max_bytes_for_level_base, this is a L0
-  // compaction backlogged mode. So that the L1 size is determined to be 100MB.
-  // Based on max_bytes_for_level_multiplier = 10, at least 3 non-0 levels will
-  // be needed. The level multiplier will be calculated to be 4 and the three
-  // levels' target to be [100MB, 400MB, 1600MB].
-  //
-  // In this mode, The number of levels will be no more than the normal mode,
-  // and the level multiplier will be lower. The write amplification will
-  // likely to be reduced.
-  //
-  //
-  // max_bytes_for_level_multiplier_additional is ignored with this flag on.
-  //
-  // To make the migration easier, when turning this feature on, files in the
-  // LSM will be trivially moved down to fill the LSM starting from the
-  // bottommost level during DB open. For example, if the LSM looks like:
-  // L0: f0, f1
-  // L1: f2, f3
-  // L2: f4
-  // L3:
-  // L4: f5
-  // and the DB is opened with num_levels = 7 with this feature turned on,
-  // new LSM after DB open looks like the following:
-  // L0: f0, f1, (and possibly data flushed from WAL)
-  // L4: f2, f3
-  // L5: f4
-  // L6: f5
-  //
   // If `allow_ingest_behind=true` or `preclude_last_level_data_seconds > 0`,
   // then the last level is reserved, and we will start filling LSM from the
-  // second last level (L5 in the above example).
+  // second last level.
+  //
+  // With this option on, compaction is more adaptive to write traffic:
+  // Compaction priority will take into account estimated bytes to be compacted
+  // down to a level and favors compacting lower levels when there is a write
+  // traffic spike (and hence more compaction debt). Refer to
+  // https://github.com/facebook/rocksdb/wiki/Leveled-Compactio#option-level_compaction_dynamic_level_bytes-and-levels-target-size
+  // for more detailed description. See more implementation detail in:
+  // VersionStorageInfo::ComputeCompactionScore().
   //
+  // With this option on, unneeded levels will be drained automatically:
   // Note that there may be excessive levels (where target level size is 0 when
-  // computed based on this feature) in the LSM after a user migrates to turn
-  // this feature on. This is especially likely when a user migrates from
-  // leveled compaction with a smaller multiplier or from universal compaction.
-  // RocksDB will gradually drain these unnecessary levels by compacting files
-  // down the LSM.
+  // computed based on this feature) in the LSM. This can happen after a user
+  // migrates to turn this feature on or deletes a lot of data. This is
+  // especially likely when a user migrates from leveled compaction with a
+  // smaller multiplier or from universal compaction. RocksDB will gradually
+  // drain these unnecessary levels by compacting files down the LSM. Smaller
+  // number of levels should help to reduce read amplification.
+  //
+  // Migration to turn on this option:
+  // - Before RocksDB v8.2, users are expected to do a full manual compaction
+  //   and then restart DB to turn on this option.
+  // - Since RocksDB v8.2, users can just restart DB with this option on, as
+  //   long as num_levels is no smaller than number of non-empty levels in the
+  //   LSM. Migration will be done automatically by RocksDB. See more in
+  //   https://github.com/facebook/rocksdb/wiki/Leveled-Compaction#migrating-from-level_compaction_dynamic_level_bytesfalse-to-level_compaction_dynamic_level_bytestrue
   //
-  // Default: false
-  bool level_compaction_dynamic_level_bytes = false;
+  // Default: true
+  bool level_compaction_dynamic_level_bytes = true;
 
   // Allows RocksDB to generate files that are not exactly the target_file_size
   // only for the non-bottommost files. Which can reduce the write-amplification
@@ -714,6 +699,8 @@ struct AdvancedColumnFamilyOptions {
   // Different max-size multipliers for different levels.
   // These are multiplied by max_bytes_for_level_multiplier to arrive
   // at the max-size of each level.
+  // This option only applies to leveled compaction with
+  // `level_compaction_dynamic_level_bytes = false`.
   //
   // Default: 1
   //
@@ -879,30 +866,60 @@ struct AdvancedColumnFamilyOptions {
   // Dynamically changeable through SetOptions() API
   bool report_bg_io_stats = false;
 
-  // Files containing updates older than TTL will go through the compaction
-  // process. This usually happens in a cascading way so that those entries
-  // will be compacted to bottommost level/file.
-  // The feature is used to remove stale entries that have been deleted or
-  // updated from the file system.
-  // Pre-req: This needs max_open_files to be set to -1.
-  // In Level: Non-bottom-level files older than TTL will go through the
-  //           compaction process.
-  // In FIFO: Files older than TTL will be deleted.
+  // This option has different meanings for different compaction styles:
+  //
+  // Leveled: Non-bottom-level files with all keys older than TTL will go
+  //    through the compaction process. This usually happens in a cascading
+  //    way so that those entries will be compacted to bottommost level/file.
+  //    The feature is used to remove stale entries that have been deleted or
+  //    updated from the file system.
+  //
+  // FIFO: Files with all keys older than TTL will be deleted. TTL is only
+  //    supported if option max_open_files is set to -1.
+  //
+  // Universal: users should only set the option `periodic_compaction_seconds`
+  //    below instead. For backward compatibility, this option has the same
+  //    meaning as `periodic_compaction_seconds`. See more in comments for
+  //    `periodic_compaction_seconds` on the interaction between these two
+  //    options.
+  //
+  // This option only supports block based table format for any compaction
+  // style.
+  //
   // unit: seconds. Ex: 1 day = 1 * 24 * 60 * 60
-  // In FIFO, this option will have the same meaning as
-  // periodic_compaction_seconds. Whichever stricter will be used.
   // 0 means disabling.
   // UINT64_MAX - 1 (0xfffffffffffffffe) is special flag to allow RocksDB to
   // pick default.
   //
-  // Default: 30 days for leveled compaction + block based table. disable
-  //          otherwise.
+  // Default: 30 days if using block based table. 0 (disable) otherwise.
   //
   // Dynamically changeable through SetOptions() API
+  // Note that dynamically changing this option only works for leveled and FIFO
+  // compaction. For universal compaction, dynamically changing this option has
+  // no effect, users should dynamically change `periodic_compaction_seconds`
+  // instead.
   uint64_t ttl = 0xfffffffffffffffe;
 
-  // Files older than this value will be picked up for compaction, and
-  // re-written to the same level as they were before.
+  // This option has different meanings for different compaction styles:
+  //
+  // Leveled: files older than `periodic_compaction_seconds` will be picked up
+  //    for compaction and will be re-written to the same level as they were
+  //    before.
+  //
+  // FIFO: not supported. Setting this option has no effect for FIFO compaction.
+  //
+  // Universal: when there are files older than `periodic_compaction_seconds`,
+  //    rocksdb will try to do as large a compaction as possible including the
+  //    last level. Such compaction is only skipped if only last level is to
+  //    be compacted and no file in last level is older than
+  //    `periodic_compaction_seconds`. See more in
+  //    UniversalCompactionBuilder::PickPeriodicCompaction().
+  //    For backward compatibility, the effective value of this option takes
+  //    into account the value of option `ttl`. The logic is as follows:
+  //    - both options are set to 30 days if they have the default value.
+  //    - if both options are zero, zero is picked. Otherwise, we take the min
+  //    value among non-zero options values (i.e. takes the stricter limit).
+  //
   // One main use of the feature is to make sure a file goes through compaction
   // filters periodically. Users can also use the feature to clear up SST
   // files using old format.
@@ -912,25 +929,19 @@ struct AdvancedColumnFamilyOptions {
   // age is based on the file's last modified time (given by the underlying
   // Env).
   //
-  // Supported in all compaction styles.
-  // In Universal compaction, rocksdb will try to do a full compaction when
-  // possible, see more in UniversalCompactionBuilder::PickPeriodicCompaction().
-  // In FIFO compaction, this option has the same meaning as TTL and whichever
-  // stricter will be used.
-  // Pre-req: max_open_file == -1.
+  // This option only supports block based table format for any compaction
+  // style.
+  //
   // unit: seconds. Ex: 7 days = 7 * 24 * 60 * 60
   //
   // Values:
   // 0: Turn off Periodic compactions.
-  // UINT64_MAX - 1 (i.e 0xfffffffffffffffe): Let RocksDB control this feature
-  //     as needed. For now, RocksDB will change this value to 30 days
-  //     (i.e 30 * 24 * 60 * 60) so that every file goes through the compaction
-  //     process at least once every 30 days if not compacted sooner.
-  //     In FIFO compaction, since the option has the same meaning as ttl,
-  //     when this value is left default, and ttl is left to 0, 30 days will be
-  //     used. Otherwise, min(ttl, periodic_compaction_seconds) will be used.
+  // UINT64_MAX - 1 (0xfffffffffffffffe) is special flag to allow RocksDB to
+  // pick default.
   //
-  // Default: UINT64_MAX - 1 (allow RocksDB to auto-tune)
+  // Default: 30 days if using block based table format + compaction filter +
+  //  leveled compaction or block based table format + universal compaction.
+  //  0 (disabled) otherwise.
   //
   // Dynamically changeable through SetOptions() API
   uint64_t periodic_compaction_seconds = 0xfffffffffffffffe;
@@ -957,6 +968,14 @@ struct AdvancedColumnFamilyOptions {
   Temperature bottommost_temperature = Temperature::kUnknown;
   Temperature last_level_temperature = Temperature::kUnknown;
 
+  // EXPERIMENTAL
+  // When this field is set, all SST files without an explicitly set temperature
+  // will be treated as if they have this temperature for file reading
+  // accounting purpose, such as io statistics, io perf context.
+  //
+  // Not dynamically changeable, change it requires db restart.
+  Temperature default_temperature = Temperature::kUnknown;
+
   // EXPERIMENTAL
   // The feature is still in development and is incomplete.
   // If this option is set, when data insert time is within this time range, it
@@ -1133,6 +1152,7 @@ struct AdvancedColumnFamilyOptions {
   //
   // Default: 0 (no protection)
   // Supported values: 0, 1, 2, 4, 8.
+  // Dynamically changeable through the SetOptions() API.
   uint32_t memtable_protection_bytes_per_key = 0;
 
   // UNDER CONSTRUCTION -- DO NOT USE
@@ -1141,11 +1161,43 @@ struct AdvancedColumnFamilyOptions {
   //
   // When it's false, the user-defined timestamps will be removed from the user
   // keys when data is flushed from memtables to SST files. Other places that
-  // user keys can be persisted like WAL and blob files go through a similar
-  // process. Users should call `DB::IncreaseFullHistoryTsLow` to set a cutoff
-  // timestamp. RocksDB refrains from flushing a memtable with data still above
-  // the cutoff timestamp with best effort. When users try to read below the
-  // cutoff timestamp, an error will be returned.
+  // user keys can be persisted like file boundaries in file metadata and blob
+  // files go through a similar process. There are two major motivations
+  // for this flag:
+  // 1) backward compatibility: if the user later decides to
+  // disable the user-defined timestamp feature for the column family, these SST
+  // files can be handled by a user comparator that is not aware of user-defined
+  // timestamps.
+  // 2) enable user-defined timestamp feature for an existing column family
+  // while set this flag to be `false`: user keys in the newly generated SST
+  // files are of the same format as the existing SST files.
+  //
+  // Currently only user comparator that formats user-defined timesamps as
+  // uint64_t via using one of the RocksDB provided comparator
+  // `ComparatorWithU64TsImpl` are supported.
+  //
+  // 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.
+  // NOTE: in order for the cutoff timestamp to work properly, users of this
+  // feature need to ensure to write to a column family with globally
+  // non-decreasing user-defined timestamps.
+  //
+  // Users can do user-defined
+  // multi-versioned read above the cutoff timestamp. When users try to read
+  // below the cutoff timestamp, an error will be returned.
+  //
+  // Note that if WAL is enabled, unlike SST files, user-defined timestamps are
+  // persisted to WAL even if this flag is set to `false`. The benefit of this
+  // is that user-defined timestamps can be recovered with the caveat that users
+  // should flush all memtables so there is no active WAL files before doing a
+  // downgrade.
+  //
+  // Note that setting this flag to false is not supported in combination with
+  // atomic flush, or concurrent memtable write enabled by
+  // `allow_concurrent_memtable_write`.
   //
   // Default: true (user-defined timestamps are persisted)
   // Not dynamically changeable, change it requires db restart and
@@ -1164,8 +1216,21 @@ struct AdvancedColumnFamilyOptions {
   //
   // Default: 0 (no protection)
   // Supported values: 0, 1, 2, 4, 8.
+  // Dynamically changeable through the SetOptions() API.
   uint8_t block_protection_bytes_per_key = 0;
 
+  // For leveled compaction, RocksDB may compact a file at the bottommost level
+  // if it can compact away data that were protected by some snapshot.
+  // The compaction reason in LOG for this kind of compactions is
+  // "BottommostFiles". Usually such compaction can happen as soon as a
+  // relevant snapshot is released. This option allows user to delay
+  // such compactions. A file is qualified for "BottommostFiles" compaction
+  // if it is at least "bottommost_file_compaction_delay" seconds old.
+  //
+  // Default: 0 (no delay)
+  // Dynamically changeable through the SetOptions() API.
+  uint32_t bottommost_file_compaction_delay = 0;
+
   // Create ColumnFamilyOptions with default values for all fields
   AdvancedColumnFamilyOptions();
   // Create ColumnFamilyOptions from Options