ceph/src/rocksdb/include/rocksdb/utilities/options_util.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 // This file contains utility functions for RocksDB Options.
   7 #pragma once
   8
   9 #ifndef ROCKSDB_LITE
  10
  11 #include <string>
  12 #include <vector>
  13
  14 #include "rocksdb/convenience.h"
  15 #include "rocksdb/db.h"
  16 #include "rocksdb/env.h"
  17 #include "rocksdb/options.h"
  18 #include "rocksdb/status.h"
  19
  20 namespace ROCKSDB_NAMESPACE {
  21 struct ConfigOptions;
  22 // Constructs the DBOptions and ColumnFamilyDescriptors by loading the
  23 // latest RocksDB options file stored in the specified rocksdb database.
  24 //
  25 // Note that the all the pointer options (except table_factory, which will
  26 // be described in more details below) will be initialized with the default
  27 // values.  Developers can further initialize them after this function call.
  28 // Below is an example list of pointer options which will be initialized
  29 //
  30 // * env
  31 // * memtable_factory
  32 // * compaction_filter_factory
  33 // * prefix_extractor
  34 // * comparator
  35 // * merge_operator
  36 // * compaction_filter
  37 //
  38 // User can also choose to load customized comparator, env, and/or
  39 // merge_operator through object registry:
  40 // * comparator needs to be registered through Registrar<const Comparator>
  41 // * env needs to be registered through Registrar<Env>
  42 // * merge operator needs to be registered through
  43 //     Registrar<std::shared_ptr<MergeOperator>>.
  44 //
  45 // For table_factory, this function further supports deserializing
  46 // BlockBasedTableFactory and its BlockBasedTableOptions except the
  47 // pointer options of BlockBasedTableOptions (flush_block_policy_factory,
  48 // block_cache, and block_cache_compressed), which will be initialized with
  49 // default values.  Developers can further specify these three options by
  50 // casting the return value of TableFactory::GetOptions() to
  51 // BlockBasedTableOptions and making necessary changes.
  52 //
  53 // ignore_unknown_options can be set to true if you want to ignore options
  54 // that are from a newer version of the db, esentially for forward
  55 // compatibility.
  56 //
  57 // config_options contains a set of options that controls the processing
  58 // of the options.  The LoadLatestOptions(ConfigOptions...) should be preferred;
  59 // the alternative signature may be deprecated in a future release. The
  60 // equivalent functionality can be achieved by setting the corresponding options
  61 // in the ConfigOptions parameter.
  62 //
  63 // examples/options_file_example.cc demonstrates how to use this function
  64 // to open a RocksDB instance.
  65 //
  66 // @return the function returns an OK status when it went successfully.  If
  67 //     the specified "dbpath" does not contain any option file, then a
  68 //     Status::NotFound will be returned.  A return value other than
  69 //     Status::OK or Status::NotFound indicates there're some error related
  70 //     to the options file itself.
  71 //
  72 // @see LoadOptionsFromFile
  73 Status LoadLatestOptions(const std::string& dbpath, Env* env,
  74                          DBOptions* db_options,
  75                          std::vector<ColumnFamilyDescriptor>* cf_descs,
  76                          bool ignore_unknown_options = false,
  77                          std::shared_ptr<Cache>* cache = {});
  78 Status LoadLatestOptions(const ConfigOptions& config_options,
  79                          const std::string& dbpath, DBOptions* db_options,
  80                          std::vector<ColumnFamilyDescriptor>* cf_descs,
  81                          std::shared_ptr<Cache>* cache = {});
  82
  83 // Similar to LoadLatestOptions, this function constructs the DBOptions
  84 // and ColumnFamilyDescriptors based on the specified RocksDB Options file.
  85 //
  86 // The LoadOptionsFile(ConfigOptions...) should be preferred;
  87 // the alternative signature may be deprecated in a future release. The
  88 // equivalent functionality can be achieved by setting the corresponding
  89 // options in the ConfigOptions parameter.
  90 //
  91 // @see LoadLatestOptions
  92 Status LoadOptionsFromFile(const std::string& options_file_name, Env* env,
  93                            DBOptions* db_options,
  94                            std::vector<ColumnFamilyDescriptor>* cf_descs,
  95                            bool ignore_unknown_options = false,
  96                            std::shared_ptr<Cache>* cache = {});
  97 Status LoadOptionsFromFile(const ConfigOptions& config_options,
  98                            const std::string& options_file_name,
  99                            DBOptions* db_options,
 100                            std::vector<ColumnFamilyDescriptor>* cf_descs,
 101                            std::shared_ptr<Cache>* cache = {});
 102
 103 // Returns the latest options file name under the specified db path.
 104 Status GetLatestOptionsFileName(const std::string& dbpath, Env* env,
 105                                 std::string* options_file_name);
 106
 107 // Returns Status::OK if the input DBOptions and ColumnFamilyDescriptors
 108 // are compatible with the latest options stored in the specified DB path.
 109 //
 110 // If the return status is non-ok, it means the specified RocksDB instance
 111 // might not be correctly opened with the input set of options.  Currently,
 112 // changing one of the following options will fail the compatibility check:
 113 //
 114 // * comparator
 115 // * prefix_extractor
 116 // * table_factory
 117 // * merge_operator
 118 Status CheckOptionsCompatibility(
 119     const std::string& dbpath, Env* env, const DBOptions& db_options,
 120     const std::vector<ColumnFamilyDescriptor>& cf_descs,
 121     bool ignore_unknown_options = false);
 122 Status CheckOptionsCompatibility(
 123     const ConfigOptions& config_options, const std::string& dbpath,
 124     const DBOptions& db_options,
 125     const std::vector<ColumnFamilyDescriptor>& cf_descs);
 126
 127 }  // namespace ROCKSDB_NAMESPACE
 128 #endif  // !ROCKSDB_LITE