OLD | NEW |
(Empty) | |
| 1 // Copyright (c) 2006, Google Inc. |
| 2 // All rights reserved. |
| 3 // |
| 4 // Redistribution and use in source and binary forms, with or without |
| 5 // modification, are permitted provided that the following conditions are |
| 6 // met: |
| 7 // |
| 8 // * Redistributions of source code must retain the above copyright |
| 9 // notice, this list of conditions and the following disclaimer. |
| 10 // * Redistributions in binary form must reproduce the above |
| 11 // copyright notice, this list of conditions and the following disclaimer |
| 12 // in the documentation and/or other materials provided with the |
| 13 // distribution. |
| 14 // * Neither the name of Google Inc. nor the names of its |
| 15 // contributors may be used to endorse or promote products derived from |
| 16 // this software without specific prior written permission. |
| 17 // |
| 18 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS |
| 19 // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT |
| 20 // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR |
| 21 // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT |
| 22 // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, |
| 23 // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT |
| 24 // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, |
| 25 // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY |
| 26 // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT |
| 27 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE |
| 28 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
| 29 |
| 30 // --- |
| 31 // Author: Ray Sidney |
| 32 // Revamped and reorganized by Craig Silverstein |
| 33 // |
| 34 // This is the file that should be included by any file which declares |
| 35 // or defines a command line flag or wants to parse command line flags |
| 36 // or print a program usage message (which will include information about |
| 37 // flags). Executive summary, in the form of an example foo.cc file: |
| 38 // |
| 39 // #include "foo.h" // foo.h has a line "DECLARE_int32(start);" |
| 40 // #include "validators.h" // hypothetical file defining ValidateIsFile() |
| 41 // |
| 42 // DEFINE_int32(end, 1000, "The last record to read"); |
| 43 // |
| 44 // DEFINE_string(filename, "my_file.txt", "The file to read"); |
| 45 // // Crash if the specified file does not exist. |
| 46 // static bool dummy = RegisterFlagValidator(&FLAGS_filename, |
| 47 // &ValidateIsFile); |
| 48 // |
| 49 // DECLARE_bool(verbose); // some other file has a DEFINE_bool(verbose, ...) |
| 50 // |
| 51 // void MyFunc() { |
| 52 // if (FLAGS_verbose) printf("Records %d-%d\n", FLAGS_start, FLAGS_end); |
| 53 // } |
| 54 // |
| 55 // Then, at the command-line: |
| 56 // ./foo --noverbose --start=5 --end=100 |
| 57 // |
| 58 // For more details, see |
| 59 // doc/gflags.html |
| 60 // |
| 61 // --- A note about thread-safety: |
| 62 // |
| 63 // We describe many functions in this routine as being thread-hostile, |
| 64 // thread-compatible, or thread-safe. Here are the meanings we use: |
| 65 // |
| 66 // thread-safe: it is safe for multiple threads to call this routine |
| 67 // (or, when referring to a class, methods of this class) |
| 68 // concurrently. |
| 69 // thread-hostile: it is not safe for multiple threads to call this |
| 70 // routine (or methods of this class) concurrently. In gflags, |
| 71 // most thread-hostile routines are intended to be called early in, |
| 72 // or even before, main() -- that is, before threads are spawned. |
| 73 // thread-compatible: it is safe for multiple threads to read from |
| 74 // this variable (when applied to variables), or to call const |
| 75 // methods of this class (when applied to classes), as long as no |
| 76 // other thread is writing to the variable or calling non-const |
| 77 // methods of this class. |
| 78 |
| 79 #ifndef GOOGLE_GFLAGS_H_ |
| 80 #define GOOGLE_GFLAGS_H_ |
| 81 |
| 82 #include <string> |
| 83 #include <vector> |
| 84 |
| 85 // We care a lot about number of bits things take up. Unfortunately, |
| 86 // systems define their bit-specific ints in a lot of different ways. |
| 87 // We use our own way, and have a typedef to get there. |
| 88 // Note: these commands below may look like "#if 1" or "#if 0", but |
| 89 // that's because they were constructed that way at ./configure time. |
| 90 // Look at gflags.h.in to see how they're calculated (based on your config). |
| 91 #if 0 |
| 92 #include <stdint.h> // the normal place uint16_t is defined |
| 93 #endif |
| 94 #if 1 |
| 95 #include <sys/types.h> // the normal place u_int16_t is defined |
| 96 #endif |
| 97 #if 0 |
| 98 #include <inttypes.h> // a third place for uint16_t or u_int16_t |
| 99 #endif |
| 100 |
| 101 // Annoying stuff for windows -- makes sure clients can import these functions |
| 102 #if defined(_WIN32) |
| 103 # ifndef GFLAGS_DLL_DECL |
| 104 # define GFLAGS_DLL_DECL __declspec(dllimport) |
| 105 # endif |
| 106 # ifndef GFLAGS_DLL_DECLARE_FLAG |
| 107 # define GFLAGS_DLL_DECLARE_FLAG __declspec(dllimport) |
| 108 # endif |
| 109 # ifndef GFLAGS_DLL_DEFINE_FLAG |
| 110 # define GFLAGS_DLL_DEFINE_FLAG __declspec(dllexport) |
| 111 # endif |
| 112 #else |
| 113 # ifndef GFLAGS_DLL_DECL |
| 114 # define GFLAGS_DLL_DECL |
| 115 # endif |
| 116 # ifndef GFLAGS_DLL_DECLARE_FLAG |
| 117 # define GFLAGS_DLL_DECLARE_FLAG |
| 118 # endif |
| 119 # ifndef GFLAGS_DLL_DEFINE_FLAG |
| 120 # define GFLAGS_DLL_DEFINE_FLAG |
| 121 # endif |
| 122 #endif |
| 123 |
| 124 namespace google { |
| 125 |
| 126 #if 0 // the C99 format |
| 127 typedef int32_t int32; |
| 128 typedef uint32_t uint32; |
| 129 typedef int64_t int64; |
| 130 typedef uint64_t uint64; |
| 131 #elif 0 // the BSD format |
| 132 typedef int32_t int32; |
| 133 typedef u_int32_t uint32; |
| 134 typedef int64_t int64; |
| 135 typedef u_int64_t uint64; |
| 136 #elif 1 // the windows (vc7) format |
| 137 typedef __int32 int32; |
| 138 typedef unsigned __int32 uint32; |
| 139 typedef __int64 int64; |
| 140 typedef unsigned __int64 uint64; |
| 141 #else |
| 142 #error Do not know how to define a 32-bit integer quantity on your system |
| 143 #endif |
| 144 |
| 145 // TODO(kjellander): update generated .h's for new gflags. |
| 146 // https://code.google.com/p/webrtc/issues/detail?id=2251 |
| 147 extern const char* VersionString(); |
| 148 extern void SetVersionString(const std::string& version); |
| 149 |
| 150 // -------------------------------------------------------------------- |
| 151 // To actually define a flag in a file, use DEFINE_bool, |
| 152 // DEFINE_string, etc. at the bottom of this file. You may also find |
| 153 // it useful to register a validator with the flag. This ensures that |
| 154 // when the flag is parsed from the commandline, or is later set via |
| 155 // SetCommandLineOption, we call the validation function. It is _not_ |
| 156 // called when you assign the value to the flag directly using the = operator. |
| 157 // |
| 158 // The validation function should return true if the flag value is valid, and |
| 159 // false otherwise. If the function returns false for the new setting of the |
| 160 // flag, the flag will retain its current value. If it returns false for the |
| 161 // default value, ParseCommandLineFlags() will die. |
| 162 // |
| 163 // This function is safe to call at global construct time (as in the |
| 164 // example below). |
| 165 // |
| 166 // Example use: |
| 167 // static bool ValidatePort(const char* flagname, int32 value) { |
| 168 // if (value > 0 && value < 32768) // value is ok |
| 169 // return true; |
| 170 // printf("Invalid value for --%s: %d\n", flagname, (int)value); |
| 171 // return false; |
| 172 // } |
| 173 // DEFINE_int32(port, 0, "What port to listen on"); |
| 174 // static bool dummy = RegisterFlagValidator(&FLAGS_port, &ValidatePort); |
| 175 |
| 176 // Returns true if successfully registered, false if not (because the |
| 177 // first argument doesn't point to a command-line flag, or because a |
| 178 // validator is already registered for this flag). |
| 179 GFLAGS_DLL_DECL bool RegisterFlagValidator(const bool* flag, |
| 180 bool (*validate_fn)(const char*, bool)); |
| 181 GFLAGS_DLL_DECL bool RegisterFlagValidator(const int32* flag, |
| 182 bool (*validate_fn)(const char*, int32)); |
| 183 GFLAGS_DLL_DECL bool RegisterFlagValidator(const int64* flag, |
| 184 bool (*validate_fn)(const char*, int64)); |
| 185 GFLAGS_DLL_DECL bool RegisterFlagValidator(const uint64* flag, |
| 186 bool (*validate_fn)(const char*, uint64)); |
| 187 GFLAGS_DLL_DECL bool RegisterFlagValidator(const double* flag, |
| 188 bool (*validate_fn)(const char*, double)); |
| 189 GFLAGS_DLL_DECL bool RegisterFlagValidator(const std::string* flag, |
| 190 bool (*validate_fn)(const char*, const std::string&))
; |
| 191 |
| 192 |
| 193 // -------------------------------------------------------------------- |
| 194 // These methods are the best way to get access to info about the |
| 195 // list of commandline flags. Note that these routines are pretty slow. |
| 196 // GetAllFlags: mostly-complete info about the list, sorted by file. |
| 197 // ShowUsageWithFlags: pretty-prints the list to stdout (what --help does) |
| 198 // ShowUsageWithFlagsRestrict: limit to filenames with restrict as a substr |
| 199 // |
| 200 // In addition to accessing flags, you can also access argv[0] (the program |
| 201 // name) and argv (the entire commandline), which we sock away a copy of. |
| 202 // These variables are static, so you should only set them once. |
| 203 |
| 204 struct GFLAGS_DLL_DECL CommandLineFlagInfo { |
| 205 std::string name; // the name of the flag |
| 206 std::string type; // the type of the flag: int32, etc |
| 207 std::string description; // the "help text" associated with the flag |
| 208 std::string current_value; // the current value, as a string |
| 209 std::string default_value; // the default value, as a string |
| 210 std::string filename; // 'cleaned' version of filename holding the flag |
| 211 bool has_validator_fn; // true if RegisterFlagValidator called on flag |
| 212 bool is_default; // true if the flag has the default value and |
| 213 // has not been set explicitly from the cmdline |
| 214 // or via SetCommandLineOption |
| 215 const void* flag_ptr; |
| 216 }; |
| 217 |
| 218 // Using this inside of a validator is a recipe for a deadlock. |
| 219 // TODO(wojtekm) Fix locking when validators are running, to make it safe to |
| 220 // call validators during ParseAllFlags. |
| 221 // Also make sure then to uncomment the corresponding unit test in |
| 222 // commandlineflags_unittest.sh |
| 223 extern GFLAGS_DLL_DECL void GetAllFlags(std::vector<CommandLineFlagInfo>* OUTPUT
); |
| 224 // These two are actually defined in commandlineflags_reporting.cc. |
| 225 extern GFLAGS_DLL_DECL void ShowUsageWithFlags(const char *argv0); // what --he
lp does |
| 226 extern GFLAGS_DLL_DECL void ShowUsageWithFlagsRestrict(const char *argv0, const
char *restrict); |
| 227 |
| 228 // Create a descriptive string for a flag. |
| 229 // Goes to some trouble to make pretty line breaks. |
| 230 extern GFLAGS_DLL_DECL std::string DescribeOneFlag(const CommandLineFlagInfo& fl
ag); |
| 231 |
| 232 // Thread-hostile; meant to be called before any threads are spawned. |
| 233 extern GFLAGS_DLL_DECL void SetArgv(int argc, const char** argv); |
| 234 // The following functions are thread-safe as long as SetArgv() is |
| 235 // only called before any threads start. |
| 236 extern GFLAGS_DLL_DECL const std::vector<std::string>& GetArgvs(); // all of ar
gv as a vector |
| 237 extern GFLAGS_DLL_DECL const char* GetArgv(); // all of argv as a
string |
| 238 extern GFLAGS_DLL_DECL const char* GetArgv0(); // only argv0 |
| 239 extern GFLAGS_DLL_DECL uint32 GetArgvSum(); // simple checksum o
f argv |
| 240 extern GFLAGS_DLL_DECL const char* ProgramInvocationName(); // argv0, or "UNKNOW
N" if not set |
| 241 extern GFLAGS_DLL_DECL const char* ProgramInvocationShortName(); // basename(a
rgv0) |
| 242 // ProgramUsage() is thread-safe as long as SetUsageMessage() is only |
| 243 // called before any threads start. |
| 244 extern GFLAGS_DLL_DECL const char* ProgramUsage(); // string set by Set
UsageMessage() |
| 245 |
| 246 |
| 247 // -------------------------------------------------------------------- |
| 248 // Normally you access commandline flags by just saying "if (FLAGS_foo)" |
| 249 // or whatever, and set them by calling "FLAGS_foo = bar" (or, more |
| 250 // commonly, via the DEFINE_foo macro). But if you need a bit more |
| 251 // control, we have programmatic ways to get/set the flags as well. |
| 252 // These programmatic ways to access flags are thread-safe, but direct |
| 253 // access is only thread-compatible. |
| 254 |
| 255 // Return true iff the flagname was found. |
| 256 // OUTPUT is set to the flag's value, or unchanged if we return false. |
| 257 extern GFLAGS_DLL_DECL bool GetCommandLineOption(const char* name, std::string*
OUTPUT); |
| 258 |
| 259 // Return true iff the flagname was found. OUTPUT is set to the flag's |
| 260 // CommandLineFlagInfo or unchanged if we return false. |
| 261 extern GFLAGS_DLL_DECL bool GetCommandLineFlagInfo(const char* name, |
| 262 CommandLineFlagInfo* OUTPUT); |
| 263 |
| 264 // Return the CommandLineFlagInfo of the flagname. exit() if name not found. |
| 265 // Example usage, to check if a flag's value is currently the default value: |
| 266 // if (GetCommandLineFlagInfoOrDie("foo").is_default) ... |
| 267 extern GFLAGS_DLL_DECL CommandLineFlagInfo GetCommandLineFlagInfoOrDie(const cha
r* name); |
| 268 |
| 269 enum GFLAGS_DLL_DECL FlagSettingMode { |
| 270 // update the flag's value (can call this multiple times). |
| 271 SET_FLAGS_VALUE, |
| 272 // update the flag's value, but *only if* it has not yet been updated |
| 273 // with SET_FLAGS_VALUE, SET_FLAG_IF_DEFAULT, or "FLAGS_xxx = nondef". |
| 274 SET_FLAG_IF_DEFAULT, |
| 275 // set the flag's default value to this. If the flag has not yet updated |
| 276 // yet (via SET_FLAGS_VALUE, SET_FLAG_IF_DEFAULT, or "FLAGS_xxx = nondef") |
| 277 // change the flag's current value to the new default value as well. |
| 278 SET_FLAGS_DEFAULT |
| 279 }; |
| 280 |
| 281 // Set a particular flag ("command line option"). Returns a string |
| 282 // describing the new value that the option has been set to. The |
| 283 // return value API is not well-specified, so basically just depend on |
| 284 // it to be empty if the setting failed for some reason -- the name is |
| 285 // not a valid flag name, or the value is not a valid value -- and |
| 286 // non-empty else. |
| 287 |
| 288 // SetCommandLineOption uses set_mode == SET_FLAGS_VALUE (the common case) |
| 289 extern GFLAGS_DLL_DECL std::string SetCommandLineOption(const char* name, const
char* value); |
| 290 extern GFLAGS_DLL_DECL std::string SetCommandLineOptionWithMode(const char* name
, const char* value, |
| 291 FlagSettingMode set_mode); |
| 292 |
| 293 |
| 294 // -------------------------------------------------------------------- |
| 295 // Saves the states (value, default value, whether the user has set |
| 296 // the flag, registered validators, etc) of all flags, and restores |
| 297 // them when the FlagSaver is destroyed. This is very useful in |
| 298 // tests, say, when you want to let your tests change the flags, but |
| 299 // make sure that they get reverted to the original states when your |
| 300 // test is complete. |
| 301 // |
| 302 // Example usage: |
| 303 // void TestFoo() { |
| 304 // FlagSaver s1; |
| 305 // FLAG_foo = false; |
| 306 // FLAG_bar = "some value"; |
| 307 // |
| 308 // // test happens here. You can return at any time |
| 309 // // without worrying about restoring the FLAG values. |
| 310 // } |
| 311 // |
| 312 // Note: This class is marked with __attribute__((unused)) because all the |
| 313 // work is done in the constructor and destructor, so in the standard |
| 314 // usage example above, the compiler would complain that it's an |
| 315 // unused variable. |
| 316 // |
| 317 // This class is thread-safe. |
| 318 |
| 319 class GFLAGS_DLL_DECL FlagSaver { |
| 320 public: |
| 321 FlagSaver(); |
| 322 ~FlagSaver(); |
| 323 |
| 324 private: |
| 325 class FlagSaverImpl* impl_; // we use pimpl here to keep API steady |
| 326 |
| 327 FlagSaver(const FlagSaver&); // no copying! |
| 328 void operator=(const FlagSaver&); |
| 329 } ; |
| 330 |
| 331 // -------------------------------------------------------------------- |
| 332 // Some deprecated or hopefully-soon-to-be-deprecated functions. |
| 333 |
| 334 // This is often used for logging. TODO(csilvers): figure out a better way |
| 335 extern GFLAGS_DLL_DECL std::string CommandlineFlagsIntoString(); |
| 336 // Usually where this is used, a FlagSaver should be used instead. |
| 337 extern GFLAGS_DLL_DECL bool ReadFlagsFromString(const std::string& flagfileconte
nts, |
| 338 const char* prog_name, |
| 339 bool errors_are_fatal); // uses SET_FLAGS_VALUE |
| 340 |
| 341 // These let you manually implement --flagfile functionality. |
| 342 // DEPRECATED. |
| 343 extern GFLAGS_DLL_DECL bool AppendFlagsIntoFile(const std::string& filename, con
st char* prog_name); |
| 344 extern GFLAGS_DLL_DECL bool SaveCommandFlags(); // actually defined in google.c
c ! |
| 345 extern GFLAGS_DLL_DECL bool ReadFromFlagsFile(const std::string& filename, const
char* prog_name, |
| 346 bool errors_are_fatal); // uses SET_FLAGS_VALUE |
| 347 |
| 348 |
| 349 // -------------------------------------------------------------------- |
| 350 // Useful routines for initializing flags from the environment. |
| 351 // In each case, if 'varname' does not exist in the environment |
| 352 // return defval. If 'varname' does exist but is not valid |
| 353 // (e.g., not a number for an int32 flag), abort with an error. |
| 354 // Otherwise, return the value. NOTE: for booleans, for true use |
| 355 // 't' or 'T' or 'true' or '1', for false 'f' or 'F' or 'false' or '0'. |
| 356 |
| 357 extern GFLAGS_DLL_DECL bool BoolFromEnv(const char *varname, bool defval); |
| 358 extern GFLAGS_DLL_DECL int32 Int32FromEnv(const char *varname, int32 defval); |
| 359 extern GFLAGS_DLL_DECL int64 Int64FromEnv(const char *varname, int64 defval); |
| 360 extern GFLAGS_DLL_DECL uint64 Uint64FromEnv(const char *varname, uint64 defval); |
| 361 extern GFLAGS_DLL_DECL double DoubleFromEnv(const char *varname, double defval); |
| 362 extern GFLAGS_DLL_DECL const char *StringFromEnv(const char *varname, const char
*defval); |
| 363 |
| 364 |
| 365 // -------------------------------------------------------------------- |
| 366 // The next two functions parse commandlineflags from main(): |
| 367 |
| 368 // Set the "usage" message for this program. For example: |
| 369 // string usage("This program does nothing. Sample usage:\n"); |
| 370 // usage += argv[0] + " <uselessarg1> <uselessarg2>"; |
| 371 // SetUsageMessage(usage); |
| 372 // Do not include commandline flags in the usage: we do that for you! |
| 373 // Thread-hostile; meant to be called before any threads are spawned. |
| 374 extern GFLAGS_DLL_DECL void SetUsageMessage(const std::string& usage); |
| 375 |
| 376 // Looks for flags in argv and parses them. Rearranges argv to put |
| 377 // flags first, or removes them entirely if remove_flags is true. |
| 378 // If a flag is defined more than once in the command line or flag |
| 379 // file, the last definition is used. |
| 380 // See top-of-file for more details on this function. |
| 381 #ifndef SWIG // In swig, use ParseCommandLineFlagsScript() instead. |
| 382 extern GFLAGS_DLL_DECL uint32 ParseCommandLineFlags(int *argc, char*** argv, |
| 383 bool remove_flags); |
| 384 #endif |
| 385 |
| 386 |
| 387 // Calls to ParseCommandLineNonHelpFlags and then to |
| 388 // HandleCommandLineHelpFlags can be used instead of a call to |
| 389 // ParseCommandLineFlags during initialization, in order to allow for |
| 390 // changing default values for some FLAGS (via |
| 391 // e.g. SetCommandLineOptionWithMode calls) between the time of |
| 392 // command line parsing and the time of dumping help information for |
| 393 // the flags as a result of command line parsing. |
| 394 // If a flag is defined more than once in the command line or flag |
| 395 // file, the last definition is used. |
| 396 extern GFLAGS_DLL_DECL uint32 ParseCommandLineNonHelpFlags(int *argc, char*** ar
gv, |
| 397 bool remove_flags); |
| 398 // This is actually defined in commandlineflags_reporting.cc. |
| 399 // This function is misnamed (it also handles --version, etc.), but |
| 400 // it's too late to change that now. :-( |
| 401 extern GFLAGS_DLL_DECL void HandleCommandLineHelpFlags(); // in commandlinefla
gs_reporting.cc |
| 402 |
| 403 // Allow command line reparsing. Disables the error normally |
| 404 // generated when an unknown flag is found, since it may be found in a |
| 405 // later parse. Thread-hostile; meant to be called before any threads |
| 406 // are spawned. |
| 407 extern GFLAGS_DLL_DECL void AllowCommandLineReparsing(); |
| 408 |
| 409 // Reparse the flags that have not yet been recognized. |
| 410 // Only flags registered since the last parse will be recognized. |
| 411 // Any flag value must be provided as part of the argument using "=", |
| 412 // not as a separate command line argument that follows the flag argument. |
| 413 // Intended for handling flags from dynamically loaded libraries, |
| 414 // since their flags are not registered until they are loaded. |
| 415 extern GFLAGS_DLL_DECL void ReparseCommandLineNonHelpFlags(); |
| 416 |
| 417 // Clean up memory allocated by flags. This is only needed to reduce |
| 418 // the quantity of "potentially leaked" reports emitted by memory |
| 419 // debugging tools such as valgrind. It is not required for normal |
| 420 // operation, or for the perftools heap-checker. It must only be called |
| 421 // when the process is about to exit, and all threads that might |
| 422 // access flags are quiescent. Referencing flags after this is called |
| 423 // will have unexpected consequences. This is not safe to run when |
| 424 // multiple threads might be running: the function is thread-hostile. |
| 425 extern GFLAGS_DLL_DECL void ShutDownCommandLineFlags(); |
| 426 |
| 427 |
| 428 // -------------------------------------------------------------------- |
| 429 // Now come the command line flag declaration/definition macros that |
| 430 // will actually be used. They're kind of hairy. A major reason |
| 431 // for this is initialization: we want people to be able to access |
| 432 // variables in global constructors and have that not crash, even if |
| 433 // their global constructor runs before the global constructor here. |
| 434 // (Obviously, we can't guarantee the flags will have the correct |
| 435 // default value in that case, but at least accessing them is safe.) |
| 436 // The only way to do that is have flags point to a static buffer. |
| 437 // So we make one, using a union to ensure proper alignment, and |
| 438 // then use placement-new to actually set up the flag with the |
| 439 // correct default value. In the same vein, we have to worry about |
| 440 // flag access in global destructors, so FlagRegisterer has to be |
| 441 // careful never to destroy the flag-values it constructs. |
| 442 // |
| 443 // Note that when we define a flag variable FLAGS_<name>, we also |
| 444 // preemptively define a junk variable, FLAGS_no<name>. This is to |
| 445 // cause a link-time error if someone tries to define 2 flags with |
| 446 // names like "logging" and "nologging". We do this because a bool |
| 447 // flag FLAG can be set from the command line to true with a "-FLAG" |
| 448 // argument, and to false with a "-noFLAG" argument, and so this can |
| 449 // potentially avert confusion. |
| 450 // |
| 451 // We also put flags into their own namespace. It is purposefully |
| 452 // named in an opaque way that people should have trouble typing |
| 453 // directly. The idea is that DEFINE puts the flag in the weird |
| 454 // namespace, and DECLARE imports the flag from there into the current |
| 455 // namespace. The net result is to force people to use DECLARE to get |
| 456 // access to a flag, rather than saying "extern bool FLAGS_whatever;" |
| 457 // or some such instead. We want this so we can put extra |
| 458 // functionality (like sanity-checking) in DECLARE if we want, and |
| 459 // make sure it is picked up everywhere. |
| 460 // |
| 461 // We also put the type of the variable in the namespace, so that |
| 462 // people can't DECLARE_int32 something that they DEFINE_bool'd |
| 463 // elsewhere. |
| 464 |
| 465 class GFLAGS_DLL_DECL FlagRegisterer { |
| 466 public: |
| 467 FlagRegisterer(const char* name, const char* type, |
| 468 const char* help, const char* filename, |
| 469 void* current_storage, void* defvalue_storage); |
| 470 }; |
| 471 |
| 472 extern bool FlagsTypeWarn(const char *name); |
| 473 |
| 474 // If your application #defines STRIP_FLAG_HELP to a non-zero value |
| 475 // before #including this file, we remove the help message from the |
| 476 // binary file. This can reduce the size of the resulting binary |
| 477 // somewhat, and may also be useful for security reasons. |
| 478 |
| 479 extern const char kStrippedFlagHelp[]; |
| 480 |
| 481 } |
| 482 |
| 483 #ifndef SWIG // In swig, ignore the main flag declarations |
| 484 |
| 485 #if defined(STRIP_FLAG_HELP) && STRIP_FLAG_HELP > 0 |
| 486 // Need this construct to avoid the 'defined but not used' warning. |
| 487 #define MAYBE_STRIPPED_HELP(txt) (false ? (txt) : kStrippedFlagHelp) |
| 488 #else |
| 489 #define MAYBE_STRIPPED_HELP(txt) txt |
| 490 #endif |
| 491 |
| 492 // Each command-line flag has two variables associated with it: one |
| 493 // with the current value, and one with the default value. However, |
| 494 // we have a third variable, which is where value is assigned; it's a |
| 495 // constant. This guarantees that FLAG_##value is initialized at |
| 496 // static initialization time (e.g. before program-start) rather than |
| 497 // than global construction time (which is after program-start but |
| 498 // before main), at least when 'value' is a compile-time constant. We |
| 499 // use a small trick for the "default value" variable, and call it |
| 500 // FLAGS_no<name>. This serves the second purpose of assuring a |
| 501 // compile error if someone tries to define a flag named no<name> |
| 502 // which is illegal (--foo and --nofoo both affect the "foo" flag). |
| 503 #define DEFINE_VARIABLE(type, shorttype, name, value, help) \ |
| 504 namespace fL##shorttype { \ |
| 505 static const type FLAGS_nono##name = value; \ |
| 506 /* We always want to export defined variables, dll or no */ \ |
| 507 GFLAGS_DLL_DEFINE_FLAG type FLAGS_##name = FLAGS_nono##name; \ |
| 508 type FLAGS_no##name = FLAGS_nono##name; \ |
| 509 static ::google::FlagRegisterer o_##name( \ |
| 510 #name, #type, MAYBE_STRIPPED_HELP(help), __FILE__, \ |
| 511 &FLAGS_##name, &FLAGS_no##name); \ |
| 512 } \ |
| 513 using fL##shorttype::FLAGS_##name |
| 514 |
| 515 #define DECLARE_VARIABLE(type, shorttype, name) \ |
| 516 namespace fL##shorttype { \ |
| 517 /* We always want to import declared variables, dll or no */ \ |
| 518 extern GFLAGS_DLL_DECLARE_FLAG type FLAGS_##name; \ |
| 519 } \ |
| 520 using fL##shorttype::FLAGS_##name |
| 521 |
| 522 // For DEFINE_bool, we want to do the extra check that the passed-in |
| 523 // value is actually a bool, and not a string or something that can be |
| 524 // coerced to a bool. These declarations (no definition needed!) will |
| 525 // help us do that, and never evaluate From, which is important. |
| 526 // We'll use 'sizeof(IsBool(val))' to distinguish. This code requires |
| 527 // that the compiler have different sizes for bool & double. Since |
| 528 // this is not guaranteed by the standard, we check it with a |
| 529 // compile-time assert (msg[-1] will give a compile-time error). |
| 530 namespace fLB { |
| 531 struct CompileAssert {}; |
| 532 typedef CompileAssert expected_sizeof_double_neq_sizeof_bool[ |
| 533 (sizeof(double) != sizeof(bool)) ? 1 : -1]; |
| 534 template<typename From> GFLAGS_DLL_DECL double IsBoolFlag(const From& from); |
| 535 GFLAGS_DLL_DECL bool IsBoolFlag(bool from); |
| 536 } // namespace fLB |
| 537 |
| 538 #define DECLARE_bool(name) DECLARE_VARIABLE(bool, B, name) |
| 539 #define DEFINE_bool(name, val, txt) \ |
| 540 namespace fLB { \ |
| 541 typedef ::fLB::CompileAssert FLAG_##name##_value_is_not_a_bool[ \ |
| 542 (sizeof(::fLB::IsBoolFlag(val)) != sizeof(double)) ? 1 : -1]; \ |
| 543 } \ |
| 544 DEFINE_VARIABLE(bool, B, name, val, txt) |
| 545 |
| 546 #define DECLARE_int32(name) DECLARE_VARIABLE(::google::int32, I, name) |
| 547 #define DEFINE_int32(name,val,txt) DEFINE_VARIABLE(::google::int32, I, name, va
l, txt) |
| 548 |
| 549 #define DECLARE_int64(name) DECLARE_VARIABLE(::google::int64, I64, name) |
| 550 #define DEFINE_int64(name,val,txt) DEFINE_VARIABLE(::google::int64, I64, name,
val, txt) |
| 551 |
| 552 #define DECLARE_uint64(name) DECLARE_VARIABLE(::google::uint64, U64, name
) |
| 553 #define DEFINE_uint64(name,val,txt) DEFINE_VARIABLE(::google::uint64, U64, name,
val, txt) |
| 554 |
| 555 #define DECLARE_double(name) DECLARE_VARIABLE(double, D, name) |
| 556 #define DEFINE_double(name, val, txt) DEFINE_VARIABLE(double, D, name, val, txt) |
| 557 |
| 558 // Strings are trickier, because they're not a POD, so we can't |
| 559 // construct them at static-initialization time (instead they get |
| 560 // constructed at global-constructor time, which is much later). To |
| 561 // try to avoid crashes in that case, we use a char buffer to store |
| 562 // the string, which we can static-initialize, and then placement-new |
| 563 // into it later. It's not perfect, but the best we can do. |
| 564 |
| 565 namespace fLS { |
| 566 // The meaning of "string" might be different between now and when the |
| 567 // macros below get invoked (e.g., if someone is experimenting with |
| 568 // other string implementations that get defined after this file is |
| 569 // included). Save the current meaning now and use it in the macros. |
| 570 typedef std::string clstring; |
| 571 |
| 572 inline clstring* dont_pass0toDEFINE_string(char *stringspot, |
| 573 const char *value) { |
| 574 return new(stringspot) clstring(value); |
| 575 } |
| 576 inline clstring* dont_pass0toDEFINE_string(char *stringspot, |
| 577 const clstring &value) { |
| 578 return new(stringspot) clstring(value); |
| 579 } |
| 580 inline clstring* dont_pass0toDEFINE_string(char *stringspot, |
| 581 int value); |
| 582 } // namespace fLS |
| 583 |
| 584 #define DECLARE_string(name) namespace fLS { extern GFLAGS_DLL_DECLARE_FLAG ::f
LS::clstring& FLAGS_##name; } \ |
| 585 using fLS::FLAGS_##name |
| 586 |
| 587 // We need to define a var named FLAGS_no##name so people don't define |
| 588 // --string and --nostring. And we need a temporary place to put val |
| 589 // so we don't have to evaluate it twice. Two great needs that go |
| 590 // great together! |
| 591 #define DEFINE_string(name, val, txt) \ |
| 592 namespace fLS { \ |
| 593 using ::fLS::clstring; \ |
| 594 static union { void* align; char s[sizeof(clstring)]; } s_##name[2]; \ |
| 595 clstring* const FLAGS_no##name = ::fLS:: \ |
| 596 dont_pass0toDEFINE_string(s_##name[0].s, \ |
| 597 val); \ |
| 598 static ::google::FlagRegisterer o_##name( \ |
| 599 #name, "string", MAYBE_STRIPPED_HELP(txt), __FILE__, \ |
| 600 s_##name[0].s, new (s_##name[1].s) clstring(*FLAGS_no##name)); \ |
| 601 GFLAGS_DLL_DEFINE_FLAG clstring& FLAGS_##name = *FLAGS_no##name; \ |
| 602 } \ |
| 603 using fLS::FLAGS_##name |
| 604 |
| 605 #endif // SWIG |
| 606 |
| 607 #endif // GOOGLE_GFLAGS_H_ |
OLD | NEW |