Austin Schuh | 36244a1 | 2019-09-21 17:52:38 -0700 | [diff] [blame^] | 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 | |
| 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 | #if !defined(_MSC_VER) |
| 67 | template <typename T> |
| 68 | using 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 | |
| 82 | namespace flags_internal { |
| 83 | void LockGlobalConstructionGuard(); |
| 84 | void UnlockGlobalConstructionGuard(); |
| 85 | } // namespace flags_internal |
| 86 | |
| 87 | template <typename T> |
| 88 | class 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); |
| 177 | template <typename T> |
| 178 | ABSL_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); |
| 192 | ABSL_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. |
| 202 | template <typename T> |
| 203 | void 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`. |
| 210 | template <typename T, typename V> |
| 211 | void 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_ |