Export of internal Abseil changes.

--
78293ba4eb4981991ae7e6edd25eb9245fcd7515 by Andy Soffer <asoffer@google.com>:

internal changes

PiperOrigin-RevId: 247073879

--
7bd97e3aad0c3012b89a39392a6ad3f254e9f3c3 by Derek Mauro <dmauro@google.com>:

Release commandline flags

PiperOrigin-RevId: 247065920

--
2a991849fd7b140a43b073076d194b61533fd199 by Tom Manshreck <shreck@google.com>:

Add documentation for built-in usage flags

PiperOrigin-RevId: 247058863

--
14157b0de45841706bbd631284191fd94c313db9 by Derek Mauro <dmauro@google.com>:

Internal change

PiperOrigin-RevId: 247058292

--
ed67e0a80468596e30540b367727a250fa415b68 by Abseil Team <absl-team@google.com>:

Internal Change.

PiperOrigin-RevId: 246828655

--
e1bc8c2aa3f90b3d56c55c5b7244e718c919265d by Abseil Team <absl-team@google.com>:

Internal change

PiperOrigin-RevId: 246822325

--
907a68f287199f749cb9bdb48571b50bc34731e1 by Eric Fiselier <ericwf@google.com>:

Accept vector<bool>::reference in StrCat and friends.

Converting vector<bool>::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 <absl-team@google.com>:

Clarify the proper way to define AbslHashValue, and fix confusing indentation.

PiperOrigin-RevId: 246406528

--
d7174681a72d4a25c8fd2b4d9f515a0763eff87c by Gennadiy Rozental <rogeeff@google.com>:

Internal change

PiperOrigin-RevId: 246358214

--
a7fdc19683cf1a5885e9e1af52fcdb2db1eda53b by Abseil Team <absl-team@google.com>:

Fix sample template instantiation.

PiperOrigin-RevId: 246354617

--
29a23c6835f872948d09b24d890385bf195bc995 by Abseil Team <absl-team@google.com>:

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 <gfalcon@google.com>:

Import of CCTZ from GitHub.

PiperOrigin-RevId: 245418790

--
7f90a7f94cdd5e21232c749efe952a750b5c43a2 by Abseil Team <absl-team@google.com>:

Internal change

PiperOrigin-RevId: 245412658

--
730a329cf047d54b46971fce1781edd857208c2a by Greg Falcon <gfalcon@google.com>:

internal change

PiperOrigin-RevId: 245293234

--
cf0216be6338200cbb18167d3f3b2e98e372be77 by Greg Falcon <gfalcon@google.com>:

Internal change

PiperOrigin-RevId: 245288164
GitOrigin-RevId: 78293ba4eb4981991ae7e6edd25eb9245fcd7515
Change-Id: I5ea9a852c36c722bae2d6be65fb7f72473d94ab6

1 files changed, 365 insertions, 0 deletions

diff --git a/absl/flags/internal/commandlineflag.h b/absl/flags/internal/commandlineflag.h
new file mode 100644
index 000000000000..4815cdc7c9a2
--- /dev/null
+++ b/absl/flags/internal/commandlineflag.h
@@ -0,0 +1,365 @@
+//
+// 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.
+
+#ifndef ABSL_FLAGS_INTERNAL_COMMANDLINEFLAG_H_
+#define ABSL_FLAGS_INTERNAL_COMMANDLINEFLAG_H_
+
+#include <atomic>
+
+#include "absl/base/macros.h"
+#include "absl/flags/marshalling.h"
+#include "absl/synchronization/mutex.h"
+#include "absl/types/optional.h"
+
+namespace absl {
+namespace flags_internal {
+
+// Type-specific operations, eg., parsing, copying, etc. are provided
+// by function specific to that type with a signature matching FlagOpFn.
+enum FlagOp {
+  kDelete,
+  kClone,
+  kCopy,
+  kCopyConstruct,
+  kSizeof,
+  kParse,
+  kUnparse
+};
+using FlagOpFn = void* (*)(FlagOp, const void*, void*);
+using FlagMarshallingOpFn = void* (*)(FlagOp, const void*, void*, void*);
+
+// Options that control SetCommandLineOptionWithMode.
+enum FlagSettingMode {
+  // update the flag's value unconditionally (can call this multiple times).
+  SET_FLAGS_VALUE,
+  // update the flag's value, but *only if* it has not yet been updated
+  // with SET_FLAGS_VALUE, SET_FLAG_IF_DEFAULT, or "FLAGS_xxx = nondef".
+  SET_FLAG_IF_DEFAULT,
+  // set the flag's default value to this.  If the flag has not been updated
+  // yet (via SET_FLAGS_VALUE, SET_FLAG_IF_DEFAULT, or "FLAGS_xxx = nondef")
+  // change the flag's current value to the new default value as well.
+  SET_FLAGS_DEFAULT
+};
+
+// Options that control SetFromString: Source of a value.
+enum ValueSource {
+  // Flag is being set by value specified on a command line.
+  kCommandLine,
+  // Flag is being set by value specified in the code.
+  kProgrammaticChange,
+};
+
+// Signature for the help generation function used as an argument for the
+// absl::Flag constructor.
+using HelpGenFunc = std::string (*)();
+
+// Signature for the function generating the initial flag value based (usually
+// based on default value supplied in flag's definition)
+using InitialValGenFunc = void* (*)();
+
+// Signature for the mutation callback used by watched Flags
+// The callback is noexcept.
+// TODO(rogeeff): add noexcept after C++17 support is added.
+using FlagCallback = void (*)();
+
+extern const char kStrippedFlagHelp[];
+
+// The per-type function
+template <typename T>
+void* FlagOps(FlagOp op, const void* v1, void* v2) {
+  switch (op) {
+    case kDelete:
+      delete static_cast<const T*>(v1);
+      return nullptr;
+    case kClone:
+      return new T(*static_cast<const T*>(v1));
+    case kCopy:
+      *static_cast<T*>(v2) = *static_cast<const T*>(v1);
+      return nullptr;
+    case kCopyConstruct:
+      new (v2) T(*static_cast<const T*>(v1));
+      return nullptr;
+    case kSizeof:
+      return reinterpret_cast<void*>(sizeof(T));
+    default:
+      return nullptr;
+  }
+}
+
+template <typename T>
+void* FlagMarshallingOps(FlagOp op, const void* v1, void* v2, void* v3) {
+  switch (op) {
+    case kParse: {
+      // initialize the temporary instance of type T based on current value in
+      // destination (which is going to be flag's default value).
+      T temp(*static_cast<T*>(v2));
+      if (!absl::ParseFlag<T>(*static_cast<const absl::string_view*>(v1), &temp,
+                              static_cast<std::string*>(v3))) {
+        return nullptr;
+      }
+      *static_cast<T*>(v2) = std::move(temp);
+      return v2;
+    }
+    case kUnparse:
+      *static_cast<std::string*>(v2) =
+          absl::UnparseFlag<T>(*static_cast<const T*>(v1));
+      return nullptr;
+    default:
+      return nullptr;
+  }
+}
+
+// Functions that invoke flag-type-specific operations.
+inline void Delete(FlagOpFn op, const void* obj) {
+  op(flags_internal::kDelete, obj, nullptr);
+}
+
+inline void* Clone(FlagOpFn op, const void* obj) {
+  return op(flags_internal::kClone, obj, nullptr);
+}
+
+inline void Copy(FlagOpFn op, const void* src, void* dst) {
+  op(flags_internal::kCopy, src, dst);
+}
+
+inline void CopyConstruct(FlagOpFn op, const void* src, void* dst) {
+  op(flags_internal::kCopyConstruct, src, dst);
+}
+
+inline bool Parse(FlagMarshallingOpFn op, absl::string_view text, void* dst,
+                  std::string* error) {
+  return op(flags_internal::kParse, &text, dst, error) != nullptr;
+}
+
+inline std::string Unparse(FlagMarshallingOpFn op, const void* val) {
+  std::string result;
+  op(flags_internal::kUnparse, val, &result, nullptr);
+  return result;
+}
+
+inline size_t Sizeof(FlagOpFn op) {
+  // This sequence of casts reverses the sequence from base::internal::FlagOps()
+  return static_cast<size_t>(reinterpret_cast<intptr_t>(
+      op(flags_internal::kSizeof, nullptr, nullptr)));
+}
+
+// The following struct contains the locks in a CommandLineFlag struct.
+// They are in a separate struct that is lazily allocated to avoid problems
+// with static initialization and to avoid multiple allocations.
+struct CommandLineFlagLocks {
+  absl::Mutex primary_mu;   // protects several fields in CommandLineFlag
+  absl::Mutex callback_mu;  // used to serialize callbacks
+};
+
+// Holds either a pointer to help text or a function which produces it.  This is
+// needed for supporting both static initialization of Flags while supporting
+// the legacy registration framework.  We can't use absl::variant<const char*,
+// const char*(*)()> since anybody passing 0 or nullptr in to a CommandLineFlag
+// would find an ambiguity.
+class HelpText {
+ public:
+  static constexpr HelpText FromFunctionPointer(const HelpGenFunc fn) {
+    return HelpText(fn, nullptr);
+  }
+  static constexpr HelpText FromStaticCString(const char* msg) {
+    return HelpText(nullptr, msg);
+  }
+
+  std::string GetHelpText() const;
+
+  HelpText() = delete;
+  HelpText(const HelpText&) = default;
+  HelpText(HelpText&&) = default;
+
+ private:
+  explicit constexpr HelpText(const HelpGenFunc fn, const char* msg)
+      : help_function_(fn), help_message_(msg) {}
+
+  HelpGenFunc help_function_;
+  const char* help_message_;
+};
+
+// Holds all information for a flag.
+struct CommandLineFlag {
+  constexpr CommandLineFlag(
+      const char* name_arg, HelpText help_text, const char* filename_arg,
+      const flags_internal::FlagOpFn op_arg,
+      const flags_internal::FlagMarshallingOpFn marshalling_op_arg,
+      const flags_internal::InitialValGenFunc initial_value_gen,
+      const bool retired_arg, void* def_arg, void* cur_arg)
+      : name(name_arg),
+        help(help_text),
+        filename(filename_arg),
+        op(op_arg),
+        marshalling_op(marshalling_op_arg),
+        make_init_value(initial_value_gen),
+        retired(retired_arg),
+        inited(false),
+        modified(false),
+        on_command_line(false),
+        validator(nullptr),
+        callback(nullptr),
+        def(def_arg),
+        cur(cur_arg),
+        counter(0),
+        atomic(kAtomicInit),
+        locks(nullptr) {}
+
+  // Not copyable/assignable.
+  CommandLineFlag(const CommandLineFlag&) = delete;
+  CommandLineFlag& operator=(const CommandLineFlag&) = delete;
+
+  absl::string_view Name() const { return name; }
+  std::string Help() const { return help.GetHelpText(); }
+  bool IsRetired() const { return this->retired; }
+  bool IsSpecifiedOnCommandLine() const { return on_command_line; }
+  // Returns true iff this is a handle to an Abseil Flag.
+  bool IsAbseilFlag() const {
+    // Set to null for V1 flags
+    return this->make_init_value != nullptr;
+  }
+
+  absl::string_view Typename() const;
+  std::string Filename() const;
+  std::string DefaultValue() const;
+  std::string CurrentValue() const;
+
+  // Return true iff flag has type T.
+  template <typename T>
+  inline bool IsOfType() const {
+    return this->op == &flags_internal::FlagOps<T>;
+  }
+
+  // Attempts to retrieve the flag value. Returns value on success,
+  // absl::nullopt otherwise.
+  template <typename T>
+  absl::optional<T> Get() {
+    if (IsRetired() || flags_internal::FlagOps<T> != this->op)
+      return absl::nullopt;
+
+    T res;
+    Read(&res, flags_internal::FlagOps<T>);
+
+    return res;
+  }
+
+  void SetCallback(const flags_internal::FlagCallback mutation_callback);
+
+  // Sets the value of the flag based on specified std::string `value`. If the flag
+  // was successfully set to new value, it returns true. Otherwise, sets `error`
+  // to indicate the error, leaves the flag unchanged, and returns false. There
+  // are three ways to set the flag's value:
+  //  * Update the current flag value
+  //  * Update the flag's default value
+  //  * Update the current flag value if it was never set before
+  // The mode is selected based on `set_mode` parameter.
+  bool SetFromString(absl::string_view value,
+                     flags_internal::FlagSettingMode set_mode,
+                     flags_internal::ValueSource source, std::string* error);
+
+  // Constant configuration for a particular flag.
+ private:
+  const char* const name;
+  const HelpText help;
+  const char* const filename;
+
+ public:
+  const FlagOpFn op;                  // Type-specific handler
+  const FlagMarshallingOpFn marshalling_op;  // Marshalling ops handler
+  const InitialValGenFunc make_init_value;   // Makes initial value for the flag
+  const bool retired;                 // Is the flag retired?
+  std::atomic<bool> inited;           // fields have been lazily initialized
+
+  // Mutable state (guarded by locks->primary_mu).
+  bool modified;          // Has flag value been modified?
+  bool on_command_line;   // Specified on command line.
+  bool (*validator)();    // Validator function, or nullptr
+  FlagCallback callback;  // Mutation callback, or nullptr
+  void* def;              // Lazily initialized pointer to default value
+  void* cur;              // Lazily initialized pointer to current value
+  int64_t counter;          // Mutation counter
+
+  // For some types, a copy of the current value is kept in an atomically
+  // accessible field.
+  static const int64_t kAtomicInit = 0xababababababababll;
+  std::atomic<int64_t> atomic;
+
+  // Lazily initialized mutexes for this flag value.  We cannot inline a
+  // SpinLock or Mutex here because those have non-constexpr constructors and
+  // so would prevent constant initialization of this type.
+  // TODO(rogeeff): fix it once Mutex has constexpr constructor
+  struct CommandLineFlagLocks* locks;  // locks, laziliy allocated.
+
+  // copy construct new value of flag's type in a memory referenced by dst
+  // based on current flag's value
+  void Read(void* dst, const flags_internal::FlagOpFn dst_op) const;
+  // updates flag's value to *src (locked)
+  void Write(const void* src, const flags_internal::FlagOpFn src_op);
+
+  ABSL_DEPRECATED(
+      "temporary until FlagName call sites are migrated and validator API is "
+      "changed")
+  const char* NameAsCString() const { return name; }
+
+ private:
+  friend class FlagRegistry;
+};
+
+// Ensure that the lazily initialized fields of *flag have been initialized,
+// and return &flag->locks->primary_mu.
+absl::Mutex* InitFlagIfNecessary(CommandLineFlag* flag);
+// Update any copy of the flag value that is stored in an atomic word.
+// In addition if flag has a mutation callback this function invokes it. While
+// callback is being invoked the primary flag's mutex is unlocked and it is
+// re-locked back after call to callback is completed. Callback invocation is
+// guarded by flag's secondary mutex instead which prevents concurrent callback
+// invocation. Note that it is possible for other thread to grab the primary
+// lock and update flag's value at any time during the callback invocation.
+// This is by design. Callback can get a value of the flag if necessary, but it
+// might be different from the value initiated the callback and it also can be
+// different by the time the callback invocation is completed.
+// Requires that *primary_lock be held in exclusive mode; it may be released
+// and reacquired by the implementation.
+void UpdateCopy(CommandLineFlag* flag, absl::Mutex* primary_lock);
+// Return true iff flag value was changed via direct-access.
+bool ChangedDirectly(CommandLineFlag* flag, const void* a, const void* b);
+// Direct-access flags can be modified without going through the
+// flag API.  Detect such changes and updated the modified bit.
+void UpdateModifiedBit(CommandLineFlag* flag);
+// Invoke the flag validators for old flags.
+// TODO(rogeeff): implement proper validators for Abseil Flags
+bool Validate(CommandLineFlag* flag, const void* value);
+
+// This macro is the "source of truth" for the list of supported flag types we
+// expect to perform lock free operations on. Specifically it generates code,
+// a one argument macro operating on a type, supplied as a macro argument, for
+// each type in the list.
+#define ABSL_FLAGS_INTERNAL_FOR_EACH_LOCK_FREE(A) \
+  A(bool)                                         \
+  A(short)                                        \
+  A(unsigned short)                               \
+  A(int)                                          \
+  A(unsigned int)                                 \
+  A(long)                                         \
+  A(unsigned long)                                \
+  A(long long)                                    \
+  A(unsigned long long)                           \
+  A(double)                                       \
+  A(float)
+
+}  // namespace flags_internal
+}  // namespace absl
+
+#endif  // ABSL_FLAGS_INTERNAL_COMMANDLINEFLAG_H_