1// Copyright (C) 2020 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
3
4#ifndef QTAGGEDPOINTER_H
5#define QTAGGEDPOINTER_H
6
7#include <QtCore/qglobal.h>
8#include <QtCore/qalgorithms.h>
9#include <QtCore/qmath.h>
10#include <QtCore/qtypeinfo.h>
11
12QT_BEGIN_NAMESPACE
13
14namespace QtPrivate {
15 constexpr quint8 nextByteSize(quint8 bits) { return quint8((bits + 7) / 8); }
16
17 template <typename T>
18 struct TagInfo
19 {
20 static constexpr size_t alignment = alignof(T);
21 static_assert((alignment & (alignment - 1)) == 0,
22 "Alignment of template parameter must be power of two");
23
24 static constexpr quint8 tagBits = quint8{QtPrivate::qConstexprCountTrailingZeroBits(v: alignment)};
25 static_assert(tagBits > 0,
26 "Alignment of template parameter does not allow any tags");
27
28 static constexpr size_t tagSize = QtPrivate::qConstexprNextPowerOfTwo(v: nextByteSize(bits: tagBits));
29 static_assert(tagSize < sizeof(quintptr),
30 "Alignment of template parameter allows tags masking away pointer");
31
32 using TagType = typename QIntegerForSize<tagSize>::Unsigned;
33 };
34}
35
36template <typename T, typename Tag = typename QtPrivate::TagInfo<T>::TagType>
37class QTaggedPointer
38{
39public:
40 using Type = T;
41 using TagType = Tag;
42
43 static constexpr quintptr tagMask() { return QtPrivate::TagInfo<T>::alignment - 1; }
44 static constexpr quintptr pointerMask() { return ~tagMask(); }
45
46 Q_NODISCARD_CTOR constexpr QTaggedPointer() noexcept : d(0) {}
47 Q_NODISCARD_CTOR constexpr QTaggedPointer(std::nullptr_t) noexcept : QTaggedPointer() {}
48
49 Q_NODISCARD_CTOR explicit QTaggedPointer(T *pointer, Tag tag = Tag()) noexcept
50 : d(quintptr(pointer) | quintptr(tag))
51 {
52 static_assert(sizeof(Type*) == sizeof(QTaggedPointer));
53
54 Q_ASSERT_X((quintptr(pointer) & tagMask()) == 0, "QTaggedPointer<T, Tag>", "Pointer is not aligned");
55 Q_ASSERT_X((static_cast<typename QtPrivate::TagInfo<T>::TagType>(tag) & pointerMask()) == 0,
56 "QTaggedPointer<T, Tag>::setTag", "Tag is larger than allowed by number of available tag bits");
57 }
58
59 Type &operator*() const noexcept
60 {
61 Q_ASSERT(data());
62 return *data();
63 }
64
65 Type *operator->() const noexcept
66 {
67 return data();
68 }
69
70 explicit operator bool() const noexcept
71 {
72 return !isNull();
73 }
74
75#ifdef Q_QDOC
76 QTaggedPointer &operator=(T *other) noexcept;
77#else
78 // Disables the usage of `ptr = {}`, which would go through this operator
79 // (rather than using the implicitly-generated assignment operator).
80 // The operators have different semantics: the ones here leave the tag intact,
81 // the implicitly-generated one overwrites it.
82 template <typename U,
83 std::enable_if_t<std::is_convertible_v<U *, T *>, bool> = false>
84 QTaggedPointer &operator=(U *other) noexcept
85 {
86 T *otherT = other;
87 d = reinterpret_cast<quintptr>(otherT) | (d & tagMask());
88 return *this;
89 }
90
91 template <typename U,
92 std::enable_if_t<std::is_null_pointer_v<U>, bool> = false>
93 QTaggedPointer &operator=(U) noexcept
94 {
95 d = reinterpret_cast<quintptr>(static_cast<T *>(nullptr)) | (d & tagMask());
96 return *this;
97 }
98#endif
99
100 static constexpr Tag maximumTag() noexcept
101 {
102 return TagType(typename QtPrivate::TagInfo<T>::TagType(tagMask()));
103 }
104
105 void setTag(Tag tag)
106 {
107 Q_ASSERT_X(
108 (static_cast<quintptr>(tag) & pointerMask()) == 0,
109 "QTaggedPointer<T, Tag>::setTag",
110 "Tag is larger than allowed by number of available tag bits");
111
112 d = (d & pointerMask()) | static_cast<quintptr>(tag);
113 }
114
115 Tag tag() const noexcept
116 {
117 return TagType(typename QtPrivate::TagInfo<T>::TagType(d & tagMask()));
118 }
119
120 T* data() const noexcept
121 {
122 return reinterpret_cast<T*>(d & pointerMask());
123 }
124
125 bool isNull() const noexcept
126 {
127 return !data();
128 }
129
130 void swap(QTaggedPointer &other) noexcept
131 {
132 std::swap(a&: d, b&: other.d);
133 }
134
135 friend inline bool operator==(QTaggedPointer lhs, QTaggedPointer rhs) noexcept
136 {
137 return lhs.data() == rhs.data();
138 }
139
140 friend inline bool operator!=(QTaggedPointer lhs, QTaggedPointer rhs) noexcept
141 {
142 return lhs.data() != rhs.data();
143 }
144
145 friend inline bool operator==(QTaggedPointer lhs, std::nullptr_t) noexcept
146 {
147 return lhs.isNull();
148 }
149
150 friend inline bool operator==(std::nullptr_t, QTaggedPointer rhs) noexcept
151 {
152 return rhs.isNull();
153 }
154
155 friend inline bool operator!=(QTaggedPointer lhs, std::nullptr_t) noexcept
156 {
157 return !lhs.isNull();
158 }
159
160 friend inline bool operator!=(std::nullptr_t, QTaggedPointer rhs) noexcept
161 {
162 return !rhs.isNull();
163 }
164
165 friend inline bool operator!(QTaggedPointer ptr) noexcept
166 {
167 return !ptr.data();
168 }
169
170 friend inline void swap(QTaggedPointer &p1, QTaggedPointer &p2) noexcept
171 {
172 p1.swap(other&: p2);
173 }
174
175protected:
176 quintptr d;
177};
178
179template <typename T, typename Tag>
180constexpr inline std::size_t qHash(QTaggedPointer<T, Tag> p, std::size_t seed = 0) noexcept
181{ return qHash(p.data(), seed); }
182
183template <typename T, typename Tag>
184class QTypeInfo<QTaggedPointer<T, Tag>>
185 : public QTypeInfoMerger<QTaggedPointer<T, Tag>, quintptr> {};
186
187QT_END_NAMESPACE
188
189#endif // QTAGGEDPOINTER_H
190