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 #include <map>
21 #include <string>
22
23 #include "absl/base/config.h"
24 #include "absl/base/macros.h"
25 #include "absl/flags/internal/commandlineflag.h"
26 #include "absl/strings/string_view.h"
27
28 // --------------------------------------------------------------------
29 // Global flags registry API.
30
31 namespace absl {
32 ABSL_NAMESPACE_BEGIN
33 namespace flags_internal {
34
35 CommandLineFlag* FindCommandLineFlag(absl::string_view name);
36 CommandLineFlag* FindRetiredFlag(absl::string_view name);
37
38 // Executes specified visitor for each non-retired flag in the registry.
39 // Requires the caller hold the registry lock.
40 void ForEachFlagUnlocked(std::function<void(CommandLineFlag*)> visitor);
41 // Executes specified visitor for each non-retired flag in the registry. While
42 // callback are executed, the registry is locked and can't be changed.
43 void ForEachFlag(std::function<void(CommandLineFlag*)> visitor);
44
45 //-----------------------------------------------------------------------------
46
47 bool RegisterCommandLineFlag(CommandLineFlag*);
48
49 //-----------------------------------------------------------------------------
50 // Retired registrations:
51 //
52 // Retired flag registrations are treated specially. A 'retired' flag is
53 // provided only for compatibility with automated invocations that still
54 // name it. A 'retired' flag:
55 // - is not bound to a C++ FLAGS_ reference.
56 // - has a type and a value, but that value is intentionally inaccessible.
57 // - does not appear in --help messages.
58 // - is fully supported by _all_ flag parsing routines.
59 // - consumes args normally, and complains about type mismatches in its
60 // argument.
61 // - emits a complaint but does not die (e.g. LOG(ERROR)) if it is
62 // accessed by name through the flags API for parsing or otherwise.
63 //
64 // The registrations for a flag happen in an unspecified order as the
65 // initializers for the namespace-scope objects of a program are run.
66 // Any number of weak registrations for a flag can weakly define the flag.
67 // One non-weak registration will upgrade the flag from weak to non-weak.
68 // Further weak registrations of a non-weak flag are ignored.
69 //
70 // This mechanism is designed to support moving dead flags into a
71 // 'graveyard' library. An example migration:
72 //
73 // 0: Remove references to this FLAGS_flagname in the C++ codebase.
74 // 1: Register as 'retired' in old_lib.
75 // 2: Make old_lib depend on graveyard.
76 // 3: Add a redundant 'retired' registration to graveyard.
77 // 4: Remove the old_lib 'retired' registration.
78 // 5: Eventually delete the graveyard registration entirely.
79 //
80
81 // Retire flag with name "name" and type indicated by ops.
82 bool Retire(const char* name, FlagFastTypeId type_id);
83
84 // Registered a retired flag with name 'flag_name' and type 'T'.
85 template <typename T>
RetiredFlag(const char * flag_name)86 inline bool RetiredFlag(const char* flag_name) {
87 return flags_internal::Retire(flag_name, base_internal::FastTypeId<T>());
88 }
89
90 // If the flag is retired, returns true and indicates in |*type_is_bool|
91 // whether the type of the retired flag is a bool.
92 // Only to be called by code that needs to explicitly ignore retired flags.
93 bool IsRetiredFlag(absl::string_view name, bool* type_is_bool);
94
95 //-----------------------------------------------------------------------------
96 // Saves the states (value, default value, whether the user has set
97 // the flag, registered validators, etc) of all flags, and restores
98 // them when the FlagSaver is destroyed.
99 //
100 // This class is thread-safe. However, its destructor writes to
101 // exactly the set of flags that have changed value during its
102 // lifetime, so concurrent _direct_ access to those flags
103 // (i.e. FLAGS_foo instead of {Get,Set}CommandLineOption()) is unsafe.
104
105 class FlagSaver {
106 public:
107 FlagSaver();
108 ~FlagSaver();
109
110 FlagSaver(const FlagSaver&) = delete;
111 void operator=(const FlagSaver&) = delete;
112
113 // Prevents saver from restoring the saved state of flags.
114 void Ignore();
115
116 private:
117 class FlagSaverImpl* impl_; // we use pimpl here to keep API steady
118 };
119
120 } // namespace flags_internal
121 ABSL_NAMESPACE_END
122 } // namespace absl
123
124 #endif // ABSL_FLAGS_INTERNAL_REGISTRY_H_
125