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   SstFileWriter(const EnvOptions& env_options, const Options& options,
  90                 ColumnFamilyHandle* column_family = nullptr,
  91                 bool invalidate_page_cache = true,
  92                 Env::IOPriority io_priority = Env::IOPriority::IO_TOTAL,
  93                 bool skip_filters = false)
  94       : SstFileWriter(env_options, options, options.comparator, column_family,
  95                       invalidate_page_cache, io_priority, skip_filters) {}
  96
  97   // Deprecated API
  98   SstFileWriter(const EnvOptions& env_options, const Options& options,
  99                 const Comparator* user_comparator,
 100                 ColumnFamilyHandle* column_family = nullptr,
 101                 bool invalidate_page_cache = true,
 102                 Env::IOPriority io_priority = Env::IOPriority::IO_TOTAL,
 103                 bool skip_filters = false);
 104
 105   ~SstFileWriter();
 106
 107   // Prepare SstFileWriter to write into file located at "file_path".
 108   Status Open(const std::string& file_path);
 109
 110   // Add a Put key with value to currently opened file (deprecated)
 111   // REQUIRES: key is after any previously added key according to comparator.
 112   ROCKSDB_DEPRECATED_FUNC Status Add(const Slice& user_key, const Slice& value);
 113
 114   // Add a Put key with value to currently opened file
 115   // REQUIRES: key is after any previously added key according to comparator.
 116   Status Put(const Slice& user_key, const Slice& value);
 117
 118   // Add a Merge key with value to currently opened file
 119   // REQUIRES: key is after any previously added key according to comparator.
 120   Status Merge(const Slice& user_key, const Slice& value);
 121
 122   // Add a deletion key to currently opened file
 123   // REQUIRES: key is after any previously added key according to comparator.
 124   Status Delete(const Slice& user_key);
 125
 126   // Add a range deletion tombstone to currently opened file
 127   Status DeleteRange(const Slice& begin_key, const Slice& end_key);
 128
 129   // Finalize writing to sst file and close file.
 130   //
 131   // An optional ExternalSstFileInfo pointer can be passed to the function
 132   // which will be populated with information about the created sst file.
 133   Status Finish(ExternalSstFileInfo* file_info = nullptr);
 134
 135   // Return the current file size.
 136   uint64_t FileSize();
 137
 138  private:
 139   void InvalidatePageCache(bool closing);
 140   struct Rep;
 141   std::unique_ptr<Rep> rep_;
 142 };
 143 }  // namespace ROCKSDB_NAMESPACE
 144
 145 #endif  // !ROCKSDB_LITE