]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | // Copyright (c) 2011-present, Facebook, Inc. All rights reserved. |
2 | // This source code is licensed under the BSD-style license found in the | |
3 | // LICENSE file in the root directory of this source tree. An additional grant | |
4 | // of patent rights can be found in the PATENTS file in the same directory. | |
5 | ||
6 | #pragma once | |
7 | ||
8 | #include <string> | |
9 | #include <unordered_map> | |
10 | #include <vector> | |
11 | ||
12 | #include "rocksdb/db.h" | |
13 | #include "rocksdb/options.h" | |
14 | #include "rocksdb/table.h" | |
15 | ||
16 | namespace rocksdb { | |
17 | ||
18 | #ifndef ROCKSDB_LITE | |
19 | // The following set of functions provide a way to construct RocksDB Options | |
20 | // from a string or a string-to-string map. Here're the general rule of | |
21 | // setting option values from strings by type. Some RocksDB types are also | |
22 | // supported in these APIs. Please refer to the comment of the function itself | |
23 | // to find more information about how to config those RocksDB types. | |
24 | // | |
25 | // * Strings: | |
26 | // Strings will be used as values directly without any truncating or | |
27 | // trimming. | |
28 | // | |
29 | // * Booleans: | |
30 | // - "true" or "1" => true | |
31 | // - "false" or "0" => false. | |
32 | // [Example]: | |
33 | // - {"optimize_filters_for_hits", "1"} in GetColumnFamilyOptionsFromMap, or | |
34 | // - "optimize_filters_for_hits=true" in GetColumnFamilyOptionsFromString. | |
35 | // | |
36 | // * Integers: | |
37 | // Integers are converted directly from string, in addtion to the following | |
38 | // units that we support: | |
39 | // - 'k' or 'K' => 2^10 | |
40 | // - 'm' or 'M' => 2^20 | |
41 | // - 'g' or 'G' => 2^30 | |
42 | // - 't' or 'T' => 2^40 // only for unsigned int with sufficient bits. | |
43 | // [Example]: | |
44 | // - {"arena_block_size", "19G"} in GetColumnFamilyOptionsFromMap, or | |
45 | // - "arena_block_size=19G" in GetColumnFamilyOptionsFromString. | |
46 | // | |
47 | // * Doubles / Floating Points: | |
48 | // Doubles / Floating Points are converted directly from string. Note that | |
49 | // currently we do not support units. | |
50 | // [Example]: | |
51 | // - {"hard_rate_limit", "2.1"} in GetColumnFamilyOptionsFromMap, or | |
52 | // - "hard_rate_limit=2.1" in GetColumnFamilyOptionsFromString. | |
53 | // * Array / Vectors: | |
54 | // An array is specified by a list of values, where ':' is used as | |
55 | // the delimiter to separate each value. | |
56 | // [Example]: | |
57 | // - {"compression_per_level", "kNoCompression:kSnappyCompression"} | |
58 | // in GetColumnFamilyOptionsFromMap, or | |
59 | // - "compression_per_level=kNoCompression:kSnappyCompression" in | |
60 | // GetColumnFamilyOptionsFromMapString | |
61 | // * Enums: | |
62 | // The valid values of each enum are identical to the names of its constants. | |
63 | // [Example]: | |
64 | // - CompressionType: valid values are "kNoCompression", | |
65 | // "kSnappyCompression", "kZlibCompression", "kBZip2Compression", ... | |
66 | // - CompactionStyle: valid values are "kCompactionStyleLevel", | |
67 | // "kCompactionStyleUniversal", "kCompactionStyleFIFO", and | |
68 | // "kCompactionStyleNone". | |
69 | // | |
70 | ||
71 | // Take a default ColumnFamilyOptions "base_options" in addition to a | |
72 | // map "opts_map" of option name to option value to construct the new | |
73 | // ColumnFamilyOptions "new_options". | |
74 | // | |
75 | // Below are the instructions of how to config some non-primitive-typed | |
76 | // options in ColumnFOptions: | |
77 | // | |
78 | // * table_factory: | |
79 | // table_factory can be configured using our custom nested-option syntax. | |
80 | // | |
81 | // {option_a=value_a; option_b=value_b; option_c=value_c; ... } | |
82 | // | |
83 | // A nested option is enclosed by two curly braces, within which there are | |
84 | // multiple option assignments. Each assignment is of the form | |
85 | // "variable_name=value;". | |
86 | // | |
87 | // Currently we support the following types of TableFactory: | |
88 | // - BlockBasedTableFactory: | |
89 | // Use name "block_based_table_factory" to initialize table_factory with | |
90 | // BlockBasedTableFactory. Its BlockBasedTableFactoryOptions can be | |
91 | // configured using the nested-option syntax. | |
92 | // [Example]: | |
93 | // * {"block_based_table_factory", "{block_cache=1M;block_size=4k;}"} | |
94 | // is equivalent to assigning table_factory with a BlockBasedTableFactory | |
95 | // that has 1M LRU block-cache with block size equals to 4k: | |
96 | // ColumnFamilyOptions cf_opt; | |
97 | // BlockBasedTableOptions blk_opt; | |
98 | // blk_opt.block_cache = NewLRUCache(1 * 1024 * 1024); | |
99 | // blk_opt.block_size = 4 * 1024; | |
100 | // cf_opt.table_factory.reset(NewBlockBasedTableFactory(blk_opt)); | |
101 | // - PlainTableFactory: | |
102 | // Use name "plain_table_factory" to initialize table_factory with | |
103 | // PlainTableFactory. Its PlainTableFactoryOptions can be configured using | |
104 | // the nested-option syntax. | |
105 | // [Example]: | |
106 | // * {"plain_table_factory", "{user_key_len=66;bloom_bits_per_key=20;}"} | |
107 | // | |
108 | // * memtable_factory: | |
109 | // Use "memtable" to config memtable_factory. Here are the supported | |
110 | // memtable factories: | |
111 | // - SkipList: | |
112 | // Pass "skip_list:<lookahead>" to config memtable to use SkipList, | |
113 | // or simply "skip_list" to use the default SkipList. | |
114 | // [Example]: | |
115 | // * {"memtable", "skip_list:5"} is equivalent to setting | |
116 | // memtable to SkipListFactory(5). | |
117 | // - PrefixHash: | |
118 | // Pass "prfix_hash:<hash_bucket_count>" to config memtable | |
119 | // to use PrefixHash, or simply "prefix_hash" to use the default | |
120 | // PrefixHash. | |
121 | // [Example]: | |
122 | // * {"memtable", "prefix_hash:1000"} is equivalent to setting | |
123 | // memtable to NewHashSkipListRepFactory(hash_bucket_count). | |
124 | // - HashLinkedList: | |
125 | // Pass "hash_linkedlist:<hash_bucket_count>" to config memtable | |
126 | // to use HashLinkedList, or simply "hash_linkedlist" to use the default | |
127 | // HashLinkedList. | |
128 | // [Example]: | |
129 | // * {"memtable", "hash_linkedlist:1000"} is equivalent to | |
130 | // setting memtable to NewHashLinkListRepFactory(1000). | |
131 | // - VectorRepFactory: | |
132 | // Pass "vector:<count>" to config memtable to use VectorRepFactory, | |
133 | // or simply "vector" to use the default Vector memtable. | |
134 | // [Example]: | |
135 | // * {"memtable", "vector:1024"} is equivalent to setting memtable | |
136 | // to VectorRepFactory(1024). | |
137 | // - HashCuckooRepFactory: | |
138 | // Pass "cuckoo:<write_buffer_size>" to use HashCuckooRepFactory with the | |
139 | // specified write buffer size, or simply "cuckoo" to use the default | |
140 | // HashCuckooRepFactory. | |
141 | // [Example]: | |
142 | // * {"memtable", "cuckoo:1024"} is equivalent to setting memtable | |
143 | // to NewHashCuckooRepFactory(1024). | |
144 | // | |
145 | // * compression_opts: | |
146 | // Use "compression_opts" to config compression_opts. The value format | |
147 | // is of the form "<window_bits>:<level>:<strategy>:<max_dict_bytes>". | |
148 | // [Example]: | |
149 | // * {"compression_opts", "4:5:6:7"} is equivalent to setting: | |
150 | // ColumnFamilyOptions cf_opt; | |
151 | // cf_opt.compression_opts.window_bits = 4; | |
152 | // cf_opt.compression_opts.level = 5; | |
153 | // cf_opt.compression_opts.strategy = 6; | |
154 | // cf_opt.compression_opts.max_dict_bytes = 7; | |
155 | // | |
156 | // @param base_options the default options of the output "new_options". | |
157 | // @param opts_map an option name to value map for specifying how "new_options" | |
158 | // should be set. | |
159 | // @param new_options the resulting options based on "base_options" with the | |
160 | // change specified in "opts_map". | |
161 | // @param input_strings_escaped when set to true, each escaped characters | |
162 | // prefixed by '\' in the values of the opts_map will be further converted | |
163 | // back to the raw string before assigning to the associated options. | |
164 | // @return Status::OK() on success. Otherwise, a non-ok status indicating | |
165 | // error will be returned, and "new_options" will be set to "base_options". | |
166 | Status GetColumnFamilyOptionsFromMap( | |
167 | const ColumnFamilyOptions& base_options, | |
168 | const std::unordered_map<std::string, std::string>& opts_map, | |
169 | ColumnFamilyOptions* new_options, bool input_strings_escaped = false); | |
170 | ||
171 | // Take a default DBOptions "base_options" in addition to a | |
172 | // map "opts_map" of option name to option value to construct the new | |
173 | // DBOptions "new_options". | |
174 | // | |
175 | // Below are the instructions of how to config some non-primitive-typed | |
176 | // options in DBOptions: | |
177 | // | |
178 | // * rate_limiter_bytes_per_sec: | |
179 | // RateLimiter can be configured directly by specifying its bytes_per_sec. | |
180 | // [Example]: | |
181 | // - Passing {"rate_limiter_bytes_per_sec", "1024"} is equivalent to | |
182 | // passing NewGenericRateLimiter(1024) to rate_limiter_bytes_per_sec. | |
183 | // | |
184 | // @param base_options the default options of the output "new_options". | |
185 | // @param opts_map an option name to value map for specifying how "new_options" | |
186 | // should be set. | |
187 | // @param new_options the resulting options based on "base_options" with the | |
188 | // change specified in "opts_map". | |
189 | // @param input_strings_escaped when set to true, each escaped characters | |
190 | // prefixed by '\' in the values of the opts_map will be further converted | |
191 | // back to the raw string before assigning to the associated options. | |
192 | // @return Status::OK() on success. Otherwise, a non-ok status indicating | |
193 | // error will be returned, and "new_options" will be set to "base_options". | |
194 | Status GetDBOptionsFromMap( | |
195 | const DBOptions& base_options, | |
196 | const std::unordered_map<std::string, std::string>& opts_map, | |
197 | DBOptions* new_options, bool input_strings_escaped = false); | |
198 | ||
199 | // Take a default BlockBasedTableOptions "table_options" in addition to a | |
200 | // map "opts_map" of option name to option value to construct the new | |
201 | // BlockBasedTableOptions "new_table_options". | |
202 | // | |
203 | // Below are the instructions of how to config some non-primitive-typed | |
204 | // options in BlockBasedTableOptions: | |
205 | // | |
206 | // * filter_policy: | |
207 | // We currently only support the following FilterPolicy in the convenience | |
208 | // functions: | |
209 | // - BloomFilter: use "bloomfilter:[bits_per_key]:[use_block_based_builder]" | |
210 | // to specify BloomFilter. The above string is equivalent to calling | |
211 | // NewBloomFilterPolicy(bits_per_key, use_block_based_builder). | |
212 | // [Example]: | |
213 | // - Pass {"filter_policy", "bloomfilter:4:true"} in | |
214 | // GetBlockBasedTableOptionsFromMap to use a BloomFilter with 4-bits | |
215 | // per key and use_block_based_builder enabled. | |
216 | // | |
217 | // * block_cache / block_cache_compressed: | |
218 | // We currently only support LRU cache in the GetOptions API. The LRU | |
219 | // cache can be set by directly specifying its size. | |
220 | // [Example]: | |
221 | // - Passing {"block_cache", "1M"} in GetBlockBasedTableOptionsFromMap is | |
222 | // equivalent to setting block_cache using NewLRUCache(1024 * 1024). | |
223 | // | |
224 | // @param table_options the default options of the output "new_table_options". | |
225 | // @param opts_map an option name to value map for specifying how | |
226 | // "new_table_options" should be set. | |
227 | // @param new_table_options the resulting options based on "table_options" | |
228 | // with the change specified in "opts_map". | |
229 | // @param input_strings_escaped when set to true, each escaped characters | |
230 | // prefixed by '\' in the values of the opts_map will be further converted | |
231 | // back to the raw string before assigning to the associated options. | |
232 | // @return Status::OK() on success. Otherwise, a non-ok status indicating | |
233 | // error will be returned, and "new_table_options" will be set to | |
234 | // "table_options". | |
235 | Status GetBlockBasedTableOptionsFromMap( | |
236 | const BlockBasedTableOptions& table_options, | |
237 | const std::unordered_map<std::string, std::string>& opts_map, | |
238 | BlockBasedTableOptions* new_table_options, | |
239 | bool input_strings_escaped = false); | |
240 | ||
241 | // Take a default PlainTableOptions "table_options" in addition to a | |
242 | // map "opts_map" of option name to option value to construct the new | |
243 | // PlainTableOptions "new_table_options". | |
244 | // | |
245 | // @param table_options the default options of the output "new_table_options". | |
246 | // @param opts_map an option name to value map for specifying how | |
247 | // "new_table_options" should be set. | |
248 | // @param new_table_options the resulting options based on "table_options" | |
249 | // with the change specified in "opts_map". | |
250 | // @param input_strings_escaped when set to true, each escaped characters | |
251 | // prefixed by '\' in the values of the opts_map will be further converted | |
252 | // back to the raw string before assigning to the associated options. | |
253 | // @return Status::OK() on success. Otherwise, a non-ok status indicating | |
254 | // error will be returned, and "new_table_options" will be set to | |
255 | // "table_options". | |
256 | Status GetPlainTableOptionsFromMap( | |
257 | const PlainTableOptions& table_options, | |
258 | const std::unordered_map<std::string, std::string>& opts_map, | |
259 | PlainTableOptions* new_table_options, | |
260 | bool input_strings_escaped = false); | |
261 | ||
262 | // Take a string representation of option names and values, apply them into the | |
263 | // base_options, and return the new options as a result. The string has the | |
264 | // following format: | |
265 | // "write_buffer_size=1024;max_write_buffer_number=2" | |
266 | // Nested options config is also possible. For example, you can define | |
267 | // BlockBasedTableOptions as part of the string for block-based table factory: | |
268 | // "write_buffer_size=1024;block_based_table_factory={block_size=4k};" | |
269 | // "max_write_buffer_num=2" | |
270 | Status GetColumnFamilyOptionsFromString( | |
271 | const ColumnFamilyOptions& base_options, | |
272 | const std::string& opts_str, | |
273 | ColumnFamilyOptions* new_options); | |
274 | ||
275 | Status GetDBOptionsFromString( | |
276 | const DBOptions& base_options, | |
277 | const std::string& opts_str, | |
278 | DBOptions* new_options); | |
279 | ||
280 | Status GetStringFromDBOptions(std::string* opts_str, | |
281 | const DBOptions& db_options, | |
282 | const std::string& delimiter = "; "); | |
283 | ||
284 | Status GetStringFromColumnFamilyOptions(std::string* opts_str, | |
285 | const ColumnFamilyOptions& cf_options, | |
286 | const std::string& delimiter = "; "); | |
287 | ||
288 | Status GetStringFromCompressionType(std::string* compression_str, | |
289 | CompressionType compression_type); | |
290 | ||
291 | std::vector<CompressionType> GetSupportedCompressions(); | |
292 | ||
293 | Status GetBlockBasedTableOptionsFromString( | |
294 | const BlockBasedTableOptions& table_options, | |
295 | const std::string& opts_str, | |
296 | BlockBasedTableOptions* new_table_options); | |
297 | ||
298 | Status GetPlainTableOptionsFromString( | |
299 | const PlainTableOptions& table_options, | |
300 | const std::string& opts_str, | |
301 | PlainTableOptions* new_table_options); | |
302 | ||
303 | Status GetMemTableRepFactoryFromString( | |
304 | const std::string& opts_str, | |
305 | std::unique_ptr<MemTableRepFactory>* new_mem_factory); | |
306 | ||
307 | Status GetOptionsFromString(const Options& base_options, | |
308 | const std::string& opts_str, Options* new_options); | |
309 | ||
310 | Status StringToMap(const std::string& opts_str, | |
311 | std::unordered_map<std::string, std::string>* opts_map); | |
312 | ||
313 | // Request stopping background work, if wait is true wait until it's done | |
314 | void CancelAllBackgroundWork(DB* db, bool wait = false); | |
315 | ||
316 | // Delete files which are entirely in the given range | |
317 | // Could leave some keys in the range which are in files which are not | |
318 | // entirely in the range. | |
319 | // Snapshots before the delete might not see the data in the given range. | |
320 | Status DeleteFilesInRange(DB* db, ColumnFamilyHandle* column_family, | |
321 | const Slice* begin, const Slice* end); | |
322 | #endif // ROCKSDB_LITE | |
323 | ||
324 | } // namespace rocksdb |