/src/abseil-cpp/absl/flags/internal/flag.h
Line | Count | Source (jump to first uncovered line) |
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_FLAG_H_ |
17 | | #define ABSL_FLAGS_INTERNAL_FLAG_H_ |
18 | | |
19 | | #include <stddef.h> |
20 | | #include <stdint.h> |
21 | | |
22 | | #include <atomic> |
23 | | #include <cstring> |
24 | | #include <memory> |
25 | | #include <string> |
26 | | #include <type_traits> |
27 | | #include <typeinfo> |
28 | | |
29 | | #include "absl/base/attributes.h" |
30 | | #include "absl/base/call_once.h" |
31 | | #include "absl/base/casts.h" |
32 | | #include "absl/base/config.h" |
33 | | #include "absl/base/optimization.h" |
34 | | #include "absl/base/thread_annotations.h" |
35 | | #include "absl/flags/commandlineflag.h" |
36 | | #include "absl/flags/config.h" |
37 | | #include "absl/flags/internal/commandlineflag.h" |
38 | | #include "absl/flags/internal/registry.h" |
39 | | #include "absl/flags/internal/sequence_lock.h" |
40 | | #include "absl/flags/marshalling.h" |
41 | | #include "absl/meta/type_traits.h" |
42 | | #include "absl/strings/string_view.h" |
43 | | #include "absl/synchronization/mutex.h" |
44 | | #include "absl/utility/utility.h" |
45 | | |
46 | | namespace absl { |
47 | | ABSL_NAMESPACE_BEGIN |
48 | | |
49 | | /////////////////////////////////////////////////////////////////////////////// |
50 | | // Forward declaration of absl::Flag<T> public API. |
51 | | namespace flags_internal { |
52 | | template <typename T> |
53 | | class Flag; |
54 | | } // namespace flags_internal |
55 | | |
56 | | template <typename T> |
57 | | using Flag = flags_internal::Flag<T>; |
58 | | |
59 | | template <typename T> |
60 | | ABSL_MUST_USE_RESULT T GetFlag(const absl::Flag<T>& flag); |
61 | | |
62 | | template <typename T> |
63 | | void SetFlag(absl::Flag<T>* flag, const T& v); |
64 | | |
65 | | template <typename T, typename V> |
66 | | void SetFlag(absl::Flag<T>* flag, const V& v); |
67 | | |
68 | | template <typename U> |
69 | | const CommandLineFlag& GetFlagReflectionHandle(const absl::Flag<U>& f); |
70 | | |
71 | | /////////////////////////////////////////////////////////////////////////////// |
72 | | // Flag value type operations, eg., parsing, copying, etc. are provided |
73 | | // by function specific to that type with a signature matching FlagOpFn. |
74 | | |
75 | | namespace flags_internal { |
76 | | |
77 | | enum class FlagOp { |
78 | | kAlloc, |
79 | | kDelete, |
80 | | kCopy, |
81 | | kCopyConstruct, |
82 | | kSizeof, |
83 | | kFastTypeId, |
84 | | kRuntimeTypeId, |
85 | | kParse, |
86 | | kUnparse, |
87 | | kValueOffset, |
88 | | }; |
89 | | using FlagOpFn = void* (*)(FlagOp, const void*, void*, void*); |
90 | | |
91 | | // Forward declaration for Flag value specific operations. |
92 | | template <typename T> |
93 | | void* FlagOps(FlagOp op, const void* v1, void* v2, void* v3); |
94 | | |
95 | | // Allocate aligned memory for a flag value. |
96 | 0 | inline void* Alloc(FlagOpFn op) { |
97 | 0 | return op(FlagOp::kAlloc, nullptr, nullptr, nullptr); |
98 | 0 | } |
99 | | // Deletes memory interpreting obj as flag value type pointer. |
100 | 0 | inline void Delete(FlagOpFn op, void* obj) { |
101 | 0 | op(FlagOp::kDelete, nullptr, obj, nullptr); |
102 | 0 | } |
103 | | // Copies src to dst interpreting as flag value type pointers. |
104 | 0 | inline void Copy(FlagOpFn op, const void* src, void* dst) { |
105 | 0 | op(FlagOp::kCopy, src, dst, nullptr); |
106 | 0 | } |
107 | | // Construct a copy of flag value in a location pointed by dst |
108 | | // based on src - pointer to the flag's value. |
109 | 0 | inline void CopyConstruct(FlagOpFn op, const void* src, void* dst) { |
110 | 0 | op(FlagOp::kCopyConstruct, src, dst, nullptr); |
111 | 0 | } |
112 | | // Makes a copy of flag value pointed by obj. |
113 | 0 | inline void* Clone(FlagOpFn op, const void* obj) { |
114 | 0 | void* res = flags_internal::Alloc(op); |
115 | 0 | flags_internal::CopyConstruct(op, obj, res); |
116 | 0 | return res; |
117 | 0 | } |
118 | | // Returns true if parsing of input text is successful. |
119 | | inline bool Parse(FlagOpFn op, absl::string_view text, void* dst, |
120 | 0 | std::string* error) { |
121 | 0 | return op(FlagOp::kParse, &text, dst, error) != nullptr; |
122 | 0 | } |
123 | | // Returns string representing supplied value. |
124 | 0 | inline std::string Unparse(FlagOpFn op, const void* val) { |
125 | 0 | std::string result; |
126 | 0 | op(FlagOp::kUnparse, val, &result, nullptr); |
127 | 0 | return result; |
128 | 0 | } |
129 | | // Returns size of flag value type. |
130 | 2 | inline size_t Sizeof(FlagOpFn op) { |
131 | | // This sequence of casts reverses the sequence from |
132 | | // `flags_internal::FlagOps()` |
133 | 2 | return static_cast<size_t>(reinterpret_cast<intptr_t>( |
134 | 2 | op(FlagOp::kSizeof, nullptr, nullptr, nullptr))); |
135 | 2 | } |
136 | | // Returns fast type id corresponding to the value type. |
137 | 7.21k | inline FlagFastTypeId FastTypeId(FlagOpFn op) { |
138 | 7.21k | return reinterpret_cast<FlagFastTypeId>( |
139 | 7.21k | op(FlagOp::kFastTypeId, nullptr, nullptr, nullptr)); |
140 | 7.21k | } |
141 | | // Returns fast type id corresponding to the value type. |
142 | 0 | inline const std::type_info* RuntimeTypeId(FlagOpFn op) { |
143 | 0 | return reinterpret_cast<const std::type_info*>( |
144 | 0 | op(FlagOp::kRuntimeTypeId, nullptr, nullptr, nullptr)); |
145 | 0 | } |
146 | | // Returns offset of the field value_ from the field impl_ inside of |
147 | | // absl::Flag<T> data. Given FlagImpl pointer p you can get the |
148 | | // location of the corresponding value as: |
149 | | // reinterpret_cast<char*>(p) + ValueOffset(). |
150 | 2 | inline ptrdiff_t ValueOffset(FlagOpFn op) { |
151 | | // This sequence of casts reverses the sequence from |
152 | | // `flags_internal::FlagOps()` |
153 | 2 | return static_cast<ptrdiff_t>(reinterpret_cast<intptr_t>( |
154 | 2 | op(FlagOp::kValueOffset, nullptr, nullptr, nullptr))); |
155 | 2 | } |
156 | | |
157 | | // Returns an address of RTTI's typeid(T). |
158 | | template <typename T> |
159 | | inline const std::type_info* GenRuntimeTypeId() { |
160 | | #ifdef ABSL_INTERNAL_HAS_RTTI |
161 | | return &typeid(T); |
162 | | #else |
163 | | return nullptr; |
164 | | #endif |
165 | | } |
166 | | |
167 | | /////////////////////////////////////////////////////////////////////////////// |
168 | | // Flag help auxiliary structs. |
169 | | |
170 | | // This is help argument for absl::Flag encapsulating the string literal pointer |
171 | | // or pointer to function generating it as well as enum descriminating two |
172 | | // cases. |
173 | | using HelpGenFunc = std::string (*)(); |
174 | | |
175 | | template <size_t N> |
176 | | struct FixedCharArray { |
177 | | char value[N]; |
178 | | |
179 | | template <size_t... I> |
180 | | static constexpr FixedCharArray<N> FromLiteralString( |
181 | | absl::string_view str, absl::index_sequence<I...>) { |
182 | | return (void)str, FixedCharArray<N>({{str[I]..., '\0'}}); |
183 | | } |
184 | | }; |
185 | | |
186 | | template <typename Gen, size_t N = Gen::Value().size()> |
187 | | constexpr FixedCharArray<N + 1> HelpStringAsArray(int) { |
188 | | return FixedCharArray<N + 1>::FromLiteralString( |
189 | | Gen::Value(), absl::make_index_sequence<N>{}); |
190 | | } |
191 | | |
192 | | template <typename Gen> |
193 | | constexpr std::false_type HelpStringAsArray(char) { |
194 | | return std::false_type{}; |
195 | | } |
196 | | |
197 | | union FlagHelpMsg { |
198 | 0 | constexpr explicit FlagHelpMsg(const char* help_msg) : literal(help_msg) {} |
199 | 0 | constexpr explicit FlagHelpMsg(HelpGenFunc help_gen) : gen_func(help_gen) {} |
200 | | |
201 | | const char* literal; |
202 | | HelpGenFunc gen_func; |
203 | | }; |
204 | | |
205 | | enum class FlagHelpKind : uint8_t { kLiteral = 0, kGenFunc = 1 }; |
206 | | |
207 | | struct FlagHelpArg { |
208 | | FlagHelpMsg source; |
209 | | FlagHelpKind kind; |
210 | | }; |
211 | | |
212 | | extern const char kStrippedFlagHelp[]; |
213 | | |
214 | | // These two HelpArg overloads allows us to select at compile time one of two |
215 | | // way to pass Help argument to absl::Flag. We'll be passing |
216 | | // AbslFlagHelpGenFor##name as Gen and integer 0 as a single argument to prefer |
217 | | // first overload if possible. If help message is evaluatable on constexpr |
218 | | // context We'll be able to make FixedCharArray out of it and we'll choose first |
219 | | // overload. In this case the help message expression is immediately evaluated |
220 | | // and is used to construct the absl::Flag. No additional code is generated by |
221 | | // ABSL_FLAG Otherwise SFINAE kicks in and first overload is dropped from the |
222 | | // consideration, in which case the second overload will be used. The second |
223 | | // overload does not attempt to evaluate the help message expression |
224 | | // immediately and instead delays the evaluation by returning the function |
225 | | // pointer (&T::NonConst) generating the help message when necessary. This is |
226 | | // evaluatable in constexpr context, but the cost is an extra function being |
227 | | // generated in the ABSL_FLAG code. |
228 | | template <typename Gen, size_t N> |
229 | | constexpr FlagHelpArg HelpArg(const FixedCharArray<N>& value) { |
230 | | return {FlagHelpMsg(value.value), FlagHelpKind::kLiteral}; |
231 | | } |
232 | | |
233 | | template <typename Gen> |
234 | | constexpr FlagHelpArg HelpArg(std::false_type) { |
235 | | return {FlagHelpMsg(&Gen::NonConst), FlagHelpKind::kGenFunc}; |
236 | | } |
237 | | |
238 | | /////////////////////////////////////////////////////////////////////////////// |
239 | | // Flag default value auxiliary structs. |
240 | | |
241 | | // Signature for the function generating the initial flag value (usually |
242 | | // based on default value supplied in flag's definition) |
243 | | using FlagDfltGenFunc = void (*)(void*); |
244 | | |
245 | | union FlagDefaultSrc { |
246 | | constexpr explicit FlagDefaultSrc(FlagDfltGenFunc gen_func_arg) |
247 | 0 | : gen_func(gen_func_arg) {} |
248 | | |
249 | | #define ABSL_FLAGS_INTERNAL_DFLT_FOR_TYPE(T, name) \ |
250 | | T name##_value; \ |
251 | 0 | constexpr explicit FlagDefaultSrc(T value) : name##_value(value) {} // NOLINT Unexecuted instantiation: absl::flags_internal::FlagDefaultSrc::FlagDefaultSrc(bool) Unexecuted instantiation: absl::flags_internal::FlagDefaultSrc::FlagDefaultSrc(short) Unexecuted instantiation: absl::flags_internal::FlagDefaultSrc::FlagDefaultSrc(unsigned short) Unexecuted instantiation: absl::flags_internal::FlagDefaultSrc::FlagDefaultSrc(int) Unexecuted instantiation: absl::flags_internal::FlagDefaultSrc::FlagDefaultSrc(unsigned int) Unexecuted instantiation: absl::flags_internal::FlagDefaultSrc::FlagDefaultSrc(long) Unexecuted instantiation: absl::flags_internal::FlagDefaultSrc::FlagDefaultSrc(unsigned long) Unexecuted instantiation: absl::flags_internal::FlagDefaultSrc::FlagDefaultSrc(long long) Unexecuted instantiation: absl::flags_internal::FlagDefaultSrc::FlagDefaultSrc(unsigned long long) Unexecuted instantiation: absl::flags_internal::FlagDefaultSrc::FlagDefaultSrc(double) Unexecuted instantiation: absl::flags_internal::FlagDefaultSrc::FlagDefaultSrc(float) |
252 | | ABSL_FLAGS_INTERNAL_BUILTIN_TYPES(ABSL_FLAGS_INTERNAL_DFLT_FOR_TYPE) |
253 | | #undef ABSL_FLAGS_INTERNAL_DFLT_FOR_TYPE |
254 | | |
255 | | void* dynamic_value; |
256 | | FlagDfltGenFunc gen_func; |
257 | | }; |
258 | | |
259 | | enum class FlagDefaultKind : uint8_t { |
260 | | kDynamicValue = 0, |
261 | | kGenFunc = 1, |
262 | | kOneWord = 2 // for default values UP to one word in size |
263 | | }; |
264 | | |
265 | | struct FlagDefaultArg { |
266 | | FlagDefaultSrc source; |
267 | | FlagDefaultKind kind; |
268 | | }; |
269 | | |
270 | | // This struct and corresponding overload to InitDefaultValue are used to |
271 | | // facilitate usage of {} as default value in ABSL_FLAG macro. |
272 | | // TODO(rogeeff): Fix handling types with explicit constructors. |
273 | | struct EmptyBraces {}; |
274 | | |
275 | | template <typename T> |
276 | | constexpr T InitDefaultValue(T t) { |
277 | | return t; |
278 | | } |
279 | | |
280 | | template <typename T> |
281 | | constexpr T InitDefaultValue(EmptyBraces) { |
282 | | return T{}; |
283 | | } |
284 | | |
285 | | template <typename ValueT, typename GenT, |
286 | | typename std::enable_if<std::is_integral<ValueT>::value, int>::type = |
287 | | ((void)GenT{}, 0)> |
288 | | constexpr FlagDefaultArg DefaultArg(int) { |
289 | | return {FlagDefaultSrc(GenT{}.value), FlagDefaultKind::kOneWord}; |
290 | | } |
291 | | |
292 | | template <typename ValueT, typename GenT> |
293 | | constexpr FlagDefaultArg DefaultArg(char) { |
294 | | return {FlagDefaultSrc(&GenT::Gen), FlagDefaultKind::kGenFunc}; |
295 | | } |
296 | | |
297 | | /////////////////////////////////////////////////////////////////////////////// |
298 | | // Flag storage selector traits. Each trait indicates what kind of storage kind |
299 | | // to use for the flag value. |
300 | | |
301 | | template <typename T> |
302 | | using FlagUseValueAndInitBitStorage = |
303 | | std::integral_constant<bool, std::is_trivially_copyable<T>::value && |
304 | | std::is_default_constructible<T>::value && |
305 | | (sizeof(T) < 8)>; |
306 | | |
307 | | template <typename T> |
308 | | using FlagUseOneWordStorage = |
309 | | std::integral_constant<bool, std::is_trivially_copyable<T>::value && |
310 | | (sizeof(T) <= 8)>; |
311 | | |
312 | | template <class T> |
313 | | using FlagUseSequenceLockStorage = |
314 | | std::integral_constant<bool, std::is_trivially_copyable<T>::value && |
315 | | (sizeof(T) > 8)>; |
316 | | |
317 | | enum class FlagValueStorageKind : uint8_t { |
318 | | kValueAndInitBit = 0, |
319 | | kOneWordAtomic = 1, |
320 | | kSequenceLocked = 2, |
321 | | kHeapAllocated = 3, |
322 | | }; |
323 | | |
324 | | // This constexpr function returns the storage kind for the given flag value |
325 | | // type. |
326 | | template <typename T> |
327 | | static constexpr FlagValueStorageKind StorageKind() { |
328 | | return FlagUseValueAndInitBitStorage<T>::value |
329 | | ? FlagValueStorageKind::kValueAndInitBit |
330 | | : FlagUseOneWordStorage<T>::value |
331 | | ? FlagValueStorageKind::kOneWordAtomic |
332 | | : FlagUseSequenceLockStorage<T>::value |
333 | | ? FlagValueStorageKind::kSequenceLocked |
334 | | : FlagValueStorageKind::kHeapAllocated; |
335 | | } |
336 | | |
337 | | // This is a base class for the storage classes used by kOneWordAtomic and |
338 | | // kValueAndInitBit storage kinds. It literally just stores the one word value |
339 | | // as an atomic. By default, it is initialized to a magic value that is unlikely |
340 | | // a valid value for the flag value type. |
341 | | struct FlagOneWordValue { |
342 | 0 | constexpr static int64_t Uninitialized() { |
343 | 0 | return static_cast<int64_t>(0xababababababababll); |
344 | 0 | } |
345 | | |
346 | 0 | constexpr FlagOneWordValue() : value(Uninitialized()) {} |
347 | 0 | constexpr explicit FlagOneWordValue(int64_t v) : value(v) {} |
348 | | std::atomic<int64_t> value; |
349 | | }; |
350 | | |
351 | | // This class represents a memory layout used by kValueAndInitBit storage kind. |
352 | | template <typename T> |
353 | | struct alignas(8) FlagValueAndInitBit { |
354 | | T value; |
355 | | // Use an int instead of a bool to guarantee that a non-zero value has |
356 | | // a bit set. |
357 | | uint8_t init; |
358 | | }; |
359 | | |
360 | | // This class implements an aligned pointer with two options stored via masks |
361 | | // in unused bits of the pointer value (due to alignment requirement). |
362 | | // - IsUnprotectedReadCandidate - indicates that the value can be switched to |
363 | | // unprotected read without a lock. |
364 | | // - HasBeenRead - indicates that the value has been read at least once. |
365 | | // - AllowsUnprotectedRead - combination of the two options above and indicates |
366 | | // that the value can now be read without a lock. |
367 | | // Further details of these options and their use is covered in the description |
368 | | // of the FlagValue<T, FlagValueStorageKind::kHeapAllocated> specialization. |
369 | | class MaskedPointer { |
370 | | public: |
371 | | using mask_t = uintptr_t; |
372 | | using ptr_t = void*; |
373 | | |
374 | 0 | static constexpr int RequiredAlignment() { return 4; } |
375 | | |
376 | 0 | constexpr explicit MaskedPointer(ptr_t rhs) : ptr_(rhs) {} |
377 | | MaskedPointer(ptr_t rhs, bool is_candidate); |
378 | | |
379 | 0 | void* Ptr() const { |
380 | 0 | return reinterpret_cast<void*>(reinterpret_cast<mask_t>(ptr_) & |
381 | 0 | kPtrValueMask); |
382 | 0 | } |
383 | 0 | bool AllowsUnprotectedRead() const { |
384 | 0 | return (reinterpret_cast<mask_t>(ptr_) & kAllowsUnprotectedRead) == |
385 | 0 | kAllowsUnprotectedRead; |
386 | 0 | } |
387 | | bool IsUnprotectedReadCandidate() const; |
388 | | bool HasBeenRead() const; |
389 | | |
390 | | void Set(FlagOpFn op, const void* src, bool is_candidate); |
391 | | void MarkAsRead(); |
392 | | |
393 | | private: |
394 | | // Masks |
395 | | // Indicates that the flag value either default or originated from command |
396 | | // line. |
397 | | static constexpr mask_t kUnprotectedReadCandidate = 0x1u; |
398 | | // Indicates that flag has been read. |
399 | | static constexpr mask_t kHasBeenRead = 0x2u; |
400 | | static constexpr mask_t kAllowsUnprotectedRead = |
401 | | kUnprotectedReadCandidate | kHasBeenRead; |
402 | | static constexpr mask_t kPtrValueMask = ~kAllowsUnprotectedRead; |
403 | | |
404 | | void ApplyMask(mask_t mask); |
405 | | bool CheckMask(mask_t mask) const; |
406 | | |
407 | | ptr_t ptr_; |
408 | | }; |
409 | | |
410 | | // This class implements a type erased storage of the heap allocated flag value. |
411 | | // It is used as a base class for the storage class for kHeapAllocated storage |
412 | | // kind. The initial_buffer is expected to have an alignment of at least |
413 | | // MaskedPointer::RequiredAlignment(), so that the bits used by the |
414 | | // MaskedPointer to store masks are set to 0. This guarantees that value starts |
415 | | // in an uninitialized state. |
416 | | struct FlagMaskedPointerValue { |
417 | | constexpr explicit FlagMaskedPointerValue(MaskedPointer::ptr_t initial_buffer) |
418 | 0 | : value(MaskedPointer(initial_buffer)) {} |
419 | | |
420 | | std::atomic<MaskedPointer> value; |
421 | | }; |
422 | | |
423 | | // This is the forward declaration for the template that represents a storage |
424 | | // for the flag values. This template is expected to be explicitly specialized |
425 | | // for each storage kind and it does not have a generic default |
426 | | // implementation. |
427 | | template <typename T, |
428 | | FlagValueStorageKind Kind = flags_internal::StorageKind<T>()> |
429 | | struct FlagValue; |
430 | | |
431 | | // This specialization represents the storage of flag values types with the |
432 | | // kValueAndInitBit storage kind. It is based on the FlagOneWordValue class |
433 | | // and relies on memory layout in FlagValueAndInitBit<T> to indicate that the |
434 | | // value has been initialized or not. |
435 | | template <typename T> |
436 | | struct FlagValue<T, FlagValueStorageKind::kValueAndInitBit> : FlagOneWordValue { |
437 | | constexpr FlagValue() : FlagOneWordValue(0) {} |
438 | | bool Get(const SequenceLock&, T& dst) const { |
439 | | int64_t storage = value.load(std::memory_order_acquire); |
440 | | if (ABSL_PREDICT_FALSE(storage == 0)) { |
441 | | // This assert is to ensure that the initialization inside FlagImpl::Init |
442 | | // is able to set init member correctly. |
443 | | static_assert(offsetof(FlagValueAndInitBit<T>, init) == sizeof(T), |
444 | | "Unexpected memory layout of FlagValueAndInitBit"); |
445 | | return false; |
446 | | } |
447 | | dst = absl::bit_cast<FlagValueAndInitBit<T>>(storage).value; |
448 | | return true; |
449 | | } |
450 | | }; |
451 | | |
452 | | // This specialization represents the storage of flag values types with the |
453 | | // kOneWordAtomic storage kind. It is based on the FlagOneWordValue class |
454 | | // and relies on the magic uninitialized state of default constructed instead of |
455 | | // FlagOneWordValue to indicate that the value has been initialized or not. |
456 | | template <typename T> |
457 | | struct FlagValue<T, FlagValueStorageKind::kOneWordAtomic> : FlagOneWordValue { |
458 | | constexpr FlagValue() : FlagOneWordValue() {} |
459 | | bool Get(const SequenceLock&, T& dst) const { |
460 | | int64_t one_word_val = value.load(std::memory_order_acquire); |
461 | | if (ABSL_PREDICT_FALSE(one_word_val == FlagOneWordValue::Uninitialized())) { |
462 | | return false; |
463 | | } |
464 | | std::memcpy(&dst, static_cast<const void*>(&one_word_val), sizeof(T)); |
465 | | return true; |
466 | | } |
467 | | }; |
468 | | |
469 | | // This specialization represents the storage of flag values types with the |
470 | | // kSequenceLocked storage kind. This storage is used by trivially copyable |
471 | | // types with size greater than 8 bytes. This storage relies on uninitialized |
472 | | // state of the SequenceLock to indicate that the value has been initialized or |
473 | | // not. This storage also provides lock-free read access to the underlying |
474 | | // value once it is initialized. |
475 | | template <typename T> |
476 | | struct FlagValue<T, FlagValueStorageKind::kSequenceLocked> { |
477 | | bool Get(const SequenceLock& lock, T& dst) const { |
478 | | return lock.TryRead(&dst, value_words, sizeof(T)); |
479 | | } |
480 | | |
481 | | static constexpr int kNumWords = |
482 | | flags_internal::AlignUp(sizeof(T), sizeof(uint64_t)) / sizeof(uint64_t); |
483 | | |
484 | | alignas(T) alignas( |
485 | | std::atomic<uint64_t>) std::atomic<uint64_t> value_words[kNumWords]; |
486 | | }; |
487 | | |
488 | | // This specialization represents the storage of flag values types with the |
489 | | // kHeapAllocated storage kind. This is a storage of last resort and is used |
490 | | // if none of other storage kinds are applicable. |
491 | | // |
492 | | // Generally speaking the values with this storage kind can't be accessed |
493 | | // atomically and thus can't be read without holding a lock. If we would ever |
494 | | // want to avoid the lock, we'd need to leak the old value every time new flag |
495 | | // value is being set (since we are in danger of having a race condition |
496 | | // otherwise). |
497 | | // |
498 | | // Instead of doing that, this implementation attempts to cater to some common |
499 | | // use cases by allowing at most 2 values to be leaked - default value and |
500 | | // value set from the command line. |
501 | | // |
502 | | // This specialization provides an initial buffer for the first flag value. This |
503 | | // is where the default value is going to be stored. We attempt to reuse this |
504 | | // buffer if possible, including storing the value set from the command line |
505 | | // there. |
506 | | // |
507 | | // As long as we only read this value, we can access it without a lock (in |
508 | | // practice we still use the lock for the very first read to be able set |
509 | | // "has been read" option on this flag). |
510 | | // |
511 | | // If flag is specified on the command line we store the parsed value either |
512 | | // in the internal buffer (if the default value never been read) or we leak the |
513 | | // default value and allocate the new storage for the parse value. This value is |
514 | | // also a candidate for an unprotected read. If flag is set programmatically |
515 | | // after the command line is parsed, the storage for this value is going to be |
516 | | // leaked. Note that in both scenarios we are not going to have a real leak. |
517 | | // Instead we'll store the leaked value pointers in the internal freelist to |
518 | | // avoid triggering the memory leak checker complains. |
519 | | // |
520 | | // If the flag is ever set programmatically, it stops being the candidate for an |
521 | | // unprotected read, and any follow up access to the flag value requires a lock. |
522 | | // Note that if the value if set programmatically before the command line is |
523 | | // parsed, we can switch back to enabling unprotected reads for that value. |
524 | | template <typename T> |
525 | | struct FlagValue<T, FlagValueStorageKind::kHeapAllocated> |
526 | | : FlagMaskedPointerValue { |
527 | | // We const initialize the value with unmasked pointer to the internal buffer, |
528 | | // making sure it is not a candidate for unprotected read. This way we can |
529 | | // ensure Init is done before any access to the flag value. |
530 | | constexpr FlagValue() : FlagMaskedPointerValue(&buffer[0]) {} |
531 | | |
532 | | bool Get(const SequenceLock&, T& dst) const { |
533 | | MaskedPointer ptr_value = value.load(std::memory_order_acquire); |
534 | | |
535 | | if (ABSL_PREDICT_TRUE(ptr_value.AllowsUnprotectedRead())) { |
536 | | ::new (static_cast<void*>(&dst)) T(*static_cast<T*>(ptr_value.Ptr())); |
537 | | return true; |
538 | | } |
539 | | return false; |
540 | | } |
541 | | |
542 | | alignas(MaskedPointer::RequiredAlignment()) alignas( |
543 | | T) char buffer[sizeof(T)]{}; |
544 | | }; |
545 | | |
546 | | /////////////////////////////////////////////////////////////////////////////// |
547 | | // Flag callback auxiliary structs. |
548 | | |
549 | | // Signature for the mutation callback used by watched Flags |
550 | | // The callback is noexcept. |
551 | | // TODO(rogeeff): add noexcept after C++17 support is added. |
552 | | using FlagCallbackFunc = void (*)(); |
553 | | |
554 | | struct FlagCallback { |
555 | | FlagCallbackFunc func; |
556 | | absl::Mutex guard; // Guard for concurrent callback invocations. |
557 | | }; |
558 | | |
559 | | /////////////////////////////////////////////////////////////////////////////// |
560 | | // Flag implementation, which does not depend on flag value type. |
561 | | // The class encapsulates the Flag's data and access to it. |
562 | | |
563 | | struct DynValueDeleter { |
564 | | explicit DynValueDeleter(FlagOpFn op_arg = nullptr); |
565 | | void operator()(void* ptr) const; |
566 | | |
567 | | FlagOpFn op; |
568 | | }; |
569 | | |
570 | | class FlagState; |
571 | | |
572 | | // These are only used as constexpr global objects. |
573 | | // They do not use a virtual destructor to simplify their implementation. |
574 | | // They are not destroyed except at program exit, so leaks do not matter. |
575 | | #if defined(__GNUC__) && !defined(__clang__) |
576 | | #pragma GCC diagnostic push |
577 | | #pragma GCC diagnostic ignored "-Wnon-virtual-dtor" |
578 | | #endif |
579 | | class FlagImpl final : public CommandLineFlag { |
580 | | public: |
581 | | constexpr FlagImpl(const char* name, const char* filename, FlagOpFn op, |
582 | | FlagHelpArg help, FlagValueStorageKind value_kind, |
583 | | FlagDefaultArg default_arg) |
584 | | : name_(name), |
585 | | filename_(filename), |
586 | | op_(op), |
587 | | help_(help.source), |
588 | | help_source_kind_(static_cast<uint8_t>(help.kind)), |
589 | | value_storage_kind_(static_cast<uint8_t>(value_kind)), |
590 | | def_kind_(static_cast<uint8_t>(default_arg.kind)), |
591 | | modified_(false), |
592 | | on_command_line_(false), |
593 | | callback_(nullptr), |
594 | | default_value_(default_arg.source), |
595 | 0 | data_guard_{} {} |
596 | | |
597 | | // Constant access methods |
598 | | int64_t ReadOneWord() const ABSL_LOCKS_EXCLUDED(*DataGuard()); |
599 | | bool ReadOneBool() const ABSL_LOCKS_EXCLUDED(*DataGuard()); |
600 | | void Read(void* dst) const override ABSL_LOCKS_EXCLUDED(*DataGuard()); |
601 | 0 | void Read(bool* value) const ABSL_LOCKS_EXCLUDED(*DataGuard()) { |
602 | 0 | *value = ReadOneBool(); |
603 | 0 | } |
604 | | template <typename T, |
605 | | absl::enable_if_t<flags_internal::StorageKind<T>() == |
606 | | FlagValueStorageKind::kOneWordAtomic, |
607 | | int> = 0> |
608 | | void Read(T* value) const ABSL_LOCKS_EXCLUDED(*DataGuard()) { |
609 | | int64_t v = ReadOneWord(); |
610 | | std::memcpy(value, static_cast<const void*>(&v), sizeof(T)); |
611 | | } |
612 | | template <typename T, |
613 | | typename std::enable_if<flags_internal::StorageKind<T>() == |
614 | | FlagValueStorageKind::kValueAndInitBit, |
615 | | int>::type = 0> |
616 | | void Read(T* value) const ABSL_LOCKS_EXCLUDED(*DataGuard()) { |
617 | | *value = absl::bit_cast<FlagValueAndInitBit<T>>(ReadOneWord()).value; |
618 | | } |
619 | | |
620 | | // Mutating access methods |
621 | | void Write(const void* src) ABSL_LOCKS_EXCLUDED(*DataGuard()); |
622 | | |
623 | | // Interfaces to operate on callbacks. |
624 | | void SetCallback(const FlagCallbackFunc mutation_callback) |
625 | | ABSL_LOCKS_EXCLUDED(*DataGuard()); |
626 | | void InvokeCallback() const ABSL_EXCLUSIVE_LOCKS_REQUIRED(*DataGuard()); |
627 | | |
628 | | // Used in read/write operations to validate source/target has correct type. |
629 | | // For example if flag is declared as absl::Flag<int> FLAGS_foo, a call to |
630 | | // absl::GetFlag(FLAGS_foo) validates that the type of FLAGS_foo is indeed |
631 | | // int. To do that we pass the assumed type id (which is deduced from type |
632 | | // int) as an argument `type_id`, which is in turn is validated against the |
633 | | // type id stored in flag object by flag definition statement. |
634 | | void AssertValidType(FlagFastTypeId type_id, |
635 | | const std::type_info* (*gen_rtti)()) const; |
636 | | |
637 | | private: |
638 | | template <typename T> |
639 | | friend class Flag; |
640 | | friend class FlagState; |
641 | | |
642 | | // Ensures that `data_guard_` is initialized and returns it. |
643 | | absl::Mutex* DataGuard() const |
644 | | ABSL_LOCK_RETURNED(reinterpret_cast<absl::Mutex*>(data_guard_)); |
645 | | // Returns heap allocated value of type T initialized with default value. |
646 | | std::unique_ptr<void, DynValueDeleter> MakeInitValue() const |
647 | | ABSL_EXCLUSIVE_LOCKS_REQUIRED(*DataGuard()); |
648 | | // Flag initialization called via absl::call_once. |
649 | | void Init(); |
650 | | |
651 | | // Offset value access methods. One per storage kind. These methods to not |
652 | | // respect const correctness, so be very careful using them. |
653 | | |
654 | | // This is a shared helper routine which encapsulates most of the magic. Since |
655 | | // it is only used inside the three routines below, which are defined in |
656 | | // flag.cc, we can define it in that file as well. |
657 | | template <typename StorageT> |
658 | | StorageT* OffsetValue() const; |
659 | | |
660 | | // The same as above, but used for sequencelock-protected storage. |
661 | | std::atomic<uint64_t>* AtomicBufferValue() const; |
662 | | |
663 | | // This is an accessor for a value stored as one word atomic. Returns a |
664 | | // mutable reference to an atomic value. |
665 | | std::atomic<int64_t>& OneWordValue() const; |
666 | | |
667 | | std::atomic<MaskedPointer>& PtrStorage() const; |
668 | | |
669 | | // Attempts to parse supplied `value` string. If parsing is successful, |
670 | | // returns new value. Otherwise returns nullptr. |
671 | | std::unique_ptr<void, DynValueDeleter> TryParse(absl::string_view value, |
672 | | std::string& err) const |
673 | | ABSL_EXCLUSIVE_LOCKS_REQUIRED(*DataGuard()); |
674 | | // Stores the flag value based on the pointer to the source. |
675 | | void StoreValue(const void* src, ValueSource source) |
676 | | ABSL_EXCLUSIVE_LOCKS_REQUIRED(*DataGuard()); |
677 | | |
678 | | // Copy the flag data, protected by `seq_lock_` into `dst`. |
679 | | // |
680 | | // REQUIRES: ValueStorageKind() == kSequenceLocked. |
681 | | void ReadSequenceLockedData(void* dst) const |
682 | | ABSL_LOCKS_EXCLUDED(*DataGuard()); |
683 | | |
684 | 0 | FlagHelpKind HelpSourceKind() const { |
685 | 0 | return static_cast<FlagHelpKind>(help_source_kind_); |
686 | 0 | } |
687 | 8 | FlagValueStorageKind ValueStorageKind() const { |
688 | 8 | return static_cast<FlagValueStorageKind>(value_storage_kind_); |
689 | 8 | } |
690 | | FlagDefaultKind DefaultKind() const |
691 | 0 | ABSL_EXCLUSIVE_LOCKS_REQUIRED(*DataGuard()) { |
692 | 0 | return static_cast<FlagDefaultKind>(def_kind_); |
693 | 0 | } |
694 | | |
695 | | // CommandLineFlag interface implementation |
696 | | absl::string_view Name() const override; |
697 | | std::string Filename() const override; |
698 | | std::string Help() const override; |
699 | | FlagFastTypeId TypeId() const override; |
700 | | bool IsSpecifiedOnCommandLine() const override |
701 | | ABSL_LOCKS_EXCLUDED(*DataGuard()); |
702 | | std::string DefaultValue() const override ABSL_LOCKS_EXCLUDED(*DataGuard()); |
703 | | std::string CurrentValue() const override ABSL_LOCKS_EXCLUDED(*DataGuard()); |
704 | | bool ValidateInputValue(absl::string_view value) const override |
705 | | ABSL_LOCKS_EXCLUDED(*DataGuard()); |
706 | | void CheckDefaultValueParsingRoundtrip() const override |
707 | | ABSL_LOCKS_EXCLUDED(*DataGuard()); |
708 | | |
709 | | int64_t ModificationCount() const ABSL_EXCLUSIVE_LOCKS_REQUIRED(*DataGuard()); |
710 | | |
711 | | // Interfaces to save and restore flags to/from persistent state. |
712 | | // Returns current flag state or nullptr if flag does not support |
713 | | // saving and restoring a state. |
714 | | std::unique_ptr<FlagStateInterface> SaveState() override |
715 | | ABSL_LOCKS_EXCLUDED(*DataGuard()); |
716 | | |
717 | | // Restores the flag state to the supplied state object. If there is |
718 | | // nothing to restore returns false. Otherwise returns true. |
719 | | bool RestoreState(const FlagState& flag_state) |
720 | | ABSL_LOCKS_EXCLUDED(*DataGuard()); |
721 | | |
722 | | bool ParseFrom(absl::string_view value, FlagSettingMode set_mode, |
723 | | ValueSource source, std::string& error) override |
724 | | ABSL_LOCKS_EXCLUDED(*DataGuard()); |
725 | | |
726 | | // Immutable flag's state. |
727 | | |
728 | | // Flags name passed to ABSL_FLAG as second arg. |
729 | | const char* const name_; |
730 | | // The file name where ABSL_FLAG resides. |
731 | | const char* const filename_; |
732 | | // Type-specific operations vtable. |
733 | | const FlagOpFn op_; |
734 | | // Help message literal or function to generate it. |
735 | | const FlagHelpMsg help_; |
736 | | // Indicates if help message was supplied as literal or generator func. |
737 | | const uint8_t help_source_kind_ : 1; |
738 | | // Kind of storage this flag is using for the flag's value. |
739 | | const uint8_t value_storage_kind_ : 2; |
740 | | |
741 | | uint8_t : 0; // The bytes containing the const bitfields must not be |
742 | | // shared with bytes containing the mutable bitfields. |
743 | | |
744 | | // Mutable flag's state (guarded by `data_guard_`). |
745 | | |
746 | | // def_kind_ is not guard by DataGuard() since it is accessed in Init without |
747 | | // locks. |
748 | | uint8_t def_kind_ : 2; |
749 | | // Has this flag's value been modified? |
750 | | bool modified_ : 1 ABSL_GUARDED_BY(*DataGuard()); |
751 | | // Has this flag been specified on command line. |
752 | | bool on_command_line_ : 1 ABSL_GUARDED_BY(*DataGuard()); |
753 | | |
754 | | // Unique tag for absl::call_once call to initialize this flag. |
755 | | absl::once_flag init_control_; |
756 | | |
757 | | // Sequence lock / mutation counter. |
758 | | flags_internal::SequenceLock seq_lock_; |
759 | | |
760 | | // Optional flag's callback and absl::Mutex to guard the invocations. |
761 | | FlagCallback* callback_ ABSL_GUARDED_BY(*DataGuard()); |
762 | | // Either a pointer to the function generating the default value based on the |
763 | | // value specified in ABSL_FLAG or pointer to the dynamically set default |
764 | | // value via SetCommandLineOptionWithMode. def_kind_ is used to distinguish |
765 | | // these two cases. |
766 | | FlagDefaultSrc default_value_; |
767 | | |
768 | | // This is reserved space for an absl::Mutex to guard flag data. It will be |
769 | | // initialized in FlagImpl::Init via placement new. |
770 | | // We can't use "absl::Mutex data_guard_", since this class is not literal. |
771 | | // We do not want to use "absl::Mutex* data_guard_", since this would require |
772 | | // heap allocation during initialization, which is both slows program startup |
773 | | // and can fail. Using reserved space + placement new allows us to avoid both |
774 | | // problems. |
775 | | alignas(absl::Mutex) mutable char data_guard_[sizeof(absl::Mutex)]; |
776 | | }; |
777 | | #if defined(__GNUC__) && !defined(__clang__) |
778 | | #pragma GCC diagnostic pop |
779 | | #endif |
780 | | |
781 | | /////////////////////////////////////////////////////////////////////////////// |
782 | | // The Flag object parameterized by the flag's value type. This class implements |
783 | | // flag reflection handle interface. |
784 | | |
785 | | template <typename T> |
786 | | class Flag { |
787 | | public: |
788 | | constexpr Flag(const char* name, const char* filename, FlagHelpArg help, |
789 | | const FlagDefaultArg default_arg) |
790 | | : impl_(name, filename, &FlagOps<T>, help, |
791 | | flags_internal::StorageKind<T>(), default_arg), |
792 | | value_() {} |
793 | | |
794 | | // CommandLineFlag interface |
795 | | absl::string_view Name() const { return impl_.Name(); } |
796 | | std::string Filename() const { return impl_.Filename(); } |
797 | | std::string Help() const { return impl_.Help(); } |
798 | | // Do not use. To be removed. |
799 | | bool IsSpecifiedOnCommandLine() const { |
800 | | return impl_.IsSpecifiedOnCommandLine(); |
801 | | } |
802 | | std::string DefaultValue() const { return impl_.DefaultValue(); } |
803 | | std::string CurrentValue() const { return impl_.CurrentValue(); } |
804 | | |
805 | | private: |
806 | | template <typename, bool> |
807 | | friend class FlagRegistrar; |
808 | | friend class FlagImplPeer; |
809 | | |
810 | | T Get() const { |
811 | | // See implementation notes in CommandLineFlag::Get(). |
812 | | union U { |
813 | | T value; |
814 | | U() {} |
815 | | ~U() { value.~T(); } |
816 | | }; |
817 | | U u; |
818 | | |
819 | | #if !defined(NDEBUG) |
820 | | impl_.AssertValidType(base_internal::FastTypeId<T>(), &GenRuntimeTypeId<T>); |
821 | | #endif |
822 | | |
823 | | if (ABSL_PREDICT_FALSE(!value_.Get(impl_.seq_lock_, u.value))) { |
824 | | impl_.Read(&u.value); |
825 | | } |
826 | | return std::move(u.value); |
827 | | } |
828 | | void Set(const T& v) { |
829 | | impl_.AssertValidType(base_internal::FastTypeId<T>(), &GenRuntimeTypeId<T>); |
830 | | impl_.Write(&v); |
831 | | } |
832 | | |
833 | | // Access to the reflection. |
834 | | const CommandLineFlag& Reflect() const { return impl_; } |
835 | | |
836 | | // Flag's data |
837 | | // The implementation depends on value_ field to be placed exactly after the |
838 | | // impl_ field, so that impl_ can figure out the offset to the value and |
839 | | // access it. |
840 | | FlagImpl impl_; |
841 | | FlagValue<T> value_; |
842 | | }; |
843 | | |
844 | | /////////////////////////////////////////////////////////////////////////////// |
845 | | // Trampoline for friend access |
846 | | |
847 | | class FlagImplPeer { |
848 | | public: |
849 | | template <typename T, typename FlagType> |
850 | | static T InvokeGet(const FlagType& flag) { |
851 | | return flag.Get(); |
852 | | } |
853 | | template <typename FlagType, typename T> |
854 | | static void InvokeSet(FlagType& flag, const T& v) { |
855 | | flag.Set(v); |
856 | | } |
857 | | template <typename FlagType> |
858 | | static const CommandLineFlag& InvokeReflect(const FlagType& f) { |
859 | | return f.Reflect(); |
860 | | } |
861 | | }; |
862 | | |
863 | | /////////////////////////////////////////////////////////////////////////////// |
864 | | // Implementation of Flag value specific operations routine. |
865 | | template <typename T> |
866 | | void* FlagOps(FlagOp op, const void* v1, void* v2, void* v3) { |
867 | | struct AlignedSpace { |
868 | | alignas(MaskedPointer::RequiredAlignment()) alignas(T) char buf[sizeof(T)]; |
869 | | }; |
870 | | using Allocator = std::allocator<AlignedSpace>; |
871 | | switch (op) { |
872 | | case FlagOp::kAlloc: { |
873 | | Allocator alloc; |
874 | | return std::allocator_traits<Allocator>::allocate(alloc, 1); |
875 | | } |
876 | | case FlagOp::kDelete: { |
877 | | T* p = static_cast<T*>(v2); |
878 | | p->~T(); |
879 | | Allocator alloc; |
880 | | std::allocator_traits<Allocator>::deallocate( |
881 | | alloc, reinterpret_cast<AlignedSpace*>(p), 1); |
882 | | return nullptr; |
883 | | } |
884 | | case FlagOp::kCopy: |
885 | | *static_cast<T*>(v2) = *static_cast<const T*>(v1); |
886 | | return nullptr; |
887 | | case FlagOp::kCopyConstruct: |
888 | | new (v2) T(*static_cast<const T*>(v1)); |
889 | | return nullptr; |
890 | | case FlagOp::kSizeof: |
891 | | return reinterpret_cast<void*>(static_cast<uintptr_t>(sizeof(T))); |
892 | | case FlagOp::kFastTypeId: |
893 | | return const_cast<void*>(base_internal::FastTypeId<T>()); |
894 | | case FlagOp::kRuntimeTypeId: |
895 | | return const_cast<std::type_info*>(GenRuntimeTypeId<T>()); |
896 | | case FlagOp::kParse: { |
897 | | // Initialize the temporary instance of type T based on current value in |
898 | | // destination (which is going to be flag's default value). |
899 | | T temp(*static_cast<T*>(v2)); |
900 | | if (!absl::ParseFlag<T>(*static_cast<const absl::string_view*>(v1), &temp, |
901 | | static_cast<std::string*>(v3))) { |
902 | | return nullptr; |
903 | | } |
904 | | *static_cast<T*>(v2) = std::move(temp); |
905 | | return v2; |
906 | | } |
907 | | case FlagOp::kUnparse: |
908 | | *static_cast<std::string*>(v2) = |
909 | | absl::UnparseFlag<T>(*static_cast<const T*>(v1)); |
910 | | return nullptr; |
911 | | case FlagOp::kValueOffset: { |
912 | | // Round sizeof(FlagImp) to a multiple of alignof(FlagValue<T>) to get the |
913 | | // offset of the data. |
914 | | size_t round_to = alignof(FlagValue<T>); |
915 | | size_t offset = (sizeof(FlagImpl) + round_to - 1) / round_to * round_to; |
916 | | return reinterpret_cast<void*>(offset); |
917 | | } |
918 | | } |
919 | | return nullptr; |
920 | | } |
921 | | |
922 | | /////////////////////////////////////////////////////////////////////////////// |
923 | | // This class facilitates Flag object registration and tail expression-based |
924 | | // flag definition, for example: |
925 | | // ABSL_FLAG(int, foo, 42, "Foo help").OnUpdate(NotifyFooWatcher); |
926 | | struct FlagRegistrarEmpty {}; |
927 | | template <typename T, bool do_register> |
928 | | class FlagRegistrar { |
929 | | public: |
930 | | constexpr explicit FlagRegistrar(Flag<T>& flag, const char* filename) |
931 | | : flag_(flag) { |
932 | | if (do_register) |
933 | | flags_internal::RegisterCommandLineFlag(flag_.impl_, filename); |
934 | | } |
935 | | |
936 | | FlagRegistrar OnUpdate(FlagCallbackFunc cb) && { |
937 | | flag_.impl_.SetCallback(cb); |
938 | | return *this; |
939 | | } |
940 | | |
941 | | // Makes the registrar die gracefully as an empty struct on a line where |
942 | | // registration happens. Registrar objects are intended to live only as |
943 | | // temporary. |
944 | | constexpr operator FlagRegistrarEmpty() const { return {}; } // NOLINT |
945 | | |
946 | | private: |
947 | | Flag<T>& flag_; // Flag being registered (not owned). |
948 | | }; |
949 | | |
950 | | /////////////////////////////////////////////////////////////////////////////// |
951 | | // Test only API |
952 | | uint64_t NumLeakedFlagValues(); |
953 | | |
954 | | } // namespace flags_internal |
955 | | ABSL_NAMESPACE_END |
956 | | } // namespace absl |
957 | | |
958 | | #endif // ABSL_FLAGS_INTERNAL_FLAG_H_ |