ceph/src/rocksdb/include/rocksdb/sst_file_writer.h

   1 //  Copyright (c) 2011-present, Facebook, Inc.  All rights reserved.
   2 //  This source code is licensed under both the GPLv2 (found in the
   3 //  COPYING file in the root directory) and Apache 2.0 License
   4 //  (found in the LICENSE.Apache file in the root directory).
   5
   6 #pragma once
   7
   8 #ifndef ROCKSDB_LITE
   9
  10 #include <memory>
  11 #include <string>
  12
  13 #include "rocksdb/env.h"
  14 #include "rocksdb/options.h"
  15 #include "rocksdb/table_properties.h"
  16 #include "rocksdb/types.h"
  17
  18 #if defined(__GNUC__) || defined(__clang__)
  19 #define ROCKSDB_DEPRECATED_FUNC __attribute__((__deprecated__))
  20 #elif _WIN32
  21 #define ROCKSDB_DEPRECATED_FUNC __declspec(deprecated)
  22 #endif
  23
  24 namespace ROCKSDB_NAMESPACE {
  25
  26 class Comparator;
  27
  28 // ExternalSstFileInfo include information about sst files created
  29 // using SstFileWriter.
  30 struct ExternalSstFileInfo {
  31   ExternalSstFileInfo()
  32       : file_path(""),
  33         smallest_key(""),
  34         largest_key(""),
  35         smallest_range_del_key(""),
  36         largest_range_del_key(""),
  37         file_checksum(""),
  38         file_checksum_func_name(""),
  39         sequence_number(0),
  40         file_size(0),
  41         num_entries(0),
  42         num_range_del_entries(0),
  43         version(0) {}
  44
  45   ExternalSstFileInfo(const std::string& _file_path,
  46                       const std::string& _smallest_key,
  47                       const std::string& _largest_key,
  48                       SequenceNumber _sequence_number, uint64_t _file_size,
  49                       int32_t _num_entries, int32_t _version)
  50       : file_path(_file_path),
  51         smallest_key(_smallest_key),
  52         largest_key(_largest_key),
  53         smallest_range_del_key(""),
  54         largest_range_del_key(""),
  55         file_checksum(""),
  56         file_checksum_func_name(""),
  57         sequence_number(_sequence_number),
  58         file_size(_file_size),
  59         num_entries(_num_entries),
  60         num_range_del_entries(0),
  61         version(_version) {}
  62
  63   std::string file_path;     // external sst file path
  64   std::string smallest_key;  // smallest user key in file
  65   std::string largest_key;   // largest user key in file
  66   std::string
  67       smallest_range_del_key;  // smallest range deletion user key in file
  68   std::string largest_range_del_key;  // largest range deletion user key in file
  69   std::string file_checksum;          // sst file checksum;
  70   std::string file_checksum_func_name;  // The name of file checksum function
  71   SequenceNumber sequence_number;       // sequence number of all keys in file
  72   uint64_t file_size;                   // file size in bytes
  73   uint64_t num_entries;                 // number of entries in file
  74   uint64_t num_range_del_entries;  // number of range deletion entries in file
  75   int32_t version;                 // file version
  76 };
  77
  78 // SstFileWriter is used to create sst files that can be added to database later
  79 // All keys in files generated by SstFileWriter will have sequence number = 0.
  80 class SstFileWriter {
  81  public:
  82   // User can pass `column_family` to specify that the generated file will
  83   // be ingested into this column_family, note that passing nullptr means that
  84   // the column_family is unknown.
  85   // If invalidate_page_cache is set to true, SstFileWriter will give the OS a
  86   // hint that this file pages is not needed every time we write 1MB to the
  87   // file. To use the rate limiter an io_priority smaller than IO_TOTAL can be
  88   // passed.
  89   // The `skip_filters` option is DEPRECATED and could be removed in the
  90   // future. Use `BlockBasedTableOptions::filter_policy` to control filter
  91   // generation.
  92   SstFileWriter(const EnvOptions& env_options, const Options& options,
  93                 ColumnFamilyHandle* column_family = nullptr,
  94                 bool invalidate_page_cache = true,
  95                 Env::IOPriority io_priority = Env::IOPriority::IO_TOTAL,
  96                 bool skip_filters = false)
  97       : SstFileWriter(env_options, options, options.comparator, column_family,
  98                       invalidate_page_cache, io_priority, skip_filters) {}
  99
 100   // Deprecated API
 101   SstFileWriter(const EnvOptions& env_options, const Options& options,
 102                 const Comparator* user_comparator,
 103                 ColumnFamilyHandle* column_family = nullptr,
 104                 bool invalidate_page_cache = true,
 105                 Env::IOPriority io_priority = Env::IOPriority::IO_TOTAL,
 106                 bool skip_filters = false);
 107
 108   ~SstFileWriter();
 109
 110   // Prepare SstFileWriter to write into file located at "file_path".
 111   Status Open(const std::string& file_path);
 112
 113   // Add a Put key with value to currently opened file (deprecated)
 114   // REQUIRES: key is after any previously added key according to comparator.
 115   // REQUIRES: comparator is *not* timestamp-aware.
 116   ROCKSDB_DEPRECATED_FUNC Status Add(const Slice& user_key, const Slice& value);
 117
 118   // Add a Put key with value to currently opened file
 119   // REQUIRES: key is after any previously added key according to comparator.
 120   // REQUIRES: comparator is *not* timestamp-aware.
 121   Status Put(const Slice& user_key, const Slice& value);
 122
 123   // Add a Put (key with timestamp, value) to the currently opened file
 124   // REQUIRES: key is after any previously added key according to the
 125   // comparator.
 126   // REQUIRES: the timestamp's size is equal to what is expected by
 127   // the comparator.
 128   Status Put(const Slice& user_key, const Slice& timestamp, const Slice& value);
 129
 130   // Add a Merge key with value to currently opened file
 131   // REQUIRES: key is after any previously added key according to comparator.
 132   // REQUIRES: comparator is *not* timestamp-aware.
 133   Status Merge(const Slice& user_key, const Slice& value);
 134
 135   // Add a deletion key to currently opened file
 136   // REQUIRES: key is after any previously added key according to comparator.
 137   // REQUIRES: comparator is *not* timestamp-aware.
 138   Status Delete(const Slice& user_key);
 139
 140   // Add a deletion key with timestamp to the currently opened file
 141   // REQUIRES: key is after any previously added key according to the
 142   // comparator.
 143   // REQUIRES: the timestamp's size is equal to what is expected by
 144   // the comparator.
 145   Status Delete(const Slice& user_key, const Slice& timestamp);
 146
 147   // Add a range deletion tombstone to currently opened file
 148   // REQUIRES: comparator is *not* timestamp-aware.
 149   Status DeleteRange(const Slice& begin_key, const Slice& end_key);
 150
 151   // Add a range deletion tombstone to currently opened file.
 152   // REQUIRES: begin_key and end_key are user keys without timestamp.
 153   // REQUIRES: the timestamp's size is equal to what is expected by
 154   // the comparator.
 155   Status DeleteRange(const Slice& begin_key, const Slice& end_key,
 156                      const Slice& timestamp);
 157
 158   // Finalize writing to sst file and close file.
 159   //
 160   // An optional ExternalSstFileInfo pointer can be passed to the function
 161   // which will be populated with information about the created sst file.
 162   Status Finish(ExternalSstFileInfo* file_info = nullptr);
 163
 164   // Return the current file size.
 165   uint64_t FileSize();
 166
 167  private:
 168   void InvalidatePageCache(bool closing);
 169   struct Rep;
 170   std::unique_ptr<Rep> rep_;
 171 };
 172 }  // namespace ROCKSDB_NAMESPACE
 173
 174 #endif  // !ROCKSDB_LITE