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 "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.
66template <typename T>
67using Flag = flags_internal::Flag<T>;
68
69// GetFlag()
70//
71// Returns the value (of type `T`) of an `absl::Flag<T>` instance, by value. Do
72// not construct an `absl::Flag<T>` directly and call `absl::GetFlag()`;
73// instead, refer to flag's constructed variable name (e.g. `FLAGS_name`).
74// Because this function returns by value and not by reference, it is
75// thread-safe, but note that the operation may be expensive; as a result, avoid
76// `absl::GetFlag()` within any tight loops.
77//
78// Example:
79//
80// // FLAGS_count is a Flag of type `int`
81// int my_count = absl::GetFlag(FLAGS_count);
82//
83// // FLAGS_firstname is a Flag of type `std::string`
84// std::string first_name = absl::GetFlag(FLAGS_firstname);
85template <typename T>
86T GetFlag(const absl::Flag<T>& flag) {
87#define ABSL_FLAGS_INTERNAL_LOCK_FREE_VALIDATE(BIT) \
88 static_assert( \
89 !std::is_same<T, BIT>::value, \
90 "Do not specify explicit template parameters to absl::GetFlag");
91 ABSL_FLAGS_INTERNAL_FOR_EACH_LOCK_FREE(ABSL_FLAGS_INTERNAL_LOCK_FREE_VALIDATE)
92#undef ABSL_FLAGS_INTERNAL_LOCK_FREE_VALIDATE
93
94 // Implementation notes:
95 //
96 // We are wrapping a union around the value of `T` to serve three purposes:
97 //
98 // 1. `U.value` has correct size and alignment for a value of type `T`
99 // 2. The `U.value` constructor is not invoked since U's constructor does not
100 // do it explicitly.
101 // 3. The `U.value` destructor is invoked since U's destructor does it
102 // explicitly. This makes `U` a kind of RAII wrapper around non default
103 // constructible value of T, which is destructed when we leave the scope.
104 // We do need to destroy U.value, which is constructed by
105 // CommandLineFlag::Read even though we left it in a moved-from state
106 // after std::move.
107 //
108 // All of this serves to avoid requiring `T` being default constructible.
109 union U {
110 T value;
111 U() {}
112 ~U() { value.~T(); }
113 };
114 U u;
115
116 flag.internal.Read(&u.value, &flags_internal::FlagOps<T>);
117 return std::move(u.value);
118}
119
120// Overload for `GetFlag()` for types that support lock-free reads.
121#define ABSL_FLAGS_INTERNAL_LOCK_FREE_EXPORT(T) \
122 extern T GetFlag(const absl::Flag<T>& flag);
123ABSL_FLAGS_INTERNAL_FOR_EACH_LOCK_FREE(ABSL_FLAGS_INTERNAL_LOCK_FREE_EXPORT)
124#undef ABSL_FLAGS_INTERNAL_LOCK_FREE_EXPORT
125
126// SetFlag()
127//
128// Sets the value of an `absl::Flag` to the value `v`. Do not construct an
129// `absl::Flag<T>` directly and call `absl::SetFlag()`; instead, use the
130// flag's variable name (e.g. `FLAGS_name`). This function is
131// thread-safe, but is potentially expensive. Avoid setting flags in general,
132// but especially within performance-critical code.
133template <typename T>
134void SetFlag(absl::Flag<T>* flag, const T& v) {
135 flag->internal.Write(&v, &flags_internal::FlagOps<T>);
136}
137
138// Overload of `SetFlag()` to allow callers to pass in a value that is
139// convertible to `T`. E.g., use this overload to pass a "const char*" when `T`
140// is `std::string`.
141template <typename T, typename V>
142void SetFlag(absl::Flag<T>* flag, const V& v) {
143 T value(v);
144 SetFlag<T>(flag, value);
145}
146
147} // namespace absl
148
149
150// ABSL_FLAG()
151//
152// This macro defines an `absl::Flag<T>` instance of a specified type `T`:
153//
154// ABSL_FLAG(T, name, default_value, help);
155//
156// where:
157//
158// * `T` is a supported flag type (see the list of types in `marshalling.h`),
159// * `name` designates the name of the flag (as a global variable
160// `FLAGS_name`),
161// * `default_value` is an expression holding the default value for this flag
162// (which must be implicitly convertible to `T`),
163// * `help` is the help text, which can also be an expression.
164//
165// This macro expands to a flag named 'FLAGS_name' of type 'T':
166//
167// absl::Flag<T> FLAGS_name = ...;
168//
169// Note that all such instances are created as global variables.
170//
171// For `ABSL_FLAG()` values that you wish to expose to other translation units,
172// it is recommended to define those flags within the `.cc` file associated with
173// the header where the flag is declared.
174//
175// Note: do not construct objects of type `absl::Flag<T>` directly. Only use the
176// `ABSL_FLAG()` macro for such construction.
177#define ABSL_FLAG(Type, name, default_value, help) \
178 ABSL_FLAG_IMPL(Type, name, default_value, help)
179
180// ABSL_FLAG().OnUpdate()
181//
182// Defines a flag of type `T` with a callback attached:
183//
184// ABSL_FLAG(T, name, default_value, help).OnUpdate(callback);
185//
186// After any setting of the flag value, the callback will be called at least
187// once. A rapid sequence of changes may be merged together into the same
188// callback. No concurrent calls to the callback will be made for the same
189// flag. Callbacks are allowed to read the current value of the flag but must
190// not mutate that flag.
191//
192// The update mechanism guarantees "eventual consistency"; if the callback
193// derives an auxiliary data structure from the flag value, it is guaranteed
194// that eventually the flag value and the derived data structure will be
195// consistent.
196//
197// Note: ABSL_FLAG.OnUpdate() does not have a public definition. Hence, this
198// comment serves as its API documentation.
199
200
201// -----------------------------------------------------------------------------
202// Implementation details below this section
203// -----------------------------------------------------------------------------
204
205// ABSL_FLAG_IMPL macro definition conditional on ABSL_FLAGS_STRIP_NAMES
206
207#if ABSL_FLAGS_STRIP_NAMES
208#define ABSL_FLAG_IMPL_FLAGNAME(txt) ""
209#define ABSL_FLAG_IMPL_FILENAME() ""
210#define ABSL_FLAG_IMPL_REGISTRAR(T, flag) \
211 absl::flags_internal::FlagRegistrar<T, false>(&flag)
212#else
213#define ABSL_FLAG_IMPL_FLAGNAME(txt) txt
214#define ABSL_FLAG_IMPL_FILENAME() __FILE__
215#define ABSL_FLAG_IMPL_REGISTRAR(T, flag) \
216 absl::flags_internal::FlagRegistrar<T, true>(&flag)
217#endif
218
219// ABSL_FLAG_IMPL macro definition conditional on ABSL_FLAGS_STRIP_HELP
220
221#if ABSL_FLAGS_STRIP_HELP
222#define ABSL_FLAG_IMPL_FLAGHELP(txt) absl::flags_internal::kStrippedFlagHelp
223#else
224#define ABSL_FLAG_IMPL_FLAGHELP(txt) txt
225#endif
226
227#define ABSL_FLAG_IMPL_DECLARE_HELP_WRAPPER(name, txt) \
228 static std::string AbslFlagsWrapHelp##name() { \
229 return ABSL_FLAG_IMPL_FLAGHELP(txt); \
230 }
231
232#define ABSL_FLAG_IMPL_DECLARE_DEF_VAL_WRAPPER(name, Type, default_value) \
233 static void* AbslFlagsInitFlag##name() { \
234 return absl::flags_internal::MakeFromDefaultValue<Type>(default_value); \
235 }
236
237// ABSL_FLAG_IMPL
238//
239// Note: Name of registrar object is not arbitrary. It is used to "grab"
240// global name for FLAGS_no<flag_name> symbol, thus preventing the possibility
241// of defining two flags with names foo and nofoo.
242#define ABSL_FLAG_IMPL(Type, name, default_value, help) \
243 namespace absl {} \
244 ABSL_FLAG_IMPL_DECLARE_DEF_VAL_WRAPPER(name, Type, default_value) \
245 ABSL_FLAG_IMPL_DECLARE_HELP_WRAPPER(name, help) \
246 absl::Flag<Type> FLAGS_##name( \
247 ABSL_FLAG_IMPL_FLAGNAME(#name), \
248 &AbslFlagsWrapHelp##name, \
249 ABSL_FLAG_IMPL_FILENAME(), \
250 &absl::flags_internal::FlagMarshallingOps<Type>, \
251 &AbslFlagsInitFlag##name); \
252 extern bool FLAGS_no##name; \
253 bool FLAGS_no##name = ABSL_FLAG_IMPL_REGISTRAR(Type, FLAGS_##name)
254
255// ABSL_RETIRED_FLAG
256//
257// Designates the flag (which is usually pre-existing) as "retired." A retired
258// flag is a flag that is now unused by the program, but may still be passed on
259// the command line, usually by production scripts. A retired flag is ignored
260// and code can't access it at runtime.
261//
262// This macro registers a retired flag with given name and type, with a name
263// identical to the name of the original flag you are retiring. The retired
264// flag's type can change over time, so that you can retire code to support a
265// custom flag type.
266//
267// This macro has the same signature as `ABSL_FLAG`. To retire a flag, simply
268// replace an `ABSL_FLAG` definition with `ABSL_RETIRED_FLAG`, leaving the
269// arguments unchanged (unless of course you actually want to retire the flag
270// type at this time as well).
271//
272// `default_value` is only used as a double check on the type. `explanation` is
273// unused.
274// TODO(rogeeff): Return an anonymous struct instead of bool, and place it into
275// the unnamed namespace.
276#define ABSL_RETIRED_FLAG(type, flagname, default_value, explanation) \
277 ABSL_ATTRIBUTE_UNUSED static const bool ignored_##flagname = \
278 ([] { return type(default_value); }, \
279 absl::flags_internal::RetiredFlag<type>(#flagname))
280
281#endif // ABSL_FLAGS_FLAG_H_
282