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