blob: 881f8502ef015234b466fc677e80c9c602c50307 [file] [log] [blame]
Austin Schuh36244a12019-09-21 17:52:38 -07001//
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 "absl/base/attributes.h"
33#include "absl/base/casts.h"
34#include "absl/flags/config.h"
35#include "absl/flags/declare.h"
36#include "absl/flags/internal/commandlineflag.h"
37#include "absl/flags/internal/flag.h"
38#include "absl/flags/marshalling.h"
39
40namespace absl {
41
42// Flag
43//
44// An `absl::Flag` holds a command-line flag value, providing a runtime
45// parameter to a binary. Such flags should be defined in the global namespace
46// and (preferably) in the module containing the binary's `main()` function.
47//
48// You should not construct and cannot use the `absl::Flag` type directly;
49// instead, you should declare flags using the `ABSL_DECLARE_FLAG()` macro
50// within a header file, and define your flag using `ABSL_FLAG()` within your
51// header's associated `.cc` file. Such flags will be named `FLAGS_name`.
52//
53// Example:
54//
55// .h file
56//
57// // Declares usage of a flag named "FLAGS_count"
58// ABSL_DECLARE_FLAG(int, count);
59//
60// .cc file
61//
62// // Defines a flag named "FLAGS_count" with a default `int` value of 0.
63// ABSL_FLAG(int, count, 0, "Count of items to process");
64//
65// No public methods of `absl::Flag<T>` are part of the Abseil Flags API.
66#if !defined(_MSC_VER)
67template <typename T>
68using Flag = flags_internal::Flag<T>;
69#else
70// MSVC debug builds do not implement constexpr correctly for classes with
71// virtual methods. To work around this we adding level of indirection, so that
72// the class `absl::Flag` contains an `internal::Flag*` (instead of being an
73// alias to that class) and dynamically allocates an instance when necessary.
74// We also forward all calls to internal::Flag methods via trampoline methods.
75// In this setup the `absl::Flag` class does not have virtual methods and thus
76// MSVC is able to initialize it at link time. To deal with multiple threads
77// accessing the flag for the first time concurrently we use an atomic boolean
78// indicating if flag object is constructed. We also employ the double-checked
79// locking pattern where the second level of protection is a global Mutex, so
80// if two threads attempt to construct the flag concurrently only one wins.
81
82namespace flags_internal {
83void LockGlobalConstructionGuard();
84void UnlockGlobalConstructionGuard();
85} // namespace flags_internal
86
87template <typename T>
88class Flag {
89 public:
90 constexpr Flag(const char* name, const flags_internal::HelpGenFunc help_gen,
91 const char* filename,
92 const flags_internal::FlagMarshallingOpFn marshalling_op,
93 const flags_internal::InitialValGenFunc initial_value_gen)
94 : name_(name),
95 help_gen_(help_gen),
96 filename_(filename),
97 marshalling_op_(marshalling_op),
98 initial_value_gen_(initial_value_gen),
99 inited_(false) {}
100
101 flags_internal::Flag<T>* GetImpl() const {
102 if (!inited_.load(std::memory_order_acquire)) {
103 flags_internal::LockGlobalConstructionGuard();
104
105 if (inited_.load(std::memory_order_acquire)) {
106 return impl_;
107 }
108
109 impl_ = new flags_internal::Flag<T>(name_, help_gen_, filename_,
110 marshalling_op_, initial_value_gen_);
111 inited_.store(true, std::memory_order_release);
112
113 flags_internal::UnlockGlobalConstructionGuard();
114 }
115
116 return impl_;
117 }
118
119 // absl::Flag API
120 bool IsRetired() const { return GetImpl()->IsRetired(); }
121 bool IsAbseilFlag() const { return GetImpl()->IsAbseilFlag(); }
122 absl::string_view Name() const { return GetImpl()->Name(); }
123 std::string Help() const { return GetImpl()->Help(); }
124 bool IsModified() const { return GetImpl()->IsModified(); }
125 void SetModified(bool is_modified) { GetImpl()->SetModified(is_modified); }
126 bool IsSpecifiedOnCommandLine() const {
127 GetImpl()->IsSpecifiedOnCommandLine();
128 }
129 absl::string_view Typename() const { return GetImpl()->Typename(); }
130 std::string Filename() const { return GetImpl()->Filename(); }
131 std::string DefaultValue() const { return GetImpl()->DefaultValue(); }
132 std::string CurrentValue() const { return GetImpl()->CurrentValue(); }
133 bool HasValidatorFn() const { return GetImpl()->HasValidatorFn(); }
134 bool InvokeValidator(const void* value) const {
135 return GetImpl()->InvokeValidator(value);
136 }
137 template <typename T>
138 inline bool IsOfType() const {
139 return GetImpl()->IsOftype<T>();
140 }
141 T Get() const { return GetImpl()->Get(); }
142 bool AtomicGet(T* v) const { return GetImpl()->AtomicGet(v); }
143 void Set(const T& v) { GetImpl()->Set(v); }
144 void SetCallback(const flags_internal::FlagCallback mutation_callback) {
145 GetImpl()->SetCallback(mutation_callback);
146 }
147 void InvokeCallback() { GetImpl()->InvokeCallback(); }
148
149 private:
150 const char* name_;
151 const flags_internal::HelpGenFunc help_gen_;
152 const char* filename_;
153 const flags_internal::FlagMarshallingOpFn marshalling_op_;
154 const flags_internal::InitialValGenFunc initial_value_gen_;
155
156 mutable std::atomic<bool> inited_;
157 mutable flags_internal::Flag<T>* impl_ = nullptr;
158};
159#endif
160
161// GetFlag()
162//
163// Returns the value (of type `T`) of an `absl::Flag<T>` instance, by value. Do
164// not construct an `absl::Flag<T>` directly and call `absl::GetFlag()`;
165// instead, refer to flag's constructed variable name (e.g. `FLAGS_name`).
166// Because this function returns by value and not by reference, it is
167// thread-safe, but note that the operation may be expensive; as a result, avoid
168// `absl::GetFlag()` within any tight loops.
169//
170// Example:
171//
172// // FLAGS_count is a Flag of type `int`
173// int my_count = absl::GetFlag(FLAGS_count);
174//
175// // FLAGS_firstname is a Flag of type `std::string`
176// std::string first_name = absl::GetFlag(FLAGS_firstname);
177template <typename T>
178ABSL_MUST_USE_RESULT T GetFlag(const absl::Flag<T>& flag) {
179#define ABSL_FLAGS_INTERNAL_LOCK_FREE_VALIDATE(BIT) \
180 static_assert( \
181 !std::is_same<T, BIT>::value, \
182 "Do not specify explicit template parameters to absl::GetFlag");
183 ABSL_FLAGS_INTERNAL_FOR_EACH_LOCK_FREE(ABSL_FLAGS_INTERNAL_LOCK_FREE_VALIDATE)
184#undef ABSL_FLAGS_INTERNAL_LOCK_FREE_VALIDATE
185
186 return flag.Get();
187}
188
189// Overload for `GetFlag()` for types that support lock-free reads.
190#define ABSL_FLAGS_INTERNAL_LOCK_FREE_EXPORT(T) \
191 ABSL_MUST_USE_RESULT T GetFlag(const absl::Flag<T>& flag);
192ABSL_FLAGS_INTERNAL_FOR_EACH_LOCK_FREE(ABSL_FLAGS_INTERNAL_LOCK_FREE_EXPORT)
193#undef ABSL_FLAGS_INTERNAL_LOCK_FREE_EXPORT
194
195// SetFlag()
196//
197// Sets the value of an `absl::Flag` to the value `v`. Do not construct an
198// `absl::Flag<T>` directly and call `absl::SetFlag()`; instead, use the
199// flag's variable name (e.g. `FLAGS_name`). This function is
200// thread-safe, but is potentially expensive. Avoid setting flags in general,
201// but especially within performance-critical code.
202template <typename T>
203void SetFlag(absl::Flag<T>* flag, const T& v) {
204 flag->Set(v);
205}
206
207// Overload of `SetFlag()` to allow callers to pass in a value that is
208// convertible to `T`. E.g., use this overload to pass a "const char*" when `T`
209// is `std::string`.
210template <typename T, typename V>
211void SetFlag(absl::Flag<T>* flag, const V& v) {
212 T value(v);
213 flag->Set(value);
214}
215
216} // namespace absl
217
218
219// ABSL_FLAG()
220//
221// This macro defines an `absl::Flag<T>` instance of a specified type `T`:
222//
223// ABSL_FLAG(T, name, default_value, help);
224//
225// where:
226//
227// * `T` is a supported flag type (see the list of types in `marshalling.h`),
228// * `name` designates the name of the flag (as a global variable
229// `FLAGS_name`),
230// * `default_value` is an expression holding the default value for this flag
231// (which must be implicitly convertible to `T`),
232// * `help` is the help text, which can also be an expression.
233//
234// This macro expands to a flag named 'FLAGS_name' of type 'T':
235//
236// absl::Flag<T> FLAGS_name = ...;
237//
238// Note that all such instances are created as global variables.
239//
240// For `ABSL_FLAG()` values that you wish to expose to other translation units,
241// it is recommended to define those flags within the `.cc` file associated with
242// the header where the flag is declared.
243//
244// Note: do not construct objects of type `absl::Flag<T>` directly. Only use the
245// `ABSL_FLAG()` macro for such construction.
246#define ABSL_FLAG(Type, name, default_value, help) \
247 ABSL_FLAG_IMPL(Type, name, default_value, help)
248
249// ABSL_FLAG().OnUpdate()
250//
251// Defines a flag of type `T` with a callback attached:
252//
253// ABSL_FLAG(T, name, default_value, help).OnUpdate(callback);
254//
255// After any setting of the flag value, the callback will be called at least
256// once. A rapid sequence of changes may be merged together into the same
257// callback. No concurrent calls to the callback will be made for the same
258// flag. Callbacks are allowed to read the current value of the flag but must
259// not mutate that flag.
260//
261// The update mechanism guarantees "eventual consistency"; if the callback
262// derives an auxiliary data structure from the flag value, it is guaranteed
263// that eventually the flag value and the derived data structure will be
264// consistent.
265//
266// Note: ABSL_FLAG.OnUpdate() does not have a public definition. Hence, this
267// comment serves as its API documentation.
268
269
270// -----------------------------------------------------------------------------
271// Implementation details below this section
272// -----------------------------------------------------------------------------
273
274// ABSL_FLAG_IMPL macro definition conditional on ABSL_FLAGS_STRIP_NAMES
275
276#if ABSL_FLAGS_STRIP_NAMES
277#define ABSL_FLAG_IMPL_FLAGNAME(txt) ""
278#define ABSL_FLAG_IMPL_FILENAME() ""
279#if !defined(_MSC_VER)
280#define ABSL_FLAG_IMPL_REGISTRAR(T, flag) \
281 absl::flags_internal::FlagRegistrar<T, false>(&flag)
282#else
283#define ABSL_FLAG_IMPL_REGISTRAR(T, flag) \
284 absl::flags_internal::FlagRegistrar<T, false>(flag.GetImpl())
285#endif
286#else
287#define ABSL_FLAG_IMPL_FLAGNAME(txt) txt
288#define ABSL_FLAG_IMPL_FILENAME() __FILE__
289#if !defined(_MSC_VER)
290#define ABSL_FLAG_IMPL_REGISTRAR(T, flag) \
291 absl::flags_internal::FlagRegistrar<T, true>(&flag)
292#else
293#define ABSL_FLAG_IMPL_REGISTRAR(T, flag) \
294 absl::flags_internal::FlagRegistrar<T, true>(flag.GetImpl())
295#endif
296#endif
297
298// ABSL_FLAG_IMPL macro definition conditional on ABSL_FLAGS_STRIP_HELP
299
300#if ABSL_FLAGS_STRIP_HELP
301#define ABSL_FLAG_IMPL_FLAGHELP(txt) absl::flags_internal::kStrippedFlagHelp
302#else
303#define ABSL_FLAG_IMPL_FLAGHELP(txt) txt
304#endif
305
306#define ABSL_FLAG_IMPL_DECLARE_HELP_WRAPPER(name, txt) \
307 static std::string AbslFlagsWrapHelp##name() { \
308 return ABSL_FLAG_IMPL_FLAGHELP(txt); \
309 }
310
311#define ABSL_FLAG_IMPL_DECLARE_DEF_VAL_WRAPPER(name, Type, default_value) \
312 static void* AbslFlagsInitFlag##name() { \
313 return absl::flags_internal::MakeFromDefaultValue<Type>(default_value); \
314 }
315
316// ABSL_FLAG_IMPL
317//
318// Note: Name of registrar object is not arbitrary. It is used to "grab"
319// global name for FLAGS_no<flag_name> symbol, thus preventing the possibility
320// of defining two flags with names foo and nofoo.
321#define ABSL_FLAG_IMPL(Type, name, default_value, help) \
322 namespace absl /* block flags in namespaces */ {} \
323 ABSL_FLAG_IMPL_DECLARE_DEF_VAL_WRAPPER(name, Type, default_value) \
324 ABSL_FLAG_IMPL_DECLARE_HELP_WRAPPER(name, help) \
325 ABSL_CONST_INIT absl::Flag<Type> FLAGS_##name( \
326 ABSL_FLAG_IMPL_FLAGNAME(#name), &AbslFlagsWrapHelp##name, \
327 ABSL_FLAG_IMPL_FILENAME(), \
328 &absl::flags_internal::FlagMarshallingOps<Type>, \
329 &AbslFlagsInitFlag##name); \
330 extern bool FLAGS_no##name; \
331 bool FLAGS_no##name = ABSL_FLAG_IMPL_REGISTRAR(Type, FLAGS_##name)
332
333// ABSL_RETIRED_FLAG
334//
335// Designates the flag (which is usually pre-existing) as "retired." A retired
336// flag is a flag that is now unused by the program, but may still be passed on
337// the command line, usually by production scripts. A retired flag is ignored
338// and code can't access it at runtime.
339//
340// This macro registers a retired flag with given name and type, with a name
341// identical to the name of the original flag you are retiring. The retired
342// flag's type can change over time, so that you can retire code to support a
343// custom flag type.
344//
345// This macro has the same signature as `ABSL_FLAG`. To retire a flag, simply
346// replace an `ABSL_FLAG` definition with `ABSL_RETIRED_FLAG`, leaving the
347// arguments unchanged (unless of course you actually want to retire the flag
348// type at this time as well).
349//
350// `default_value` is only used as a double check on the type. `explanation` is
351// unused.
352// TODO(rogeeff): Return an anonymous struct instead of bool, and place it into
353// the unnamed namespace.
354#define ABSL_RETIRED_FLAG(type, flagname, default_value, explanation) \
355 ABSL_ATTRIBUTE_UNUSED static const bool ignored_##flagname = \
356 ([] { return type(default_value); }, \
357 absl::flags_internal::RetiredFlag<type>(#flagname))
358
359#endif // ABSL_FLAGS_FLAG_H_