flag.h
Go to the documentation of this file.
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"
38 #include "absl/flags/marshalling.h"
39 
40 namespace 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 template <typename T>
67 using 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);
85 template <typename T>
86 T 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");
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);
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.
133 template <typename T>
134 void 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`.
141 template <typename T, typename V>
142 void 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 below),
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_
int v
Definition: variant_test.cc:81
void Read(void *dst, const flags_internal::FlagOpFn dst_op) const
#define ABSL_FLAGS_INTERNAL_FOR_EACH_LOCK_FREE(A)
Definition: algorithm.h:29
flags_internal::Flag< T > Flag
Definition: declare.h:43
absl::flags_internal::CommandLineFlag internal
Definition: internal/flag.h:47
#define ABSL_FLAGS_INTERNAL_LOCK_FREE_VALIDATE(BIT)
#define ABSL_FLAGS_INTERNAL_LOCK_FREE_EXPORT(T)
Definition: flag.h:121
size_t value
T GetFlag(const absl::Flag< T > &flag)
Definition: flag.h:86
constexpr absl::remove_reference_t< T > && move(T &&t) noexcept
Definition: utility.h:219
void SetFlag(absl::Flag< T > *flag, const T &v)
Definition: flag.h:134
void Write(const void *src, const flags_internal::FlagOpFn src_op)


abseil_cpp
Author(s):
autogenerated on Tue Jun 18 2019 19:44:36