1 //===- llvm/ADT/PointerIntPair.h - Pair for pointer and int -----*- C++ -*-===//
2 //
3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4 // See https://llvm.org/LICENSE.txt for license information.
5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6 //
7 //===----------------------------------------------------------------------===//
8 ///
9 /// \file
10 /// This file defines the PointerIntPair class.
11 ///
12 //===----------------------------------------------------------------------===//
13 
14 #ifndef LLVM_ADT_POINTERINTPAIR_H
15 #define LLVM_ADT_POINTERINTPAIR_H
16 
17 #include "llvm/Support/Compiler.h"
18 #include "llvm/Support/PointerLikeTypeTraits.h"
19 #include "llvm/Support/type_traits.h"
20 #include <cassert>
21 #include <cstdint>
22 #include <limits>
23 
24 namespace llvm {
25 
26 template <typename T, typename Enable> struct DenseMapInfo;
27 template <typename PointerT, unsigned IntBits, typename PtrTraits>
28 struct PointerIntPairInfo;
29 
30 /// PointerIntPair - This class implements a pair of a pointer and small
31 /// integer.  It is designed to represent this in the space required by one
32 /// pointer by bitmangling the integer into the low part of the pointer.  This
33 /// can only be done for small integers: typically up to 3 bits, but it depends
34 /// on the number of bits available according to PointerLikeTypeTraits for the
35 /// type.
36 ///
37 /// Note that PointerIntPair always puts the IntVal part in the highest bits
38 /// possible.  For example, PointerIntPair<void*, 1, bool> will put the bit for
39 /// the bool into bit #2, not bit #0, which allows the low two bits to be used
40 /// for something else.  For example, this allows:
41 ///   PointerIntPair<PointerIntPair<void*, 1, bool>, 1, bool>
42 /// ... and the two bools will land in different bits.
43 template <typename PointerTy, unsigned IntBits, typename IntType = unsigned,
44           typename PtrTraits = PointerLikeTypeTraits<PointerTy>,
45           typename Info = PointerIntPairInfo<PointerTy, IntBits, PtrTraits>>
46 class PointerIntPair {
47   // Used by MSVC visualizer and generally helpful for debugging/visualizing.
48   using InfoTy = Info;
49   intptr_t Value = 0;
50 
51 public:
52   constexpr PointerIntPair() = default;
53 
54   PointerIntPair(PointerTy PtrVal, IntType IntVal) {
55     setPointerAndInt(PtrVal, IntVal);
56   }
57 
58   explicit PointerIntPair(PointerTy PtrVal) { initWithPointer(PtrVal); }
59 
60   PointerTy getPointer() const { return Info::getPointer(Value); }
61 
62   IntType getInt() const { return (IntType)Info::getInt(Value); }
63 
64   void setPointer(PointerTy PtrVal) & {
65     Value = Info::updatePointer(Value, PtrVal);
66   }
67 
68   void setInt(IntType IntVal) & {
69     Value = Info::updateInt(Value, static_cast<intptr_t>(IntVal));
70   }
71 
72   void initWithPointer(PointerTy PtrVal) & {
73     Value = Info::updatePointer(0, PtrVal);
74   }
75 
76   void setPointerAndInt(PointerTy PtrVal, IntType IntVal) & {
77     Value = Info::updateInt(Info::updatePointer(0, PtrVal),
78                             static_cast<intptr_t>(IntVal));
79   }
80 
81   PointerTy const *getAddrOfPointer() const {
82     return const_cast<PointerIntPair *>(this)->getAddrOfPointer();
83   }
84 
85   PointerTy *getAddrOfPointer() {
86     assert(Value == reinterpret_cast<intptr_t>(getPointer()) &&
87            "Can only return the address if IntBits is cleared and "
88            "PtrTraits doesn't change the pointer");
89     return reinterpret_cast<PointerTy *>(&Value);
90   }
91 
92   void *getOpaqueValue() const { return reinterpret_cast<void *>(Value); }
93 
94   void setFromOpaqueValue(void *Val) & {
95     Value = reinterpret_cast<intptr_t>(Val);
96   }
97 
98   static PointerIntPair getFromOpaqueValue(void *V) {
99     PointerIntPair P;
100     P.setFromOpaqueValue(V);
101     return P;
102   }
103 
104   // Allow PointerIntPairs to be created from const void * if and only if the
105   // pointer type could be created from a const void *.
106   static PointerIntPair getFromOpaqueValue(const void *V) {
107     (void)PtrTraits::getFromVoidPointer(V);
108     return getFromOpaqueValue(const_cast<void *>(V));
109   }
110 
111   bool operator==(const PointerIntPair &RHS) const {
112     return Value == RHS.Value;
113   }
114 
115   bool operator!=(const PointerIntPair &RHS) const {
116     return Value != RHS.Value;
117   }
118 
119   bool operator<(const PointerIntPair &RHS) const { return Value < RHS.Value; }
120   bool operator>(const PointerIntPair &RHS) const { return Value > RHS.Value; }
121 
122   bool operator<=(const PointerIntPair &RHS) const {
123     return Value <= RHS.Value;
124   }
125 
126   bool operator>=(const PointerIntPair &RHS) const {
127     return Value >= RHS.Value;
128   }
129 };
130 
131 // Specialize is_trivially_copyable to avoid limitation of llvm::is_trivially_copyable
132 // when compiled with gcc 4.9.
133 template <typename PointerTy, unsigned IntBits, typename IntType,
134           typename PtrTraits,
135           typename Info>
136 struct is_trivially_copyable<PointerIntPair<PointerTy, IntBits, IntType, PtrTraits, Info>> : std::true_type {
137 #ifdef HAVE_STD_IS_TRIVIALLY_COPYABLE
138   static_assert(std::is_trivially_copyable<PointerIntPair<PointerTy, IntBits, IntType, PtrTraits, Info>>::value,
139                 "inconsistent behavior between llvm:: and std:: implementation of is_trivially_copyable");
140 #endif
141 };
142 
143 
144 template <typename PointerT, unsigned IntBits, typename PtrTraits>
145 struct PointerIntPairInfo {
146   static_assert(PtrTraits::NumLowBitsAvailable <
147                     std::numeric_limits<uintptr_t>::digits,
148                 "cannot use a pointer type that has all bits free");
149   static_assert(IntBits <= PtrTraits::NumLowBitsAvailable,
150                 "PointerIntPair with integer size too large for pointer");
151   enum MaskAndShiftConstants : uintptr_t {
152     /// PointerBitMask - The bits that come from the pointer.
153     PointerBitMask =
154         ~(uintptr_t)(((intptr_t)1 << PtrTraits::NumLowBitsAvailable) - 1),
155 
156     /// IntShift - The number of low bits that we reserve for other uses, and
157     /// keep zero.
158     IntShift = (uintptr_t)PtrTraits::NumLowBitsAvailable - IntBits,
159 
160     /// IntMask - This is the unshifted mask for valid bits of the int type.
161     IntMask = (uintptr_t)(((intptr_t)1 << IntBits) - 1),
162 
163     // ShiftedIntMask - This is the bits for the integer shifted in place.
164     ShiftedIntMask = (uintptr_t)(IntMask << IntShift)
165   };
166 
167   static PointerT getPointer(intptr_t Value) {
168     return PtrTraits::getFromVoidPointer(
169         reinterpret_cast<void *>(Value & PointerBitMask));
170   }
171 
172   static intptr_t getInt(intptr_t Value) {
173     return (Value >> IntShift) & IntMask;
174   }
175 
176   static intptr_t updatePointer(intptr_t OrigValue, PointerT Ptr) {
177     intptr_t PtrWord =
178         reinterpret_cast<intptr_t>(PtrTraits::getAsVoidPointer(Ptr));
179     assert((PtrWord & ~PointerBitMask) == 0 &&
180            "Pointer is not sufficiently aligned");
181     // Preserve all low bits, just update the pointer.
182     return PtrWord | (OrigValue & ~PointerBitMask);
183   }
184 
185   static intptr_t updateInt(intptr_t OrigValue, intptr_t Int) {
186     intptr_t IntWord = static_cast<intptr_t>(Int);
187     assert((IntWord & ~IntMask) == 0 && "Integer too large for field");
188 
189     // Preserve all bits other than the ones we are updating.
190     return (OrigValue & ~ShiftedIntMask) | IntWord << IntShift;
191   }
192 };
193 
194 // Provide specialization of DenseMapInfo for PointerIntPair.
195 template <typename PointerTy, unsigned IntBits, typename IntType>
196 struct DenseMapInfo<PointerIntPair<PointerTy, IntBits, IntType>, void> {
197   using Ty = PointerIntPair<PointerTy, IntBits, IntType>;
198 
199   static Ty getEmptyKey() {
200     uintptr_t Val = static_cast<uintptr_t>(-1);
201     Val <<= PointerLikeTypeTraits<Ty>::NumLowBitsAvailable;
202     return Ty::getFromOpaqueValue(reinterpret_cast<void *>(Val));
203   }
204 
205   static Ty getTombstoneKey() {
206     uintptr_t Val = static_cast<uintptr_t>(-2);
207     Val <<= PointerLikeTypeTraits<PointerTy>::NumLowBitsAvailable;
208     return Ty::getFromOpaqueValue(reinterpret_cast<void *>(Val));
209   }
210 
211   static unsigned getHashValue(Ty V) {
212     uintptr_t IV = reinterpret_cast<uintptr_t>(V.getOpaqueValue());
213     return unsigned(IV) ^ unsigned(IV >> 9);
214   }
215 
216   static bool isEqual(const Ty &LHS, const Ty &RHS) { return LHS == RHS; }
217 };
218 
219 // Teach SmallPtrSet that PointerIntPair is "basically a pointer".
220 template <typename PointerTy, unsigned IntBits, typename IntType,
221           typename PtrTraits>
222 struct PointerLikeTypeTraits<
223     PointerIntPair<PointerTy, IntBits, IntType, PtrTraits>> {
224   static inline void *
225   getAsVoidPointer(const PointerIntPair<PointerTy, IntBits, IntType> &P) {
226     return P.getOpaqueValue();
227   }
228 
229   static inline PointerIntPair<PointerTy, IntBits, IntType>
230   getFromVoidPointer(void *P) {
231     return PointerIntPair<PointerTy, IntBits, IntType>::getFromOpaqueValue(P);
232   }
233 
234   static inline PointerIntPair<PointerTy, IntBits, IntType>
235   getFromVoidPointer(const void *P) {
236     return PointerIntPair<PointerTy, IntBits, IntType>::getFromOpaqueValue(P);
237   }
238 
239   static constexpr int NumLowBitsAvailable =
240       PtrTraits::NumLowBitsAvailable - IntBits;
241 };
242 
243 } // end namespace llvm
244 
245 #endif // LLVM_ADT_POINTERINTPAIR_H
246