1 // Copyright 2016 The Chromium Authors 2 // Use of this source code is governed by a BSD-style license that can be 3 // found in the LICENSE file. 4 5 #ifndef BASE_TYPES_ID_TYPE_H_ 6 #define BASE_TYPES_ID_TYPE_H_ 7 8 #include <cstdint> 9 #include <type_traits> 10 11 #include "base/ranges/algorithm.h" 12 #include "base/types/strong_alias.h" 13 14 namespace base { 15 16 // A specialization of StrongAlias for integer-based identifiers. 17 // 18 // IdType32<>, IdType64<>, etc. wrap an integer id in a custom, type-safe type. 19 // 20 // IdType32<Foo> is an alternative to int, for a class Foo with methods like: 21 // 22 // int GetId() { return id_; }; 23 // static Foo* FromId(int id) { return g_all_foos_by_id[id]; } 24 // 25 // Such methods are a standard means of safely referring to objects across 26 // thread and process boundaries. But if a nearby class Bar also represents 27 // its IDs as a bare int, horrific mixups are possible -- one example, of many, 28 // is http://crrev.com/365437. IdType<> offers compile-time protection against 29 // such mishaps, since IdType32<Foo> is incompatible with IdType32<Bar>, even 30 // though both just compile down to an int32_t. 31 // 32 // Templates in this file: 33 // IdType32<T> / IdTypeU32<T>: Signed / unsigned 32-bit IDs 34 // IdType64<T> / IdTypeU64<T>: Signed / unsigned 64-bit IDs 35 // IdType<>: For when you need a different underlying type or 36 // default/null values other than zero. 37 // 38 // IdType32<Foo> behaves just like an int32_t in the following aspects: 39 // - it can be used as a key in std::map; 40 // - it can be used as a key in std::unordered_map (see StrongAlias::Hasher); 41 // - it can be used as an argument to DCHECK_EQ or streamed to LOG(ERROR); 42 // - it has the same memory footprint and runtime overhead as int32_t; 43 // - it can be copied by memcpy. 44 // - it can be used in IPC messages. 45 // 46 // IdType32<Foo> has the following differences from a bare int32_t: 47 // - it forces coercions to go through the explicit constructor and value() 48 // getter; 49 // - it restricts the set of available operations (e.g. no multiplication); 50 // - it default-constructs to a null value and allows checking against the null 51 // value via is_null method. 52 // - optionally it may have additional values that are all considered null. 53 template <typename TypeMarker, 54 typename WrappedType, 55 WrappedType kInvalidValue, 56 WrappedType kFirstGeneratedId = kInvalidValue + 1, 57 WrappedType... kExtraInvalidValues> 58 class IdType : public StrongAlias<TypeMarker, WrappedType> { 59 public: 60 static constexpr WrappedType kAllInvalidValues[] = {kInvalidValue, 61 kExtraInvalidValues...}; 62 63 static_assert(std::is_unsigned_v<WrappedType> || 64 base::ranges::all_of(kAllInvalidValues, 65 [](WrappedType v) { return v <= 0; }), 66 "If signed, invalid values should be negative or equal to zero " 67 "to avoid overflow issues."); 68 69 static_assert(base::ranges::all_of(kAllInvalidValues, 70 [](WrappedType v) { 71 return kFirstGeneratedId != v; 72 }), 73 "The first generated ID cannot be invalid."); 74 75 static_assert(std::is_unsigned_v<WrappedType> || 76 base::ranges::all_of(kAllInvalidValues, 77 [](WrappedType v) { 78 return kFirstGeneratedId > v; 79 }), 80 "If signed, the first generated ID must be greater than all " 81 "invalid values so that the monotonically increasing " 82 "GenerateNextId method will never return an invalid value."); 83 84 using StrongAlias<TypeMarker, WrappedType>::StrongAlias; 85 86 // This class can be used to generate unique IdTypes. It keeps an internal 87 // counter that is continually increased by one every time an ID is generated. 88 class Generator { 89 public: 90 Generator() = default; 91 92 // Generates the next unique ID. GenerateNextId()93 IdType GenerateNextId() { return FromUnsafeValue(next_id_++); } 94 95 // Non-copyable. 96 Generator(const Generator&) = delete; 97 Generator& operator=(const Generator&) = delete; 98 99 private: 100 WrappedType next_id_ = kFirstGeneratedId; 101 }; 102 103 // Default-construct in the null state. IdType()104 constexpr IdType() 105 : StrongAlias<TypeMarker, WrappedType>::StrongAlias(kInvalidValue) {} 106 is_null()107 constexpr bool is_null() const { 108 return base::ranges::any_of(kAllInvalidValues, [this](WrappedType value) { 109 return this->value() == value; 110 }); 111 } 112 113 constexpr explicit operator bool() const { return !is_null(); } 114 115 // TODO(mpawlowski) Replace these with constructor/value() getter. The 116 // conversions are safe as long as they're explicit (which is taken care of by 117 // StrongAlias). FromUnsafeValue(WrappedType value)118 constexpr static IdType FromUnsafeValue(WrappedType value) { 119 return IdType(value); 120 } GetUnsafeValue()121 constexpr WrappedType GetUnsafeValue() const { return this->value(); } 122 }; 123 124 // Type aliases for convenience: 125 template <typename TypeMarker> 126 using IdType32 = IdType<TypeMarker, std::int32_t, 0>; 127 template <typename TypeMarker> 128 using IdTypeU32 = IdType<TypeMarker, std::uint32_t, 0>; 129 template <typename TypeMarker> 130 using IdType64 = IdType<TypeMarker, std::int64_t, 0>; 131 template <typename TypeMarker> 132 using IdTypeU64 = IdType<TypeMarker, std::uint64_t, 0>; 133 134 } // namespace base 135 136 #endif // BASE_TYPES_ID_TYPE_H_ 137