@nxtedition/rocksdb 15.4.0 → 15.5.0

package/deps/rocksdb/rocksdb/include/rocksdb/io_dispatcher.h

@@ -0,0 +1,358 @@
+//  Copyright (c) Meta Platforms, Inc. and affiliates.
+//  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).
+
+#pragma once
+
+#include <atomic>
+#include <functional>
+#include <memory>
+#include <unordered_map>
+#include <unordered_set>
+#include <vector>
+
+#include "rocksdb/options.h"
+#include "rocksdb/rocksdb_namespace.h"
+#include "rocksdb/status.h"
+
+namespace ROCKSDB_NAMESPACE {
+
+class FileSystem;
+class Statistics;
+
+// Forward declaration for internal implementation
+struct IODispatcherImplData;
+struct PendingPrefetchRequest;
+
+// Options for configuring IODispatcher behavior
+struct IODispatcherOptions {
+  // Maximum memory (in bytes) for prefetching across all ReadSets.
+  // When this limit is reached, SubmitJob() blocks until memory is released.
+  // Set to 0 (default) for unlimited prefetch memory.
+  size_t max_prefetch_memory_bytes = 0;
+
+  // Optional statistics for tracking memory limiter metrics
+  Statistics* statistics = nullptr;
+};
+
+/*
+ * IODispatcher is a class that allows users to submit groups of IO jobs to be
+ * dispatched asynchronously (or synchronously), upon submission the
+ * IODispatcher will return a ReadSet which act as an ownership object of those
+ * IOs. Users read from their readset when they require the data, and either
+ * poll for completion of the block, or read synchronously if the block is not
+ * in cache at that point.
+ *
+ * ReadSets have RAII semantics, meaning on destruction they will cancel any on
+ * going IO, and release the underlying pinned blocks.
+ *
+ * IODispatcher main goal is to act as control plane for all readers using the
+ * dispatcher, allowing for future ratelimiting and smarter dispatching policies
+ * in the future.
+ *
+ * Example 1: Basic Usage
+ * ----------------------
+ * // Submitting an IO job and reading blocks:
+ * //
+ * // std::shared_ptr<IOJob> job = std::make_shared<IOJob>();
+ * // job->table = table_reader;  // Provided BlockBasedTable*
+ * // job->job_options.io_coalesce_threshold = 32 * 1024;
+ * // job->job_options.read_options = read_options;  // Provided ReadOptions
+ * //
+ * // // Populate the job with block handles (e.g., from an index/iterator)
+ * // job->block_handles.push_back(handle1);
+ * // job->block_handles.push_back(handle2);
+ * // job->block_handles.push_back(handle3);
+ * //
+ * // std::unique_ptr<IODispatcher> dispatcher(NewIODispatcher());
+ * // std::shared_ptr<ReadSet> read_set;
+ * // Status s = dispatcher->SubmitJob(job, &read_set);
+ * // if (!s.ok()) {
+ * //   // Handle submit error
+ * // }
+ * //
+ * // // Read by index
+ * // for (size_t i = 1; i < job->block_handles.size(); ++i) {
+ * //   CachableEntry<Block> block_entry;
+ * //   Status rs = read_set->ReadIndex(i, &block_entry);
+ * //   if (!rs.ok()) {
+ * //     // Handle read error
+ * //     continue;
+ * //   }
+ * //   // Use block_entry (block contents are pinned here)
+ * // }
+ * //
+ * // // Or read by byte offset
+ * // {
+ * //   size_t offset =
+ static_cast<size_t>(job->block_handles.front().offset());
+ * //   CachableEntry<Block> block_entry;
+ * //   Status rs = read_set->ReadOffset(offset, &block_entry);
+ * //   if (rs.ok()) {
+ * //     // Use block_entry
+ * //   }
+ * // }
+ * //
+ * // // Stats
+ * // uint64_t cache_hits = read_set->GetNumCacheHits();
+ * // uint64_t async_reads = read_set->GetNumAsyncReads();
+ * // uint64_t sync_reads = read_set->GetNumSyncReads();
+ *
+ * Example 2: Memory-Limited Prefetching
+ * -------------------------------------
+ * // Configure a memory budget for prefetching to prevent unbounded memory use.
+ * // When the budget is exceeded, IODispatcher uses "partial prefetch":
+ * //   - Dispatches as many blocks as fit in available memory (earlier first)
+ * //   - Queues remaining blocks for later dispatch when memory is released
+ * //   - Never blocks on SubmitJob - remaining blocks are read on-demand
+ * //
+ * // IODispatcherOptions opts;
+ * // opts.max_prefetch_memory_bytes = 64 * 1024 * 1024;  // 64MB budget
+ * // opts.statistics = db_options.statistics.get();      // Optional metrics
+ * //
+ * // std::unique_ptr<IODispatcher> dispatcher(NewIODispatcher(opts));
+ * //
+ * // // Submit a job that needs more memory than available
+ * // // Partial prefetch will dispatch what fits immediately
+ * // std::shared_ptr<ReadSet> read_set;
+ * // Status s = dispatcher->SubmitJob(job, &read_set);  // Never blocks
+ * //
+ * // // Read blocks in order - earlier blocks are more likely to be prefetched
+ * // for (size_t i = 0; i < job->block_handles.size(); ++i) {
+ * //   CachableEntry<Block> block;
+ * //   Status rs = read_set->ReadIndex(i, &block);
+ * //   // Use block...
+ * //
+ * //   // Release block when done to free memory for pending prefetches
+ * //   read_set->ReleaseBlock(i);  // Triggers dispatch of queued blocks
+ * // }
+ * //
+ * // Memory limiting statistics (when statistics is configured):
+ * // - PREFETCH_MEMORY_BYTES_GRANTED: Total bytes acquired for prefetching
+ * // - PREFETCH_MEMORY_BYTES_RELEASED: Total bytes released after use
+ * // - PREFETCH_MEMORY_REQUESTS_BLOCKED: Number of blocks that couldn't be
+ * //   prefetched immediately due to memory pressure
+
+ */
+
+class BlockHandle;
+struct ReadOptions;
+struct AsyncIOState;
+
+template <typename T>
+class CachableEntry;
+class Block;
+class BlockBasedTable;
+
+struct JobOptions {
+  uint64_t io_coalesce_threshold = 16 * 1024;
+  ReadOptions read_options;
+};
+
+class IOJob {
+ public:
+  std::vector<BlockHandle> block_handles;
+
+  // Table reader for accessing block cache and index
+  BlockBasedTable* table = nullptr;
+
+  // Job execution options
+  JobOptions job_options;
+};
+
+/*
+ * ReadSet represents a set of blocks that may be in cache, being read
+ * asynchronously, or need to be read synchronously. The Read() method
+ * transparently handles all three cases.
+ */
+class ReadSet {
+ public:
+  ReadSet() = default;
+  ~ReadSet();
+
+  ReadSet(const ReadSet&) = delete;
+  ReadSet& operator=(const ReadSet&) = delete;
+  ReadSet(ReadSet&&) noexcept = delete;
+  ReadSet& operator=(ReadSet&&) noexcept = delete;
+
+  // Read a block by index
+  // - If the block is in cache, returns it immediately
+  // - If the block is being read asynchronously, polls for completion and
+  // returns it
+  // - If the block needs to be read, performs a synchronous read and returns it
+  //
+  // block_index: Index into the original IOJob's block_handles vector
+  // out: Output parameter for the pinned block entry
+  //
+  // Returns: Status::OK() on success, error status otherwise
+  Status ReadIndex(size_t block_index, CachableEntry<Block>* out);
+  // Read a block by offset
+  // - If the block is in cache, returns it immediately
+  // - If the block is being read asynchronously, polls for completion and
+  // returns it
+  // - If the block needs to be read, performs a synchronous read and returns it
+
+  // block_offset: Byte Offset into the SST file of the block.
+
+  // out: Output parameter for the pinned block entry
+  Status ReadOffset(size_t offset, CachableEntry<Block>* out);
+
+  // Release a block by index, unpinning it from cache.
+  // After this call, ReadIndex() for this block will return an error.
+  // This is useful for eager memory reclamation when blocks are no longer
+  // needed.
+  void ReleaseBlock(size_t block_index);
+
+  // Check if a block at the given index is still available (not released).
+  // Returns true if the block can be read, false otherwise.
+  bool IsBlockAvailable(size_t block_index) const;
+
+  // Statistics accessors
+  uint64_t GetNumSyncReads() const { return num_sync_reads_; }
+  uint64_t GetNumAsyncReads() const { return num_async_reads_; }
+  uint64_t GetNumCacheHits() const { return num_cache_hits_; }
+
+ private:
+  friend class IODispatcherImpl;
+
+  // Job data
+  std::shared_ptr<IOJob> job_;
+
+  // FileSystem for calling AbortIO in destructor
+  std::shared_ptr<FileSystem> fs_;
+
+  // Storage for pinned blocks (one per block handle in the job)
+  std::vector<CachableEntry<Block>> pinned_blocks_;
+
+  // Sorted index for binary search in ReadOffset.
+  // sorted_block_indices_[i] is the original index of the i-th smallest block
+  // by offset. Built once during SubmitJob for O(log n) ReadOffset lookups.
+  std::vector<size_t> sorted_block_indices_;
+
+  // Map from block index to async IO state for blocks being read
+  // asynchronously. Multiple block indices may map to the same async state when
+  // blocks are coalesced into a single IO request.
+  std::unordered_map<size_t, std::shared_ptr<AsyncIOState>> async_io_map_;
+
+  // For memory release notifications back to dispatcher (weak ref to avoid
+  // cycles)
+  std::weak_ptr<IODispatcherImplData> dispatcher_data_;
+
+  // Size of each block (parallel to pinned_blocks_) for memory accounting
+  std::vector<size_t> block_sizes_;
+
+  // Statistics counters
+  std::atomic<uint64_t> num_sync_reads_ = 0;
+  std::atomic<uint64_t> num_async_reads_ = 0;
+  std::atomic<uint64_t> num_cache_hits_ = 0;
+
+  // Poll and process a specific async IO request
+  Status PollAndProcessAsyncIO(
+      const std::shared_ptr<AsyncIOState>& async_state);
+
+  // Perform synchronous read for a specific block
+  Status SyncRead(size_t block_index);
+
+  // Remove a block from pending prefetch (called by ReadIndex/ReleaseBlock)
+  void RemoveFromPending(size_t block_index);
+
+  // Atomic flags indicating if block is pending prefetch (lock-free check)
+  std::unique_ptr<std::atomic<bool>[]> pending_prefetch_flags_;
+  size_t pending_prefetch_flags_size_ = 0;
+
+  // Reference to pending request (for removal notification)
+  std::shared_ptr<PendingPrefetchRequest> pending_request_;
+};
+
+/*
+ * IODispatcher handles IO operations synchronously or asynchronously based
+ * on JobOptions. When async is true, it uses ReadAsync; when false, it uses
+ * standard synchronous reads.
+ * */
+class IODispatcher {
+ protected:
+  IODispatcher() = default;
+
+ public:
+  virtual ~IODispatcher() {}
+
+  IODispatcher(const IODispatcher&) = delete;
+  IODispatcher& operator=(const IODispatcher&) = delete;
+  IODispatcher(IODispatcher&&) = delete;
+  IODispatcher& operator=(IODispatcher&&) = delete;
+
+  // Submit a job for IO processing
+  // job: The IO job to submit
+  // read_set: Output parameter that will be populated with the ReadSet on
+  // success Returns: Status::OK() on success, error status otherwise
+  virtual Status SubmitJob(const std::shared_ptr<IOJob>& job,
+                           std::shared_ptr<ReadSet>* read_set) = 0;
+};
+
+// Create IODispatcher with default options (no memory limit)
+IODispatcher* NewIODispatcher();
+
+// Create IODispatcher with custom options
+IODispatcher* NewIODispatcher(const IODispatcherOptions& options);
+
+// TrackingIODispatcher wraps another IODispatcher and tracks all ReadSets
+// created. This is useful for testing to verify IO statistics.
+class TrackingIODispatcher : public IODispatcher {
+ public:
+  TrackingIODispatcher() : impl_(NewIODispatcher()) {}
+  explicit TrackingIODispatcher(IODispatcher* impl) : impl_(impl) {}
+
+  Status SubmitJob(const std::shared_ptr<IOJob>& job,
+                   std::shared_ptr<ReadSet>* read_set) override {
+    Status s = impl_->SubmitJob(job, read_set);
+    if (s.ok() && read_set && *read_set) {
+      read_sets_.push_back(*read_set);
+    }
+    return s;
+  }
+
+  // Get all ReadSets created by this dispatcher
+  const std::vector<std::shared_ptr<ReadSet>>& GetReadSets() const {
+    return read_sets_;
+  }
+
+  // Get aggregated statistics from all ReadSets
+  uint64_t GetTotalSyncReads() const {
+    uint64_t total = 0;
+    for (const auto& rs : read_sets_) {
+      total += rs->GetNumSyncReads();
+    }
+    return total;
+  }
+
+  uint64_t GetTotalAsyncReads() const {
+    uint64_t total = 0;
+    for (const auto& rs : read_sets_) {
+      total += rs->GetNumAsyncReads();
+    }
+    return total;
+  }
+
+  uint64_t GetTotalCacheHits() const {
+    uint64_t total = 0;
+    for (const auto& rs : read_sets_) {
+      total += rs->GetNumCacheHits();
+    }
+    return total;
+  }
+
+  // Get total IO operations (sum of all types)
+  uint64_t GetTotalIOOperations() const {
+    return GetTotalSyncReads() + GetTotalAsyncReads() + GetTotalCacheHits();
+  }
+
+  // Clear tracked ReadSets
+  void ClearReadSets() { read_sets_.clear(); }
+
+ private:
+  std::unique_ptr<IODispatcher> impl_;
+  std::vector<std::shared_ptr<ReadSet>> read_sets_;
+};
+
+}  // namespace ROCKSDB_NAMESPACE

package/deps/rocksdb/rocksdb/include/rocksdb/iostats_context.h

@@ -38,6 +38,10 @@ struct FileIOByTemperature {
   uint64_t cold_file_bytes_read;
   // the number of bytes read to Temperature::kIce file
   uint64_t ice_file_bytes_read;
+  // the number of bytes read to Temperature::kUnknown file not in last level
+  uint64_t unknown_non_last_level_bytes_read;
+  // the number of bytes read to Temperature::kUnknown file in last level
+  uint64_t unknown_last_level_bytes_read;
   // total number of reads to Temperature::kHot file
   uint64_t hot_file_read_count;
   // total number of reads to Temperature::kWarm file
@@ -48,6 +52,11 @@ struct FileIOByTemperature {
   uint64_t cold_file_read_count;
   // total number of reads to Temperature::kIce file
   uint64_t ice_file_read_count;
+  // total number of reads to Temperature::kUnknown file not in last level
+  uint64_t unknown_non_last_level_read_count;
+  // total number of reads to Temperature::kUnknown file in last level
+  uint64_t unknown_last_level_read_count;
+
   // reset all the statistics to 0.
   void Reset() {
     hot_file_bytes_read = 0;
@@ -55,11 +64,15 @@ struct FileIOByTemperature {
     cool_file_bytes_read = 0;
     cold_file_bytes_read = 0;
     ice_file_bytes_read = 0;
+    unknown_non_last_level_bytes_read = 0;
+    unknown_last_level_bytes_read = 0;
     hot_file_read_count = 0;
     warm_file_read_count = 0;
     cool_file_read_count = 0;
     cold_file_read_count = 0;
     ice_file_read_count = 0;
+    unknown_non_last_level_read_count = 0;
+    unknown_last_level_read_count = 0;
   }
 };
 

package/deps/rocksdb/rocksdb/include/rocksdb/listener.h

@@ -201,6 +201,7 @@ enum class BackgroundErrorReason {
   kManifestWrite,
   kFlushNoWAL,
   kManifestWriteNoWAL,
+  kAsyncFileOpen,
 };
 
 struct WriteStallInfo {
@@ -488,6 +489,9 @@ struct CompactionJobInfo {
   // Information about blob files deleted during compaction in Integrated
   // BlobDB.
   std::vector<BlobFileGarbageInfo> blob_file_garbage_infos;
+
+  // Whether this compaction was aborted via AbortAllCompactions()
+  bool aborted = false;
 };
 
 struct MemTableInfo {
@@ -550,6 +554,34 @@ struct IOErrorInfo {
   uint64_t offset;
 };
 
+// EXPERIMENTAL — under active development, fields may change.
+// Point-in-time snapshot of background job pressure for one DB: how busy
+// compaction and flush are, and how close the DB is to write-stalling.
+struct BackgroundJobPressure {
+  // Compaction scheduling (LOW + BOTTOM priority combined)
+  int compaction_scheduled = 0;
+  int compaction_running = 0;
+
+  // Per-priority compaction breakdown
+  int compaction_low_scheduled = 0;
+  int compaction_low_running = 0;
+  int compaction_bottom_scheduled = 0;
+  int compaction_bottom_running = 0;
+
+  // Flush scheduling
+  int flush_scheduled = 0;
+  int flush_running = 0;
+
+  // How close the DB is to a write stall, as a percentage (0 = healthy,
+  // 100 = at stall threshold). Can exceed 100 when already stalling.
+  // Max across all column families based on write-stall triggers.
+  int write_stall_proximity_pct = 0;
+  // Whether RocksDB has activated compaction speedup due to write pressure
+  bool compaction_speedup_active = false;
+
+  bool operator==(const BackgroundJobPressure&) const = default;
+};
+
 // EventListener class contains a set of callback functions that will
 // be called when specific RocksDB event happens such as flush.  It can
 // be used as a building block for developing custom features such as
@@ -866,6 +898,17 @@ class EventListener : public Customizable {
   // happens. ShouldBeNotifiedOnFileIO should be set to true to get a callback.
   virtual void OnIOError(const IOErrorInfo& /*info*/) {}
 
+  // EXPERIMENTAL
+  // Called after a flush or compaction background job completes, providing a
+  // snapshot of current background job scheduling pressure and write-stall
+  // proximity. Fires on the background thread that completed the job, without
+  // holding db_mutex_. This callback fires on every completion, even if
+  // pressure values have not changed from the previous call.
+  // Implementations should not run for an extended period of time before
+  // returning, as this blocks RocksDB background work.
+  virtual void OnBackgroundJobPressureChanged(
+      DB* /*db*/, const BackgroundJobPressure& /*pressure*/) {}
+
   ~EventListener() override {}
 };
 

package/deps/rocksdb/rocksdb/include/rocksdb/memtablerep.h

@@ -211,6 +211,26 @@ class MemTableRep {
     return Status::NotSupported("GetAndValidate() not implemented.");
   }
 
+  // Batch lookup of multiple sorted keys. For each key, finds the first
+  // matching entry and calls callback_func with callback_args[i] and the
+  // entry. Continues calling for subsequent entries until callback_func
+  // returns false.
+  //
+  // Keys must be memtable-encoded and in non-decreasing order. Implementations
+  // may exploit the sorted key order for more efficient lookups.
+  //
+  // When detect_key_out_of_order is true, validates key ordering during
+  // traversal and returns Corruption if out-of-order keys are found.
+  // When key_validation_callback is non-null, calls it on each visited node.
+  //
+  // Default implementation calls Get() per key via an iterator.
+  virtual Status MultiGet(
+      size_t num_keys, const char* const* keys, void** callback_args,
+      bool (*callback_func)(void* arg, const char* entry),
+      bool allow_data_in_errors = false, bool detect_key_out_of_order = false,
+      const std::function<Status(const char*, bool)>& key_validation_callback =
+          nullptr);
+
   virtual uint64_t ApproximateNumEntries(const Slice& /*start_ikey*/,
                                          const Slice& /*end_key*/) {
     return 0;

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

@@ -58,6 +58,7 @@ class InternalKeyComparator;
 class WalFilter;
 class FileSystem;
 class UserDefinedIndexFactory;
+class IODispatcher;
 
 struct Options;
 struct DbPath;
@@ -304,9 +305,6 @@ struct ColumnFamilyOptions : public AdvancedColumnFamilyOptions {
   // Dynamically changeable through SetOptions() API
   uint64_t max_bytes_for_level_base = 256 * 1048576;
 
-  // Deprecated.
-  uint64_t snap_refresh_nanos = 0;
-
   // Disable automatic compactions. Manual compactions can still
   // be issued on this column family
   //
@@ -785,6 +783,25 @@ struct DBOptions {
   // Default: 16
   int max_file_opening_threads = 16;
 
+  // If true, SST files are opened and validated asynchronously in the
+  // background after DB::Open returns. This reduces DB open time for
+  // databases with many SST files and high latency file systems. Mostly useful
+  // when max_open_files = -1, as max_open_files != -1 usually has fast open
+  // times. See also `max_file_opening_threads` and
+  // `skip_stats_update_on_db_open` to improve file open latency.
+  //
+  // Note: This option is currently not compatible with FIFO compaction and
+  // requires skip_stats_update_on_db_open=true.
+  //
+  // Errors will no longer show up in DB::Open, but instead can show up as
+  // either background errors and/or operations that access the file (e.g.
+  // reads, compactions).
+  //
+  // When false (default), SST files are opened and validated during DB::Open.
+  //
+  // Default: false
+  bool open_files_async = false;
+
   // Once write-ahead logs exceed this size, we will start forcing the flush of
   // column families whose memtables are backed by the oldest live WAL file
   // (i.e. the ones that are causing all the space amplification). If set to 0
@@ -977,6 +994,13 @@ struct DBOptions {
   // manifest write (e.g. completed DB compaction or flush).
   uint64_t max_manifest_file_size = 1024 * 1024 * 1024;
 
+  // If true, on DB close, read back the entire MANIFEST file and validate
+  // CRC checksums and logical record content. If corruption is detected,
+  // a fresh MANIFEST is written from in-memory state before closing.
+  //
+  // This option is mutable with SetDBOptions().
+  bool verify_manifest_content_on_close = false;
+
   // This option mostly replaces max_manifest_file_size to control an auto-tuned
   // balance of manifest write amplification and space amplification. A new
   // manifest file is created with the "compacted" contents of the old one when
@@ -1362,17 +1386,6 @@ struct DBOptions {
   // Default: false
   bool skip_stats_update_on_db_open = false;
 
-  // This option is deprecated and marked as no-op. Kept for backward
-  // compatibility until usage is fully removed.
-  // File size check will be performed through a thread
-  // pool during DB Open, when max_open_files is set to -1.
-  // Therefore, the concern of DB Open slowness is eliminated.
-  // Note that when max_open_files is not set to -1, only a subset of files will
-  // be opened and checked during DB Open.
-  //
-  // Default: false
-  bool skip_checking_sst_file_sizes_on_db_open = false;
-
   // Recovery mode to control the consistency while replaying WAL
   // Default: kPointInTimeRecovery
   WALRecoveryMode wal_recovery_mode = WALRecoveryMode::kPointInTimeRecovery;
@@ -1405,9 +1418,30 @@ struct DBOptions {
   // WAL logs will be kept, so that if crash happened before flush, we still
   // have logs to recover from.
   //
+  // Note: when `enforce_write_buffer_manager_during_recovery` is also enabled,
+  // flushes may still occur during recovery to respect the
+  // WriteBufferManager's global memory limit, even if this option is true.
+  // Once any such WBM-triggered flush happens, all remaining memtables will
+  // also be flushed at the end of recovery (similar to the behavior when this
+  // option is false).
+  //
   // DEFAULT: false
   bool avoid_flush_during_recovery = false;
 
+  // If true and a WriteBufferManager is configured, RocksDB will check
+  // WriteBufferManager::ShouldFlush() during WAL recovery and schedule
+  // flushes when needed. This prevents OOM when multiple RocksDB instances
+  // share a WriteBufferManager and one instance is recovering from WAL.
+  //
+  // When triggered, all column families with non-empty memtables are scheduled
+  // for flush, which may produce smaller L0 files in some column families.
+  // This also overrides `avoid_flush_during_recovery`: once a WBM-triggered
+  // flush occurs mid-recovery, all remaining non-empty memtables will be
+  // flushed at the end of recovery as well.
+  //
+  // DEFAULT: true
+  bool enforce_write_buffer_manager_during_recovery = true;
+
   // By default RocksDB will flush all memtables on DB close if there are
   // unpersisted data (i.e. with WAL disabled) The flush can be skip to speedup
   // DB close. Unpersisted data WILL BE LOST.
@@ -1847,11 +1881,13 @@ class MultiScanArgs {
     io_coalesce_threshold = other.io_coalesce_threshold;
     max_prefetch_size = other.max_prefetch_size;
     use_async_io = other.use_async_io;
+    io_dispatcher = other.io_dispatcher;
   }
   MultiScanArgs(MultiScanArgs&& other) noexcept
       : io_coalesce_threshold(other.io_coalesce_threshold),
         max_prefetch_size(other.max_prefetch_size),
         use_async_io(other.use_async_io),
+        io_dispatcher(std::move(other.io_dispatcher)),
         comp_(other.comp_),
         original_ranges_(std::move(other.original_ranges_)) {}
 
@@ -1861,6 +1897,7 @@ class MultiScanArgs {
     io_coalesce_threshold = other.io_coalesce_threshold;
     max_prefetch_size = other.max_prefetch_size;
     use_async_io = other.use_async_io;
+    io_dispatcher = other.io_dispatcher;
     return *this;
   }
 
@@ -1871,6 +1908,7 @@ class MultiScanArgs {
       io_coalesce_threshold = other.io_coalesce_threshold;
       max_prefetch_size = other.max_prefetch_size;
       use_async_io = other.use_async_io;
+      io_dispatcher = std::move(other.io_dispatcher);
     }
     return *this;
   }
@@ -1918,6 +1956,7 @@ class MultiScanArgs {
     io_coalesce_threshold = other.io_coalesce_threshold;
     max_prefetch_size = other.max_prefetch_size;
     use_async_io = other.use_async_io;
+    io_dispatcher = other.io_dispatcher;
   }
 
   uint64_t io_coalesce_threshold = 16 << 10;  // 16KB by default
@@ -1939,6 +1978,12 @@ class MultiScanArgs {
   // When false, it will use synchronous MultiRead().
   bool use_async_io = false;
 
+  // Optional IODispatcher for multi-scan operations.
+  // If nullptr (default), a new IODispatcher is created internally.
+  // Users can provide their own IODispatcher for custom IO scheduling
+  // or for testing/monitoring purposes (e.g., to check IO statistics).
+  std::shared_ptr<IODispatcher> io_dispatcher = nullptr;
+
  private:
   // The comparator used for ordering ranges
   const Comparator* comp_;
@@ -2108,10 +2153,6 @@ struct ReadOptions {
   // that were inserted into the database after the creation of the iterator.
   bool tailing = false;
 
-  // This options is not used anymore. It was to turn on a functionality that
-  // 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.
@@ -2241,9 +2282,10 @@ struct ReadOptions {
   // block based table index. The table_factory used for the column family
   // must support building/reading this index.
   //
-  // Currently, only forward scans are supported. For forward scans, only Seek()
-  // is supported. SeekToFirst() is not supported. If the caller wishes to scan
-  // from start to end, the native index must be used.
+  // Forward scans (SeekToFirst, Seek, Next) and point lookups (Get) are
+  // supported. Reverse operations (SeekToLast, SeekForPrev, Prev) are not
+  // yet supported and will return NotSupported when this is set. Leave this
+  // null to use the native index for reverse operations.
   const UserDefinedIndexFactory* table_index_factory = nullptr;
 
   // *** END options only relevant to iterators or scans ***