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 {
  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         sequence_number(0),
  38         file_size(0),
  39         num_entries(0),
  40         num_range_del_entries(0),
  41         version(0) {}
  42
  43   ExternalSstFileInfo(const std::string& _file_path,
  44                       const std::string& _smallest_key,
  45                       const std::string& _largest_key,
  46                       SequenceNumber _sequence_number, uint64_t _file_size,
  47                       int32_t _num_entries, int32_t _version)
  48       : file_path(_file_path),
  49         smallest_key(_smallest_key),
  50         largest_key(_largest_key),
  51         smallest_range_del_key(""),
  52         largest_range_del_key(""),
  53         sequence_number(_sequence_number),
  54         file_size(_file_size),
  55         num_entries(_num_entries),
  56         num_range_del_entries(0),
  57         version(_version) {}
  58
  59   std::string file_path;     // external sst file path
  60   std::string smallest_key;  // smallest user key in file
  61   std::string largest_key;   // largest user key in file
  62   std::string
  63       smallest_range_del_key;  // smallest range deletion user key in file
  64   std::string largest_range_del_key;  // largest range deletion user key in file
  65   SequenceNumber sequence_number;     // sequence number of all keys in file
  66   uint64_t file_size;                 // file size in bytes
  67   uint64_t num_entries;               // number of entries in file
  68   uint64_t num_range_del_entries;  // number of range deletion entries in file
  69   int32_t version;                 // file version
  70 };
  71
  72 // SstFileWriter is used to create sst files that can be added to database later
  73 // All keys in files generated by SstFileWriter will have sequence number = 0.
  74 class SstFileWriter {
  75  public:
  76   // User can pass `column_family` to specify that the generated file will
  77   // be ingested into this column_family, note that passing nullptr means that
  78   // the column_family is unknown.
  79   // If invalidate_page_cache is set to true, SstFileWriter will give the OS a
  80   // hint that this file pages is not needed every time we write 1MB to the file.
  81   // To use the rate limiter an io_priority smaller than IO_TOTAL can be passed.
  82   SstFileWriter(const EnvOptions& env_options, const Options& options,
  83                 ColumnFamilyHandle* column_family = nullptr,
  84                 bool invalidate_page_cache = true,
  85                 Env::IOPriority io_priority = Env::IOPriority::IO_TOTAL,
  86                 bool skip_filters = false)
  87       : SstFileWriter(env_options, options, options.comparator, column_family,
  88                       invalidate_page_cache, io_priority, skip_filters) {}
  89
  90   // Deprecated API
  91   SstFileWriter(const EnvOptions& env_options, const Options& options,
  92                 const Comparator* user_comparator,
  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
  98   ~SstFileWriter();
  99
 100   // Prepare SstFileWriter to write into file located at "file_path".
 101   Status Open(const std::string& file_path);
 102
 103   // Add a Put key with value to currently opened file (deprecated)
 104   // REQUIRES: key is after any previously added key according to comparator.
 105   ROCKSDB_DEPRECATED_FUNC Status Add(const Slice& user_key, const Slice& value);
 106
 107   // Add a Put key with value to currently opened file
 108   // REQUIRES: key is after any previously added key according to comparator.
 109   Status Put(const Slice& user_key, const Slice& value);
 110
 111   // Add a Merge key with value to currently opened file
 112   // REQUIRES: key is after any previously added key according to comparator.
 113   Status Merge(const Slice& user_key, const Slice& value);
 114
 115   // Add a deletion key to currently opened file
 116   // REQUIRES: key is after any previously added key according to comparator.
 117   Status Delete(const Slice& user_key);
 118
 119   // Add a range deletion tombstone to currently opened file
 120   Status DeleteRange(const Slice& begin_key, const Slice& end_key);
 121
 122   // Finalize writing to sst file and close file.
 123   //
 124   // An optional ExternalSstFileInfo pointer can be passed to the function
 125   // which will be populated with information about the created sst file.
 126   Status Finish(ExternalSstFileInfo* file_info = nullptr);
 127
 128   // Return the current file size.
 129   uint64_t FileSize();
 130
 131  private:
 132   void InvalidatePageCache(bool closing);
 133   struct Rep;
 134   std::unique_ptr<Rep> rep_;
 135 };
 136 }  // namespace rocksdb
 137
 138 #endif  // !ROCKSDB_LITE