@nxtedition/rocksdb 8.2.0 → 8.2.2

package/deps/rocksdb/rocksdb/include/rocksdb/memory_allocator.h

@@ -55,6 +55,11 @@ struct JemallocAllocatorOptions {
   // Upper bound of allocation size to use tcache, if limit_tcache_size=true.
   // When used with block cache, it is recommended to set it to block_size.
   size_t tcache_size_upper_bound = 16 * 1024;
+
+  // Number of arenas across which we spread allocation requests. Increasing
+  // this setting can mitigate arena mutex contention. The value must be
+  // positive.
+  size_t num_arenas = 1;
 };
 
 // Generate memory allocator which allocates through Jemalloc and utilize
@@ -70,7 +75,8 @@ struct JemallocAllocatorOptions {
 // core dump. Side benefit of using single arena would be reduction of jemalloc
 // metadata for some workloads.
 //
-// To mitigate mutex contention for using one single arena, jemalloc tcache
+// To mitigate mutex contention for using one single arena (see also
+// `JemallocAllocatorOptions::num_arenas` above), jemalloc tcache
 // (thread-local cache) is enabled to cache unused allocations for future use.
 // The tcache normally incurs 0.5M extra memory usage per-thread. The usage
 // can be reduced by limiting allocation sizes to cache.

package/deps/rocksdb/rocksdb/include/rocksdb/options.h

@@ -1157,7 +1157,7 @@ struct DBOptions {
 
   // A global cache for table-level rows.
   // Default: nullptr (disabled)
-  std::shared_ptr<Cache> row_cache = nullptr;
+  std::shared_ptr<GeneralCache> row_cache = nullptr;
 
   // A filter object supplied to be invoked while processing write-ahead-logs
   // (WALs) during recovery. The filter provides a way to inspect log
@@ -1457,12 +1457,119 @@ enum ReadTier {
 
 // Options that control read operations
 struct ReadOptions {
+  // *** BEGIN options relevant to point lookups as well as scans ***
+
   // If "snapshot" is non-nullptr, read as of the supplied snapshot
   // (which must belong to the DB that is being read and which must
   // not have been released).  If "snapshot" is nullptr, use an implicit
   // snapshot of the state at the beginning of this read operation.
-  // Default: nullptr
-  const Snapshot* snapshot;
+  const Snapshot* snapshot = nullptr;
+
+  // Timestamp of operation. Read should return the latest data visible to the
+  // specified timestamp. All timestamps of the same database must be of the
+  // same length and format. The user is responsible for providing a customized
+  // compare function via Comparator to order <key, timestamp> tuples.
+  // For iterator, iter_start_ts is the lower bound (older) and timestamp
+  // serves as the upper bound. Versions of the same record that fall in
+  // the timestamp range will be returned. If iter_start_ts is nullptr,
+  // only the most recent version visible to timestamp is returned.
+  // The user-specified timestamp feature is still under active development,
+  // and the API is subject to change.
+  const Slice* timestamp = nullptr;
+  const Slice* iter_start_ts = nullptr;
+
+  // Deadline for completing an API call (Get/MultiGet/Seek/Next for now)
+  // in microseconds.
+  // It should be set to microseconds since epoch, i.e, gettimeofday or
+  // equivalent plus allowed duration in microseconds. The best way is to use
+  // env->NowMicros() + some timeout.
+  // This is best efforts. The call may exceed the deadline if there is IO
+  // involved and the file system doesn't support deadlines, or due to
+  // checking for deadline periodically rather than for every key if
+  // processing a batch
+  std::chrono::microseconds deadline = std::chrono::microseconds::zero();
+
+  // A timeout in microseconds to be passed to the underlying FileSystem for
+  // reads. As opposed to deadline, this determines the timeout for each
+  // individual file read request. If a MultiGet/Get/Seek/Next etc call
+  // results in multiple reads, each read can last up to io_timeout us.
+  std::chrono::microseconds io_timeout = std::chrono::microseconds::zero();
+
+  // Specify if this read request should process data that ALREADY
+  // resides on a particular cache. If the required data is not
+  // found at the specified cache, then Status::Incomplete is returned.
+  ReadTier read_tier = kReadAllTier;
+
+  // For file reads associated with this option, charge the internal rate
+  // limiter (see `DBOptions::rate_limiter`) at the specified priority. The
+  // special value `Env::IO_TOTAL` disables charging the rate limiter.
+  //
+  // The rate limiting is bypassed no matter this option's value for file reads
+  // on plain tables (these can exist when `ColumnFamilyOptions::table_factory`
+  // is a `PlainTableFactory`) and cuckoo tables (these can exist when
+  // `ColumnFamilyOptions::table_factory` is a `CuckooTableFactory`).
+  //
+  // The bytes charged to rate limiter may not exactly match the file read bytes
+  // since there are some seemingly insignificant reads, like for file
+  // headers/footers, that we currently do not charge to rate limiter.
+  Env::IOPriority rate_limiter_priority = Env::IO_TOTAL;
+
+  // It limits the maximum cumulative value size of the keys in batch while
+  // reading through MultiGet. Once the cumulative value size exceeds this
+  // soft limit then all the remaining keys are returned with status Aborted.
+  uint64_t value_size_soft_limit = std::numeric_limits<uint64_t>::max();
+
+  // If true, all data read from underlying storage will be
+  // verified against corresponding checksums.
+  bool verify_checksums = true;
+
+  // Should the "data block"/"index block" read for this iteration be placed in
+  // block cache?
+  // Callers may wish to set this field to false for bulk scans.
+  // This would help not to the change eviction order of existing items in the
+  // block cache.
+  bool fill_cache = true;
+
+  // If true, range tombstones handling will be skipped in key lookup paths.
+  // For DB instances that don't use DeleteRange() calls, this setting can
+  // be used to optimize the read performance.
+  // Note that, if this assumption (of no previous DeleteRange() calls) is
+  // broken, stale keys could be served in read paths.
+  bool ignore_range_deletions = false;
+
+  // Experimental
+  //
+  // If async_io is enabled, RocksDB will prefetch some of data asynchronously.
+  // RocksDB apply it if reads are sequential and its internal automatic
+  // prefetching.
+  bool async_io = false;
+
+  // Experimental
+  //
+  // If async_io is set, then this flag controls whether we read SST files
+  // in multiple levels asynchronously. Enabling this flag can help reduce
+  // MultiGet latency by maximizing the number of SST files read in
+  // parallel if the keys in the MultiGet batch are in different levels. It
+  // comes at the expense of slightly higher CPU overhead.
+  bool optimize_multiget_for_io = true;
+
+  // *** END options relevant to point lookups (as well as scans) ***
+  // *** BEGIN options only relevant to iterators or scans ***
+
+  // RocksDB does auto-readahead for iterators on noticing more than two reads
+  // for a table file. The readahead starts at 8KB and doubles on every
+  // additional read up to 256KB.
+  // This option can help if most of the range scans are large, and if it is
+  // determined that a larger readahead than that enabled by auto-readahead is
+  // needed.
+  // Using a large readahead size (> 2MB) can typically improve the performance
+  // of forward iteration on spinning disks.
+  size_t readahead_size = 0;
+
+  // A threshold for the number of keys that can be skipped before failing an
+  // iterator seek as incomplete. The default value of 0 should be used to
+  // never fail a request as incomplete, even on skipping too many keys.
+  uint64_t max_skippable_internal_keys = 0;
 
   // `iterate_lower_bound` defines the smallest key at which the backward
   // iterator can return an entry. Once the bound is passed, Valid() will be
@@ -1475,8 +1582,7 @@ struct ReadOptions {
   //
   // In case of user_defined timestamp, if enabled, iterate_lower_bound should
   // point to key without timestamp part.
-  // Default: nullptr
-  const Slice* iterate_lower_bound;
+  const Slice* iterate_lower_bound = nullptr;
 
   // "iterate_upper_bound" defines the extent up to which the forward iterator
   // can return entries. Once the bound is reached, Valid() will be false.
@@ -1496,63 +1602,24 @@ struct ReadOptions {
   //
   // In case of user_defined timestamp, if enabled, iterate_upper_bound should
   // point to key without timestamp part.
-  // Default: nullptr
-  const Slice* iterate_upper_bound;
-
-  // RocksDB does auto-readahead for iterators on noticing more than two reads
-  // for a table file. The readahead starts at 8KB and doubles on every
-  // additional read up to 256KB.
-  // This option can help if most of the range scans are large, and if it is
-  // determined that a larger readahead than that enabled by auto-readahead is
-  // needed.
-  // Using a large readahead size (> 2MB) can typically improve the performance
-  // of forward iteration on spinning disks.
-  // Default: 0
-  size_t readahead_size;
-
-  // A threshold for the number of keys that can be skipped before failing an
-  // iterator seek as incomplete. The default value of 0 should be used to
-  // never fail a request as incomplete, even on skipping too many keys.
-  // Default: 0
-  uint64_t max_skippable_internal_keys;
-
-  // Specify if this read request should process data that ALREADY
-  // resides on a particular cache. If the required data is not
-  // found at the specified cache, then Status::Incomplete is returned.
-  // Default: kReadAllTier
-  ReadTier read_tier;
-
-  // If true, all data read from underlying storage will be
-  // verified against corresponding checksums.
-  // Default: true
-  bool verify_checksums;
-
-  // Should the "data block"/"index block" read for this iteration be placed in
-  // block cache?
-  // Callers may wish to set this field to false for bulk scans.
-  // This would help not to the change eviction order of existing items in the
-  // block cache.
-  // Default: true
-  bool fill_cache;
+  const Slice* iterate_upper_bound = nullptr;
 
   // Specify to create a tailing iterator -- a special iterator that has a
   // view of the complete database (i.e. it can also be used to read newly
   // added data) and is optimized for sequential reads. It will return records
   // that were inserted into the database after the creation of the iterator.
-  // Default: false
-  bool tailing;
+  bool tailing = false;
 
   // This options is not used anymore. It was to turn on a functionality that
-  // has been removed.
-  bool managed;
+  // has been removed. DEPRECATED
+  bool managed = false;
 
   // Enable a total order seek regardless of index format (e.g. hash index)
   // used in the table. Some table format (e.g. plain table) may not support
   // this option.
   // If true when calling Get(), we also skip prefix bloom when reading from
   // block based table, which only affects Get() performance.
-  // Default: false
-  bool total_order_seek;
+  bool total_order_seek = false;
 
   // When true, by default use total_order_seek = true, and RocksDB can
   // selectively enable prefix seek mode if won't generate a different result
@@ -1568,38 +1635,37 @@ struct ReadOptions {
   // iterators. (We are also assuming the new condition on
   // IsSameLengthImmediateSuccessor is satisfied; see its BUG section).
   // A bug example is in DBTest2::AutoPrefixMode1, search for "BUG".
-  // Default: false
-  bool auto_prefix_mode;
+  bool auto_prefix_mode = false;
 
   // Enforce that the iterator only iterates over the same prefix as the seek.
   // This option is effective only for prefix seeks, i.e. prefix_extractor is
   // non-null for the column family and total_order_seek is false.  Unlike
   // iterate_upper_bound, prefix_same_as_start only works within a prefix
   // but in both directions.
-  // Default: false
-  bool prefix_same_as_start;
+  bool prefix_same_as_start = false;
 
   // Keep the blocks loaded by the iterator pinned in memory as long as the
   // iterator is not deleted, If used when reading from tables created with
   // BlockBasedTableOptions::use_delta_encoding = false,
   // Iterator's property "rocksdb.iterator.is-key-pinned" is guaranteed to
   // return 1.
-  // Default: false
-  bool pin_data;
+  bool pin_data = false;
+
+  // For iterators, RocksDB does auto-readahead on noticing more than two
+  // sequential reads for a table file if user doesn't provide readahead_size.
+  // The readahead starts at 8KB and doubles on every additional read upto
+  // max_auto_readahead_size only when reads are sequential. However at each
+  // level, if iterator moves over next file, readahead_size starts again from
+  // 8KB.
+  //
+  // By enabling this option, RocksDB will do some enhancements for
+  // prefetching the data.
+  bool adaptive_readahead = false;
 
   // If true, when PurgeObsoleteFile is called in CleanupIteratorState, we
   // schedule a background job in the flush job queue and delete obsolete files
   // in background.
-  // Default: false
-  bool background_purge_on_iterator_cleanup;
-
-  // If true, range tombstones handling will be skipped in key lookup paths.
-  // For DB instances that don't use DeleteRange() calls, this setting can
-  // be used to optimize the read performance.
-  // Note that, if this assumption (of no previous DeleteRange() calls) is
-  // broken, stale keys could be served in read paths.
-  // Default: false
-  bool ignore_range_deletions;
+  bool background_purge_on_iterator_cleanup = false;
 
   // A callback to determine whether relevant keys for this scan exist in a
   // given table based on the table's properties. The callback is passed the
@@ -1609,95 +1675,14 @@ struct ReadOptions {
   // Default: empty (every table will be scanned)
   std::function<bool(const TableProperties&)> table_filter;
 
-  // Timestamp of operation. Read should return the latest data visible to the
-  // specified timestamp. All timestamps of the same database must be of the
-  // same length and format. The user is responsible for providing a customized
-  // compare function via Comparator to order <key, timestamp> tuples.
-  // For iterator, iter_start_ts is the lower bound (older) and timestamp
-  // serves as the upper bound. Versions of the same record that fall in
-  // the timestamp range will be returned. If iter_start_ts is nullptr,
-  // only the most recent version visible to timestamp is returned.
-  // The user-specified timestamp feature is still under active development,
-  // and the API is subject to change.
-  // Default: nullptr
-  const Slice* timestamp;
-  const Slice* iter_start_ts;
+  // *** END options only relevant to iterators or scans ***
 
-  // Deadline for completing an API call (Get/MultiGet/Seek/Next for now)
-  // in microseconds.
-  // It should be set to microseconds since epoch, i.e, gettimeofday or
-  // equivalent plus allowed duration in microseconds. The best way is to use
-  // env->NowMicros() + some timeout.
-  // This is best efforts. The call may exceed the deadline if there is IO
-  // involved and the file system doesn't support deadlines, or due to
-  // checking for deadline periodically rather than for every key if
-  // processing a batch
-  std::chrono::microseconds deadline;
-
-  // A timeout in microseconds to be passed to the underlying FileSystem for
-  // reads. As opposed to deadline, this determines the timeout for each
-  // individual file read request. If a MultiGet/Get/Seek/Next etc call
-  // results in multiple reads, each read can last up to io_timeout us.
-  std::chrono::microseconds io_timeout;
-
-  // It limits the maximum cumulative value size of the keys in batch while
-  // reading through MultiGet. Once the cumulative value size exceeds this
-  // soft limit then all the remaining keys are returned with status Aborted.
-  //
-  // Default: std::numeric_limits<uint64_t>::max()
-  uint64_t value_size_soft_limit;
-
-  // For iterators, RocksDB does auto-readahead on noticing more than two
-  // sequential reads for a table file if user doesn't provide readahead_size.
-  // The readahead starts at 8KB and doubles on every additional read upto
-  // max_auto_readahead_size only when reads are sequential. However at each
-  // level, if iterator moves over next file, readahead_size starts again from
-  // 8KB.
-  //
-  // By enabling this option, RocksDB will do some enhancements for
-  // prefetching the data.
-  //
-  // Default: false
-  bool adaptive_readahead;
-
-  // For file reads associated with this option, charge the internal rate
-  // limiter (see `DBOptions::rate_limiter`) at the specified priority. The
-  // special value `Env::IO_TOTAL` disables charging the rate limiter.
-  //
-  // The rate limiting is bypassed no matter this option's value for file reads
-  // on plain tables (these can exist when `ColumnFamilyOptions::table_factory`
-  // is a `PlainTableFactory`) and cuckoo tables (these can exist when
-  // `ColumnFamilyOptions::table_factory` is a `CuckooTableFactory`).
-  //
-  // The bytes charged to rate limiter may not exactly match the file read bytes
-  // since there are some seemingly insignificant reads, like for file
-  // headers/footers, that we currently do not charge to rate limiter.
-  //
-  // Default: `Env::IO_TOTAL`.
-  Env::IOPriority rate_limiter_priority = Env::IO_TOTAL;
-
-  // Experimental
-  //
-  // If async_io is enabled, RocksDB will prefetch some of data asynchronously.
-  // RocksDB apply it if reads are sequential and its internal automatic
-  // prefetching.
-  //
-  // Default: false
-  bool async_io;
-
-  // Experimental
-  //
-  // If async_io is set, then this flag controls whether we read SST files
-  // in multiple levels asynchronously. Enabling this flag can help reduce
-  // MultiGet latency by maximizing the number of SST files read in
-  // parallel if the keys in the MultiGet batch are in different levels. It
-  // comes at the expense of slightly higher CPU overhead.
-  //
-  // Default: true
-  bool optimize_multiget_for_io;
+  // ** For RocksDB internal use only **
+  Env::IOActivity io_activity = Env::IOActivity::kUnknown;
 
-  ReadOptions();
-  ReadOptions(bool cksum, bool cache);
+  ReadOptions() {}
+  ReadOptions(bool _verify_checksums, bool _fill_cache);
+  explicit ReadOptions(Env::IOActivity _io_activity);
 };
 
 // Options that control write operations

package/deps/rocksdb/rocksdb/include/rocksdb/perf_context.h

@@ -14,13 +14,19 @@
 
 namespace ROCKSDB_NAMESPACE {
 
-// A thread local context for gathering performance counter efficiently
-// and transparently.
-// Use SetPerfLevel(PerfLevel::kEnableTime) to enable time stats.
+/*
+ * NOTE:
+ * Please do not reorder the fields in this structure. If you plan to do that or
+ * add/remove fields to this structure, builds would fail. The way to fix the
+ * builds would be to add the appropriate fields to the
+ * DEF_PERF_CONTEXT_LEVEL_METRICS() macro in the perf_context.cc file.
+ */
 
 // Break down performance counters by level and store per-level perf context in
 // PerfContextByLevel
-struct PerfContextByLevel {
+struct PerfContextByLevelBase {
+  // These Bloom stats apply to point reads (Get/MultiGet) for whole key and
+  // prefix filters.
   // # of times bloom filter has avoided file reads, i.e., negatives.
   uint64_t bloom_filter_useful = 0;
   // # of times bloom FullFilter has not avoided the reads.
@@ -38,37 +44,34 @@ struct PerfContextByLevel {
 
   uint64_t block_cache_hit_count = 0;   // total number of block cache hits
   uint64_t block_cache_miss_count = 0;  // total number of block cache misses
-
-  void Reset();  // reset all performance counters to zero
 };
 
-struct PerfContext {
-  ~PerfContext();
-
-  PerfContext() {}
-
-  PerfContext(const PerfContext&);
-  PerfContext& operator=(const PerfContext&);
-  PerfContext(PerfContext&&) noexcept;
+// A thread local context for gathering performance counter efficiently
+// and transparently.
+// Use SetPerfLevel(PerfLevel::kEnableTime) to enable time stats.
 
+// Break down performance counters by level and store per-level perf context in
+// PerfContextByLevel
+struct PerfContextByLevel : public PerfContextByLevelBase {
   void Reset();  // reset all performance counters to zero
+};
 
-  std::string ToString(bool exclude_zero_counters = false) const;
-
-  // enable per level perf context and allocate storage for PerfContextByLevel
-  void EnablePerLevelPerfContext();
-
-  // temporarily disable per level perf context by setting the flag to false
-  void DisablePerLevelPerfContext();
-
-  // free the space for PerfContextByLevel, also disable per level perf context
-  void ClearPerLevelPerfContext();
+/*
+ * NOTE:
+ * Please do not reorder the fields in this structure. If you plan to do that or
+ * add/remove fields to this structure, builds would fail. The way to fix the
+ * builds would be to add the appropriate fields to the
+ * DEF_PERF_CONTEXT_METRICS() macro in the perf_context.cc file.
+ */
 
+struct PerfContextBase {
   uint64_t user_key_comparison_count;  // total number of user key comparisons
   uint64_t block_cache_hit_count;      // total number of block cache hits
   uint64_t block_read_count;           // total number of block reads (with IO)
   uint64_t block_read_byte;            // total number of bytes from block reads
   uint64_t block_read_time;            // total nanos spent on block reads
+  // total cpu time in nanos spent on block reads
+  uint64_t block_read_cpu_time;
   uint64_t block_cache_index_hit_count;  // total number of index block hits
   // total number of standalone handles lookup from secondary cache
   uint64_t block_cache_standalone_handle_count;
@@ -216,9 +219,9 @@ struct PerfContext {
   uint64_t bloom_memtable_hit_count;
   // total number of mem table bloom misses
   uint64_t bloom_memtable_miss_count;
-  // total number of SST table bloom hits
+  // total number of SST bloom hits
   uint64_t bloom_sst_hit_count;
-  // total number of SST table bloom misses
+  // total number of SST bloom misses
   uint64_t bloom_sst_miss_count;
 
   // Time spent waiting on key locks in transaction lock manager.
@@ -254,15 +257,47 @@ struct PerfContext {
   uint64_t iter_prev_cpu_nanos;
   uint64_t iter_seek_cpu_nanos;
 
+  // EXPERIMENTAL
+  // Total number of db iterator's Next(), Prev(), Seek-related APIs being
+  // called
+  uint64_t iter_next_count;
+  uint64_t iter_prev_count;
+  uint64_t iter_seek_count;
+
   // Time spent in encrypting data. Populated when EncryptedEnv is used.
   uint64_t encrypt_data_nanos;
   // Time spent in decrypting data. Populated when EncryptedEnv is used.
   uint64_t decrypt_data_nanos;
 
   uint64_t number_async_seek;
+};
+
+struct PerfContext : public PerfContextBase {
+  ~PerfContext();
+
+  PerfContext() {}
+
+  PerfContext(const PerfContext&);
+  PerfContext& operator=(const PerfContext&);
+  PerfContext(PerfContext&&) noexcept;
+
+  void Reset();  // reset all performance counters to zero
+
+  std::string ToString(bool exclude_zero_counters = false) const;
+
+  // enable per level perf context and allocate storage for PerfContextByLevel
+  void EnablePerLevelPerfContext();
+
+  // temporarily disable per level perf context by setting the flag to false
+  void DisablePerLevelPerfContext();
+
+  // free the space for PerfContextByLevel, also disable per level perf context
+  void ClearPerLevelPerfContext();
 
   std::map<uint32_t, PerfContextByLevel>* level_to_perf_context = nullptr;
   bool per_level_perf_context_enabled = false;
+
+  void copyMetrics(const PerfContext* other) noexcept;
 };
 
 // If RocksDB is compiled with -DNPERF_CONTEXT, then a pointer to a global,

package/deps/rocksdb/rocksdb/include/rocksdb/secondary_cache.h

@@ -17,11 +17,23 @@
 
 namespace ROCKSDB_NAMESPACE {
 
-// A handle for lookup result. The handle may not be immediately ready or
-// have a valid value. The caller must call isReady() to determine if its
-// ready, and call Wait() in order to block until it becomes ready.
-// The caller must call Value() after it becomes ready to determine if the
-// handle successfullly read the item.
+// A handle for lookup result. Immediately after SecondaryCache::Lookup() with
+// wait=false (and depending on the implementation), the handle could be in any
+// of the below states. It must not be destroyed while in the pending state.
+// * Pending state (IsReady() == false): result is not ready. Value() and Size()
+// must not be called.
+// * Ready + not found state (IsReady() == true, Value() == nullptr): the lookup
+// has completed, finding no match. Or an error occurred that prevented
+// normal completion of the Lookup.
+// * Ready + found state (IsReady() == false, Value() != nullptr): the lookup
+// has completed, finding an entry that has been loaded into an object that is
+// now owned by the caller.
+//
+// Wait() or SecondaryCache::WaitAll() may be skipped if IsReady() happens to
+// return true, but (depending on the implementation) IsReady() might never
+// return true without Wait() or SecondaryCache::WaitAll(). After the handle
+// is known ready, calling Value() is required to avoid a memory leak in case
+// of a cache hit.
 class SecondaryCacheResultHandle {
  public:
   virtual ~SecondaryCacheResultHandle() = default;
@@ -36,7 +48,9 @@ class SecondaryCacheResultHandle {
   // the lookup was unsuccessful.
   virtual Cache::ObjectPtr Value() = 0;
 
-  // Return the size of value
+  // Return the out_charge from the helper->create_cb used to construct the
+  // object.
+  // WART: potentially confusing name
   virtual size_t Size() = 0;
 };
 
@@ -57,24 +71,13 @@ class SecondaryCache : public Customizable {
                                  const std::string& id,
                                  std::shared_ptr<SecondaryCache>* result);
 
-  // Insert the given value into this cache. Ownership of `value` is
-  // transferred to the callee, who is reponsible for deleting the value
-  // with helper->del_cb if del_cb is not nullptr. Unlike Cache::Insert(),
-  // the callee is responsible for such cleanup even in case of non-OK
-  // Status.
-  // Typically, the value is not saved directly but the implementation
-  // uses the SaveToCallback provided by helper to extract value's
-  // persistable data (typically uncompressed block), which will be written
-  // to this tier. The implementation may or may not write it to cache
-  // depending on the admission control policy, even if the return status
-  // is success (OK).
-  //
-  // If the implementation is asynchronous or otherwise uses `value` after
-  // the call returns, then InsertSaved() must be overridden not to rely on
-  // Insert(). For example, there could be a "holding area" in memory where
-  // Lookup() might return the same parsed value back. But more typically, if
-  // the implementation only uses `value` for getting persistable data during
-  // the call, then the default implementation of `InsertSaved()` suffices.
+  // Suggest inserting an entry into this cache. The caller retains ownership
+  // of `obj` (also called the "value"), so is only used directly by the
+  // SecondaryCache during Insert(). When the cache chooses to perform the
+  // suggested insertion, it uses the size_cb and saveto_cb provided by
+  // `helper` to extract the persistable data (typically an uncompressed block)
+  // and writes it to this cache tier. OK may be returned even if the insertion
+  // is not made.
   virtual Status Insert(const Slice& key, Cache::ObjectPtr obj,
                         const Cache::CacheItemHelper* helper) = 0;
 
@@ -84,8 +87,9 @@ class SecondaryCache : public Customizable {
   // may or may not write it to cache depending on the admission control
   // policy, even if the return status is success.
   //
-  // The default implementation assumes synchronous, non-escaping Insert(),
-  // wherein `value` is not used after return of Insert(). See Insert().
+  // The default implementation only assumes the entry helper's create_cb is
+  // called at Lookup() time and not Insert() time, so should work for all
+  // foreseeable implementations.
   virtual Status InsertSaved(const Slice& key, const Slice& saved);
 
   // Lookup the data for the given key in this cache. The create_cb