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