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 #ifndef ABSL_FLAGS_INTERNAL_REGISTRY_H_ 17 #define ABSL_FLAGS_INTERNAL_REGISTRY_H_ 18 19 #include <functional> 20 21 #include "absl/base/config.h" 22 #include "absl/flags/commandlineflag.h" 23 #include "absl/flags/internal/commandlineflag.h" 24 #include "absl/strings/string_view.h" 25 26 // -------------------------------------------------------------------- 27 // Global flags registry API. 28 29 namespace absl { 30 ABSL_NAMESPACE_BEGIN 31 namespace flags_internal { 32 33 // Executes specified visitor for each non-retired flag in the registry. 34 // Requires the caller hold the registry lock. 35 void ForEachFlagUnlocked(std::function<void(CommandLineFlag&)> visitor); 36 // Executes specified visitor for each non-retired flag in the registry. While 37 // callback are executed, the registry is locked and can't be changed. 38 void ForEachFlag(std::function<void(CommandLineFlag&)> visitor); 39 40 //----------------------------------------------------------------------------- 41 42 bool RegisterCommandLineFlag(CommandLineFlag&); 43 44 //----------------------------------------------------------------------------- 45 // Retired registrations: 46 // 47 // Retired flag registrations are treated specially. A 'retired' flag is 48 // provided only for compatibility with automated invocations that still 49 // name it. A 'retired' flag: 50 // - is not bound to a C++ FLAGS_ reference. 51 // - has a type and a value, but that value is intentionally inaccessible. 52 // - does not appear in --help messages. 53 // - is fully supported by _all_ flag parsing routines. 54 // - consumes args normally, and complains about type mismatches in its 55 // argument. 56 // - emits a complaint but does not die (e.g. LOG(ERROR)) if it is 57 // accessed by name through the flags API for parsing or otherwise. 58 // 59 // The registrations for a flag happen in an unspecified order as the 60 // initializers for the namespace-scope objects of a program are run. 61 // Any number of weak registrations for a flag can weakly define the flag. 62 // One non-weak registration will upgrade the flag from weak to non-weak. 63 // Further weak registrations of a non-weak flag are ignored. 64 // 65 // This mechanism is designed to support moving dead flags into a 66 // 'graveyard' library. An example migration: 67 // 68 // 0: Remove references to this FLAGS_flagname in the C++ codebase. 69 // 1: Register as 'retired' in old_lib. 70 // 2: Make old_lib depend on graveyard. 71 // 3: Add a redundant 'retired' registration to graveyard. 72 // 4: Remove the old_lib 'retired' registration. 73 // 5: Eventually delete the graveyard registration entirely. 74 // 75 76 // Retire flag with name "name" and type indicated by ops. 77 void Retire(const char* name, FlagFastTypeId type_id, char* buf); 78 79 constexpr size_t kRetiredFlagObjSize = 3 * sizeof(void*); 80 constexpr size_t kRetiredFlagObjAlignment = alignof(void*); 81 82 // Registered a retired flag with name 'flag_name' and type 'T'. 83 template <typename T> 84 class RetiredFlag { 85 public: Retire(const char * flag_name)86 void Retire(const char* flag_name) { 87 flags_internal::Retire(flag_name, base_internal::FastTypeId<T>(), buf_); 88 } 89 90 private: 91 alignas(kRetiredFlagObjAlignment) char buf_[kRetiredFlagObjSize]; 92 }; 93 94 } // namespace flags_internal 95 ABSL_NAMESPACE_END 96 } // namespace absl 97 98 #endif // ABSL_FLAGS_INTERNAL_REGISTRY_H_ 99