Add Prepare interface to user defined index iterator (facebook#13728)

Summary:
Pull Request resolved: facebook#13728

The Prepare interface allows the user defined index iterator to prefetch index entries, as well as take custom scan termination criteria specified in the property_bag into account.

Reviewed By: pdillinger

Differential Revision: D76165546

fbshipit-source-id: 83d628598924aa7a60dff7ed62a16ae575b2c8ec

Author: anand1976

include/rocksdb/iterator.h

@@ -95,14 +95,18 @@ class Iterator : public IteratorBase {
     return Slice();
   }
 
-  // RocksDB Internal - DO NOT USE
-  // Prepare the iterator to scan the ranges specified in scan_opts. The
-  // upper bound and other table specific limits may be specified. This will
-  // typically be followed by Seeks to the start keys in the order they're
-  // specified in scan_opts. If the user does a Seek to some other target key,
-  // the iterator should disregard the scan_opts from that point onwards and
-  // behave like a normal iterator. Its the user's responsibility to again
-  // call Prepare().
+  // Prepare the iterator to scan the ranges specified in scan_opts. This
+  // includes prefetching relevant blocks from disk. The upper bound and
+  // other table specific limits should be specified for each
+  // scan for best results. If an upper bound is not specified, Prepare may
+  // skip prefetching as it cannot accurately determine how much to prefetch.
+  //
+  // Prepare should typically be followed by Seeks to the start keys in the
+  // order they're specified in scan_opts. If the user does a Seek to some
+  // other target key, the iterator should disregard the scan_opts from that
+  // point onwards and behave like a normal iterator. Its the user's
+  // responsibility to again call Prepare().
+  //
   // If Prepare() is called, it overrides the iterate_upper_bound in
   // ReadOptions
   virtual void Prepare(const std::vector<ScanOptions>& /*scan_opts*/) {}

include/rocksdb/user_defined_index.h

@@ -89,6 +89,10 @@ class UserDefinedIndexIterator {
  public:
   virtual ~UserDefinedIndexIterator() = default;
 
+  // Prepare the iterator for a series of scans. The iterator should use
+  // this as an opportunity to do any prefetching and buffering of results.
+  virtual void Prepare(const ScanOptions scan_opts[], size_t num_opts) = 0;
+
   // Given the target key, position the index iterator at the index entry
   // with the smallest key >= target. The result must be updated with the
   // index key, and the bound_check_result. The bound_check_result should

table/block_based/block_based_table_iterator.h

@@ -222,6 +222,10 @@ class BlockBasedTableIterator : public InternalIteratorBase<Slice> {
     }
   }
 
+  void Prepare(const std::vector<ScanOptions>* scan_opts) override {
+    index_iter_->Prepare(scan_opts);
+  }
+
   FilePrefetchBuffer* prefetch_buffer() {
     return block_prefetcher_.prefetch_buffer();
   }

table/block_based/user_defined_index_wrapper.h

@@ -181,6 +181,10 @@ class UserDefinedIndexIteratorWrapper
 
   Status status() const override { return status_; }
 
+  void Prepare(const std::vector<ScanOptions>* scan_opts) override {
+    udi_iter_->Prepare(scan_opts->data(), scan_opts->size());
+  }
+
  private:
   std::unique_ptr<UserDefinedIndexIterator> udi_iter_;
   IterateResult result_;