LLVM API Documentation

ValueHandle.h
Go to the documentation of this file.
00001 //===- llvm/Support/ValueHandle.h - Value Smart Pointer classes -*- C++ -*-===//
00002 //
00003 //                     The LLVM Compiler Infrastructure
00004 //
00005 // This file is distributed under the University of Illinois Open Source
00006 // License. See LICENSE.TXT for details.
00007 //
00008 //===----------------------------------------------------------------------===//
00009 //
00010 // This file declares the ValueHandle class and its sub-classes.
00011 //
00012 //===----------------------------------------------------------------------===//
00013 
00014 #ifndef LLVM_SUPPORT_VALUEHANDLE_H
00015 #define LLVM_SUPPORT_VALUEHANDLE_H
00016 
00017 #include "llvm/ADT/DenseMapInfo.h"
00018 #include "llvm/ADT/PointerIntPair.h"
00019 #include "llvm/IR/Value.h"
00020 
00021 namespace llvm {
00022 class ValueHandleBase;
00023 template<typename From> struct simplify_type;
00024 
00025 // ValueHandleBase** is only 4-byte aligned.
00026 template<>
00027 class PointerLikeTypeTraits<ValueHandleBase**> {
00028 public:
00029   static inline void *getAsVoidPointer(ValueHandleBase** P) { return P; }
00030   static inline ValueHandleBase **getFromVoidPointer(void *P) {
00031     return static_cast<ValueHandleBase**>(P);
00032   }
00033   enum { NumLowBitsAvailable = 2 };
00034 };
00035 
00036 /// ValueHandleBase - This is the common base class of value handles.
00037 /// ValueHandle's are smart pointers to Value's that have special behavior when
00038 /// the value is deleted or ReplaceAllUsesWith'd.  See the specific handles
00039 /// below for details.
00040 ///
00041 class ValueHandleBase {
00042   friend class Value;
00043 protected:
00044   /// HandleBaseKind - This indicates what sub class the handle actually is.
00045   /// This is to avoid having a vtable for the light-weight handle pointers. The
00046   /// fully general Callback version does have a vtable.
00047   enum HandleBaseKind {
00048     Assert,
00049     Callback,
00050     Tracking,
00051     Weak
00052   };
00053 
00054 private:
00055   PointerIntPair<ValueHandleBase**, 2, HandleBaseKind> PrevPair;
00056   ValueHandleBase *Next;
00057 
00058   // A subclass may want to store some information along with the value
00059   // pointer. Allow them to do this by making the value pointer a pointer-int
00060   // pair. The 'setValPtrInt' and 'getValPtrInt' methods below give them this
00061   // access.
00062   PointerIntPair<Value*, 2> VP;
00063 
00064   ValueHandleBase(const ValueHandleBase&) LLVM_DELETED_FUNCTION;
00065 public:
00066   explicit ValueHandleBase(HandleBaseKind Kind)
00067     : PrevPair(0, Kind), Next(0), VP(0, 0) {}
00068   ValueHandleBase(HandleBaseKind Kind, Value *V)
00069     : PrevPair(0, Kind), Next(0), VP(V, 0) {
00070     if (isValid(VP.getPointer()))
00071       AddToUseList();
00072   }
00073   ValueHandleBase(HandleBaseKind Kind, const ValueHandleBase &RHS)
00074     : PrevPair(0, Kind), Next(0), VP(RHS.VP) {
00075     if (isValid(VP.getPointer()))
00076       AddToExistingUseList(RHS.getPrevPtr());
00077   }
00078   ~ValueHandleBase() {
00079     if (isValid(VP.getPointer()))
00080       RemoveFromUseList();
00081   }
00082 
00083   Value *operator=(Value *RHS) {
00084     if (VP.getPointer() == RHS) return RHS;
00085     if (isValid(VP.getPointer())) RemoveFromUseList();
00086     VP.setPointer(RHS);
00087     if (isValid(VP.getPointer())) AddToUseList();
00088     return RHS;
00089   }
00090 
00091   Value *operator=(const ValueHandleBase &RHS) {
00092     if (VP.getPointer() == RHS.VP.getPointer()) return RHS.VP.getPointer();
00093     if (isValid(VP.getPointer())) RemoveFromUseList();
00094     VP.setPointer(RHS.VP.getPointer());
00095     if (isValid(VP.getPointer())) AddToExistingUseList(RHS.getPrevPtr());
00096     return VP.getPointer();
00097   }
00098 
00099   Value *operator->() const { return getValPtr(); }
00100   Value &operator*() const { return *getValPtr(); }
00101 
00102 protected:
00103   Value *getValPtr() const { return VP.getPointer(); }
00104 
00105   void setValPtrInt(unsigned K) { VP.setInt(K); }
00106   unsigned getValPtrInt() const { return VP.getInt(); }
00107 
00108   static bool isValid(Value *V) {
00109     return V &&
00110            V != DenseMapInfo<Value *>::getEmptyKey() &&
00111            V != DenseMapInfo<Value *>::getTombstoneKey();
00112   }
00113 
00114 public:
00115   // Callbacks made from Value.
00116   static void ValueIsDeleted(Value *V);
00117   static void ValueIsRAUWd(Value *Old, Value *New);
00118 
00119 private:
00120   // Internal implementation details.
00121   ValueHandleBase **getPrevPtr() const { return PrevPair.getPointer(); }
00122   HandleBaseKind getKind() const { return PrevPair.getInt(); }
00123   void setPrevPtr(ValueHandleBase **Ptr) { PrevPair.setPointer(Ptr); }
00124 
00125   /// AddToExistingUseList - Add this ValueHandle to the use list for VP, where
00126   /// List is the address of either the head of the list or a Next node within
00127   /// the existing use list.
00128   void AddToExistingUseList(ValueHandleBase **List);
00129 
00130   /// AddToExistingUseListAfter - Add this ValueHandle to the use list after
00131   /// Node.
00132   void AddToExistingUseListAfter(ValueHandleBase *Node);
00133 
00134   /// AddToUseList - Add this ValueHandle to the use list for VP.
00135   void AddToUseList();
00136   /// RemoveFromUseList - Remove this ValueHandle from its current use list.
00137   void RemoveFromUseList();
00138 };
00139 
00140 /// WeakVH - This is a value handle that tries hard to point to a Value, even
00141 /// across RAUW operations, but will null itself out if the value is destroyed.
00142 /// this is useful for advisory sorts of information, but should not be used as
00143 /// the key of a map (since the map would have to rearrange itself when the
00144 /// pointer changes).
00145 class WeakVH : public ValueHandleBase {
00146 public:
00147   WeakVH() : ValueHandleBase(Weak) {}
00148   WeakVH(Value *P) : ValueHandleBase(Weak, P) {}
00149   WeakVH(const WeakVH &RHS)
00150     : ValueHandleBase(Weak, RHS) {}
00151 
00152   Value *operator=(Value *RHS) {
00153     return ValueHandleBase::operator=(RHS);
00154   }
00155   Value *operator=(const ValueHandleBase &RHS) {
00156     return ValueHandleBase::operator=(RHS);
00157   }
00158 
00159   operator Value*() const {
00160     return getValPtr();
00161   }
00162 };
00163 
00164 // Specialize simplify_type to allow WeakVH to participate in
00165 // dyn_cast, isa, etc.
00166 template<> struct simplify_type<WeakVH> {
00167   typedef Value* SimpleType;
00168   static SimpleType getSimplifiedValue(WeakVH &WVH) {
00169     return WVH;
00170   }
00171 };
00172 
00173 /// AssertingVH - This is a Value Handle that points to a value and asserts out
00174 /// if the value is destroyed while the handle is still live.  This is very
00175 /// useful for catching dangling pointer bugs and other things which can be
00176 /// non-obvious.  One particularly useful place to use this is as the Key of a
00177 /// map.  Dangling pointer bugs often lead to really subtle bugs that only occur
00178 /// if another object happens to get allocated to the same address as the old
00179 /// one.  Using an AssertingVH ensures that an assert is triggered as soon as
00180 /// the bad delete occurs.
00181 ///
00182 /// Note that an AssertingVH handle does *not* follow values across RAUW
00183 /// operations.  This means that RAUW's need to explicitly update the
00184 /// AssertingVH's as it moves.  This is required because in non-assert mode this
00185 /// class turns into a trivial wrapper around a pointer.
00186 template <typename ValueTy>
00187 class AssertingVH
00188 #ifndef NDEBUG
00189   : public ValueHandleBase
00190 #endif
00191   {
00192 
00193 #ifndef NDEBUG
00194   ValueTy *getValPtr() const {
00195     return static_cast<ValueTy*>(ValueHandleBase::getValPtr());
00196   }
00197   void setValPtr(ValueTy *P) {
00198     ValueHandleBase::operator=(GetAsValue(P));
00199   }
00200 #else
00201   ValueTy *ThePtr;
00202   ValueTy *getValPtr() const { return ThePtr; }
00203   void setValPtr(ValueTy *P) { ThePtr = P; }
00204 #endif
00205 
00206   // Convert a ValueTy*, which may be const, to the type the base
00207   // class expects.
00208   static Value *GetAsValue(Value *V) { return V; }
00209   static Value *GetAsValue(const Value *V) { return const_cast<Value*>(V); }
00210 
00211 public:
00212 #ifndef NDEBUG
00213   AssertingVH() : ValueHandleBase(Assert) {}
00214   AssertingVH(ValueTy *P) : ValueHandleBase(Assert, GetAsValue(P)) {}
00215   AssertingVH(const AssertingVH &RHS) : ValueHandleBase(Assert, RHS) {}
00216 #else
00217   AssertingVH() : ThePtr(0) {}
00218   AssertingVH(ValueTy *P) : ThePtr(P) {}
00219 #endif
00220 
00221   operator ValueTy*() const {
00222     return getValPtr();
00223   }
00224 
00225   ValueTy *operator=(ValueTy *RHS) {
00226     setValPtr(RHS);
00227     return getValPtr();
00228   }
00229   ValueTy *operator=(const AssertingVH<ValueTy> &RHS) {
00230     setValPtr(RHS.getValPtr());
00231     return getValPtr();
00232   }
00233 
00234   ValueTy *operator->() const { return getValPtr(); }
00235   ValueTy &operator*() const { return *getValPtr(); }
00236 };
00237 
00238 // Specialize DenseMapInfo to allow AssertingVH to participate in DenseMap.
00239 template<typename T>
00240 struct DenseMapInfo<AssertingVH<T> > {
00241   typedef DenseMapInfo<T*> PointerInfo;
00242   static inline AssertingVH<T> getEmptyKey() {
00243     return AssertingVH<T>(PointerInfo::getEmptyKey());
00244   }
00245   static inline T* getTombstoneKey() {
00246     return AssertingVH<T>(PointerInfo::getTombstoneKey());
00247   }
00248   static unsigned getHashValue(const AssertingVH<T> &Val) {
00249     return PointerInfo::getHashValue(Val);
00250   }
00251   static bool isEqual(const AssertingVH<T> &LHS, const AssertingVH<T> &RHS) {
00252     return LHS == RHS;
00253   }
00254 };
00255   
00256 template <typename T>
00257 struct isPodLike<AssertingVH<T> > {
00258 #ifdef NDEBUG
00259   static const bool value = true;
00260 #else
00261   static const bool value = false;
00262 #endif
00263 };
00264 
00265 
00266 /// TrackingVH - This is a value handle that tracks a Value (or Value subclass),
00267 /// even across RAUW operations.
00268 ///
00269 /// TrackingVH is designed for situations where a client needs to hold a handle
00270 /// to a Value (or subclass) across some operations which may move that value,
00271 /// but should never destroy it or replace it with some unacceptable type.
00272 ///
00273 /// It is an error to do anything with a TrackingVH whose value has been
00274 /// destroyed, except to destruct it.
00275 ///
00276 /// It is an error to attempt to replace a value with one of a type which is
00277 /// incompatible with any of its outstanding TrackingVHs.
00278 template<typename ValueTy>
00279 class TrackingVH : public ValueHandleBase {
00280   void CheckValidity() const {
00281     Value *VP = ValueHandleBase::getValPtr();
00282 
00283     // Null is always ok.
00284     if (!VP) return;
00285 
00286     // Check that this value is valid (i.e., it hasn't been deleted). We
00287     // explicitly delay this check until access to avoid requiring clients to be
00288     // unnecessarily careful w.r.t. destruction.
00289     assert(ValueHandleBase::isValid(VP) && "Tracked Value was deleted!");
00290 
00291     // Check that the value is a member of the correct subclass. We would like
00292     // to check this property on assignment for better debugging, but we don't
00293     // want to require a virtual interface on this VH. Instead we allow RAUW to
00294     // replace this value with a value of an invalid type, and check it here.
00295     assert(isa<ValueTy>(VP) &&
00296            "Tracked Value was replaced by one with an invalid type!");
00297   }
00298 
00299   ValueTy *getValPtr() const {
00300     CheckValidity();
00301     return (ValueTy*)ValueHandleBase::getValPtr();
00302   }
00303   void setValPtr(ValueTy *P) {
00304     CheckValidity();
00305     ValueHandleBase::operator=(GetAsValue(P));
00306   }
00307 
00308   // Convert a ValueTy*, which may be const, to the type the base
00309   // class expects.
00310   static Value *GetAsValue(Value *V) { return V; }
00311   static Value *GetAsValue(const Value *V) { return const_cast<Value*>(V); }
00312 
00313 public:
00314   TrackingVH() : ValueHandleBase(Tracking) {}
00315   TrackingVH(ValueTy *P) : ValueHandleBase(Tracking, GetAsValue(P)) {}
00316   TrackingVH(const TrackingVH &RHS) : ValueHandleBase(Tracking, RHS) {}
00317 
00318   operator ValueTy*() const {
00319     return getValPtr();
00320   }
00321 
00322   ValueTy *operator=(ValueTy *RHS) {
00323     setValPtr(RHS);
00324     return getValPtr();
00325   }
00326   ValueTy *operator=(const TrackingVH<ValueTy> &RHS) {
00327     setValPtr(RHS.getValPtr());
00328     return getValPtr();
00329   }
00330 
00331   ValueTy *operator->() const { return getValPtr(); }
00332   ValueTy &operator*() const { return *getValPtr(); }
00333 };
00334 
00335 /// CallbackVH - This is a value handle that allows subclasses to define
00336 /// callbacks that run when the underlying Value has RAUW called on it or is
00337 /// destroyed.  This class can be used as the key of a map, as long as the user
00338 /// takes it out of the map before calling setValPtr() (since the map has to
00339 /// rearrange itself when the pointer changes).  Unlike ValueHandleBase, this
00340 /// class has a vtable and a virtual destructor.
00341 class CallbackVH : public ValueHandleBase {
00342 protected:
00343   CallbackVH(const CallbackVH &RHS)
00344     : ValueHandleBase(Callback, RHS) {}
00345 
00346   virtual ~CallbackVH() {}
00347 
00348   void setValPtr(Value *P) {
00349     ValueHandleBase::operator=(P);
00350   }
00351 
00352 public:
00353   CallbackVH() : ValueHandleBase(Callback) {}
00354   CallbackVH(Value *P) : ValueHandleBase(Callback, P) {}
00355 
00356   operator Value*() const {
00357     return getValPtr();
00358   }
00359 
00360   /// Called when this->getValPtr() is destroyed, inside ~Value(), so you may
00361   /// call any non-virtual Value method on getValPtr(), but no subclass methods.
00362   /// If WeakVH were implemented as a CallbackVH, it would use this method to
00363   /// call setValPtr(NULL).  AssertingVH would use this method to cause an
00364   /// assertion failure.
00365   ///
00366   /// All implementations must remove the reference from this object to the
00367   /// Value that's being destroyed.
00368   virtual void deleted();
00369 
00370   /// Called when this->getValPtr()->replaceAllUsesWith(new_value) is called,
00371   /// _before_ any of the uses have actually been replaced.  If WeakVH were
00372   /// implemented as a CallbackVH, it would use this method to call
00373   /// setValPtr(new_value).  AssertingVH would do nothing in this method.
00374   virtual void allUsesReplacedWith(Value *);
00375 };
00376 
00377 } // End llvm namespace
00378 
00379 #endif