LLVM API Documentation
00001 //===-- llvm/Support/Annotation.h - Annotation classes ----------*- C++ -*-===// 00002 // 00003 // The LLVM Compiler Infrastructure 00004 // 00005 // This file was developed by the LLVM research group and is distributed under 00006 // the University of Illinois Open Source License. See LICENSE.TXT for details. 00007 // 00008 //===----------------------------------------------------------------------===// 00009 // 00010 // This file contains the declarations for two classes: Annotation & Annotable. 00011 // Using these two simple classes, anything that derives from Annotable can have 00012 // Annotation subclasses attached to them, ready for easy retrieval. 00013 // 00014 // Annotations are designed to be easily attachable to various classes. 00015 // 00016 // The AnnotationManager class is essential for using these classes. It is 00017 // responsible for turning Annotation name strings into tokens [unique id #'s] 00018 // that may be used to search for and create annotations. 00019 // 00020 //===----------------------------------------------------------------------===// 00021 00022 #ifndef LLVM_SUPPORT_ANNOTATION_H 00023 #define LLVM_SUPPORT_ANNOTATION_H 00024 00025 #include <string> 00026 #include <cassert> 00027 00028 namespace llvm { 00029 00030 class AnnotationID; 00031 class Annotation; 00032 class Annotable; 00033 struct AnnotationManager; 00034 00035 //===----------------------------------------------------------------------===// 00036 // 00037 // AnnotationID - This class is a thin wrapper around an unsigned integer that 00038 // is used to hopefully prevent errors using AnnotationID's. They may be copied 00039 // freely around and passed byvalue with little or no overhead. 00040 // 00041 class AnnotationID { 00042 friend struct AnnotationManager; 00043 unsigned ID; 00044 00045 AnnotationID(); // Default ctor is disabled 00046 inline AnnotationID(unsigned i) : ID(i) {} // Only creatable from AnnMgr 00047 public: 00048 inline AnnotationID(const AnnotationID &A) : ID(A.ID) {} 00049 00050 inline bool operator==(const AnnotationID &A) const { 00051 return A.ID == ID; 00052 } 00053 inline bool operator<(const AnnotationID &A) const { 00054 return ID < A.ID; 00055 } 00056 }; 00057 00058 00059 //===----------------------------------------------------------------------===// 00060 // 00061 // Annotation Class - This class serves as a base class for any specific 00062 // annotations that you might need. Simply subclass this to add extra 00063 // information to the annotations. 00064 // 00065 class Annotation { 00066 friend class Annotable; // Annotable manipulates Next list 00067 AnnotationID ID; // ID number, as obtained from AnnotationManager 00068 Annotation *Next; // The next annotation in the linked list 00069 public: 00070 inline Annotation(AnnotationID id) : ID(id), Next(0) {} 00071 virtual ~Annotation(); // Designed to be subclassed 00072 00073 // getID - Return the unique ID# of this annotation 00074 inline AnnotationID getID() const { return ID; } 00075 00076 // getNext - Return the next annotation in the list... 00077 inline Annotation *getNext() const { return Next; } 00078 }; 00079 00080 00081 //===----------------------------------------------------------------------===// 00082 // 00083 // Annotable - This class is used as a base class for all objects that would 00084 // like to have annotation capability. One notable subclass is Value, which 00085 // means annotations can be attached to almost everything in LLVM. 00086 // 00087 // Annotable objects keep their annotation list sorted as annotations are 00088 // inserted and deleted. This is used to ensure that annotations with identical 00089 // ID#'s are stored sequentially. 00090 // 00091 class Annotable { 00092 mutable Annotation *AnnotationList; 00093 00094 Annotable(const Annotable &); // Do not implement 00095 void operator=(const Annotable &); // Do not implement 00096 public: 00097 Annotable() : AnnotationList(0) {} 00098 ~Annotable(); 00099 00100 // getAnnotation - Search the list for annotations of the specified ID. The 00101 // pointer returned is either null (if no annotations of the specified ID 00102 // exist), or it points to the first element of a potentially list of elements 00103 // with identical ID #'s. 00104 // 00105 Annotation *getAnnotation(AnnotationID ID) const { 00106 for (Annotation *A = AnnotationList; A; A = A->getNext()) 00107 if (A->getID() == ID) return A; 00108 return 0; 00109 } 00110 00111 // getOrCreateAnnotation - Search through the annotation list, if there is 00112 // no annotation with the specified ID, then use the AnnotationManager to 00113 // create one. 00114 // 00115 inline Annotation *getOrCreateAnnotation(AnnotationID ID) const; 00116 00117 // addAnnotation - Insert the annotation into the list in a sorted location. 00118 // 00119 void addAnnotation(Annotation *A) const { 00120 assert(A->Next == 0 && "Annotation already in list?!?"); 00121 00122 Annotation **AL = &AnnotationList; 00123 while (*AL && (*AL)->ID < A->getID()) // Find where to insert annotation 00124 AL = &((*AL)->Next); 00125 A->Next = *AL; // Link the annotation in 00126 *AL = A; 00127 } 00128 00129 // unlinkAnnotation - Remove the first annotation of the specified ID... and 00130 // then return the unlinked annotation. The annotation object is not deleted. 00131 // 00132 inline Annotation *unlinkAnnotation(AnnotationID ID) const { 00133 for (Annotation **A = &AnnotationList; *A; A = &((*A)->Next)) 00134 if ((*A)->getID() == ID) { 00135 Annotation *Ret = *A; 00136 *A = Ret->Next; 00137 Ret->Next = 0; 00138 return Ret; 00139 } 00140 return 0; 00141 } 00142 00143 // deleteAnnotation - Delete the first annotation of the specified ID in the 00144 // list. Unlink unlinkAnnotation, this actually deletes the annotation object 00145 // 00146 bool deleteAnnotation(AnnotationID ID) const { 00147 Annotation *A = unlinkAnnotation(ID); 00148 delete A; 00149 return A != 0; 00150 } 00151 }; 00152 00153 00154 //===----------------------------------------------------------------------===// 00155 // 00156 // AnnotationManager - This class is primarily responsible for maintaining a 00157 // one-to-one mapping between string Annotation names and Annotation ID numbers. 00158 // 00159 // Compared to the rest of the Annotation system, these mapping methods are 00160 // relatively slow, so they should be avoided by locally caching Annotation 00161 // ID #'s. These methods are safe to call at any time, even by static ctors, so 00162 // they should be used by static ctors most of the time. 00163 // 00164 // This class also provides support for annotations that are created on demand 00165 // by the Annotable::getOrCreateAnnotation method. To get this to work, simply 00166 // register an annotation handler 00167 // 00168 struct AnnotationManager { 00169 typedef Annotation *(*Factory)(AnnotationID, const Annotable *, void*); 00170 00171 //===--------------------------------------------------------------------===// 00172 // Basic ID <-> Name map functionality 00173 00174 static AnnotationID getID(const std::string &Name); // Name -> ID 00175 static const std::string &getName(AnnotationID ID); // ID -> Name 00176 00177 // getID - Name -> ID + registration of a factory function for demand driven 00178 // annotation support. 00179 static AnnotationID getID(const std::string &Name, Factory Fact, 00180 void *Data = 0); 00181 00182 //===--------------------------------------------------------------------===// 00183 // Annotation creation on demand support... 00184 00185 // registerAnnotationFactory - This method is used to register a callback 00186 // function used to create an annotation on demand if it is needed by the 00187 // Annotable::getOrCreateAnnotation method. 00188 // 00189 static void registerAnnotationFactory(AnnotationID ID, Factory Func, 00190 void *ExtraData = 0); 00191 00192 // createAnnotation - Create an annotation of the specified ID for the 00193 // specified object, using a register annotation creation function. 00194 // 00195 static Annotation *createAnnotation(AnnotationID ID, const Annotable *Obj); 00196 }; 00197 00198 00199 00200 // getOrCreateAnnotation - Search through the annotation list, if there is 00201 // no annotation with the specified ID, then use the AnnotationManager to 00202 // create one. 00203 // 00204 inline Annotation *Annotable::getOrCreateAnnotation(AnnotationID ID) const { 00205 Annotation *A = getAnnotation(ID); // Fast path, check for preexisting ann 00206 if (A) return A; 00207 00208 // No annotation found, ask the annotation manager to create an annotation... 00209 A = AnnotationManager::createAnnotation(ID, this); 00210 assert(A && "AnnotationManager could not create annotation!"); 00211 addAnnotation(A); 00212 return A; 00213 } 00214 00215 } // End namespace llvm 00216 00217 #endif