LLVM API Documentation

Main Page | Namespace List | Class Hierarchy | Alphabetical List | Class List | Directories | File List | Namespace Members | Class Members | File Members | Related Pages

Annotation.h

Go to the documentation of this file.
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