1 //
2 // Copyright 2019 The Abseil Authors.
3 //
4 // Licensed under the Apache License, Version 2.0 (the "License");
5 // you may not use this file except in compliance with the License.
6 // You may obtain a copy of the License at
7 //
8 // https://www.apache.org/licenses/LICENSE-2.0
9 //
10 // Unless required by applicable law or agreed to in writing, software
11 // distributed under the License is distributed on an "AS IS" BASIS,
12 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 // See the License for the specific language governing permissions and
14 // limitations under the License.
15 //
16 // -----------------------------------------------------------------------------
17 // File: flag.h
18 // -----------------------------------------------------------------------------
19 //
20 // This header file defines the `absl::Flag<T>` type for holding command-line
21 // flag data, and abstractions to create, get and set such flag data.
22 //
23 // It is important to note that this type is **unspecified** (an implementation
24 // detail) and you do not construct or manipulate actual `absl::Flag<T>`
25 // instances. Instead, you define and declare flags using the
26 // `ABSL_FLAG()` and `ABSL_DECLARE_FLAG()` macros, and get and set flag values
27 // using the `absl::GetFlag()` and `absl::SetFlag()` functions.
28
29 #ifndef ABSL_FLAGS_FLAG_H_
30 #define ABSL_FLAGS_FLAG_H_
31
32 #include <string>
33 #include <type_traits>
34
35 #include "absl/base/attributes.h"
36 #include "absl/base/config.h"
37 #include "absl/base/optimization.h"
38 #include "absl/flags/config.h"
39 #include "absl/flags/internal/flag.h"
40 #include "absl/flags/internal/registry.h"
41 #include "absl/strings/string_view.h"
42
43 namespace absl {
44 ABSL_NAMESPACE_BEGIN
45
46 // Flag
47 //
48 // An `absl::Flag` holds a command-line flag value, providing a runtime
49 // parameter to a binary. Such flags should be defined in the global namespace
50 // and (preferably) in the module containing the binary's `main()` function.
51 //
52 // You should not construct and cannot use the `absl::Flag` type directly;
53 // instead, you should declare flags using the `ABSL_DECLARE_FLAG()` macro
54 // within a header file, and define your flag using `ABSL_FLAG()` within your
55 // header's associated `.cc` file. Such flags will be named `FLAGS_name`.
56 //
57 // Example:
58 //
59 // .h file
60 //
61 // // Declares usage of a flag named "FLAGS_count"
62 // ABSL_DECLARE_FLAG(int, count);
63 //
64 // .cc file
65 //
66 // // Defines a flag named "FLAGS_count" with a default `int` value of 0.
67 // ABSL_FLAG(int, count, 0, "Count of items to process");
68 //
69 // No public methods of `absl::Flag<T>` are part of the Abseil Flags API.
70 #if !defined(_MSC_VER) || defined(__clang__)
71 template <typename T>
72 using Flag = flags_internal::Flag<T>;
73 #else
74 #include "absl/flags/internal/flag_msvc.inc"
75 #endif
76
77 // GetFlag()
78 //
79 // Returns the value (of type `T`) of an `absl::Flag<T>` instance, by value. Do
80 // not construct an `absl::Flag<T>` directly and call `absl::GetFlag()`;
81 // instead, refer to flag's constructed variable name (e.g. `FLAGS_name`).
82 // Because this function returns by value and not by reference, it is
83 // thread-safe, but note that the operation may be expensive; as a result, avoid
84 // `absl::GetFlag()` within any tight loops.
85 //
86 // Example:
87 //
88 // // FLAGS_count is a Flag of type `int`
89 // int my_count = absl::GetFlag(FLAGS_count);
90 //
91 // // FLAGS_firstname is a Flag of type `std::string`
92 // std::string first_name = absl::GetFlag(FLAGS_firstname);
93 template <typename T>
GetFlag(const absl::Flag<T> & flag)94 ABSL_MUST_USE_RESULT T GetFlag(const absl::Flag<T>& flag) {
95 return flags_internal::FlagImplPeer::InvokeGet<T>(flag);
96 }
97
98 // SetFlag()
99 //
100 // Sets the value of an `absl::Flag` to the value `v`. Do not construct an
101 // `absl::Flag<T>` directly and call `absl::SetFlag()`; instead, use the
102 // flag's variable name (e.g. `FLAGS_name`). This function is
103 // thread-safe, but is potentially expensive. Avoid setting flags in general,
104 // but especially within performance-critical code.
105 template <typename T>
SetFlag(absl::Flag<T> * flag,const T & v)106 void SetFlag(absl::Flag<T>* flag, const T& v) {
107 flags_internal::FlagImplPeer::InvokeSet(*flag, v);
108 }
109
110 // Overload of `SetFlag()` to allow callers to pass in a value that is
111 // convertible to `T`. E.g., use this overload to pass a "const char*" when `T`
112 // is `std::string`.
113 template <typename T, typename V>
SetFlag(absl::Flag<T> * flag,const V & v)114 void SetFlag(absl::Flag<T>* flag, const V& v) {
115 T value(v);
116 flags_internal::FlagImplPeer::InvokeSet(*flag, value);
117 }
118
119 // GetFlagReflectionHandle()
120 //
121 // Returns the reflection handle corresponding to specified Abseil Flag
122 // instance. Use this handle to access flag's reflection information, like name,
123 // location, default value etc.
124 //
125 // Example:
126 //
127 // std::string = absl::GetFlagReflectionHandle(FLAGS_count).DefaultValue();
128
129 template <typename T>
GetFlagReflectionHandle(const absl::Flag<T> & f)130 const CommandLineFlag& GetFlagReflectionHandle(const absl::Flag<T>& f) {
131 return flags_internal::FlagImplPeer::InvokeReflect(f);
132 }
133
134 ABSL_NAMESPACE_END
135 } // namespace absl
136
137
138 // ABSL_FLAG()
139 //
140 // This macro defines an `absl::Flag<T>` instance of a specified type `T`:
141 //
142 // ABSL_FLAG(T, name, default_value, help);
143 //
144 // where:
145 //
146 // * `T` is a supported flag type (see the list of types in `marshalling.h`),
147 // * `name` designates the name of the flag (as a global variable
148 // `FLAGS_name`),
149 // * `default_value` is an expression holding the default value for this flag
150 // (which must be implicitly convertible to `T`),
151 // * `help` is the help text, which can also be an expression.
152 //
153 // This macro expands to a flag named 'FLAGS_name' of type 'T':
154 //
155 // absl::Flag<T> FLAGS_name = ...;
156 //
157 // Note that all such instances are created as global variables.
158 //
159 // For `ABSL_FLAG()` values that you wish to expose to other translation units,
160 // it is recommended to define those flags within the `.cc` file associated with
161 // the header where the flag is declared.
162 //
163 // Note: do not construct objects of type `absl::Flag<T>` directly. Only use the
164 // `ABSL_FLAG()` macro for such construction.
165 #define ABSL_FLAG(Type, name, default_value, help) \
166 ABSL_FLAG_IMPL(Type, name, default_value, help)
167
168 // ABSL_FLAG().OnUpdate()
169 //
170 // Defines a flag of type `T` with a callback attached:
171 //
172 // ABSL_FLAG(T, name, default_value, help).OnUpdate(callback);
173 //
174 // `callback` should be convertible to `void (*)()`.
175 //
176 // After any setting of the flag value, the callback will be called at least
177 // once. A rapid sequence of changes may be merged together into the same
178 // callback. No concurrent calls to the callback will be made for the same
179 // flag. Callbacks are allowed to read the current value of the flag but must
180 // not mutate that flag.
181 //
182 // The update mechanism guarantees "eventual consistency"; if the callback
183 // derives an auxiliary data structure from the flag value, it is guaranteed
184 // that eventually the flag value and the derived data structure will be
185 // consistent.
186 //
187 // Note: ABSL_FLAG.OnUpdate() does not have a public definition. Hence, this
188 // comment serves as its API documentation.
189
190 // -----------------------------------------------------------------------------
191 // Implementation details below this section
192 // -----------------------------------------------------------------------------
193
194 // ABSL_FLAG_IMPL macro definition conditional on ABSL_FLAGS_STRIP_NAMES
195 #if !defined(_MSC_VER) || defined(__clang__)
196 #define ABSL_FLAG_IMPL_FLAG_PTR(flag) flag
197 #define ABSL_FLAG_IMPL_HELP_ARG(name) \
198 absl::flags_internal::HelpArg<AbslFlagHelpGenFor##name>( \
199 FLAGS_help_storage_##name)
200 #define ABSL_FLAG_IMPL_DEFAULT_ARG(Type, name) \
201 absl::flags_internal::DefaultArg<Type, AbslFlagDefaultGenFor##name>(0)
202 #else
203 #define ABSL_FLAG_IMPL_FLAG_PTR(flag) flag.GetImpl()
204 #define ABSL_FLAG_IMPL_HELP_ARG(name) &AbslFlagHelpGenFor##name::NonConst
205 #define ABSL_FLAG_IMPL_DEFAULT_ARG(Type, name) &AbslFlagDefaultGenFor##name::Gen
206 #endif
207
208 #if ABSL_FLAGS_STRIP_NAMES
209 #define ABSL_FLAG_IMPL_FLAGNAME(txt) ""
210 #define ABSL_FLAG_IMPL_FILENAME() ""
211 #define ABSL_FLAG_IMPL_REGISTRAR(T, flag) \
212 absl::flags_internal::FlagRegistrar<T, false>(ABSL_FLAG_IMPL_FLAG_PTR(flag), \
213 nullptr)
214 #else
215 #define ABSL_FLAG_IMPL_FLAGNAME(txt) txt
216 #define ABSL_FLAG_IMPL_FILENAME() __FILE__
217 #define ABSL_FLAG_IMPL_REGISTRAR(T, flag) \
218 absl::flags_internal::FlagRegistrar<T, true>(ABSL_FLAG_IMPL_FLAG_PTR(flag), \
219 __FILE__)
220 #endif
221
222 // ABSL_FLAG_IMPL macro definition conditional on ABSL_FLAGS_STRIP_HELP
223
224 #if ABSL_FLAGS_STRIP_HELP
225 #define ABSL_FLAG_IMPL_FLAGHELP(txt) absl::flags_internal::kStrippedFlagHelp
226 #else
227 #define ABSL_FLAG_IMPL_FLAGHELP(txt) txt
228 #endif
229
230 // AbslFlagHelpGenFor##name is used to encapsulate both immediate (method Const)
231 // and lazy (method NonConst) evaluation of help message expression. We choose
232 // between the two via the call to HelpArg in absl::Flag instantiation below.
233 // If help message expression is constexpr evaluable compiler will optimize
234 // away this whole struct.
235 // TODO(rogeeff): place these generated structs into local namespace and apply
236 // ABSL_INTERNAL_UNIQUE_SHORT_NAME.
237 // TODO(rogeeff): Apply __attribute__((nodebug)) to FLAGS_help_storage_##name
238 #define ABSL_FLAG_IMPL_DECLARE_HELP_WRAPPER(name, txt) \
239 struct AbslFlagHelpGenFor##name { \
240 /* The expression is run in the caller as part of the */ \
241 /* default value argument. That keeps temporaries alive */ \
242 /* long enough for NonConst to work correctly. */ \
243 static constexpr absl::string_view Value( \
244 absl::string_view absl_flag_help = ABSL_FLAG_IMPL_FLAGHELP(txt)) { \
245 return absl_flag_help; \
246 } \
247 static std::string NonConst() { return std::string(Value()); } \
248 }; \
249 constexpr auto FLAGS_help_storage_##name ABSL_INTERNAL_UNIQUE_SMALL_NAME() \
250 ABSL_ATTRIBUTE_SECTION_VARIABLE(flags_help_cold) = \
251 absl::flags_internal::HelpStringAsArray<AbslFlagHelpGenFor##name>( \
252 0);
253
254 #define ABSL_FLAG_IMPL_DECLARE_DEF_VAL_WRAPPER(name, Type, default_value) \
255 struct AbslFlagDefaultGenFor##name { \
256 Type value = absl::flags_internal::InitDefaultValue<Type>(default_value); \
257 static void Gen(void* absl_flag_default_loc) { \
258 new (absl_flag_default_loc) Type(AbslFlagDefaultGenFor##name{}.value); \
259 } \
260 };
261
262 // ABSL_FLAG_IMPL
263 //
264 // Note: Name of registrar object is not arbitrary. It is used to "grab"
265 // global name for FLAGS_no<flag_name> symbol, thus preventing the possibility
266 // of defining two flags with names foo and nofoo.
267 #define ABSL_FLAG_IMPL(Type, name, default_value, help) \
268 namespace absl /* block flags in namespaces */ {} \
269 ABSL_FLAG_IMPL_DECLARE_DEF_VAL_WRAPPER(name, Type, default_value) \
270 ABSL_FLAG_IMPL_DECLARE_HELP_WRAPPER(name, help) \
271 ABSL_CONST_INIT absl::Flag<Type> FLAGS_##name{ \
272 ABSL_FLAG_IMPL_FLAGNAME(#name), ABSL_FLAG_IMPL_FILENAME(), \
273 ABSL_FLAG_IMPL_HELP_ARG(name), ABSL_FLAG_IMPL_DEFAULT_ARG(Type, name)}; \
274 extern absl::flags_internal::FlagRegistrarEmpty FLAGS_no##name; \
275 absl::flags_internal::FlagRegistrarEmpty FLAGS_no##name = \
276 ABSL_FLAG_IMPL_REGISTRAR(Type, FLAGS_##name)
277
278 // ABSL_RETIRED_FLAG
279 //
280 // Designates the flag (which is usually pre-existing) as "retired." A retired
281 // flag is a flag that is now unused by the program, but may still be passed on
282 // the command line, usually by production scripts. A retired flag is ignored
283 // and code can't access it at runtime.
284 //
285 // This macro registers a retired flag with given name and type, with a name
286 // identical to the name of the original flag you are retiring. The retired
287 // flag's type can change over time, so that you can retire code to support a
288 // custom flag type.
289 //
290 // This macro has the same signature as `ABSL_FLAG`. To retire a flag, simply
291 // replace an `ABSL_FLAG` definition with `ABSL_RETIRED_FLAG`, leaving the
292 // arguments unchanged (unless of course you actually want to retire the flag
293 // type at this time as well).
294 //
295 // `default_value` is only used as a double check on the type. `explanation` is
296 // unused.
297 // TODO(rogeeff): replace RETIRED_FLAGS with FLAGS once forward declarations of
298 // retired flags are cleaned up.
299 #define ABSL_RETIRED_FLAG(type, name, default_value, explanation) \
300 static absl::flags_internal::RetiredFlag<type> RETIRED_FLAGS_##name; \
301 ABSL_ATTRIBUTE_UNUSED static const auto RETIRED_FLAGS_REG_##name = \
302 (RETIRED_FLAGS_##name.Retire(#name), \
303 ::absl::flags_internal::FlagRegistrarEmpty{})
304
305 #endif // ABSL_FLAGS_FLAG_H_
306