flag.h (13260B)
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 <cstdint> 33 #include <string> 34 #include <type_traits> 35 36 #include "absl/base/attributes.h" 37 #include "absl/base/config.h" 38 #include "absl/base/nullability.h" 39 #include "absl/base/optimization.h" 40 #include "absl/flags/commandlineflag.h" 41 #include "absl/flags/config.h" 42 #include "absl/flags/internal/flag.h" 43 #include "absl/flags/internal/registry.h" 44 #include "absl/strings/string_view.h" 45 46 namespace absl { 47 ABSL_NAMESPACE_BEGIN 48 49 // Flag 50 // 51 // An `absl::Flag` holds a command-line flag value, providing a runtime 52 // parameter to a binary. Such flags should be defined in the global namespace 53 // and (preferably) in the module containing the binary's `main()` function. 54 // 55 // You should not construct and cannot use the `absl::Flag` type directly; 56 // instead, you should declare flags using the `ABSL_DECLARE_FLAG()` macro 57 // within a header file, and define your flag using `ABSL_FLAG()` within your 58 // header's associated `.cc` file. Such flags will be named `FLAGS_name`. 59 // 60 // Example: 61 // 62 // .h file 63 // 64 // // Declares usage of a flag named "FLAGS_count" 65 // ABSL_DECLARE_FLAG(int, count); 66 // 67 // .cc file 68 // 69 // // Defines a flag named "FLAGS_count" with a default `int` value of 0. 70 // ABSL_FLAG(int, count, 0, "Count of items to process"); 71 // 72 // No public methods of `absl::Flag<T>` are part of the Abseil Flags API. 73 // 74 // For type support of Abseil Flags, see the marshalling.h header file, which 75 // discusses supported standard types, optional flags, and additional Abseil 76 // type support. 77 78 template <typename T> 79 using Flag = flags_internal::Flag<T>; 80 81 // GetFlag() 82 // 83 // Returns the value (of type `T`) of an `absl::Flag<T>` instance, by value. Do 84 // not construct an `absl::Flag<T>` directly and call `absl::GetFlag()`; 85 // instead, refer to flag's constructed variable name (e.g. `FLAGS_name`). 86 // Because this function returns by value and not by reference, it is 87 // thread-safe, but note that the operation may be expensive; as a result, avoid 88 // `absl::GetFlag()` within any tight loops. 89 // 90 // Example: 91 // 92 // // FLAGS_count is a Flag of type `int` 93 // int my_count = absl::GetFlag(FLAGS_count); 94 // 95 // // FLAGS_firstname is a Flag of type `std::string` 96 // std::string first_name = absl::GetFlag(FLAGS_firstname); 97 template <typename T> 98 [[nodiscard]] T GetFlag(const absl::Flag<T>& flag) { 99 return flags_internal::FlagImplPeer::InvokeGet<T>(flag); 100 } 101 102 // SetFlag() 103 // 104 // Sets the value of an `absl::Flag` to the value `v`. Do not construct an 105 // `absl::Flag<T>` directly and call `absl::SetFlag()`; instead, use the 106 // flag's variable name (e.g. `FLAGS_name`). This function is 107 // thread-safe, but is potentially expensive. Avoid setting flags in general, 108 // but especially within performance-critical code. 109 template <typename T> 110 void SetFlag(absl::Flag<T>* absl_nonnull flag, const T& v) { 111 flags_internal::FlagImplPeer::InvokeSet(*flag, v); 112 } 113 114 // Overload of `SetFlag()` to allow callers to pass in a value that is 115 // convertible to `T`. E.g., use this overload to pass a "const char*" when `T` 116 // is `std::string`. 117 template <typename T, typename V> 118 void SetFlag(absl::Flag<T>* absl_nonnull flag, const V& v) { 119 T value(v); 120 flags_internal::FlagImplPeer::InvokeSet(*flag, value); 121 } 122 123 // GetFlagReflectionHandle() 124 // 125 // Returns the reflection handle corresponding to specified Abseil Flag 126 // instance. Use this handle to access flag's reflection information, like name, 127 // location, default value etc. 128 // 129 // Example: 130 // 131 // std::string = absl::GetFlagReflectionHandle(FLAGS_count).DefaultValue(); 132 133 template <typename T> 134 const CommandLineFlag& GetFlagReflectionHandle(const absl::Flag<T>& f) { 135 return flags_internal::FlagImplPeer::InvokeReflect(f); 136 } 137 138 ABSL_NAMESPACE_END 139 } // namespace absl 140 141 142 // ABSL_FLAG() 143 // 144 // This macro defines an `absl::Flag<T>` instance of a specified type `T`: 145 // 146 // ABSL_FLAG(T, name, default_value, help); 147 // 148 // where: 149 // 150 // * `T` is a supported flag type (see the list of types in `marshalling.h`), 151 // * `name` designates the name of the flag (as a global variable 152 // `FLAGS_name`), 153 // * `default_value` is an expression holding the default value for this flag 154 // (which must be implicitly convertible to `T`), 155 // * `help` is the help text, which can also be an expression. 156 // 157 // This macro expands to a flag named 'FLAGS_name' of type 'T': 158 // 159 // absl::Flag<T> FLAGS_name = ...; 160 // 161 // Note that all such instances are created as global variables. 162 // 163 // For `ABSL_FLAG()` values that you wish to expose to other translation units, 164 // it is recommended to define those flags within the `.cc` file associated with 165 // the header where the flag is declared. 166 // 167 // Note: do not construct objects of type `absl::Flag<T>` directly. Only use the 168 // `ABSL_FLAG()` macro for such construction. 169 #define ABSL_FLAG(Type, name, default_value, help) \ 170 ABSL_FLAG_IMPL(Type, name, default_value, help) 171 172 // ABSL_FLAG().OnUpdate() 173 // 174 // Defines a flag of type `T` with a callback attached: 175 // 176 // ABSL_FLAG(T, name, default_value, help).OnUpdate(callback); 177 // 178 // `callback` should be convertible to `void (*)()`. 179 // 180 // After any setting of the flag value, the callback will be called at least 181 // once. A rapid sequence of changes may be merged together into the same 182 // callback. No concurrent calls to the callback will be made for the same 183 // flag. Callbacks are allowed to read the current value of the flag but must 184 // not mutate that flag. 185 // 186 // The update mechanism guarantees "eventual consistency"; if the callback 187 // derives an auxiliary data structure from the flag value, it is guaranteed 188 // that eventually the flag value and the derived data structure will be 189 // consistent. 190 // 191 // Note: ABSL_FLAG.OnUpdate() does not have a public definition. Hence, this 192 // comment serves as its API documentation. 193 194 // ----------------------------------------------------------------------------- 195 // Implementation details below this section 196 // ----------------------------------------------------------------------------- 197 198 // ABSL_FLAG_IMPL macro definition conditional on ABSL_FLAGS_STRIP_NAMES 199 #define ABSL_FLAG_IMPL_FLAG_PTR(flag) flag 200 #define ABSL_FLAG_IMPL_HELP_ARG(name) \ 201 absl::flags_internal::HelpArg<AbslFlagHelpGenFor##name>( \ 202 FLAGS_help_storage_##name) 203 #define ABSL_FLAG_IMPL_DEFAULT_ARG(Type, name) \ 204 absl::flags_internal::DefaultArg<Type, AbslFlagDefaultGenFor##name>(0) 205 206 #if ABSL_FLAGS_STRIP_NAMES 207 #define ABSL_FLAG_IMPL_FLAGNAME(txt) "" 208 #define ABSL_FLAG_IMPL_TYPENAME(txt) "" 209 #define ABSL_FLAG_IMPL_FILENAME() "" 210 #define ABSL_FLAG_IMPL_REGISTRAR(T, flag) \ 211 absl::flags_internal::FlagRegistrar<T, false>(ABSL_FLAG_IMPL_FLAG_PTR(flag), \ 212 nullptr) 213 #else 214 #define ABSL_FLAG_IMPL_FLAGNAME(txt) txt 215 #define ABSL_FLAG_IMPL_TYPENAME(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 extern ::absl::Flag<Type> FLAGS_##name; \ 269 namespace absl /* block flags in namespaces */ {} \ 270 ABSL_FLAG_IMPL_DECLARE_DEF_VAL_WRAPPER(name, Type, default_value) \ 271 ABSL_FLAG_IMPL_DECLARE_HELP_WRAPPER(name, help) \ 272 ABSL_CONST_INIT absl::Flag<Type> FLAGS_##name{ \ 273 ABSL_FLAG_IMPL_FLAGNAME(#name), ABSL_FLAG_IMPL_TYPENAME(#Type), \ 274 ABSL_FLAG_IMPL_FILENAME(), ABSL_FLAG_IMPL_HELP_ARG(name), \ 275 ABSL_FLAG_IMPL_DEFAULT_ARG(Type, name)}; \ 276 extern absl::flags_internal::FlagRegistrarEmpty FLAGS_no##name; \ 277 absl::flags_internal::FlagRegistrarEmpty FLAGS_no##name = \ 278 ABSL_FLAG_IMPL_REGISTRAR(Type, FLAGS_##name) 279 280 // ABSL_RETIRED_FLAG 281 // 282 // Designates the flag (which is usually pre-existing) as "retired." A retired 283 // flag is a flag that is now unused by the program, but may still be passed on 284 // the command line, usually by production scripts. A retired flag is ignored 285 // and code can't access it at runtime. 286 // 287 // This macro registers a retired flag with given name and type, with a name 288 // identical to the name of the original flag you are retiring. The retired 289 // flag's type can change over time, so that you can retire code to support a 290 // custom flag type. 291 // 292 // This macro has the same signature as `ABSL_FLAG`. To retire a flag, simply 293 // replace an `ABSL_FLAG` definition with `ABSL_RETIRED_FLAG`, leaving the 294 // arguments unchanged (unless of course you actually want to retire the flag 295 // type at this time as well). 296 // 297 // `default_value` and `explanation` are unused. 298 // TODO(rogeeff): replace RETIRED_FLAGS with FLAGS once forward declarations of 299 // retired flags are cleaned up. 300 #define ABSL_RETIRED_FLAG(type, name, default_value, explanation) \ 301 static absl::flags_internal::RetiredFlag<type> RETIRED_FLAGS_##name; \ 302 ABSL_ATTRIBUTE_UNUSED static const auto RETIRED_FLAGS_REG_##name = \ 303 (RETIRED_FLAGS_##name.Retire(#name), \ 304 ::absl::flags_internal::FlagRegistrarEmpty{}) 305 306 #endif // ABSL_FLAGS_FLAG_H_