@nxtedition/rocksdb 13.5.13 → 14.0.0

package/deps/rocksdb/rocksdb/table/block_based/block_based_table_iterator.cc

@@ -37,14 +37,14 @@ void BlockBasedTableIterator::SeekImpl(const Slice* target,
                                        bool async_prefetch) {
   // TODO(hx235): set `seek_key_prefix_for_readahead_trimming_`
   // even when `target == nullptr` that is when `SeekToFirst()` is called
+  if (!multi_scan_status_.ok()) {
+    return;
+  }
   if (multi_scan_) {
-    if (SeekMultiScan(target)) {
-      return;
-    }
+    SeekMultiScan(target);
+    return;
   }
 
-  assert(!multi_scan_);
-
   if (target != nullptr && prefix_extractor_ &&
       read_options_.prefix_same_as_start) {
     const Slice& seek_user_key = ExtractUserKey(*target);
@@ -919,351 +919,827 @@ void BlockBasedTableIterator::BlockCacheLookupForReadAheadSize(
   ResetPreviousBlockOffset();
 }
 
+BlockBasedTableIterator::MultiScanState::~MultiScanState() {
+  // Abort any pending async IO operations to prevent callback being called
+  // after async read states are destructed.
+  if (!async_states.empty()) {
+    std::vector<void*> io_handles_to_abort;
+    std::vector<AsyncReadState*> states_to_cleanup;
+
+    // Collect all pending IO handles
+    for (size_t i = 0; i < async_states.size(); ++i) {
+      auto& async_read = async_states[i];
+
+      if (async_read.io_handle != nullptr) {
+        assert(!async_read.finished);
+        io_handles_to_abort.push_back(async_read.io_handle);
+        states_to_cleanup.push_back(&async_read);
+      }
+    }
+
+    if (!io_handles_to_abort.empty()) {
+      IOStatus abort_status = fs->AbortIO(io_handles_to_abort);
+      if (!abort_status.ok()) {
+#ifndef NDEBUG
+        fprintf(stderr, "Error aborting async IO operations: %s\n",
+                abort_status.ToString().c_str());
+#endif
+        assert(false);
+      }
+      (void)abort_status;  // Suppress unused variable warning
+    }
+
+    for (auto async_read : states_to_cleanup) {
+      async_read->CleanUpIOHandle();
+    }
+  }
+}
+
 // Note:
 // - Iterator should not be reused for multiple multiscans or mixing
 // multiscan with regular iterator usage.
 // - scan ranges should be non-overlapping, and have increasing start keys.
 // If a scan range's limit is not set, then there should only be one scan range.
 // - After Prepare(), the iterator expects Seek to be called on the start key
-// of each ScanOption in order. If any other seek is done, the optimization here
-// is aborted and fall back to vanilla iterator.
+// of each ScanOption in order. If any other Seek is done, an error status is
+// returned
+// - Whenever all blocks of a scan opt are exhausted, the iterator will become
+// invalid and UpperBoundCheckResult() will return kOutOfBound. So that the
+// upper layer (LevelIterator) will stop scanning instead thinking EOF is
+// reached and continue into the next file. The only exception is for the last
+// scan opt. If we reach the end of the last scan opt, UpperBoundCheckResult()
+// will return kUnknown instead of kOutOfBound. This mechanism requires that
+// scan opts are properly pruned such that there is no scan opt that is after
+// this file's key range.
 // FIXME: DBIter and MergingIterator may
 // internally do Seek() on child iterators, e.g. due to
 // ReadOptions::max_skippable_internal_keys or reseeking into range deletion
-// end key. So these Seeks can cause iterator to fall back to normal
-// (non-prepared) iterator and ignore the optimizations done in Prepare().
-void BlockBasedTableIterator::Prepare(
-    const std::vector<ScanOptions>* scan_opts) {
-  index_iter_->Prepare(scan_opts);
-
+// end key. These Seeks will be handled properly, as long as the target is
+// moving forward.
+void BlockBasedTableIterator::Prepare(const MultiScanArgs* multiscan_opts) {
   assert(!multi_scan_);
+  if (!index_iter_->status().ok()) {
+    multi_scan_status_ = index_iter_->status();
+    return;
+  }
   if (multi_scan_) {
     multi_scan_.reset();
+    multi_scan_status_ = Status::InvalidArgument("Prepare already called");
     return;
   }
-  if (scan_opts == nullptr || scan_opts->empty()) {
+
+  index_iter_->Prepare(multiscan_opts);
+
+  std::vector<BlockHandle> scan_block_handles;
+  std::vector<std::string> data_block_separators;
+  std::vector<std::tuple<size_t, size_t>> block_index_ranges_per_scan;
+  const std::vector<ScanOptions>& scan_opts = multiscan_opts->GetScanRanges();
+  multi_scan_status_ =
+      CollectBlockHandles(scan_opts, &scan_block_handles,
+                          &block_index_ranges_per_scan, &data_block_separators);
+  if (!multi_scan_status_.ok()) {
     return;
   }
-  const bool has_limit = scan_opts->front().range.limit.has_value();
-  if (!has_limit && scan_opts->size() > 1) {
-    // Abort: overlapping ranges
+
+  // Pin already cached blocks, collect remaining blocks to read
+  std::vector<size_t> block_indices_to_read;
+  std::vector<CachableEntry<Block>> pinned_data_blocks_guard(
+      scan_block_handles.size());
+  size_t prefetched_max_idx;
+  multi_scan_status_ = FilterAndPinCachedBlocks(
+      scan_block_handles, multiscan_opts, &block_indices_to_read,
+      &pinned_data_blocks_guard, &prefetched_max_idx);
+  if (!multi_scan_status_.ok()) {
     return;
   }
 
-  // Validate scan ranges to be increasing and with limit.
-  for (size_t i = 0; i < scan_opts->size(); ++i) {
-    const auto& scan_range = (*scan_opts)[i].range;
-    if (!scan_range.start.has_value()) {
-      // Abort: no start key
+  std::vector<AsyncReadState> async_states;
+  // Maps from block index into async read request (index into async_states[])
+  UnorderedMap<size_t, size_t> block_idx_to_readreq_idx;
+  if (!block_indices_to_read.empty()) {
+    std::vector<FSReadRequest> read_reqs;
+    std::vector<std::vector<size_t>> coalesced_block_indices;
+    PrepareIORequests(block_indices_to_read, scan_block_handles, multiscan_opts,
+                      &read_reqs, &block_idx_to_readreq_idx,
+                      &coalesced_block_indices);
+
+    multi_scan_status_ =
+        ExecuteIO(scan_block_handles, multiscan_opts, coalesced_block_indices,
+                  &read_reqs, &async_states, &pinned_data_blocks_guard);
+    if (!multi_scan_status_.ok()) {
       return;
     }
+  }
+
+  // Successful Prepare, init related states so the iterator reads from prepared
+  // blocks.
+  multi_scan_ = std::make_unique<MultiScanState>(
+      table_->get_rep()->ioptions.env->GetFileSystem(), multiscan_opts,
+      std::move(pinned_data_blocks_guard), std::move(data_block_separators),
+      std::move(block_index_ranges_per_scan),
+      std::move(block_idx_to_readreq_idx), std::move(async_states),
+      prefetched_max_idx);
 
-    // Assume for each scan range start <= limit.
-    if (scan_range.limit.has_value()) {
-      assert(user_comparator_.Compare(scan_range.start.value(),
-                                      scan_range.limit.value()) <= 0);
+  is_index_at_curr_block_ = false;
+  block_iter_points_to_real_block_ = false;
+}
+
+void BlockBasedTableIterator::SeekMultiScan(const Slice* seek_target) {
+  if (SeekMultiScanImpl(seek_target)) {
+    is_out_of_bound_ = true;
+    assert(!Valid());
+  }
+}
+
+bool BlockBasedTableIterator::SeekMultiScanImpl(const Slice* seek_target) {
+  assert(multi_scan_ && multi_scan_status_.ok());
+  // This is a MultiScan and Preapre() has been called.
+
+  // Reset out of bound on seek, if it is out of bound again, it will be set
+  // properly later in the code path
+  is_out_of_bound_ = false;
+
+  // Validate seek key with scan options
+  if (!seek_target) {
+    // start key must be set for multi-scan
+    multi_scan_status_ = Status::InvalidArgument("No seek key for MultiScan");
+    return false;
+  }
+
+  constexpr auto out_of_bound = true;
+
+  // Check the case where there is no range prepared on this table
+  if (multi_scan_->scan_opts->size() == 0) {
+    // out of bound
+    return out_of_bound;
+  }
+
+  // Check whether seek key is moving forward.
+  if (!multi_scan_->prev_seek_key_.empty()) {
+    if (user_comparator_.CompareWithoutTimestamp(ExtractUserKey(*seek_target),
+                                                 /*a_has_ts=*/true,
+                                                 multi_scan_->prev_seek_key_,
+                                                 /*b_has_ts=*/false) < 0) {
+      // The seek target moved backward
+      multi_scan_status_ =
+          Status::InvalidArgument("Unexpected seek key moving backward");
+      return false;
     }
+  }
+  multi_scan_->prev_seek_key_ = ExtractUserKey(*seek_target).ToString();
+
+  // There are still a few cases we need to handle
+  // table: _____[prepared range 1]_____[prepared range 2]_____
+  // seek :   1  2        3          4                      5
+  // Case 1: seek before the first prepared ranges, return out of bound
+  // Case 2: seek at the beginning of a prepared range (expected case)
+  // Case 3: seek within a prepared range (unexpected, but supported)
+  // Case 4: seek between 2 of the prepared ranges, return out of bound
+  // Case 5: seek after all of the prepared ranges, should move on to next file
+  // The reason this could happen is due to seek key adjustment due to delete
+  // range file.
+  // E.g. LSM has 3 levels, each level has only 1 file:
+  // L1 : key :              0---10
+  // L2 : Delete range key : 0-5
+  // L3 : key :              0---10
+  // When a range 2-8 was prepared, the prepared key would be 2 on L3 file, but
+  // the seek key would be 5, as the seek key was updated by the largest key of
+  // delete range. This causes all of the cases above to be possible, when the
+  // ranges are adjusted in the above examples.
+
+  // Allow reseek on the start of the last prepared range due to too many
+  // tombstone
+  multi_scan_->next_scan_idx =
+      std::min(multi_scan_->next_scan_idx,
+               multi_scan_->block_index_ranges_per_scan.size() - 1);
+
+  auto compare_next_scan_start_result =
+      user_comparator_.CompareWithoutTimestamp(
+          ExtractUserKey(*seek_target), /*a_has_ts=*/true,
+          multi_scan_->scan_opts->GetScanRanges()[multi_scan_->next_scan_idx]
+              .range.start.value(),
+          /*b_has_ts=*/false);
+
+  if (compare_next_scan_start_result != 0) {
+    // The seek key is not exactly same as what was prepared.
+    if (compare_next_scan_start_result < 0) {
+      // Needs to handle Cases: 1, 3, 4
+      //
+      // next_scan_idx :                    |
+      //                                    V
+      // table: _____[prepared range 1]_____[prepared range 2]_____
+      // seek :   1           3          4
+
+      // Case 1: Seek key is before the start key of the first range
+      if (multi_scan_->next_scan_idx == 0) {
+        return out_of_bound;
+      }
+      // Case: 3, 4
+      MultiScanUnexpectedSeekTarget(
+          seek_target, std::get<0>(multi_scan_->block_index_ranges_per_scan
+                                       [multi_scan_->next_scan_idx - 1]));
 
-    if (i > 0) {
-      if (!scan_range.limit.has_value()) {
-        // multiple no limit scan ranges
-        return;
+    } else {
+      // Needs to handle Cases: 3, 4, 5
+      // next_scan_idx :|
+      //                V
+      // table:     ____[prepared range 1]_____[prepared range 2]_____
+      // seek :                 3           4                      5
+      MultiScanUnexpectedSeekTarget(
+          seek_target,
+          std::get<0>(
+              multi_scan_
+                  ->block_index_ranges_per_scan[multi_scan_->next_scan_idx]));
+    }
+  } else {
+    if (multi_scan_->next_scan_idx >=
+        multi_scan_->block_index_ranges_per_scan.size()) {
+      // Seeking a range that is out side of prepared ranges.
+      return out_of_bound;
+    }
+    // unpin block, then do a seek.
+    if (multi_scan_->next_scan_idx > 0) {
+      UnpinPreviousScanBlocks(multi_scan_->next_scan_idx);
+    }
+
+    auto [cur_scan_start_idx, cur_scan_end_idx] =
+        multi_scan_->block_index_ranges_per_scan[multi_scan_->next_scan_idx];
+    // We should have the data block already loaded
+    ++multi_scan_->next_scan_idx;
+    if (cur_scan_start_idx >= cur_scan_end_idx) {
+      if (multi_scan_->next_scan_idx <
+          multi_scan_->block_index_ranges_per_scan.size()) {
+        return out_of_bound;
+      } else {
+        ResetDataIter();
+        return false;
       }
+    } else {
+      is_out_of_bound_ = false;
+    }
+
+    MultiScanSeekTargetFromBlock(seek_target, cur_scan_start_idx);
+  }
+
+  return false;
+}
+
+void BlockBasedTableIterator::MultiScanUnexpectedSeekTarget(
+    const Slice* seek_target, size_t block_idx) {
+  // linear search the block that contains the seek target, and unpin blocks
+  // that are before it.
+  auto const& data_block_separators = multi_scan_->data_block_separators;
+  while (block_idx < data_block_separators.size() &&
+         (user_comparator_.CompareWithoutTimestamp(
+              ExtractUserKey(*seek_target), /*a_has_ts=*/true,
+              data_block_separators[block_idx],
+              /*b_has_ts=*/false) > 0)) {
+    if (!multi_scan_->pinned_data_blocks[block_idx].IsEmpty()) {
+      multi_scan_->pinned_data_blocks[block_idx].Reset();
+    }
+    block_idx++;
+  }
+
+  if (block_idx >= data_block_separators.size()) {
+    // Handle case 5, when seek key is larger than the last block in the last
+    // prepared range.
+    ResetDataIter();
+    assert(!Valid());
+    return;
+  }
+
+  // // The iterator from previous seek may have moved forward a few blocks,
+  // // In that case, have block_idx catch up the cur_data_block_idx
+  // // Note no need to handle block unpin, as it has been handled during
+  // iterating block_idx = std::max(block_idx, multi_scan_->cur_data_block_idx);
+
+  // advance to the right prepared range
+  while (
+      multi_scan_->next_scan_idx <
+          multi_scan_->block_index_ranges_per_scan.size() &&
+      (user_comparator_.CompareWithoutTimestamp(
+           ExtractUserKey(*seek_target), /*a_has_ts=*/true,
+           multi_scan_->scan_opts->GetScanRanges()[multi_scan_->next_scan_idx]
+               .range.start.value(),
+           /*b_has_ts=*/false) >= 0)) {
+    multi_scan_->next_scan_idx++;
+  }
+
+  // The current block may contain the data for the target key
+  MultiScanSeekTargetFromBlock(seek_target, block_idx);
+}
+
+void BlockBasedTableIterator::MultiScanSeekTargetFromBlock(
+    const Slice* seek_target, size_t block_idx) {
+  if (!block_iter_points_to_real_block_ ||
+      multi_scan_->cur_data_block_idx != block_idx) {
+    if (block_iter_points_to_real_block_) {
+      // Should be scan in increasing key range.
+      // All blocks before cur_data_block_idx_ are not pinned anymore.
+      assert(multi_scan_->cur_data_block_idx < block_idx);
+    }
+
+    ResetDataIter();
+
+    if (MultiScanLoadDataBlock(block_idx)) {
+      return;
+    }
+  }
+  multi_scan_->cur_data_block_idx = block_idx;
+  block_iter_points_to_real_block_ = true;
+  block_iter_.Seek(*seek_target);
+  FindKeyForward();
+}
+
+void BlockBasedTableIterator::UnpinPreviousScanBlocks(size_t current_scan_idx) {
+  // TODO: support aborting and clearn up async IO requests, currently
+  // only unpins already initialized blocks
+  assert(multi_scan_);
+  assert(current_scan_idx < multi_scan_->block_index_ranges_per_scan.size());
+  if (current_scan_idx == 0) return;
+
+  auto prev_start_block_idx = std::get<0>(
+      multi_scan_->block_index_ranges_per_scan[current_scan_idx - 1]);
+  // Since a block can be shared between consecutive scans, we need
+  // curr_start_block_idx here instead of just release blocks
+  // up to the end of previous range block index.
+  auto curr_start_block_idx =
+      std::get<0>(multi_scan_->block_index_ranges_per_scan[current_scan_idx]);
+  for (size_t block_idx = prev_start_block_idx;
+       block_idx < curr_start_block_idx; ++block_idx) {
+    if (!multi_scan_->pinned_data_blocks[block_idx].IsEmpty()) {
+      multi_scan_->pinned_data_blocks[block_idx].Reset();
+    }
+  }
+}
 
-      const auto& last_end_key = (*scan_opts)[i - 1].range.limit.value();
-      if (user_comparator_.Compare(scan_range.start.value(), last_end_key) <
-          0) {
-        // Abort: overlapping ranges
+void BlockBasedTableIterator::FindBlockForwardInMultiScan() {
+  assert(multi_scan_);
+  assert(multi_scan_->next_scan_idx >= 1);
+  const auto cur_scan_end_idx = std::get<1>(
+      multi_scan_->block_index_ranges_per_scan[multi_scan_->next_scan_idx - 1]);
+  do {
+    if (!block_iter_.status().ok()) {
+      return;
+    }
+
+    // If is_out_of_bound_ is true, upper layer (LevelIterator) considers this
+    // level has reached iterate_upper_bound_ and will not continue to iterate
+    // into the next file. When we are doing the last scan within a MultiScan
+    // for this file, it may need to continue to scan into the next file, so
+    // we do not set is_out_of_bound_ in this case.
+    if (multi_scan_->cur_data_block_idx + 1 >= cur_scan_end_idx) {
+      if (multi_scan_->next_scan_idx >=
+          multi_scan_->block_index_ranges_per_scan.size()) {
+        // We are done with this file, should let LevelIter advance to the
+        // next file instead of ending the scan
+        ResetDataIter();
+        assert(!is_out_of_bound_);
+        assert(!Valid());
         return;
       }
+      // We don't ResetDataIter() here since next scan might be reading from
+      // the same block. ResetDataIter() will free the underlying block cache
+      // handle and we don't want the block to be unpinned.
+      is_out_of_bound_ = true;
+      assert(!Valid());
+      return;
+    }
+    // Move to the next pinned data block
+    ResetDataIter();
+    ++multi_scan_->cur_data_block_idx;
+
+    if (MultiScanLoadDataBlock(multi_scan_->cur_data_block_idx)) {
+      return;
     }
+
+    block_iter_points_to_real_block_ = true;
+    block_iter_.SeekToFirst();
+  } while (!block_iter_.Valid());
+}
+
+Status BlockBasedTableIterator::PollForBlock(size_t idx) {
+  assert(multi_scan_);
+  const auto async_idx = multi_scan_->block_idx_to_readreq_idx.find(idx);
+  if (async_idx == multi_scan_->block_idx_to_readreq_idx.end()) {
+    // Did not require async read, should already be pinned.
+    assert(multi_scan_->pinned_data_blocks[idx].GetValue());
+    return Status::OK();
   }
 
-  // Gather all relevant data block handles
-  std::vector<BlockHandle> blocks_to_prepare;
-  Status s;
-  std::vector<std::tuple<size_t, size_t>> block_ranges_per_scan;
-  for (const auto& scan_opt : *scan_opts) {
-    size_t num_blocks = 0;
-    // Current scan overlap the last block of the previous scan.
-    bool check_overlap = !blocks_to_prepare.empty();
+  AsyncReadState& async_read = multi_scan_->async_states[async_idx->second];
+  if (async_read.finished) {
+    assert(async_read.io_handle == nullptr);
+    assert(async_read.status.ok());
+    return async_read.status;
+  }
+
+  {
+    std::vector<void*> handles = {async_read.io_handle};
+    Status poll_s =
+        table_->get_rep()->ioptions.env->GetFileSystem()->Poll(handles, 1);
+    if (!poll_s.ok()) {
+      return poll_s;
+    }
+  }
+  assert(async_read.status.ok());
+  if (!async_read.status.ok()) {
+    return async_read.status;
+  }
+  async_read.CleanUpIOHandle();
+
+  // Initialize and pin blocks from async read result.
+  for (size_t i = 0; i < async_read.blocks.size(); ++i) {
+    const auto& block = async_read.blocks[i];
+
+    Status s = CreateAndPinBlockFromBuffer(
+        block, async_read.offset, async_read.result,
+        multi_scan_->pinned_data_blocks[async_read.block_indices[i]]);
+
+    if (!s.ok()) {
+      return s;
+    }
+    assert(multi_scan_->pinned_data_blocks[async_read.block_indices[i]]
+               .GetValue());
+  }
+  assert(multi_scan_->pinned_data_blocks[idx].GetValue());
+  return Status::OK();
+}
+
+Status BlockBasedTableIterator::CreateAndPinBlockFromBuffer(
+    const BlockHandle& block, uint64_t buffer_start_offset,
+    const Slice& buffer_data, CachableEntry<Block>& pinned_block_entry) {
+  // Get decompressor and handle dictionary loading
+  UnownedPtr<Decompressor> decompressor = table_->get_rep()->decompressor.get();
+  CachableEntry<DecompressorDict> cached_dict;
+
+  if (table_->get_rep()->uncompression_dict_reader) {
+    {
+      Status s =
+          table_->get_rep()
+              ->uncompression_dict_reader->GetOrReadUncompressionDictionary(
+                  /* prefetch_buffer= */ nullptr, read_options_,
+                  /* get_context= */ nullptr, /* lookup_context= */ nullptr,
+                  &cached_dict);
+      if (!s.ok()) {
+#ifndef NDEBUG
+        fprintf(stdout, "Prepare dictionary loading failed with %s\n",
+                s.ToString().c_str());
+#endif
+        return s;
+      }
+    }
+    if (!cached_dict.GetValue()) {
+#ifndef NDEBUG
+      fprintf(stdout, "Success but no dictionary read\n");
+#endif
+      return Status::InvalidArgument("No dictionary found");
+    }
+    decompressor = cached_dict.GetValue()->decompressor_.get();
+  }
+
+  // Create block from buffer data
+  const auto block_size_with_trailer =
+      BlockBasedTable::BlockSizeWithTrailer(block);
+  const auto block_offset_in_buffer = block.offset() - buffer_start_offset;
+
+  CacheAllocationPtr data =
+      AllocateBlock(block_size_with_trailer,
+                    GetMemoryAllocator(table_->get_rep()->table_options));
+  memcpy(data.get(), buffer_data.data() + block_offset_in_buffer,
+         block_size_with_trailer);
+  BlockContents tmp_contents(std::move(data), block.size());
+
+#ifndef NDEBUG
+  tmp_contents.has_trailer =
+      table_->get_rep()->footer.GetBlockTrailerSize() > 0;
+#endif
 
-    // Scan range is specified in user key, here we seek to the minimum internal
-    // key with this user key.
-    InternalKey start_key(scan_opt.range.start.value(), kMaxSequenceNumber,
-                          kValueTypeForSeek);
+  return table_->CreateAndPinBlockInCache<Block_kData>(
+      read_options_, block, decompressor, &tmp_contents,
+      &pinned_block_entry.As<Block_kData>());
+}
+
+constexpr auto kVerbose = false;
+
+Status BlockBasedTableIterator::CollectBlockHandles(
+    const std::vector<ScanOptions>& scan_opts,
+    std::vector<BlockHandle>* scan_block_handles,
+    std::vector<std::tuple<size_t, size_t>>* block_index_ranges_per_scan,
+    std::vector<std::string>* data_block_separators) {
+  // print file name and level
+  if (kVerbose) {
+    auto file_name = table_->get_rep()->file->file_name();
+    auto level = table_->get_rep()->level;
+    printf("file name : %s, level %d\n", file_name.c_str(), level);
+  }
+  for (const auto& scan_opt : scan_opts) {
+    size_t num_blocks = 0;
+    bool check_overlap = !scan_block_handles->empty();
+
+    InternalKey start_key;
+    const size_t timestamp_size =
+        user_comparator_.user_comparator()->timestamp_size();
+    if (timestamp_size == 0) {
+      start_key = InternalKey(scan_opt.range.start.value(), kMaxSequenceNumber,
+                              kValueTypeForSeek);
+    } else {
+      std::string seek_key;
+      AppendKeyWithMaxTimestamp(&seek_key, scan_opt.range.start.value(),
+                                timestamp_size);
+      start_key = InternalKey(seek_key, kMaxSequenceNumber, kValueTypeForSeek);
+    }
     index_iter_->Seek(start_key.Encode());
-    while (index_iter_->Valid() &&
+    while (index_iter_->status().ok() && index_iter_->Valid() &&
            (!scan_opt.range.limit.has_value() ||
-            user_comparator_.CompareWithoutTimestamp(
-                index_iter_->user_key(),
-                /*a_has_ts*/ true, *scan_opt.range.limit,
-                /*b_has_ts=*/false) <= 0)) {
+            user_comparator_.CompareWithoutTimestamp(index_iter_->user_key(),
+                                                     /*a_has_ts*/ true,
+                                                     *scan_opt.range.limit,
+                                                     /*b_has_ts=*/false) < 0)) {
+      // Only add the block if the index separator is smaller than limit. When
+      // they are equal or larger, it will be handled later below.
       if (check_overlap &&
-          blocks_to_prepare.back() == index_iter_->value().handle) {
+          scan_block_handles->back() == index_iter_->value().handle) {
         // Skip the current block since it's already in the list
       } else {
-        blocks_to_prepare.push_back(index_iter_->value().handle);
+        scan_block_handles->push_back(index_iter_->value().handle);
+        // clone the Slice to avoid the lifetime issue
+        data_block_separators->push_back(index_iter_->user_key().ToString());
       }
       ++num_blocks;
       index_iter_->Next();
       check_overlap = false;
     }
-    // Stop until index->key > limit
-    // Include the current block since it can still contain keys <= limit
+
+    if (!index_iter_->status().ok()) {
+      // Abort: index iterator error
+      return index_iter_->status();
+    }
+
     if (index_iter_->Valid()) {
+      // Handle the last block when its separator is equal or larger than limit
       if (check_overlap &&
-          blocks_to_prepare.back() == index_iter_->value().handle) {
+          scan_block_handles->back() == index_iter_->value().handle) {
         // Skip adding the current block since it's already in the list
       } else {
-        blocks_to_prepare.push_back(index_iter_->value().handle);
+        scan_block_handles->push_back(index_iter_->value().handle);
+        data_block_separators->push_back(index_iter_->user_key().ToString());
       }
       ++num_blocks;
     }
-
-    if (!index_iter_->status().ok()) {
-      // Abort: index iterator error
-      return;
+    block_index_ranges_per_scan->emplace_back(
+        scan_block_handles->size() - num_blocks, scan_block_handles->size());
+    if (kVerbose) {
+      printf("separators :");
+      for (const auto& separator : *data_block_separators) {
+        printf("%s, ", separator.c_str());
+      }
+      printf("\n");
     }
-
-    block_ranges_per_scan.emplace_back(blocks_to_prepare.size() - num_blocks,
-                                       blocks_to_prepare.size());
   }
+  return Status::OK();
+}
 
-  // blocks_to_prepare has all the blocks that need to be read.
-  // Look up entries in cache and pin if exist.
-  // Store indices of blocks to read.
-  std::vector<size_t> blocks_to_read;
-  std::vector<CachableEntry<Block>> pinned_data_blocks_guard;
-  pinned_data_blocks_guard.resize(blocks_to_prepare.size());
-  for (size_t i = 0; i < blocks_to_prepare.size(); ++i) {
-    const auto& data_block_handle = blocks_to_prepare[i];
-    s = table_->LookupAndPinBlocksInCache<Block_kData>(
+Status BlockBasedTableIterator::FilterAndPinCachedBlocks(
+    const std::vector<BlockHandle>& scan_block_handles,
+    const MultiScanArgs* multiscan_opts,
+    std::vector<size_t>* block_indices_to_read,
+    std::vector<CachableEntry<Block>>* pinned_data_blocks_guard,
+    size_t* prefetched_max_idx) {
+  uint64_t total_prefetch_size = 0;
+  *prefetched_max_idx = scan_block_handles.size();
+
+  for (size_t i = 0; i < scan_block_handles.size(); ++i) {
+    const auto& data_block_handle = scan_block_handles[i];
+
+    total_prefetch_size +=
+        BlockBasedTable::BlockSizeWithTrailer(data_block_handle);
+    if (multiscan_opts->max_prefetch_size > 0 &&
+        total_prefetch_size > multiscan_opts->max_prefetch_size) {
+      for (size_t j = i; j < scan_block_handles.size(); ++j) {
+        assert((*pinned_data_blocks_guard)[j].IsEmpty());
+      }
+      *prefetched_max_idx = i;
+      break;
+    }
+
+    Status s = table_->LookupAndPinBlocksInCache<Block_kData>(
         read_options_, data_block_handle,
-        &pinned_data_blocks_guard[i].As<Block_kData>());
+        &(*pinned_data_blocks_guard)[i].As<Block_kData>());
 
     if (!s.ok()) {
       // Abort: block cache look up failed.
-      return;
+      return s;
     }
-    if (!pinned_data_blocks_guard[i].GetValue()) {
-      // Block not in cache, will read it below.
-      blocks_to_read.emplace_back(i);
+    if (!(*pinned_data_blocks_guard)[i].GetValue()) {
+      // Block not in cache
+      block_indices_to_read->emplace_back(i);
     }
   }
+  return Status::OK();
+}
 
-  // Coalesce IOs
-  // TODO: limit prefetching size to bound memory usage.
-  if (!blocks_to_read.empty()) {
-    // Each vector correspond to blocks to read in a single read request.
-    // Each member in the vector is an index into blocks_to_prepare.
-    std::vector<std::vector<size_t>> collapsed_blocks_to_read(1);
-
-    // TODO: make this threshold configurable
-    constexpr size_t kCoalesceThreshold = 16 << 10;  // 16KB
-
-    for (const auto& block_idx : blocks_to_read) {
-      if (!collapsed_blocks_to_read.back().empty()) {
-        // Check if we can coalesce.
-        const auto& last_block =
-            blocks_to_prepare[collapsed_blocks_to_read.back().back()];
-        uint64_t last_block_end =
-            last_block.offset() +
-            BlockBasedTable::BlockSizeWithTrailer(last_block);
-        uint64_t current_start = blocks_to_prepare[block_idx].offset();
+void BlockBasedTableIterator::PrepareIORequests(
+    const std::vector<size_t>& block_indices_to_read,
+    const std::vector<BlockHandle>& scan_block_handles,
+    const MultiScanArgs* multiscan_opts, std::vector<FSReadRequest>* read_reqs,
+    UnorderedMap<size_t, size_t>* block_idx_to_readreq_idx,
+    std::vector<std::vector<size_t>>* coalesced_block_indices) {
+  assert(coalesced_block_indices->empty());
+  coalesced_block_indices->resize(1);
+
+  for (const auto& block_idx : block_indices_to_read) {
+    if (!coalesced_block_indices->back().empty()) {
+      // Check if we can coalesce.
+      const auto& last_block_handle =
+          scan_block_handles[coalesced_block_indices->back().back()];
+      uint64_t last_block_end =
+          last_block_handle.offset() +
+          BlockBasedTable::BlockSizeWithTrailer(last_block_handle);
+      uint64_t current_start = scan_block_handles[block_idx].offset();
+
+      if (current_start >
+          last_block_end + multiscan_opts->io_coalesce_threshold) {
+        // new IO
+        coalesced_block_indices->emplace_back();
+      }
+    }
+    coalesced_block_indices->back().emplace_back(block_idx);
+  }
 
-        if (current_start > last_block_end + kCoalesceThreshold) {
-          // new IO
-          collapsed_blocks_to_read.emplace_back();
+  assert(read_reqs->empty());
+  read_reqs->reserve(coalesced_block_indices->size());
+  for (const auto& block_indices : *coalesced_block_indices) {
+    assert(block_indices.size());
+    const auto& first_block_handle = scan_block_handles[block_indices[0]];
+    const auto& last_block_handle = scan_block_handles[block_indices.back()];
+
+    const auto start_offset = first_block_handle.offset();
+    const auto end_offset =
+        last_block_handle.offset() +
+        BlockBasedTable::BlockSizeWithTrailer(last_block_handle);
+#ifndef NDEBUG
+    // Debug print for failing the assertion below.
+    if (start_offset >= end_offset) {
+      fprintf(stderr, "scan_block_handles: ");
+      for (const auto& block : scan_block_handles) {
+        fprintf(stderr, "offset: %" PRIu64 ", size: %" PRIu64 "; ",
+                block.offset(), block.size());
+      }
+      fprintf(stderr,
+              "\nfirst block - offset: %" PRIu64 ", size: %" PRIu64 "\n",
+              first_block_handle.offset(), first_block_handle.size());
+      fprintf(stderr, "last block - offset: %" PRIu64 ", size: %" PRIu64 "\n",
+              last_block_handle.offset(), last_block_handle.size());
+
+      fprintf(stderr, "coalesced_block_indices: ");
+      for (const auto& b : *coalesced_block_indices) {
+        fprintf(stderr, "[");
+        for (const auto& block_idx : b) {
+          fprintf(stderr, "%zu ", block_idx);
         }
+        fprintf(stderr, "] ");
       }
-      collapsed_blocks_to_read.back().emplace_back(block_idx);
+      fprintf(stderr, "\ncurrent blocks: ");
+      for (const auto& block_idx : block_indices) {
+        fprintf(stderr, "offset: %" PRIu64 ", size: %" PRIu64 "; ",
+                scan_block_handles[block_idx].offset(),
+                scan_block_handles[block_idx].size());
+      }
+      fprintf(stderr, "\n");
     }
+#endif  // NDEBUG
+    assert(end_offset > start_offset);
 
-    // do IO
-    IOOptions io_opts;
-    s = table_->get_rep()->file->PrepareIOOptions(read_options_, io_opts);
-    if (!s.ok()) {
-      // Abort: PrepareIOOptions failed
-      return;
+    read_reqs->emplace_back();
+    read_reqs->back().offset = start_offset;
+    read_reqs->back().len = end_offset - start_offset;
+
+    if (multiscan_opts->use_async_io) {
+      for (const auto& block_idx : block_indices) {
+        (*block_idx_to_readreq_idx)[block_idx] = read_reqs->size() - 1;
+      }
     }
+  }
+}
 
-    // Init read requests for Multi-Read
-    std::vector<FSReadRequest> read_reqs;
-    read_reqs.reserve(collapsed_blocks_to_read.size());
-    size_t total_len = 0;
-    for (const auto& blocks : collapsed_blocks_to_read) {
-      assert(blocks.size());
-      const auto& first_block = blocks_to_prepare[blocks[0]];
-      const auto& last_block = blocks_to_prepare[blocks.back()];
-
-      const auto start_offset = first_block.offset();
-      const auto end_offset = last_block.offset() +
-                              BlockBasedTable::BlockSizeWithTrailer(last_block);
-      assert(end_offset > start_offset);
-      FSReadRequest read_req;
-      read_req.offset = start_offset;
-      read_req.len = end_offset - start_offset;
-      total_len += read_req.len;
-      read_reqs.emplace_back(std::move(read_req));
-    }
-
-    // Init buffer for read
+Status BlockBasedTableIterator::ExecuteIO(
+    const std::vector<BlockHandle>& scan_block_handles,
+    const MultiScanArgs* multiscan_opts,
+    const std::vector<std::vector<size_t>>& coalesced_block_indices,
+    std::vector<FSReadRequest>* read_reqs,
+    std::vector<AsyncReadState>* async_states,
+    std::vector<CachableEntry<Block>>* pinned_data_blocks_guard) {
+  IOOptions io_opts;
+  Status s;
+  s = table_->get_rep()->file->PrepareIOOptions(read_options_, io_opts);
+  if (!s.ok()) {
+    // Abort: PrepareIOOptions failed
+    return s;
+  }
+  const bool direct_io = table_->get_rep()->file->use_direct_io();
+
+  if (multiscan_opts->use_async_io) {
+    async_states->resize(read_reqs->size());
+    for (size_t i = 0; i < read_reqs->size(); ++i) {
+      auto& read_req = (*read_reqs)[i];
+      auto& async_read = (*async_states)[i];
+
+      async_read.finished = false;
+      async_read.offset = read_req.offset;
+      async_read.block_indices = coalesced_block_indices[i];
+      for (const auto idx : coalesced_block_indices[i]) {
+        async_read.blocks.emplace_back(scan_block_handles[idx]);
+      }
+
+      if (direct_io) {
+        read_req.scratch = nullptr;
+      } else {
+        async_read.buf.reset(new char[read_req.len]);
+        read_req.scratch = async_read.buf.get();
+      }
+
+      auto cb = std::bind(&BlockBasedTableIterator::PrepareReadAsyncCallBack,
+                          this, std::placeholders::_1, std::placeholders::_2);
+      // TODO: for mmap, io_handle will not be set but callback will already
+      // be called.
+      s = table_->get_rep()->file.get()->ReadAsync(
+          read_req, io_opts, cb, &async_read, &async_read.io_handle,
+          &async_read.del_fn, direct_io ? &async_read.aligned_buf : nullptr);
+      if (!s.ok()) {
+#ifndef NDEBUG
+        fprintf(stderr, "ReadAsync failed with %s\n", s.ToString().c_str());
+#endif
+        assert(false);
+        return s;
+      }
+      assert(async_read.io_handle);
+      for (auto& req : *read_reqs) {
+        if (!req.status.ok()) {
+          assert(false);
+          // Silence compiler warning about NRVO
+          s = req.status;
+          return s;
+        }
+      }
+    }
+  } else {
+    // Synchronous IO using MultiRead
     std::unique_ptr<char[]> buf;
-    const bool direct_io = table_->get_rep()->file->use_direct_io();
+
     if (direct_io) {
-      for (auto& read_req : read_reqs) {
+      for (auto& read_req : *read_reqs) {
         read_req.scratch = nullptr;
       }
     } else {
       // TODO: optimize if FSSupportedOps::kFSBuffer is supported.
+      size_t total_len = 0;
+      for (const auto& req : *read_reqs) {
+        total_len += req.len;
+      }
       buf.reset(new char[total_len]);
       size_t offset = 0;
-      for (auto& read_req : read_reqs) {
+      for (auto& read_req : *read_reqs) {
         read_req.scratch = buf.get() + offset;
         offset += read_req.len;
       }
     }
 
     AlignedBuf aligned_buf;
-    s = table_->get_rep()->file.get()->MultiRead(
-        io_opts, read_reqs.data(), read_reqs.size(),
-        direct_io ? &aligned_buf : nullptr);
+    s = table_->get_rep()->file->MultiRead(io_opts, read_reqs->data(),
+                                           read_reqs->size(),
+                                           direct_io ? &aligned_buf : nullptr);
     if (!s.ok()) {
-      return;
+      return s;
     }
-    for (auto& req : read_reqs) {
+    for (auto& req : *read_reqs) {
       if (!req.status.ok()) {
-        return;
+        // Silence compiler warning about NRVO
+        s = req.status;
+        return s;
       }
     }
 
     // Init blocks and pin them in block cache.
-    MemoryAllocator* memory_allocator =
-        table_->get_rep()->table_options.block_cache->memory_allocator();
-    for (size_t i = 0; i < collapsed_blocks_to_read.size(); i++) {
-      const auto& blocks = collapsed_blocks_to_read[i];
-      const auto& read_req = read_reqs[i];
-      for (const auto& block_idx : blocks) {
-        const auto& block = blocks_to_prepare[block_idx];
-        const auto block_size_with_trailer =
-            BlockBasedTable::BlockSizeWithTrailer(block);
-        const auto block_offset_in_buffer = block.offset() - read_req.offset;
-
-        CacheAllocationPtr data =
-            AllocateBlock(block_size_with_trailer, memory_allocator);
-        memcpy(data.get(), read_req.result.data() + block_offset_in_buffer,
-               block_size_with_trailer);
-        BlockContents tmp_contents(std::move(data), block.size());
-
-#ifndef NDEBUG
-        tmp_contents.has_trailer =
-            table_->get_rep()->footer.GetBlockTrailerSize() > 0;
-#endif
-        assert(pinned_data_blocks_guard[block_idx].IsEmpty());
-        s = table_->CreateAndPinBlockInCache<Block_kData>(
-            read_options_, block, &tmp_contents,
-            &(pinned_data_blocks_guard[block_idx].As<Block_kData>()));
+    assert(read_reqs->size() == coalesced_block_indices.size());
+    for (size_t i = 0; i < coalesced_block_indices.size(); i++) {
+      const auto& read_req = (*read_reqs)[i];
+      for (const auto& block_idx : coalesced_block_indices[i]) {
+        const auto& block = scan_block_handles[block_idx];
+
+        assert((*pinned_data_blocks_guard)[block_idx].IsEmpty());
+        s = CreateAndPinBlockFromBuffer(block, read_req.offset, read_req.result,
+                                        (*pinned_data_blocks_guard)[block_idx]);
         if (!s.ok()) {
+          assert(false);
           // Abort: failed to create and pin block in cache
-          return;
+          return s;
         }
+        assert((*pinned_data_blocks_guard)[block_idx].GetValue());
       }
     }
   }
-
-  // Successful Prepare, init related states so the iterator reads from prepared
-  // blocks
-  multi_scan_.reset(new MultiScanState(scan_opts,
-                                       std::move(pinned_data_blocks_guard),
-                                       std::move(block_ranges_per_scan)));
-  is_index_at_curr_block_ = false;
-  block_iter_points_to_real_block_ = false;
+  return s;
 }
 
-bool BlockBasedTableIterator::SeekMultiScan(const Slice* target) {
-  assert(multi_scan_);
-  // This is a MultiScan and Preapre() has been called.
-  //
-  // Validate seek key with scan options
-  if (multi_scan_->next_scan_idx >= multi_scan_->scan_opts->size()) {
-    multi_scan_.reset();
-  } else if (!target) {
-    // start key must be set for multi-scan
-    multi_scan_.reset();
-  } else if (user_comparator_.CompareWithoutTimestamp(
-                 ExtractUserKey(*target), /*a_has_ts=*/true,
-                 (*multi_scan_->scan_opts)[multi_scan_->next_scan_idx]
-                     .range.start.value(),
-                 /*b_has_ts=*/false) != 0) {
-    // Unexpected seek key
-    multi_scan_.reset();
-  } else {
-    auto [cur_scan_start_idx, cur_scan_end_idx] =
-        multi_scan_->block_ranges_per_scan[multi_scan_->next_scan_idx];
-    // We should have the data block already loaded
-    ++multi_scan_->next_scan_idx;
-    if (cur_scan_start_idx >= cur_scan_end_idx) {
-      is_out_of_bound_ = true;
-      assert(!Valid());
-      return true;
-    } else {
-      is_out_of_bound_ = false;
-    }
-
-    if (!block_iter_points_to_real_block_ ||
-        multi_scan_->cur_data_block_idx != cur_scan_start_idx) {
-      if (block_iter_points_to_real_block_) {
-        // Should be scan in increasing key range.
-        // All blocks before cur_data_block_idx_ are not pinned anymore.
-        assert(multi_scan_->cur_data_block_idx < cur_scan_start_idx);
-      }
-
-      ResetDataIter();
-      // Note that the block_iter_ takes ownership of the pinned data block
-      // TODO: we can delegate the clean up like with pinned_iters_mgr_ if
-      // need to pin blocks longer.
-      table_->NewDataBlockIterator<DataBlockIter>(
-          read_options_, multi_scan_->pinned_data_blocks[cur_scan_start_idx],
-          &block_iter_, Status::OK());
-    }
-    multi_scan_->cur_data_block_idx = cur_scan_start_idx;
-    block_iter_points_to_real_block_ = true;
-    block_iter_.Seek(*target);
-    FindKeyForward();
-    return true;
-  }
-
-  return false;
-}
-
-void BlockBasedTableIterator::FindBlockForwardInMultiScan() {
-  assert(multi_scan_);
-  assert(multi_scan_->next_scan_idx >= 1);
-  const auto cur_scan_end_idx = std::get<1>(
-      multi_scan_->block_ranges_per_scan[multi_scan_->next_scan_idx - 1]);
-  do {
-    if (!block_iter_.status().ok()) {
-      return;
-    }
-
-    if (multi_scan_->cur_data_block_idx + 1 >= cur_scan_end_idx) {
-      // We don't ResetDataIter() here since next scan might be reading from
-      // the same block. ResetDataIter() will free the underlying block cache
-      // handle and we don't want the block to be unpinned.
-      is_out_of_bound_ = true;
-      assert(!Valid());
-      return;
-    }
-    // Move to the next pinned data block
-    ResetDataIter();
-    ++multi_scan_->cur_data_block_idx;
-    table_->NewDataBlockIterator<DataBlockIter>(
-        read_options_,
-        multi_scan_->pinned_data_blocks[multi_scan_->cur_data_block_idx],
-        &block_iter_, Status::OK());
-    block_iter_points_to_real_block_ = true;
-    block_iter_.SeekToFirst();
-  } while (!block_iter_.Valid());
-}
 }  // namespace ROCKSDB_NAMESPACE