@nxtedition/rocksdb 13.5.8 → 13.5.9

package/deps/rocksdb/rocksdb/include/rocksdb/external_table.h

@@ -0,0 +1,275 @@
+//  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 "rocksdb/advanced_iterator.h"
+#include "rocksdb/customizable.h"
+#include "rocksdb/file_checksum.h"
+#include "rocksdb/file_system.h"
+#include "rocksdb/iterator_base.h"
+#include "rocksdb/options.h"
+#include "rocksdb/status.h"
+
+namespace ROCKSDB_NAMESPACE {
+
+class ExternalTableFactory;
+
+// EXPERIMENTAL
+// The interface defined in this file is subject to change at any time without
+// warning!!
+
+// This file defines an interface for plugging in an external table
+// into RocksDB. The external table reader will be used instead of the
+// BlockBasedTable to load and query sst files.
+// The external table files can be created using an SstFileWriter. Eventually
+// external tables will be allowed to be ingested into a RocksDB instance
+// using the IngestExternalFIle() API.
+//
+// Initial support is for writing and querying the files using an
+// SstFileWriter and SstFileReader. We will add support for ingestion of an
+// external table into a limited RocksDB instance that only supports ingestion
+// and not live writes in the near future. It'll be followed by support for
+// replacing the column family by ingesting a new set of files. In all cases,
+// the external table files will only be allowed in the bottommost level.
+//
+// The external table can support one or both of the following layouts -
+// 1. Total order seek - All the keys in the files are in sorted order, and a
+//    user can seek to the first, last, or any key in between and iterate
+//    forwards or backwards till the end of the range. To support this mode,
+//    the implementation needs to use the comparator passed in
+//    ExternalTableOptions to enforce the key ordering. The prefix_extractor
+//    in ExternalTableOptions and the ExternalTableReader interfaces can be
+//    ignored.
+// 2. Prefix seek - In this mode, the prefix_extractor is used to extract the
+//    prefix from a key. All the keys sharing the same prefix are ordered in
+//    ascending order according to the comparator. However, no specific
+//    ordering is required across prefixes. Users can scan keys by seeking
+//    to a specific key inside a prefix, and iterate forwards or backwards
+//    within the prefix. The prefix_same_as_start flag in ReadOptions will
+//    be true.
+// 3. Both - If supporting both of the above, a user can seek inside a prefix
+//    and iterate beyond the prefix. The prefix_same_as_start in ReadOptions
+//    will be false. Additionally, the total_order_seek flag can be set to
+//    true to seek to the first non-empty prefix (as determined by the key
+//    order) if the seek prefix is empty.
+//
+// Many of the options in ReadOptions and WriteOptions may not be relevant to
+// the external table implementation.
+// TODO: Specify which options are relevant
+
+class ExternalTableIterator : public IteratorBase {
+ public:
+  virtual ~ExternalTableIterator() {}
+
+  // This can optionally be called to prepare the iterator for a series
+  // of scans. The scan_opts parameter specifies the order of scans to
+  // follow, as well as the limits for those scans. After calling this,
+  // the caller will Seek() the iterator to successive start keys in scan_opts.
+  //
+  // If Prepare() is called again with a different scan_opts pointer, it
+  // means the iterator will be reused for a new multi scan. If scan_opts
+  // is null, then the previous Prepare() can be discarded.
+  //
+  // The caller guarantees the lifetime of scan_opts until its either cleared
+  // or replaced by another Prepare().
+  // TODO: Update the contract to trim the scan_opts range to only include
+  // scans that potentially intersect the file key range.
+  //
+  // If the sequence of Seeks is interrupted by seeking to some other target
+  // key, then the iterator is free to discard anything done during Prepare.
+  virtual void Prepare(const ScanOptions scan_opts[], size_t num_opts) = 0;
+
+  // Similar to Next(), except it also fills the result and returns whether
+  // the iterator is on a valid key or not
+  virtual bool NextAndGetResult(IterateResult* result) = 0;
+
+  // Prepares the value if its lazily materialized. The implementation can
+  // request that this be called by setting value_prepared to false in
+  // IterateResult. Next() should always implicitly materialize the
+  // value.
+  bool PrepareValue() override = 0;
+
+  // Return the current key's value
+  virtual Slice value() const = 0;
+
+  // Return the current position bounds check result - kInbound if the
+  // position is a valid key, kOutOfBound if the key is out of bound (i.e
+  // scan has terminated), or kUnknown if end of file.
+  virtual IterBoundCheck UpperBoundCheckResult() = 0;
+};
+
+class ExternalTableReader {
+ public:
+  virtual ~ExternalTableReader() {}
+
+  // Return an Iterator that can be used to scan the table file.
+  // The read_options can optionally contain the upper bound
+  // key (exclusive) of the scan in iterate_upper_bound.
+  virtual ExternalTableIterator* NewIterator(
+      const ReadOptions& read_options,
+      const SliceTransform* prefix_extractor) = 0;
+
+  // Point lookup the given key and return its value
+  virtual Status Get(const ReadOptions& read_options, const Slice& key,
+                     const SliceTransform* prefix_extractor,
+                     std::string* value) = 0;
+
+  // Point lookup the given vector of keys and return the values, as well
+  // as status of each individual lookup in statuses.
+  virtual void MultiGet(const ReadOptions& read_options,
+                        const std::vector<Slice>& keys,
+                        const SliceTransform* prefix_extractor,
+                        std::vector<std::string>* values,
+                        std::vector<Status>* statuses) = 0;
+
+  // Allocate and return the contents of the properties block. If the builder
+  // supports PutPropertiesBlock(), then this must be supported. The
+  // properties block should be written to the table file as is (no
+  // compression or mutation of any kind), and its offset in the file
+  // should be returned in file_offset.
+  virtual Status GetPropertiesBlock(std::unique_ptr<char[]>* /*property_block*/,
+                                    uint64_t* /*size*/,
+                                    uint64_t* /*file_offset*/) {
+    return Status::NotSupported();
+  }
+
+  // Return TableProperties for the file. At a minimum, the following
+  // properties need to be returned -
+  // comparator_name
+  // num_entries
+  // raw_key_size
+  // raw_value_size
+  virtual std::shared_ptr<const TableProperties> GetTableProperties() const = 0;
+
+  virtual Status VerifyChecksum(const ReadOptions& /*ro*/) {
+    return Status::NotSupported("VerifyChecksum() not supported");
+  }
+};
+
+// A table builder interface that can be used by SstFileWriter to allow
+// RocksDB users to write external table files. The sequence of operations
+// to write an external table is as follows -
+// 1. Add() is called one or more times to write all key-values to the table.
+//    Its called in increasing key order, as determined by the comparator.
+//    The input key is a user key, i.e sequence number and value type are
+//    stripped out.
+// 2. After every Add() operation, status() is called to check the current
+//    status.
+// 3. After the last key is added, Finish() is called to do whatever is
+//    necessary to ensure the data is persisted in the table file.
+// 4. If there is a failure midway for some reason, Abandon() is called
+//    instead of Finish().
+// 5. At the end, FileSize(), GetTableProperties(), and status() are called to
+//    get the final size of the file, the table properties, and the final
+//    status. GetFileChecksum() and GetFileChecksumFuncName() may also be
+//    called to get checksum information about the whole file, but their
+//    implementation is optional.
+class ExternalTableBuilder {
+ public:
+  virtual ~ExternalTableBuilder() {}
+
+  // Write a single KV to the table file. This is guaranteed to be called
+  // in key order, and the write may be buffered and flushed at a later time.
+  virtual void Add(const Slice& key, const Slice& value) = 0;
+
+  // Return the current Status. This could return non-ok, for example, if
+  // Add() fails for some reason.
+  virtual Status status() const = 0;
+
+  // Flush and close the table file
+  virtual Status Finish() = 0;
+
+  // Delete the partial file and release any allocated resources. Either this
+  // or Finish() will be called, but not both.
+  virtual void Abandon() = 0;
+
+  // Return the size of the table file. Will be called at the end, after
+  // Finish().
+  virtual uint64_t FileSize() const = 0;
+
+  // Write the raw properties block as is in the table file
+  virtual Status PutPropertiesBlock(const Slice& /*property_block*/) {
+    return Status::NotSupported();
+  }
+
+  //  As mentioned in earlier comments, the following table properties must be
+  //  returned at a minimum -
+  //  comparator_name
+  //  num_entries
+  //  raw_key_size
+  //  raw_value_size
+  virtual TableProperties GetTableProperties() const = 0;
+
+  virtual std::string GetFileChecksum() const { return kUnknownFileChecksum; }
+
+  virtual const char* GetFileChecksumFuncName() const {
+    return kUnknownFileChecksumFuncName;
+  }
+};
+
+struct ExternalTableOptions {
+  const std::shared_ptr<const SliceTransform>& prefix_extractor;
+  const Comparator* comparator;
+  const std::shared_ptr<FileSystem>& fs;
+  const FileOptions& file_options;
+
+  ExternalTableOptions(
+      const std::shared_ptr<const SliceTransform>& _prefix_extractor,
+      const Comparator* _comparator, const std::shared_ptr<FileSystem>& _fs,
+      const FileOptions& _file_options)
+      : prefix_extractor(_prefix_extractor),
+        comparator(_comparator),
+        fs(_fs),
+        file_options(_file_options) {}
+};
+
+struct ExternalTableBuilderOptions {
+  const ReadOptions& read_options;
+  const WriteOptions& write_options;
+  const std::shared_ptr<const SliceTransform>& prefix_extractor;
+  const Comparator* comparator;
+  const std::string& column_family_name;
+  const std::string db_id;
+  const std::string db_session_id;
+  const TableFileCreationReason reason;
+
+  ExternalTableBuilderOptions(
+      const ReadOptions& _read_options, const WriteOptions& _write_options,
+      const std::shared_ptr<const SliceTransform>& _prefix_extractor,
+      const Comparator* _comparator, const std::string& _column_family_name,
+      const TableFileCreationReason _reason)
+      : read_options(_read_options),
+        write_options(_write_options),
+        prefix_extractor(_prefix_extractor),
+        comparator(_comparator),
+        column_family_name(_column_family_name),
+        reason(_reason) {}
+};
+
+class ExternalTableFactory : public Customizable {
+ public:
+  ~ExternalTableFactory() override {}
+
+  const char* Name() const override { return "ExternalTableFactory"; }
+
+  virtual Status NewTableReader(
+      const ReadOptions& read_options, const std::string& file_path,
+      const ExternalTableOptions& table_options,
+      std::unique_ptr<ExternalTableReader>* table_reader) const = 0;
+
+  // The table builder should use the file pointer to append to the file.
+  // Do not sync or close the file after finishing. RocksDB will do that.
+  virtual ExternalTableBuilder* NewTableBuilder(
+      const ExternalTableBuilderOptions& builder_options,
+      const std::string& file_path, FSWritableFile* file) const = 0;
+};
+
+// Allocate a TableFactory that wraps around an ExternalTableFactory. Use this
+// to allocate and set in ColumnFamilyOptions::table_factory.
+std::unique_ptr<TableFactory> NewExternalTableFactory(
+    std::shared_ptr<ExternalTableFactory> inner_factory);
+
+}  // namespace ROCKSDB_NAMESPACE

package/deps/rocksdb/rocksdb/include/rocksdb/file_checksum.h

@@ -80,7 +80,8 @@ class FileChecksumGenFactory : public Customizable {
       const ConfigOptions& options, const std::string& value,
       std::shared_ptr<FileChecksumGenFactory>* result);
 
-  // Create a new FileChecksumGenerator.
+  // Create a new FileChecksumGenerator. Recommended to return nullptr if the
+  // requested function name is not recognized.
   virtual std::unique_ptr<FileChecksumGenerator> CreateFileChecksumGenerator(
       const FileChecksumGenContext& context) = 0;
 

package/deps/rocksdb/rocksdb/include/rocksdb/file_system.h

@@ -18,6 +18,7 @@
 
 #include <stdint.h>
 
+#include <any>
 #include <chrono>
 #include <cstdarg>
 #include <functional>
@@ -192,6 +193,12 @@ struct FileOptions : EnvOptions {
   // handoff during file writes.
   ChecksumType handoff_checksum_type;
 
+  // Expose write lifetime hint on the FileOptions level to provide more
+  // flexibility in setting the hint in downstream, custom implementations
+  // that might be able to process the hint only at the time of the actual
+  // FSWritableFile object creation.
+  Env::WriteLifeTimeHint write_hint = Env::WLTH_NOT_SET;
+
   FileOptions() : EnvOptions(), handoff_checksum_type(ChecksumType::kCRC32c) {}
 
   FileOptions(const DBOptions& opts)
@@ -206,13 +213,16 @@ struct FileOptions : EnvOptions {
       : EnvOptions(opts),
         io_options(opts.io_options),
         temperature(opts.temperature),
-        handoff_checksum_type(opts.handoff_checksum_type) {}
+        handoff_checksum_type(opts.handoff_checksum_type),
+        write_hint(opts.write_hint) {}
 
   FileOptions& operator=(const FileOptions&) = default;
 };
 
 // A structure to pass back some debugging information from the FileSystem
 // implementation to RocksDB in case of an IO error
+// TODO(virajthakur): Update all calls to FS APIs for writes to pass in
+// IODebugContext
 struct IODebugContext {
   // file_path to be filled in by RocksDB in case of an error
   std::string file_path;
@@ -223,8 +233,9 @@ struct IODebugContext {
   // To be set by the FileSystem implementation
   std::string msg;
 
-  // To be set by the underlying FileSystem implementation.
-  std::string request_id;
+  // To be set by the application, to allow tracing logs/metrics from user ->
+  // RocksDB -> FS.
+  const std::string* request_id = nullptr;
 
   // In order to log required information in IO tracing for different
   // operations, Each bit in trace_data stores which corresponding info from
@@ -240,16 +251,44 @@ struct IODebugContext {
   };
   uint64_t trace_data = 0;
 
+  // Arbitrary structure containing cost information about the IO request
+  std::any cost_info;
+
   IODebugContext() {}
 
+  // Copy constructor
+  IODebugContext(const IODebugContext& other)
+      : file_path(other.file_path),
+        counters(other.counters),
+        msg(other.msg),
+        trace_data(other.trace_data),
+        cost_info(other.cost_info),
+        _request_id(other.request_id ? *other.request_id : "") {
+    request_id = other.request_id ? &_request_id : nullptr;
+  }
+
+  // Copy assignment operator
+  IODebugContext& operator=(const IODebugContext& other) {
+    if (this != &other) {
+      file_path = other.file_path;
+      counters = other.counters;
+      msg = other.msg;
+      trace_data = other.trace_data;
+      cost_info = other.cost_info;
+      _request_id = other.request_id ? *other.request_id : "";
+      request_id = other.request_id ? &_request_id : nullptr;
+    }
+    return *this;
+  }
+
   void AddCounter(std::string& name, uint64_t value) {
     counters.emplace(name, value);
   }
 
   // Called by underlying file system to set request_id and log request_id in
   // IOTracing.
-  void SetRequestId(const std::string& _request_id) {
-    request_id = _request_id;
+  void SetRequestId(const std::string* updated_request_id) {
+    request_id = updated_request_id;
     trace_data |= (1 << TraceData::kRequestID);
   }
 
@@ -262,6 +301,12 @@ struct IODebugContext {
     ss << msg;
     return ss.str();
   }
+
+ private:
+  // Private member that allows for safe copying of IODebugContext without any
+  // memory ownership issues. After copying, request_id can point directly to
+  // this field.
+  std::string _request_id;
 };
 
 // A function pointer type for custom destruction of void pointer passed to

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

@@ -10,8 +10,18 @@
 
 #include "rocksdb/perf_level.h"
 
+/*
+ * NOTE:
+ * If you plan to add new metrics, please read documentation in perf_level.h and
+ * try to come up with a metric name that follows the naming conventions
+ * mentioned there. It helps to indicate the metric's starting enabling P
+ * erfLevel. Document this starting PerfLevel if the metric name cannot meet the
+ * naming conventions.
+ */
+
 // A thread local context for gathering io-stats efficiently and transparently.
 // Use SetPerfLevel(PerfLevel::kEnableTime) to enable time stats.
+//
 
 namespace ROCKSDB_NAMESPACE {
 

package/deps/rocksdb/rocksdb/include/rocksdb/iterator.h

@@ -21,6 +21,7 @@
 #include <string>
 
 #include "rocksdb/iterator_base.h"
+#include "rocksdb/options.h"
 #include "rocksdb/wide_columns.h"
 
 namespace ROCKSDB_NAMESPACE {
@@ -93,6 +94,18 @@ class Iterator : public IteratorBase {
     assert(false);
     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().
+  // If Prepare() is called, it overrides the iterate_upper_bound in
+  // ReadOptions
+  virtual void Prepare(const std::vector<ScanOptions>& /*scan_opts*/) {}
 };
 
 // Return an empty iterator (yields nothing).

package/deps/rocksdb/rocksdb/include/rocksdb/ldb_tool.h

@@ -39,4 +39,3 @@ class LDBTool {
 };
 
 }  // namespace ROCKSDB_NAMESPACE
-

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

@@ -183,6 +183,8 @@ enum class FlushReason : int {
   kWalFull = 0xd,
   // SwitchMemtable will not be called for this flush reason.
   kCatchUpAfterErrorRecovery = 0xe,
+
+  // When adding flush reason, make sure to also add it to FlushReason in Java.
 };
 
 const char* GetFlushReasonString(FlushReason flush_reason);
@@ -211,7 +213,6 @@ struct WriteStallInfo {
   } condition;
 };
 
-
 struct FileDeletionInfo {
   FileDeletionInfo() = default;
 
@@ -438,6 +439,9 @@ struct CompactionJobInfo {
   // the job id, which is unique in the same thread.
   int job_id;
 
+  // the number of L0 files in the CF right before and after the compaction
+  int num_l0_files;
+
   // the smallest input level of the compaction.
   int base_input_level;
   // the output level of the compaction.
@@ -865,5 +869,4 @@ class EventListener : public Customizable {
   ~EventListener() override {}
 };
 
-
 }  // namespace ROCKSDB_NAMESPACE

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

@@ -162,6 +162,12 @@ class MemTableRep {
     return true;
   }
 
+  // Only used after concurrent memtable inserts.
+  // This function will be called by each writer after all writes are done
+  // through InsertConcurrently().
+  // This is used by VectorRep to do batched writes for concurrent inserts.
+  virtual void BatchPostProcess() {}
+
   // Returns true iff an entry that compares equal to key is in the collection.
   virtual bool Contains(const char* key) const = 0;
 
@@ -397,6 +403,11 @@ class SkipListFactory : public MemTableRepFactory {
 // the vector is sorted. This is useful for workloads where iteration is very
 // rare and writes are generally not issued after reads begin.
 //
+// Concurrent inserts are supported by buffering writes in thread-local vectors
+// for each write batch. To optimize performance for concurrent inserts, it is
+// recommended to perform batched writes, and enable unordered_write (refer to
+// the option comment for its impact on read consistency).
+//
 // Parameters:
 //   count: Passed to the constructor of the underlying std::vector of each
 //     VectorRep. On initialization, the underlying array will be at least count
@@ -418,6 +429,8 @@ class VectorRepFactory : public MemTableRepFactory {
   MemTableRep* CreateMemTableRep(const MemTableRep::KeyComparator&, Allocator*,
                                  const SliceTransform*,
                                  Logger* logger) override;
+
+  bool IsInsertConcurrentlySupported() const override { return true; }
 };
 
 // This class contains a fixed array of buckets, each