include/llvm/IR/ValueHandle.h

   1 //===- ValueHandle.h - Value Smart Pointer classes --------------*- C++ -*-===//
   2 //
   3 //                     The LLVM Compiler Infrastructure
   4 //
   5 // This file is distributed under the University of Illinois Open Source
   6 // License. See LICENSE.TXT for details.
   7 //
   8 //===----------------------------------------------------------------------===//
   9 //
  10 // This file declares the ValueHandle class and its sub-classes.
  11 //
  12 //===----------------------------------------------------------------------===//
  13
  14 #ifndef LLVM_IR_VALUEHANDLE_H
  15 #define LLVM_IR_VALUEHANDLE_H
  16
  17 #include "llvm/ADT/DenseMapInfo.h"
  18 #include "llvm/ADT/PointerIntPair.h"
  19 #include "llvm/IR/Value.h"
  20
  21 namespace llvm {
  22 class ValueHandleBase;
  23 template<typename From> struct simplify_type;
  24
  25 // ValueHandleBase** is only 4-byte aligned.
  26 template<>
  27 class PointerLikeTypeTraits<ValueHandleBase**> {
  28 public:
  29   static inline void *getAsVoidPointer(ValueHandleBase** P) { return P; }
  30   static inline ValueHandleBase **getFromVoidPointer(void *P) {
  31     return static_cast<ValueHandleBase**>(P);
  32   }
  33   enum { NumLowBitsAvailable = 2 };
  34 };
  35
  36 /// \brief This is the common base class of value handles.
  37 ///
  38 /// ValueHandle's are smart pointers to Value's that have special behavior when
  39 /// the value is deleted or ReplaceAllUsesWith'd.  See the specific handles
  40 /// below for details.
  41 class ValueHandleBase {
  42   friend class Value;
  43 protected:
  44   /// \brief This indicates what sub class the handle actually is.
  45   ///
  46   /// This is to avoid having a vtable for the light-weight handle pointers. The
  47   /// fully general Callback version does have a vtable.
  48   enum HandleBaseKind {
  49     Assert,
  50     Callback,
  51     Tracking,
  52     Weak
  53   };
  54
  55 private:
  56   PointerIntPair<ValueHandleBase**, 2, HandleBaseKind> PrevPair;
  57   ValueHandleBase *Next;
  58
  59   // A subclass may want to store some information along with the value
  60   // pointer. Allow them to do this by making the value pointer a pointer-int
  61   // pair. The 'setValPtrInt' and 'getValPtrInt' methods below give them this
  62   // access.
  63   PointerIntPair<Value*, 2> VP;
  64
  65   ValueHandleBase(const ValueHandleBase&) LLVM_DELETED_FUNCTION;
  66 public:
  67   explicit ValueHandleBase(HandleBaseKind Kind)
  68     : PrevPair(nullptr, Kind), Next(nullptr), VP(nullptr, 0) {}
  69   ValueHandleBase(HandleBaseKind Kind, Value *V)
  70     : PrevPair(nullptr, Kind), Next(nullptr), VP(V, 0) {
  71     if (isValid(VP.getPointer()))
  72       AddToUseList();
  73   }
  74   ValueHandleBase(HandleBaseKind Kind, const ValueHandleBase &RHS)
  75     : PrevPair(nullptr, Kind), Next(nullptr), VP(RHS.VP) {
  76     if (isValid(VP.getPointer()))
  77       AddToExistingUseList(RHS.getPrevPtr());
  78   }
  79   ~ValueHandleBase() {
  80     if (isValid(VP.getPointer()))
  81       RemoveFromUseList();
  82   }
  83
  84   Value *operator=(Value *RHS) {
  85     if (VP.getPointer() == RHS) return RHS;
  86     if (isValid(VP.getPointer())) RemoveFromUseList();
  87     VP.setPointer(RHS);
  88     if (isValid(VP.getPointer())) AddToUseList();
  89     return RHS;
  90   }
  91
  92   Value *operator=(const ValueHandleBase &RHS) {
  93     if (VP.getPointer() == RHS.VP.getPointer()) return RHS.VP.getPointer();
  94     if (isValid(VP.getPointer())) RemoveFromUseList();
  95     VP.setPointer(RHS.VP.getPointer());
  96     if (isValid(VP.getPointer())) AddToExistingUseList(RHS.getPrevPtr());
  97     return VP.getPointer();
  98   }
  99
 100   Value *operator->() const { return getValPtr(); }
 101   Value &operator*() const { return *getValPtr(); }
 102
 103 protected:
 104   Value *getValPtr() const { return VP.getPointer(); }
 105
 106   void setValPtrInt(unsigned K) { VP.setInt(K); }
 107   unsigned getValPtrInt() const { return VP.getInt(); }
 108
 109   static bool isValid(Value *V) {
 110     return V &&
 111            V != DenseMapInfo<Value *>::getEmptyKey() &&
 112            V != DenseMapInfo<Value *>::getTombstoneKey();
 113   }
 114
 115 public:
 116   // Callbacks made from Value.
 117   static void ValueIsDeleted(Value *V);
 118   static void ValueIsRAUWd(Value *Old, Value *New);
 119
 120 private:
 121   // Internal implementation details.
 122   ValueHandleBase **getPrevPtr() const { return PrevPair.getPointer(); }
 123   HandleBaseKind getKind() const { return PrevPair.getInt(); }
 124   void setPrevPtr(ValueHandleBase **Ptr) { PrevPair.setPointer(Ptr); }
 125
 126   /// \brief Add this ValueHandle to the use list for VP.
 127   ///
 128   /// List is the address of either the head of the list or a Next node within
 129   /// the existing use list.
 130   void AddToExistingUseList(ValueHandleBase **List);
 131
 132   /// \brief Add this ValueHandle to the use list after Node.
 133   void AddToExistingUseListAfter(ValueHandleBase *Node);
 134
 135   /// \brief Add this ValueHandle to the use list for VP.
 136   void AddToUseList();
 137   /// \brief Remove this ValueHandle from its current use list.
 138   void RemoveFromUseList();
 139 };
 140
 141 /// \brief Value handle that is nullable, but tries to track the Value.
 142 ///
 143 /// This is a value handle that tries hard to point to a Value, even across
 144 /// RAUW operations, but will null itself out if the value is destroyed.  this
 145 /// is useful for advisory sorts of information, but should not be used as the
 146 /// key of a map (since the map would have to rearrange itself when the pointer
 147 /// changes).
 148 class WeakVH : public ValueHandleBase {
 149 public:
 150   WeakVH() : ValueHandleBase(Weak) {}
 151   WeakVH(Value *P) : ValueHandleBase(Weak, P) {}
 152   WeakVH(const WeakVH &RHS)
 153     : ValueHandleBase(Weak, RHS) {}
 154
 155   Value *operator=(Value *RHS) {
 156     return ValueHandleBase::operator=(RHS);
 157   }
 158   Value *operator=(const ValueHandleBase &RHS) {
 159     return ValueHandleBase::operator=(RHS);
 160   }
 161
 162   operator Value*() const {
 163     return getValPtr();
 164   }
 165 };
 166
 167 // Specialize simplify_type to allow WeakVH to participate in
 168 // dyn_cast, isa, etc.
 169 template<> struct simplify_type<WeakVH> {
 170   typedef Value* SimpleType;
 171   static SimpleType getSimplifiedValue(WeakVH &WVH) {
 172     return WVH;
 173   }
 174 };
 175
 176 /// \brief Value handle that asserts if the Value is deleted.
 177 ///
 178 /// This is a Value Handle that points to a value and asserts out if the value
 179 /// is destroyed while the handle is still live.  This is very useful for
 180 /// catching dangling pointer bugs and other things which can be non-obvious.
 181 /// One particularly useful place to use this is as the Key of a map.  Dangling
 182 /// pointer bugs often lead to really subtle bugs that only occur if another
 183 /// object happens to get allocated to the same address as the old one.  Using
 184 /// an AssertingVH ensures that an assert is triggered as soon as the bad
 185 /// delete occurs.
 186 ///
 187 /// Note that an AssertingVH handle does *not* follow values across RAUW
 188 /// operations.  This means that RAUW's need to explicitly update the
 189 /// AssertingVH's as it moves.  This is required because in non-assert mode this
 190 /// class turns into a trivial wrapper around a pointer.
 191 template <typename ValueTy>
 192 class AssertingVH
 193 #ifndef NDEBUG
 194   : public ValueHandleBase
 195 #endif
 196   {
 197   friend struct DenseMapInfo<AssertingVH<ValueTy> >;
 198
 199 #ifndef NDEBUG
 200   ValueTy *getValPtr() const {
 201     return static_cast<ValueTy*>(ValueHandleBase::getValPtr());
 202   }
 203   void setValPtr(ValueTy *P) {
 204     ValueHandleBase::operator=(GetAsValue(P));
 205   }
 206 #else
 207   ValueTy *ThePtr;
 208   ValueTy *getValPtr() const { return ThePtr; }
 209   void setValPtr(ValueTy *P) { ThePtr = P; }
 210 #endif
 211
 212   // Convert a ValueTy*, which may be const, to the type the base
 213   // class expects.
 214   static Value *GetAsValue(Value *V) { return V; }
 215   static Value *GetAsValue(const Value *V) { return const_cast<Value*>(V); }
 216
 217 public:
 218 #ifndef NDEBUG
 219   AssertingVH() : ValueHandleBase(Assert) {}
 220   AssertingVH(ValueTy *P) : ValueHandleBase(Assert, GetAsValue(P)) {}
 221   AssertingVH(const AssertingVH &RHS) : ValueHandleBase(Assert, RHS) {}
 222 #else
 223   AssertingVH() : ThePtr(nullptr) {}
 224   AssertingVH(ValueTy *P) : ThePtr(P) {}
 225 #endif
 226
 227   operator ValueTy*() const {
 228     return getValPtr();
 229   }
 230
 231   ValueTy *operator=(ValueTy *RHS) {
 232     setValPtr(RHS);
 233     return getValPtr();
 234   }
 235   ValueTy *operator=(const AssertingVH<ValueTy> &RHS) {
 236     setValPtr(RHS.getValPtr());
 237     return getValPtr();
 238   }
 239
 240   ValueTy *operator->() const { return getValPtr(); }
 241   ValueTy &operator*() const { return *getValPtr(); }
 242 };
 243
 244 // Specialize DenseMapInfo to allow AssertingVH to participate in DenseMap.
 245 template<typename T>
 246 struct DenseMapInfo<AssertingVH<T> > {
 247   typedef DenseMapInfo<T*> PointerInfo;
 248   static inline AssertingVH<T> getEmptyKey() {
 249     return AssertingVH<T>(PointerInfo::getEmptyKey());
 250   }
 251   static inline T* getTombstoneKey() {
 252     return AssertingVH<T>(PointerInfo::getTombstoneKey());
 253   }
 254   static unsigned getHashValue(const AssertingVH<T> &Val) {
 255     return PointerInfo::getHashValue(Val);
 256   }
 257 #ifndef NDEBUG
 258   static bool isEqual(const AssertingVH<T> &LHS, const AssertingVH<T> &RHS) {
 259     // Avoid downcasting AssertingVH<T> to T*, as empty/tombstone keys may not
 260     // be properly aligned pointers to T*.
 261     return LHS.ValueHandleBase::getValPtr() == RHS.ValueHandleBase::getValPtr();
 262   }
 263 #else
 264   static bool isEqual(const AssertingVH<T> &LHS, const AssertingVH<T> &RHS) {
 265     return LHS == RHS;
 266   }
 267 #endif
 268 };
 269
 270 template <typename T>
 271 struct isPodLike<AssertingVH<T> > {
 272 #ifdef NDEBUG
 273   static const bool value = true;
 274 #else
 275   static const bool value = false;
 276 #endif
 277 };
 278
 279
 280 /// \brief Value handle that tracks a Value across RAUW.
 281 ///
 282 /// TrackingVH is designed for situations where a client needs to hold a handle
 283 /// to a Value (or subclass) across some operations which may move that value,
 284 /// but should never destroy it or replace it with some unacceptable type.
 285 ///
 286 /// It is an error to do anything with a TrackingVH whose value has been
 287 /// destroyed, except to destruct it.
 288 ///
 289 /// It is an error to attempt to replace a value with one of a type which is
 290 /// incompatible with any of its outstanding TrackingVHs.
 291 template<typename ValueTy>
 292 class TrackingVH : public ValueHandleBase {
 293   void CheckValidity() const {
 294     Value *VP = ValueHandleBase::getValPtr();
 295
 296     // Null is always ok.
 297     if (!VP) return;
 298
 299     // Check that this value is valid (i.e., it hasn't been deleted). We
 300     // explicitly delay this check until access to avoid requiring clients to be
 301     // unnecessarily careful w.r.t. destruction.
 302     assert(ValueHandleBase::isValid(VP) && "Tracked Value was deleted!");
 303
 304     // Check that the value is a member of the correct subclass. We would like
 305     // to check this property on assignment for better debugging, but we don't
 306     // want to require a virtual interface on this VH. Instead we allow RAUW to
 307     // replace this value with a value of an invalid type, and check it here.
 308     assert(isa<ValueTy>(VP) &&
 309            "Tracked Value was replaced by one with an invalid type!");
 310   }
 311
 312   ValueTy *getValPtr() const {
 313     CheckValidity();
 314     return (ValueTy*)ValueHandleBase::getValPtr();
 315   }
 316   void setValPtr(ValueTy *P) {
 317     CheckValidity();
 318     ValueHandleBase::operator=(GetAsValue(P));
 319   }
 320
 321   // Convert a ValueTy*, which may be const, to the type the base
 322   // class expects.
 323   static Value *GetAsValue(Value *V) { return V; }
 324   static Value *GetAsValue(const Value *V) { return const_cast<Value*>(V); }
 325
 326 public:
 327   TrackingVH() : ValueHandleBase(Tracking) {}
 328   TrackingVH(ValueTy *P) : ValueHandleBase(Tracking, GetAsValue(P)) {}
 329   TrackingVH(const TrackingVH &RHS) : ValueHandleBase(Tracking, RHS) {}
 330
 331   operator ValueTy*() const {
 332     return getValPtr();
 333   }
 334
 335   ValueTy *operator=(ValueTy *RHS) {
 336     setValPtr(RHS);
 337     return getValPtr();
 338   }
 339   ValueTy *operator=(const TrackingVH<ValueTy> &RHS) {
 340     setValPtr(RHS.getValPtr());
 341     return getValPtr();
 342   }
 343
 344   ValueTy *operator->() const { return getValPtr(); }
 345   ValueTy &operator*() const { return *getValPtr(); }
 346 };
 347
 348 /// \brief Value handle with callbacks on RAUW and destruction.
 349 ///
 350 /// This is a value handle that allows subclasses to define callbacks that run
 351 /// when the underlying Value has RAUW called on it or is destroyed.  This
 352 /// class can be used as the key of a map, as long as the user takes it out of
 353 /// the map before calling setValPtr() (since the map has to rearrange itself
 354 /// when the pointer changes).  Unlike ValueHandleBase, this class has a vtable
 355 /// and a virtual destructor.
 356 class CallbackVH : public ValueHandleBase {
 357   virtual void anchor();
 358 protected:
 359   CallbackVH(const CallbackVH &RHS)
 360     : ValueHandleBase(Callback, RHS) {}
 361
 362   virtual ~CallbackVH() {}
 363
 364   void setValPtr(Value *P) {
 365     ValueHandleBase::operator=(P);
 366   }
 367
 368 public:
 369   CallbackVH() : ValueHandleBase(Callback) {}
 370   CallbackVH(Value *P) : ValueHandleBase(Callback, P) {}
 371
 372   operator Value*() const {
 373     return getValPtr();
 374   }
 375
 376   /// \brief Callback for Value destruction.
 377   ///
 378   /// Called when this->getValPtr() is destroyed, inside ~Value(), so you
 379   /// may call any non-virtual Value method on getValPtr(), but no subclass
 380   /// methods.  If WeakVH were implemented as a CallbackVH, it would use this
 381   /// method to call setValPtr(NULL).  AssertingVH would use this method to
 382   /// cause an assertion failure.
 383   ///
 384   /// All implementations must remove the reference from this object to the
 385   /// Value that's being destroyed.
 386   virtual void deleted() { setValPtr(nullptr); }
 387
 388   /// \brief Callback for Value RAUW.
 389   ///
 390   /// Called when this->getValPtr()->replaceAllUsesWith(new_value) is called,
 391   /// _before_ any of the uses have actually been replaced.  If WeakVH were
 392   /// implemented as a CallbackVH, it would use this method to call
 393   /// setValPtr(new_value).  AssertingVH would do nothing in this method.
 394   virtual void allUsesReplacedWith(Value *) {}
 395 };
 396
 397 } // End llvm namespace
 398
 399 #endif