src/leveldb/include/leveldb/options.h

   1 // Copyright (c) 2011 The LevelDB Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file. See the AUTHORS file for names of contributors.
   4
   5 #ifndef STORAGE_LEVELDB_INCLUDE_OPTIONS_H_
   6 #define STORAGE_LEVELDB_INCLUDE_OPTIONS_H_
   7
   8 #include <stddef.h>
   9
  10 namespace leveldb {
  11
  12 class Cache;
  13 class Comparator;
  14 class Env;
  15 class FilterPolicy;
  16 class Logger;
  17 class Snapshot;
  18
  19 // DB contents are stored in a set of blocks, each of which holds a
  20 // sequence of key,value pairs.  Each block may be compressed before
  21 // being stored in a file.  The following enum describes which
  22 // compression method (if any) is used to compress a block.
  23 enum CompressionType {
  24   // NOTE: do not change the values of existing entries, as these are
  25   // part of the persistent format on disk.
  26   kNoCompression     = 0x0,
  27   kSnappyCompression = 0x1
  28 };
  29
  30 // Options to control the behavior of a database (passed to DB::Open)
  31 struct Options {
  32   // -------------------
  33   // Parameters that affect behavior
  34
  35   // Comparator used to define the order of keys in the table.
  36   // Default: a comparator that uses lexicographic byte-wise ordering
  37   //
  38   // REQUIRES: The client must ensure that the comparator supplied
  39   // here has the same name and orders keys *exactly* the same as the
  40   // comparator provided to previous open calls on the same DB.
  41   const Comparator* comparator;
  42
  43   // If true, the database will be created if it is missing.
  44   // Default: false
  45   bool create_if_missing;
  46
  47   // If true, an error is raised if the database already exists.
  48   // Default: false
  49   bool error_if_exists;
  50
  51   // If true, the implementation will do aggressive checking of the
  52   // data it is processing and will stop early if it detects any
  53   // errors.  This may have unforeseen ramifications: for example, a
  54   // corruption of one DB entry may cause a large number of entries to
  55   // become unreadable or for the entire DB to become unopenable.
  56   // Default: false
  57   bool paranoid_checks;
  58
  59   // Use the specified object to interact with the environment,
  60   // e.g. to read/write files, schedule background work, etc.
  61   // Default: Env::Default()
  62   Env* env;
  63
  64   // Any internal progress/error information generated by the db will
  65   // be written to info_log if it is non-NULL, or to a file stored
  66   // in the same directory as the DB contents if info_log is NULL.
  67   // Default: NULL
  68   Logger* info_log;
  69
  70   // -------------------
  71   // Parameters that affect performance
  72
  73   // Amount of data to build up in memory (backed by an unsorted log
  74   // on disk) before converting to a sorted on-disk file.
  75   //
  76   // Larger values increase performance, especially during bulk loads.
  77   // Up to two write buffers may be held in memory at the same time,
  78   // so you may wish to adjust this parameter to control memory usage.
  79   // Also, a larger write buffer will result in a longer recovery time
  80   // the next time the database is opened.
  81   //
  82   // Default: 4MB
  83   size_t write_buffer_size;
  84
  85   // Number of open files that can be used by the DB.  You may need to
  86   // increase this if your database has a large working set (budget
  87   // one open file per 2MB of working set).
  88   //
  89   // Default: 1000
  90   int max_open_files;
  91
  92   // Control over blocks (user data is stored in a set of blocks, and
  93   // a block is the unit of reading from disk).
  94
  95   // If non-NULL, use the specified cache for blocks.
  96   // If NULL, leveldb will automatically create and use an 8MB internal cache.
  97   // Default: NULL
  98   Cache* block_cache;
  99
 100   // Approximate size of user data packed per block.  Note that the
 101   // block size specified here corresponds to uncompressed data.  The
 102   // actual size of the unit read from disk may be smaller if
 103   // compression is enabled.  This parameter can be changed dynamically.
 104   //
 105   // Default: 4K
 106   size_t block_size;
 107
 108   // Number of keys between restart points for delta encoding of keys.
 109   // This parameter can be changed dynamically.  Most clients should
 110   // leave this parameter alone.
 111   //
 112   // Default: 16
 113   int block_restart_interval;
 114
 115   // Compress blocks using the specified compression algorithm.  This
 116   // parameter can be changed dynamically.
 117   //
 118   // Default: kSnappyCompression, which gives lightweight but fast
 119   // compression.
 120   //
 121   // Typical speeds of kSnappyCompression on an Intel(R) Core(TM)2 2.4GHz:
 122   //    ~200-500MB/s compression
 123   //    ~400-800MB/s decompression
 124   // Note that these speeds are significantly faster than most
 125   // persistent storage speeds, and therefore it is typically never
 126   // worth switching to kNoCompression.  Even if the input data is
 127   // incompressible, the kSnappyCompression implementation will
 128   // efficiently detect that and will switch to uncompressed mode.
 129   CompressionType compression;
 130
 131   // If non-NULL, use the specified filter policy to reduce disk reads.
 132   // Many applications will benefit from passing the result of
 133   // NewBloomFilterPolicy() here.
 134   //
 135   // Default: NULL
 136   const FilterPolicy* filter_policy;
 137
 138   // Create an Options object with default values for all fields.
 139   Options();
 140 };
 141
 142 // Options that control read operations
 143 struct ReadOptions {
 144   // If true, all data read from underlying storage will be
 145   // verified against corresponding checksums.
 146   // Default: false
 147   bool verify_checksums;
 148
 149   // Should the data read for this iteration be cached in memory?
 150   // Callers may wish to set this field to false for bulk scans.
 151   // Default: true
 152   bool fill_cache;
 153
 154   // If "snapshot" is non-NULL, read as of the supplied snapshot
 155   // (which must belong to the DB that is being read and which must
 156   // not have been released).  If "snapshot" is NULL, use an impliicit
 157   // snapshot of the state at the beginning of this read operation.
 158   // Default: NULL
 159   const Snapshot* snapshot;
 160
 161   ReadOptions()
 162       : verify_checksums(false),
 163         fill_cache(true),
 164         snapshot(NULL) {
 165   }
 166 };
 167
 168 // Options that control write operations
 169 struct WriteOptions {
 170   // If true, the write will be flushed from the operating system
 171   // buffer cache (by calling WritableFile::Sync()) before the write
 172   // is considered complete.  If this flag is true, writes will be
 173   // slower.
 174   //
 175   // If this flag is false, and the machine crashes, some recent
 176   // writes may be lost.  Note that if it is just the process that
 177   // crashes (i.e., the machine does not reboot), no writes will be
 178   // lost even if sync==false.
 179   //
 180   // In other words, a DB write with sync==false has similar
 181   // crash semantics as the "write()" system call.  A DB write
 182   // with sync==true has similar crash semantics to a "write()"
 183   // system call followed by "fsync()".
 184   //
 185   // Default: false
 186   bool sync;
 187
 188   WriteOptions()
 189       : sync(false) {
 190   }
 191 };
 192
 193 }  // namespace leveldb
 194
 195 #endif  // STORAGE_LEVELDB_INCLUDE_OPTIONS_H_