Coverage Report

Created: 2024-09-23 06:29

/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_