From aa468ad75539619b47979911297efbb629c52e44 Mon Sep 17 00:00:00 2001 From: Abseil Team Date: Tue, 7 May 2019 12:56:42 -0700 Subject: Export of internal Abseil changes. -- 78293ba4eb4981991ae7e6edd25eb9245fcd7515 by Andy Soffer : internal changes PiperOrigin-RevId: 247073879 -- 7bd97e3aad0c3012b89a39392a6ad3f254e9f3c3 by Derek Mauro : Release commandline flags PiperOrigin-RevId: 247065920 -- 2a991849fd7b140a43b073076d194b61533fd199 by Tom Manshreck : Add documentation for built-in usage flags PiperOrigin-RevId: 247058863 -- 14157b0de45841706bbd631284191fd94c313db9 by Derek Mauro : Internal change PiperOrigin-RevId: 247058292 -- ed67e0a80468596e30540b367727a250fa415b68 by Abseil Team : Internal Change. PiperOrigin-RevId: 246828655 -- e1bc8c2aa3f90b3d56c55c5b7244e718c919265d by Abseil Team : Internal change PiperOrigin-RevId: 246822325 -- 907a68f287199f749cb9bdb48571b50bc34731e1 by Eric Fiselier : Accept vector::reference in StrCat and friends. Converting vector::reference to alphanum requires two user defined conversions, which isn't allowed. In order to accept this, we need a special constructor that is only enabled for the bool proxy types. PiperOrigin-RevId: 246626732 -- fe4295fa95cc65dee8c881ba12dd8f516e68c40d by Abseil Team : Clarify the proper way to define AbslHashValue, and fix confusing indentation. PiperOrigin-RevId: 246406528 -- d7174681a72d4a25c8fd2b4d9f515a0763eff87c by Gennadiy Rozental : Internal change PiperOrigin-RevId: 246358214 -- a7fdc19683cf1a5885e9e1af52fcdb2db1eda53b by Abseil Team : Fix sample template instantiation. PiperOrigin-RevId: 246354617 -- 29a23c6835f872948d09b24d890385bf195bc995 by Abseil Team : Fix incorrectly copy-pasted static_assert in absl::optional::value_or The static_assert for a move-constructible type previously said the type must be copy-constructible. PiperOrigin-RevId: 246313827 -- 41884d5872d4ea2c67875b00144b8c8a5859a295 by Greg Falcon : Import of CCTZ from GitHub. PiperOrigin-RevId: 245418790 -- 7f90a7f94cdd5e21232c749efe952a750b5c43a2 by Abseil Team : Internal change PiperOrigin-RevId: 245412658 -- 730a329cf047d54b46971fce1781edd857208c2a by Greg Falcon : internal change PiperOrigin-RevId: 245293234 -- cf0216be6338200cbb18167d3f3b2e98e372be77 by Greg Falcon : Internal change PiperOrigin-RevId: 245288164 GitOrigin-RevId: 78293ba4eb4981991ae7e6edd25eb9245fcd7515 Change-Id: I5ea9a852c36c722bae2d6be65fb7f72473d94ab6 --- absl/flags/flag.h | 281 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 281 insertions(+) create mode 100644 absl/flags/flag.h (limited to 'absl/flags/flag.h') diff --git a/absl/flags/flag.h b/absl/flags/flag.h new file mode 100644 index 0000000..2cbbb45 --- /dev/null +++ b/absl/flags/flag.h @@ -0,0 +1,281 @@ +// +// Copyright 2019 The Abseil Authors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// https://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// +// ----------------------------------------------------------------------------- +// File: flag.h +// ----------------------------------------------------------------------------- +// +// This header file defines the `absl::Flag` type for holding command-line +// flag data, and abstractions to create, get and set such flag data. +// +// It is important to note that this type is **unspecified** (an implementation +// detail) and you do not construct or manipulate actual `absl::Flag` +// instances. Instead, you define and declare flags using the +// `ABSL_FLAG()` and `ABSL_DECLARE_FLAG()` macros, and get and set flag values +// using the `absl::GetFlag()` and `absl::SetFlag()` functions. + +#ifndef ABSL_FLAGS_FLAG_H_ +#define ABSL_FLAGS_FLAG_H_ + +#include "absl/base/attributes.h" +#include "absl/base/casts.h" +#include "absl/flags/config.h" +#include "absl/flags/declare.h" +#include "absl/flags/internal/commandlineflag.h" +#include "absl/flags/internal/flag.h" +#include "absl/flags/marshalling.h" + +namespace absl { + +// Flag +// +// An `absl::Flag` holds a command-line flag value, providing a runtime +// parameter to a binary. Such flags should be defined in the global namespace +// and (preferably) in the module containing the binary's `main()` function. +// +// You should not construct and cannot use the `absl::Flag` type directly; +// instead, you should declare flags using the `ABSL_DECLARE_FLAG()` macro +// within a header file, and define your flag using `ABSL_FLAG()` within your +// header's associated `.cc` file. Such flags will be named `FLAGS_name`. +// +// Example: +// +// .h file +// +// // Declares usage of a flag named "FLAGS_count" +// ABSL_DECLARE_FLAG(int, count); +// +// .cc file +// +// // Defines a flag named "FLAGS_count" with a default `int` value of 0. +// ABSL_FLAG(int, count, 0, "Count of items to process"); +// +// No public methods of `absl::Flag` are part of the Abseil Flags API. +template +using Flag = flags_internal::Flag; + +// GetFlag() +// +// Returns the value (of type `T`) of an `absl::Flag` instance, by value. Do +// not construct an `absl::Flag` directly and call `absl::GetFlag()`; +// instead, refer to flag's constructed variable name (e.g. `FLAGS_name`). +// Because this function returns by value and not by reference, it is +// thread-safe, but note that the operation may be expensive; as a result, avoid +// `absl::GetFlag()` within any tight loops. +// +// Example: +// +// // FLAGS_count is a Flag of type `int` +// int my_count = absl::GetFlag(FLAGS_count); +// +// // FLAGS_firstname is a Flag of type `std::string` +// std::string first_name = absl::GetFlag(FLAGS_firstname); +template +T GetFlag(const absl::Flag& flag) { +#define ABSL_FLAGS_INTERNAL_LOCK_FREE_VALIDATE(BIT) \ + static_assert( \ + !std::is_same::value, \ + "Do not specify explicit template parameters to absl::GetFlag"); + ABSL_FLAGS_INTERNAL_FOR_EACH_LOCK_FREE(ABSL_FLAGS_INTERNAL_LOCK_FREE_VALIDATE) +#undef ABSL_FLAGS_INTERNAL_LOCK_FREE_VALIDATE + + // Implementation notes: + // + // We are wrapping a union around the value of `T` to serve three purposes: + // + // 1. `U.value` has correct size and alignment for a value of type `T` + // 2. The `U.value` constructor is not invoked since U's constructor does not + // do it explicitly. + // 3. The `U.value` destructor is invoked since U's destructor does it + // explicitly. This makes `U` a kind of RAII wrapper around non default + // constructible value of T, which is destructed when we leave the scope. + // We do need to destroy U.value, which is constructed by + // CommandLineFlag::Read even though we left it in a moved-from state + // after std::move. + // + // All of this serves to avoid requiring `T` being default constructible. + union U { + T value; + U() {} + ~U() { value.~T(); } + }; + U u; + + flag.internal.Read(&u.value, &flags_internal::FlagOps); + return std::move(u.value); +} + +// Overload for `GetFlag()` for types that support lock-free reads. +#define ABSL_FLAGS_INTERNAL_LOCK_FREE_EXPORT(T) \ + extern T GetFlag(const absl::Flag& flag); +ABSL_FLAGS_INTERNAL_FOR_EACH_LOCK_FREE(ABSL_FLAGS_INTERNAL_LOCK_FREE_EXPORT) +#undef ABSL_FLAGS_INTERNAL_LOCK_FREE_EXPORT + +// SetFlag() +// +// Sets the value of an `absl::Flag` to the value `v`. Do not construct an +// `absl::Flag` directly and call `absl::SetFlag()`; instead, use the +// flag's variable name (e.g. `FLAGS_name`). This function is +// thread-safe, but is potentially expensive. Avoid setting flags in general, +// but especially within performance-critical code. +template +void SetFlag(absl::Flag* flag, const T& v) { + flag->internal.Write(&v, &flags_internal::FlagOps); +} + +// Overload of `SetFlag()` to allow callers to pass in a value that is +// convertible to `T`. E.g., use this overload to pass a "const char*" when `T` +// is `std::string`. +template +void SetFlag(absl::Flag* flag, const V& v) { + T value(v); + SetFlag(flag, value); +} + +} // namespace absl + + +// ABSL_FLAG() +// +// This macro defines an `absl::Flag` instance of a specified type `T`: +// +// ABSL_FLAG(T, name, default_value, help); +// +// where: +// +// * `T` is a supported flag type (See below), +// * `name` designates the name of the flag (as a global variable +// `FLAGS_name`), +// * `default_value` is an expression holding the default value for this flag +// (which must be implicitly convertible to `T`), +// * `help` is the help text, which can also be an expression. +// +// This macro expands to a flag named 'FLAGS_name' of type 'T': +// +// absl::Flag FLAGS_name = ...; +// +// Note that all such instances are created as global variables. +// +// For `ABSL_FLAG()` values that you wish to expose to other translation units, +// it is recommended to define those flags within the `.cc` file associated with +// the header where the flag is declared. +// +// Note: do not construct objects of type `absl::Flag` directly. Only use the +// `ABSL_FLAG()` macro for such construction. +#define ABSL_FLAG(Type, name, default_value, help) \ + ABSL_FLAG_IMPL(Type, name, default_value, help) + +// ABSL_FLAG().OnUpdate() +// +// Defines a flag of type `T` with a callback attached: +// +// ABSL_FLAG(T, name, default_value, help).OnUpdate(callback); +// +// After any setting of the flag value, the callback will be called at least +// once. A rapid sequence of changes may be merged together into the same +// callback. No concurrent calls to the callback will be made for the same +// flag. Callbacks are allowed to read the current value of the flag but must +// not mutate that flag. +// +// The update mechanism guarantees "eventual consistency"; if the callback +// derives an auxiliary data structure from the flag value, it is guaranteed +// that eventually the flag value and the derived data structure will be +// consistent. +// +// Note: ABSL_FLAG.OnUpdate() does not have a public definition. Hence, this +// comment serves as its API documentation. + + +// ----------------------------------------------------------------------------- +// Implementation details below this section +// ----------------------------------------------------------------------------- + +// ABSL_FLAG_IMPL macro definition conditional on ABSL_FLAGS_STRIP_NAMES + +#if ABSL_FLAGS_STRIP_NAMES +#define ABSL_FLAG_IMPL_FLAGNAME(txt) "" +#define ABSL_FLAG_IMPL_FILENAME() "" +#define ABSL_FLAG_IMPL_REGISTRAR(T, flag) \ + absl::flags_internal::FlagRegistrar(&flag) +#else +#define ABSL_FLAG_IMPL_FLAGNAME(txt) txt +#define ABSL_FLAG_IMPL_FILENAME() __FILE__ +#define ABSL_FLAG_IMPL_REGISTRAR(T, flag) \ + absl::flags_internal::FlagRegistrar(&flag) +#endif + +// ABSL_FLAG_IMPL macro definition conditional on ABSL_FLAGS_STRIP_HELP + +#if ABSL_FLAGS_STRIP_HELP +#define ABSL_FLAG_IMPL_FLAGHELP(txt) absl::flags_internal::kStrippedFlagHelp +#else +#define ABSL_FLAG_IMPL_FLAGHELP(txt) txt +#endif + +#define ABSL_FLAG_IMPL_DECLARE_HELP_WRAPPER(name, txt) \ + static std::string AbslFlagsWrapHelp##name() { \ + return ABSL_FLAG_IMPL_FLAGHELP(txt); \ + } + +#define ABSL_FLAG_IMPL_DECLARE_DEF_VAL_WRAPPER(name, Type, default_value) \ + static void* AbslFlagsInitFlag##name() { \ + return absl::flags_internal::MakeFromDefaultValue(default_value); \ + } + +// ABSL_FLAG_IMPL +// +// Note: Name of registrar object is not arbitrary. It is used to "grab" +// global name for FLAGS_no symbol, thus preventing the possibility +// of defining two flags with names foo and nofoo. +#define ABSL_FLAG_IMPL(Type, name, default_value, help) \ + namespace absl {} \ + ABSL_FLAG_IMPL_DECLARE_DEF_VAL_WRAPPER(name, Type, default_value) \ + ABSL_FLAG_IMPL_DECLARE_HELP_WRAPPER(name, help) \ + absl::Flag FLAGS_##name( \ + ABSL_FLAG_IMPL_FLAGNAME(#name), \ + &AbslFlagsWrapHelp##name, \ + ABSL_FLAG_IMPL_FILENAME(), \ + &absl::flags_internal::FlagMarshallingOps, \ + &AbslFlagsInitFlag##name); \ + extern bool FLAGS_no##name; \ + bool FLAGS_no##name = ABSL_FLAG_IMPL_REGISTRAR(Type, FLAGS_##name) + +// ABSL_RETIRED_FLAG +// +// Designates the flag (which is usually pre-existing) as "retired." A retired +// flag is a flag that is now unused by the program, but may still be passed on +// the command line, usually by production scripts. A retired flag is ignored +// and code can't access it at runtime. +// +// This macro registers a retired flag with given name and type, with a name +// identical to the name of the original flag you are retiring. The retired +// flag's type can change over time, so that you can retire code to support a +// custom flag type. +// +// This macro has the same signature as `ABSL_FLAG`. To retire a flag, simply +// replace an `ABSL_FLAG` definition with `ABSL_RETIRED_FLAG`, leaving the +// arguments unchanged (unless of course you actually want to retire the flag +// type at this time as well). +// +// `default_value` is only used as a double check on the type. `explanation` is +// unused. +// TODO(rogeeff): Return an anonymous struct instead of bool, and place it into +// the unnamed namespace. +#define ABSL_RETIRED_FLAG(type, flagname, default_value, explanation) \ + ABSL_ATTRIBUTE_UNUSED static const bool ignored_##flagname = \ + ([] { return type(default_value); }, \ + absl::flags_internal::RetiredFlag(#flagname)) + +#endif // ABSL_FLAGS_FLAG_H_ -- cgit v1.2.3