]>
git.proxmox.com Git - ceph.git/blob - ceph/src/rocksdb/include/rocksdb/configurable.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 // Copyright (c) 2011 The LevelDB Authors. All rights reserved.
6 // Use of this source code is governed by a BSD-style license that can be
7 // found in the LICENSE file. See the AUTHORS file for names of contributors.
12 #include <unordered_map>
13 #include <unordered_set>
16 #include "rocksdb/rocksdb_namespace.h"
17 #include "rocksdb/status.h"
19 namespace ROCKSDB_NAMESPACE
{
23 struct ColumnFamilyOptions
;
27 // Configurable is a base class used by the rocksdb that describes a
28 // standard way of configuring objects. A Configurable object can:
29 // -> Populate itself given:
30 // - One or more "name/value" pair strings
31 // - A string repesenting the set of name=value properties
32 // - A map of name/value properties.
33 // -> Convert itself into its string representation
34 // -> Dump itself to a Logger
35 // -> Compare itself to another Configurable object to see if the two objects
36 // have equivalent options settings
38 // If a derived class calls RegisterOptions to register (by name) how its
39 // options objects are to be processed, this functionality can typically be
40 // handled by this class without additional overrides. Otherwise, the derived
41 // class will need to implement the methods for handling the corresponding
45 friend class ConfigurableHelper
;
46 struct RegisteredOptions
{
47 // The name of the options being registered
49 // Pointer to the object being registered
52 // The map of options being registered
53 const std::unordered_map
<std::string
, OptionTypeInfo
>* type_map
;
58 Configurable() : prepared_(false) {}
59 virtual ~Configurable() {}
61 // Returns the raw pointer of the named options that is used by this
62 // object, or nullptr if this function is not supported.
63 // Since the return value is a raw pointer, the object owns the
64 // pointer and the caller should not delete the pointer.
66 // Note that changing the underlying options while the object
67 // is currently used by any open DB is undefined behavior.
68 // Developers should use DB::SetOption() instead to dynamically change
69 // options while the DB is open.
71 const T
* GetOptions() const {
72 return GetOptions
<T
>(T::kName());
76 return GetOptions
<T
>(T::kName());
79 const T
* GetOptions(const std::string
& name
) const {
80 return reinterpret_cast<const T
*>(GetOptionsPtr(name
));
83 T
* GetOptions(const std::string
& name
) {
84 return reinterpret_cast<T
*>(const_cast<void*>(GetOptionsPtr(name
)));
87 // Configures the options for this class based on the input parameters.
88 // On successful completion, the object is updated with the settings from
90 // If this method fails, an attempt is made to revert the object to original
91 // state. Note that the revert may not be the original state but may be an
92 // equivalent. For example, if the object contains an option that is a
93 // shared_ptr, the shared_ptr may not be the original one but a copy (e.g. not
94 // the Cache object that was passed in, but a Cache object of the same size).
96 // The acceptable values of the name/value pairs are documented with the
97 // specific class/instance.
99 // @param config_options Controls how the arguments are processed.
100 // @param opt_map Name/value pairs of the options to update
101 // @param unused If specified, this value will return the name/value
102 // pairs from opt_map that were NotFound for this object.
103 // @return OK If all values in the map were successfully updated
104 // If invoke_prepare_options is true, OK also implies
105 // PrepareOptions ran successfully.
106 // @return NotFound If any of the names in the opt_map were not valid
107 // for this object. If unused is specified, it will contain the
108 // collection of NotFound names.
109 // @return NotSupported If any of the names are valid but the object does
110 // not know how to convert the value. This can happen if, for example,
111 // there is some nested Configurable that cannot be created.
112 // @return InvalidArgument If any of the values cannot be successfully
113 // parsed. This can also be returned if PrepareOptions encounters an
115 // @see ConfigOptions for a description of the controls.
116 Status
ConfigureFromMap(
117 const ConfigOptions
& config_options
,
118 const std::unordered_map
<std::string
, std::string
>& opt_map
);
119 Status
ConfigureFromMap(
120 const ConfigOptions
& config_options
,
121 const std::unordered_map
<std::string
, std::string
>& opt_map
,
122 std::unordered_map
<std::string
, std::string
>* unused
);
125 // Updates the named option to the input value, returning OK if successful.
126 // Note that ConfigureOption does not cause PrepareOptions to be invoked.
127 // @param config_options Controls how the name/value is processed.
128 // @param name The name of the option to update
129 // @param value The value to set for the named option
130 // @return OK If the named field was successfully updated to value.
131 // @return NotFound If the name is not valid for this object.
132 // @return NotSupported If the name is valid but the object does
133 // not know how to convert the value. This can happen if, for example,
134 // there is some nested Configurable that cannot be created.
135 // @return InvalidArgument If the value cannot be successfully parsed.
136 Status
ConfigureOption(const ConfigOptions
& config_options
,
137 const std::string
& name
, const std::string
& value
);
138 #endif // ROCKSDB_LITE
140 // Configures the options for this class based on the input parameters.
141 // On successful completion, the object is updated with the settings from
142 // the opt_map. If this method fails, an attempt is made to revert the
143 // object to original state. Note that the revert may not be the original
144 // state but may be an equivalent.
145 // @see ConfigureFromMap for more details
146 // @param config_options Controls how the arguments are processed.
147 // @param opt_str string containing the values to update.
148 // @param unused If specified, this value will return the name/value
149 // pairs from opt_map that were NotFound for this object.
150 // @return OK If all specified values were successfully updated
151 // If invoke_prepare_options is true, OK also implies
152 // PrepareOptions ran successfully.
153 // @return NotFound If any of the names were not valid for this object.
154 // If unused is specified, it will contain the collection of NotFound
156 // @return NotSupported If any of the names are valid but the object does
157 // not know how to convert the value. This can happen if, for example,
158 // there is some nested Configurable that cannot be created.
159 // @return InvalidArgument If any of the values cannot be successfully
160 // parsed. This can also be returned if PrepareOptions encounters an
162 Status
ConfigureFromString(const ConfigOptions
& config_options
,
163 const std::string
& opts
);
165 // Fills in result with the serialized options for this object.
166 // This is the inverse of ConfigureFromString.
167 // @param config_options Controls how serialization happens.
168 // @param result The string representation of this object.
169 // @return OK If the options for this object wer successfully serialized.
170 // @return InvalidArgument If one or more of the options could not be
172 Status
GetOptionString(const ConfigOptions
& config_options
,
173 std::string
* result
) const;
175 // Returns the serialized options for this object.
176 // This method is similar to GetOptionString with no errors.
177 // @param config_options Controls how serialization happens.
178 // @param prefix A string to prepend to every option.
179 // @return The serialized representation of the options for this object
180 std::string
ToString(const ConfigOptions
& config_options
) const {
181 return ToString(config_options
, "");
183 std::string
ToString(const ConfigOptions
& config_options
,
184 const std::string
& prefix
) const;
186 // Returns the list of option names associated with this configurable
187 // @param config_options Controls how the names are returned
188 // @param result The set of option names for this object. Note that
189 // options that are deprecated or aliases are not returned.
190 // @return OK on success.
191 Status
GetOptionNames(const ConfigOptions
& config_options
,
192 std::unordered_set
<std::string
>* result
) const;
194 // Returns the value of the option associated with the input name
195 // This method is the functional inverse of ConfigureOption
196 // @param config_options Controls how the value is returned
197 // @param name The name of the option to return a value for.
198 // @param value The returned value associated with the named option.
199 // @return OK If the named field was successfully updated to value.
200 // @return NotFound If the name is not valid for this object.
201 // @param InvalidArgument If the name is valid for this object but
202 // its value cannot be serialized.
203 virtual Status
GetOption(const ConfigOptions
& config_options
,
204 const std::string
& name
, std::string
* value
) const;
205 #endif // ROCKSDB_LITE
207 // Checks to see if this Configurable is equivalent to other.
208 // This method assumes that the two objects are of the same class.
209 // @param config_options Controls how the options are compared.
210 // @param other The other object to compare to.
211 // @param mismatch If the objects do not match, this parameter contains
212 // the name of the option that triggered the match failure.
213 // @param True if the objects match, false otherwise.
214 virtual bool AreEquivalent(const ConfigOptions
& config_options
,
215 const Configurable
* other
,
216 std::string
* name
) const;
218 // Returns a pretty-printed, human-readable version of the options.
219 // This method is typically used to dump the options to a log file.
220 // Classes should override this method
221 virtual std::string
GetPrintableOptions() const { return ""; }
223 // Validates that the settings are valid/consistent and performs any object
224 // initialization required by this object. This method may be called as part
225 // of Configure (if invoke_prepare_options is set), or may be invoked
228 // Once an object has been prepared, non-mutable options can no longer be
231 // Classes must override this method to provide any implementation-specific
232 // initialization, such as opening log files or setting up cache parameters.
233 // Implementations should be idempotent (e.g. don't re-open the log file or
234 // reconfigure the cache), as there is the potential this method can be called
237 // By default, this method will also prepare all nested (Inner and
238 // OptionType::kConfigurable) objects.
240 // @param config_options Controls how the object is prepared. Also contains
241 // a Logger and Env that can be used to initialize this object.
242 // @return OK If the object was successfully initialized.
243 // @return InvalidArgument If this object could not be successfull
245 virtual Status
PrepareOptions(const ConfigOptions
& config_options
);
247 // Checks to see if the settings are valid for this object.
248 // This method checks to see if the input DBOptions and ColumnFamilyOptions
249 // are valid for the settings of this object. For example, an Env might not
250 // support certain mmap modes or a TableFactory might require certain
253 // By default, this method will also validate all nested (Inner and
254 // OptionType::kConfigurable) objects.
256 // @param db_opts The DBOptions to validate
257 // @param cf_opts The ColumnFamilyOptions to validate
258 // @return OK if the options are valid
259 // @return InvalidArgument If the arguments are not valid for the options
260 // of the current object.
261 virtual Status
ValidateOptions(const DBOptions
& db_opts
,
262 const ColumnFamilyOptions
& cf_opts
) const;
264 // Returns true if this object has been initialized via PrepareOptions, false
265 // otherwise. Once an object has been prepared, only mutable options may be
267 virtual bool IsPrepared() const { return prepared_
; }
270 // True once the object is prepared. Once the object is prepared, only
271 // mutable options can be configured.
274 // Returns the raw pointer for the associated named option.
275 // The name is typically the name of an option registered via the
276 // Classes may override this method to provide further specialization (such as
277 // returning a sub-option)
279 // The default implemntation looks at the registered options. If the
280 // input name matches that of a registered option, the pointer registered
281 // with that name is returned.
282 // e.g,, RegisterOptions("X", &my_ptr, ...); GetOptionsPtr("X") returns
284 virtual const void* GetOptionsPtr(const std::string
& name
) const;
286 // Method for allowing options to be configured outside of the normal
287 // registered options framework. Classes may override this method if they
288 // wish to support non-standard options implementations (such as configuring
289 // themselves from constant or simple ":"-separated strings.
291 // The default implementation does nothing and returns OK
292 virtual Status
ParseStringOptions(const ConfigOptions
& config_options
,
293 const std::string
& opts_str
);
295 // Internal method to configure an object from a map of name-value options.
296 // This method uses the input config_options to drive the configuration of
297 // the options in opt_map. Any option name that cannot be found from the
298 // input set will be returned in "unused".
300 // Classes may override this method to extend the functionality if required.
301 // @param config_options Controls how the options are configured and errors
303 // @param opts_map The set of options to configure
304 // @param unused Any options from opt_map that were not configured.
305 // @returns a Status based on the rules outlined in ConfigureFromMap
306 virtual Status
ConfigureOptions(
307 const ConfigOptions
& config_options
,
308 const std::unordered_map
<std::string
, std::string
>& opts_map
,
309 std::unordered_map
<std::string
, std::string
>* unused
);
312 // Method that configures a the specific opt_name from opt_value.
313 // By default, this method calls opt_info.ParseOption with the
315 // Classes may override this method to extend the functionality, or
316 // change the returned Status.
317 virtual Status
ParseOption(const ConfigOptions
& config_options
,
318 const OptionTypeInfo
& opt_info
,
319 const std::string
& opt_name
,
320 const std::string
& opt_value
, void* opt_ptr
);
322 // Internal method to see if the single option name/info matches for this and
323 // that Classes may override this value to change its behavior.
324 // @param config_options Controls how the options are being matched
325 // @param opt_info The OptionTypeInfo registered for this option name
326 // that controls what field is matched (offset) and how (type).
327 // @param name The name associated with this opt_info.
328 // @param this_ptr The base pointer to compare to. This is the object
330 // for this OptionTypeInfo.
331 // @param that_ptr The other pointer to compare to. This is the object
333 // for this OptionTypeInfo.
334 // @param bad_name If the match fails, the name of the option that failed to
336 virtual bool OptionsAreEqual(const ConfigOptions
& config_options
,
337 const OptionTypeInfo
& opt_info
,
338 const std::string
& name
,
339 const void* const this_ptr
,
340 const void* const that_ptr
,
341 std::string
* bad_name
) const;
344 // Internal method to serialize options (ToString)
345 // Classes may override this value to change its behavior.
346 virtual std::string
SerializeOptions(const ConfigOptions
& config_options
,
347 const std::string
& header
) const;
348 #endif // ROCKSDB_LITE
350 // Given a name (e.g. rocksdb.my.type.opt), returns the short name (opt)
351 virtual std::string
GetOptionName(const std::string
& long_name
) const;
354 // Contains the collection of options (name, opt_ptr, opt_map) associated with
355 // this object. This collection is typically set in the constructor of the
356 // Configurable option via
357 std::vector
<RegisteredOptions
> options_
;
359 } // namespace ROCKSDB_NAMESPACE