src/base/InstanceId.h

   1 /*
   2  * Copyright (C) 1996-2020 The Squid Software Foundation and contributors
   3  *
   4  * Squid software is distributed under GPLv2+ license and includes
   5  * contributions from numerous individuals and organizations.
   6  * Please see the COPYING and CONTRIBUTORS files for details.
   7  */
   8
   9 #ifndef SQUID_BASE_INSTANCE_ID_H
  10 #define SQUID_BASE_INSTANCE_ID_H
  11
  12 #include <iosfwd>
  13
  14 /// Represents an InstanceId<C> value independent from its owner class C. These
  15 /// "detached" IDs can be stored by and exchanged among C-unaware users at the
  16 /// price of storing a short scope c-string (that InstanceIds hard-code instead)
  17 /// and, in some cases, using more bits/space than InstanceId<C>::value uses.
  18 class ScopedId
  19 {
  20 public:
  21     ScopedId(): scope(nullptr), value(0) {}
  22     explicit ScopedId(const char *s): scope(s), value(0) {}
  23     // when the values is zero/unknown, use other constructors
  24     ScopedId(const char *s, uint64_t v): scope(s), value(v) { /* assert(value) */ }
  25
  26     /// either the prefix() of the InstanceId object that we were detached from
  27     /// or, for 0 values, some other description (with endless lifetime) or nil
  28     const char *scope;
  29
  30     /// either the value of the InstanceId object that we were detached from
  31     /// or, if our creator did not know the exact value, zero
  32     uint64_t value;
  33 };
  34
  35 std::ostream &operator <<(std::ostream &os, const ScopedId &id);
  36
  37 typedef unsigned int InstanceIdDefaultValueType;
  38 /** Identifier for class instances
  39  *   - unique IDs for a large number of concurrent instances, but may wrap;
  40  *   - useful for debugging and insecure request/response matching;
  41  *   - sequential IDs within a class except when wrapping;
  42  *   - always positive IDs.
  43  * TODO: add creation/destruction debugging?
  44  */
  45 template <class Class, class ValueType = InstanceIdDefaultValueType>
  46 class InstanceId
  47 {
  48 public:
  49     typedef ValueType Value; ///< id storage type
  50
  51     InstanceId() {change();}
  52
  53     operator Value() const { return value; }
  54     bool operator ==(const InstanceId &o) const { return value == o.value; }
  55     bool operator !=(const InstanceId &o) const { return !(*this == o); }
  56     void change();
  57
  58     /// writes a compact text representation of the ID
  59     std::ostream &print(std::ostream &) const;
  60
  61     // TODO: Refactor into static Scope().
  62     /// \returns Class-specific nickname (with endless lifetime)
  63     const char * prefix() const;
  64
  65     /// \returns a copy of the ID usable outside our Class context
  66     ScopedId detach() const { return ScopedId(prefix(), value); }
  67
  68 public:
  69     Value value = Value(); ///< instance identifier
  70
  71 private:
  72     InstanceId(const InstanceId &); ///< not implemented; IDs are unique
  73     InstanceId& operator=(const InstanceId &); ///< not implemented
  74 };
  75
  76 /// An InstanceIdDefinitions() helper. Avoid direct use.
  77 #define InstanceIdDefinitions3(Class, pfx, ValueType, ...) \
  78     template<> const char * \
  79     InstanceId<Class, ValueType>::prefix() const { \
  80         return pfx; \
  81     } \
  82     template<> std::ostream & \
  83     InstanceId<Class, ValueType>::print(std::ostream &os) const { \
  84         return os << pfx << value; \
  85     } \
  86     template<> void \
  87     InstanceId<Class, ValueType>::change() { \
  88         static auto Last = Value(); \
  89         value = ++Last ? Last : ++Last; \
  90     }
  91
  92 /// convenience macro to instantiate Class-specific stuff in .cc files
  93 #define InstanceIdDefinitions(...) InstanceIdDefinitions3(__VA_ARGS__, InstanceIdDefaultValueType)
  94
  95 /// print the id
  96 template <class Class, class ValueType>
  97 inline
  98 std::ostream &operator <<(std::ostream &os, const InstanceId<Class, ValueType> &id)
  99 {
 100     return id.print(os);
 101 }
 102
 103 #endif /* SQUID_BASE_INSTANCE_ID_H */
 104