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. 00085 // 00086 // Annotable objects keep their annotation list sorted as annotations are 00087 // inserted and deleted. This is used to ensure that annotations with identical 00088 // ID#'s are stored sequentially. 00089 // 00090 class Annotable { 00091 mutable Annotation *AnnotationList; 00092 00093 Annotable(const Annotable &); // Do not implement 00094 void operator=(const Annotable &); // Do not implement 00095 public: 00096 Annotable() : AnnotationList(0) {} 00097 ~Annotable(); 00098 00099 // getAnnotation - Search the list for annotations of the specified ID. The 00100 // pointer returned is either null (if no annotations of the specified ID 00101 // exist), or it points to the first element of a potentially list of elements 00102 // with identical ID #'s. 00103 // 00104 Annotation *getAnnotation(AnnotationID ID) const { 00105 for (Annotation *A = AnnotationList; A; A = A->getNext()) 00106 if (A->getID() == ID) return A; 00107 return 0; 00108 } 00109 00110 // getOrCreateAnnotation - Search through the annotation list, if there is 00111 // no annotation with the specified ID, then use the AnnotationManager to 00112 // create one. 00113 // 00114 inline Annotation *getOrCreateAnnotation(AnnotationID ID) const; 00115 00116 // addAnnotation - Insert the annotation into the list in a sorted location. 00117 // 00118 void addAnnotation(Annotation *A) const { 00119 assert(A->Next == 0 && "Annotation already in list?!?"); 00120 00121 Annotation **AL = &AnnotationList; 00122 while (*AL && (*AL)->ID < A->getID()) // Find where to insert annotation 00123 AL = &((*AL)->Next); 00124 A->Next = *AL; // Link the annotation in 00125 *AL = A; 00126 } 00127 00128 // unlinkAnnotation - Remove the first annotation of the specified ID... and 00129 // then return the unlinked annotation. The annotation object is not deleted. 00130 // 00131 inline Annotation *unlinkAnnotation(AnnotationID ID) const { 00132 for (Annotation **A = &AnnotationList; *A; A = &((*A)->Next)) 00133 if ((*A)->getID() == ID) { 00134 Annotation *Ret = *A; 00135 *A = Ret->Next; 00136 Ret->Next = 0; 00137 return Ret; 00138 } 00139 return 0; 00140 } 00141 00142 // deleteAnnotation - Delete the first annotation of the specified ID in the 00143 // list. Unlink unlinkAnnotation, this actually deletes the annotation object 00144 // 00145 bool deleteAnnotation(AnnotationID ID) const { 00146 Annotation *A = unlinkAnnotation(ID); 00147 delete A; 00148 return A != 0; 00149 } 00150 }; 00151 00152 00153 //===----------------------------------------------------------------------===// 00154 // 00155 // AnnotationManager - This class is primarily responsible for maintaining a 00156 // one-to-one mapping between string Annotation names and Annotation ID numbers. 00157 // 00158 // Compared to the rest of the Annotation system, these mapping methods are 00159 // relatively slow, so they should be avoided by locally caching Annotation 00160 // ID #'s. These methods are safe to call at any time, even by static ctors, so 00161 // they should be used by static ctors most of the time. 00162 // 00163 // This class also provides support for annotations that are created on demand 00164 // by the Annotable::getOrCreateAnnotation method. To get this to work, simply 00165 // register an annotation handler 00166 // 00167 struct AnnotationManager { 00168 typedef Annotation *(*Factory)(AnnotationID, const Annotable *, void*); 00169 00170 //===--------------------------------------------------------------------===// 00171 // Basic ID <-> Name map functionality 00172 00173 static AnnotationID getID(const std::string &Name); // Name -> ID 00174 static const std::string &getName(AnnotationID ID); // ID -> Name 00175 00176 // getID - Name -> ID + registration of a factory function for demand driven 00177 // annotation support. 00178 static AnnotationID getID(const std::string &Name, Factory Fact, 00179 void *Data = 0); 00180 00181 //===--------------------------------------------------------------------===// 00182 // Annotation creation on demand support... 00183 00184 // registerAnnotationFactory - This method is used to register a callback 00185 // function used to create an annotation on demand if it is needed by the 00186 // Annotable::getOrCreateAnnotation method. 00187 // 00188 static void registerAnnotationFactory(AnnotationID ID, Factory Func, 00189 void *ExtraData = 0); 00190 00191 // createAnnotation - Create an annotation of the specified ID for the 00192 // specified object, using a register annotation creation function. 00193 // 00194 static Annotation *createAnnotation(AnnotationID ID, const Annotable *Obj); 00195 }; 00196 00197 00198 00199 // getOrCreateAnnotation - Search through the annotation list, if there is 00200 // no annotation with the specified ID, then use the AnnotationManager to 00201 // create one. 00202 // 00203 inline Annotation *Annotable::getOrCreateAnnotation(AnnotationID ID) const { 00204 Annotation *A = getAnnotation(ID); // Fast path, check for preexisting ann 00205 if (A) return A; 00206 00207 // No annotation found, ask the annotation manager to create an annotation... 00208 A = AnnotationManager::createAnnotation(ID, this); 00209 assert(A && "AnnotationManager could not create annotation!"); 00210 addAnnotation(A); 00211 return A; 00212 } 00213 00214 } // End namespace llvm 00215 00216 #endif