]>
Commit | Line | Data |
---|---|---|
20effc67 TL |
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. | |
8 | ||
9 | #pragma once | |
10 | ||
11 | #include "rocksdb/configurable.h" | |
12 | #include "rocksdb/status.h" | |
13 | ||
14 | namespace ROCKSDB_NAMESPACE { | |
15 | /** | |
16 | * Customizable a base class used by the rocksdb that describes a | |
17 | * standard way of configuring and creating objects. Customizable objects | |
18 | * are configurable objects that can be created from an ObjectRegistry. | |
19 | * | |
20 | * Customizable classes are used when there are multiple potential | |
21 | * implementations of a class for use by RocksDB (e.g. Table, Cache, | |
22 | * MergeOperator, etc). The abstract base class is expected to define a method | |
23 | * declaring its type and a factory method for creating one of these, such as: | |
24 | * static const char *Type() { return "Table"; } | |
25 | * static Status CreateFromString(const ConfigOptions& options, | |
26 | * const std::string& id, | |
27 | * std::shared_ptr<TableFactory>* result); | |
28 | * The "Type" string is expected to be unique (no two base classes are the same | |
29 | * type). This factory is expected, based on the options and id, create and | |
30 | * return the appropriate derived type of the customizable class (e.g. | |
31 | * BlockBasedTableFactory, PlainTableFactory, etc). For extension developers, | |
32 | * helper classes and methods are provided for writing this factory. | |
33 | * | |
34 | * Instances of a Customizable class need to define: | |
35 | * - A "static const char *kClassName()" method. This method defines the name | |
36 | * of the class instance (e.g. BlockBasedTable, LRUCache) and is used by the | |
37 | * CheckedCast method. | |
38 | * - The Name() of the object. This name is used when creating and saving | |
39 | * instances of this class. Typically this name will be the same as | |
40 | * kClassName(). | |
41 | * | |
42 | * Additionally, Customizable classes should register any options used to | |
43 | * configure themselves with the Configurable subsystem. | |
44 | * | |
45 | * When a Customizable is being created, the "name" property specifies | |
46 | * the name of the instance being created. | |
47 | * For custom objects, their configuration and name can be specified by: | |
48 | * [prop]={name=X;option 1 = value1[; option2=value2...]} | |
49 | * | |
50 | * [prop].name=X | |
51 | * [prop].option1 = value1 | |
52 | * | |
53 | * [prop].name=X | |
54 | * X.option1 =value1 | |
55 | */ | |
56 | class Customizable : public Configurable { | |
57 | public: | |
58 | virtual ~Customizable() {} | |
59 | ||
60 | // Returns the name of this class of Customizable | |
61 | virtual const char* Name() const = 0; | |
62 | ||
63 | // Returns an identifier for this Customizable. | |
64 | // This could be its name or something more complex (like its URL/pattern). | |
65 | // Used for pretty printing. | |
66 | virtual std::string GetId() const { | |
67 | std::string id = Name(); | |
68 | return id; | |
69 | } | |
70 | ||
71 | // This is typically determined by if the input name matches the | |
72 | // name of this object. | |
73 | // This method is typically used in conjunction with CheckedCast to find the | |
74 | // derived class instance from its base. For example, if you have an Env | |
75 | // and want the "Default" env, you would IsInstanceOf("Default") to get | |
76 | // the default implementation. This method should be used when you need a | |
77 | // specific derivative or implementation of a class. | |
78 | // | |
79 | // Intermediary caches (such as SharedCache) may wish to override this method | |
80 | // to check for the intermediary name (SharedCache). Classes with multiple | |
81 | // potential names (e.g. "PosixEnv", "DefaultEnv") may also wish to override | |
82 | // this method. | |
83 | // | |
84 | // @param name The name of the instance to find. | |
85 | // Returns true if the class is an instance of the input name. | |
86 | virtual bool IsInstanceOf(const std::string& name) const { | |
87 | return name == Name(); | |
88 | } | |
89 | ||
90 | // Returns the named instance of the Customizable as a T*, or nullptr if not | |
91 | // found. This method uses IsInstanceOf to find the appropriate class instance | |
92 | // and then casts it to the expected return type. | |
93 | template <typename T> | |
94 | const T* CheckedCast() const { | |
95 | if (IsInstanceOf(T::kClassName())) { | |
96 | return static_cast<const T*>(this); | |
97 | } else { | |
98 | return nullptr; | |
99 | } | |
100 | } | |
101 | ||
102 | template <typename T> | |
103 | T* CheckedCast() { | |
104 | if (IsInstanceOf(T::kClassName())) { | |
105 | return static_cast<T*>(this); | |
106 | } else { | |
107 | return nullptr; | |
108 | } | |
109 | } | |
110 | ||
111 | // Checks to see if this Customizable is equivalent to other. | |
112 | // This method assumes that the two objects are of the same class. | |
113 | // @param config_options Controls how the options are compared. | |
114 | // @param other The other object to compare to. | |
115 | // @param mismatch If the objects do not match, this parameter contains | |
116 | // the name of the option that triggered the match failure. | |
117 | // @param True if the objects match, false otherwise. | |
118 | // @see Configurable::AreEquivalent for more details | |
119 | bool AreEquivalent(const ConfigOptions& config_options, | |
120 | const Configurable* other, | |
121 | std::string* mismatch) const override; | |
122 | #ifndef ROCKSDB_LITE | |
123 | // Gets the value of the option associated with the input name | |
124 | // @see Configurable::GetOption for more details | |
125 | Status GetOption(const ConfigOptions& config_options, const std::string& name, | |
126 | std::string* value) const override; | |
127 | ||
128 | #endif // ROCKSDB_LITE | |
129 | protected: | |
130 | // Given a name (e.g. rocksdb.my.type.opt), returns the short name (opt) | |
131 | std::string GetOptionName(const std::string& long_name) const override; | |
132 | #ifndef ROCKSDB_LITE | |
133 | std::string SerializeOptions(const ConfigOptions& options, | |
134 | const std::string& prefix) const override; | |
135 | #endif // ROCKSDB_LITE | |
136 | }; | |
137 | ||
138 | } // namespace ROCKSDB_NAMESPACE |