include/Support/Annotation.h

   1 //===-- llvm/Annotation.h - Annotation classes -------------------*- C++ -*--=//
   2 //
   3 // This file contains the declarations for two classes: Annotation & Annotable.
   4 // Using these two simple classes, anything that derives from Annotable can have
   5 // Annotation subclasses attached to them, ready for easy retrieval.
   6 //
   7 // Annotations are designed to be easily attachable to LLVM code (as all Value's
   8 // are Annotable), and can even be serialized to bytecode and to assembly.
   9 //
  10 // The AnnotationManager class (defined in AnnotationManager.h) is essential for
  11 // using these classes.  It is responsible for turning Annotation name strings
  12 // into tokens [unique id #'s] that may be used to search for and create
  13 // annotations.
  14 //
  15 //===----------------------------------------------------------------------===//
  16
  17 #ifndef LLVM_ANNOTATION_H
  18 #define LLVM_ANNOTATION_H
  19
  20 #include <string>
  21 class AnnotationID;
  22 class Annotation;
  23 class Annotable;
  24 class AnnotationManager;
  25
  26 //===----------------------------------------------------------------------===//
  27 //
  28 // AnnotationID - This class is a thin wrapper around an unsigned integer that
  29 // is used to hopefully prevent errors using AnnotationID's.  They may be copied
  30 // freely around and passed byvalue with little or no overhead.
  31 //
  32 class AnnotationID {
  33   friend class AnnotationManager;
  34   unsigned ID;
  35
  36   AnnotationID();                             // Default ctor is disabled
  37   inline AnnotationID(unsigned i) : ID(i) {}  // Only creatable from AnnMgr
  38 public:
  39   inline AnnotationID(const AnnotationID &A) : ID(A.ID) {}
  40
  41   inline bool operator==(const AnnotationID &A) const {
  42     return A.ID == ID;
  43   }
  44   inline bool operator<(const AnnotationID &A) const {
  45     return ID < A.ID;
  46   }
  47 };
  48
  49
  50 //===----------------------------------------------------------------------===//
  51 //
  52 // Annotation Class - This class serves as a base class for any specific
  53 // annotations that you might need.  Simply subclass this to add extra
  54 // information to the annotations.
  55 //
  56 class Annotation {
  57   friend class Annotable;  // Annotable manipulates Next list
  58   AnnotationID ID;         // ID number, as obtained from AnnotationManager
  59   Annotation *Next;        // The next annotation in the linked list
  60 public:
  61   inline Annotation(AnnotationID id) : ID(id), Next(0) {}
  62   virtual ~Annotation() {}  // Designed to be subclassed
  63
  64   // getID - Return the unique ID# of this annotation
  65   inline AnnotationID getID() const { return ID; }
  66
  67   // getNext - Return the next annotation in the list...
  68   inline Annotation *getNext() const { return Next; }
  69 };
  70
  71
  72 //===----------------------------------------------------------------------===//
  73 //
  74 // Annotable - This class is used as a base class for all objects that would
  75 // like to have annotation capability.  One notable subclass is Value, which
  76 // means annotations can be attached to almost everything in LLVM.
  77 //
  78 // Annotable objects keep their annotation list sorted as annotations are
  79 // inserted and deleted.  This is used to ensure that annotations with identical
  80 // ID#'s are stored sequentially.
  81 //
  82 class Annotable {
  83   Annotation *AnnotationList;
  84 public:
  85   Annotable() : AnnotationList(0) {}
  86   virtual ~Annotable() {   // Virtual because it's designed to be subclassed...
  87     Annotation *A = AnnotationList;
  88     while (A) {
  89       Annotation *Next = A->getNext();
  90       delete A;
  91       A = Next;
  92     }
  93   }
  94
  95   // getAnnotation - Search the list for annotations of the specified ID.  The
  96   // pointer returned is either null (if no annotations of the specified ID
  97   // exist), or it points to the first element of a potentially list of elements
  98   // with identical ID #'s.
  99   //
 100   Annotation *getAnnotation(AnnotationID ID) const {
 101     for (Annotation *A = AnnotationList; A; A = A->getNext())
 102       if (A->getID() == ID) return A;
 103     return 0;
 104   }
 105
 106   // getOrCreateAnnotation - Search through the annotation list, if there is
 107   // no annotation with the specified ID, then use the AnnotationManager to
 108   // create one.
 109   //
 110   inline Annotation *getOrCreateAnnotation(AnnotationID ID);
 111
 112   // addAnnotation - Insert the annotation into the list in a sorted location.
 113   //
 114   void addAnnotation(Annotation *A) {
 115     assert(A->Next == 0 && "Annotation already in list?!?");
 116
 117     Annotation **AL = &AnnotationList;
 118     while (*AL && (*AL)->ID < A->getID())  // Find where to insert annotation
 119       AL = &((*AL)->Next);
 120     A->Next = *AL;                         // Link the annotation in
 121     *AL = A;
 122   }
 123
 124   // unlinkAnnotation - Remove the first annotation of the specified ID... and
 125   // then return the unlinked annotation.  The annotation object is not deleted.
 126   //
 127   inline Annotation *unlinkAnnotation(AnnotationID ID) {
 128     for (Annotation **A = &AnnotationList; *A; A = &((*A)->Next))
 129       if ((*A)->getID() == ID) {
 130         Annotation *Ret = *A;
 131         *A = Ret->Next;
 132         Ret->Next = 0;
 133         return Ret;
 134       }
 135     return 0;
 136   }
 137
 138   // deleteAnnotation - Delete the first annotation of the specified ID in the
 139   // list.  Unlink unlinkAnnotation, this actually deletes the annotation object
 140   //
 141   bool deleteAnnotation(AnnotationID ID) {
 142     Annotation *A = unlinkAnnotation(ID);
 143     delete A;
 144     return A != 0;
 145   }
 146 };
 147
 148
 149 //===----------------------------------------------------------------------===//
 150 //
 151 // AnnotationManager - This class is primarily responsible for maintaining a
 152 // one-to-one mapping between string Annotation names and Annotation ID numbers.
 153 //
 154 // Compared to the rest of the Annotation system, these mapping methods are
 155 // relatively slow, so they should be avoided by locally caching Annotation
 156 // ID #'s.  These methods are safe to call at any time, even by static ctors, so
 157 // they should be used by static ctors most of the time.
 158 //
 159 // This class also provides support for annotations that are created on demand
 160 // by the Annotable::getOrCreateAnnotation method.  To get this to work, simply
 161 // register an annotation handler
 162 //
 163 struct AnnotationManager {
 164   //===--------------------------------------------------------------------===//
 165   // Basic ID <-> Name map functionality
 166
 167   static AnnotationID  getID  (const string &Name);  // Name -> ID
 168   static const string &getName(AnnotationID ID);     // ID -> Name
 169
 170
 171   //===--------------------------------------------------------------------===//
 172   // Annotation creation on demand support...
 173
 174   // registerAnnotationFactory - This method is used to register a callback
 175   // function used to create an annotation on demand if it is needed by the
 176   // Annotable::getOrCreateAnnotation method.
 177   //
 178   static void registerAnnotationFactory(AnnotationID ID,
 179                           Annotation *(*Func)(AnnotationID, Annotable *, void*),
 180                                         void *ExtraData = 0);
 181
 182   // createAnnotation - Create an annotation of the specified ID for the
 183   // specified object, using a register annotation creation function.
 184   //
 185   static Annotation *createAnnotation(AnnotationID ID, Annotable *Obj);
 186 };
 187
 188
 189
 190 // getOrCreateAnnotation - Search through the annotation list, if there is
 191 // no annotation with the specified ID, then use the AnnotationManager to
 192 // create one.
 193 //
 194 inline Annotation *Annotable::getOrCreateAnnotation(AnnotationID ID) {
 195   Annotation *A = getAnnotation(ID);   // Fast path, check for preexisting ann
 196   if (A) return A;
 197
 198   // No annotation found, ask the annotation manager to create an annotation...
 199   A = AnnotationManager::createAnnotation(ID, this);
 200   assert(A && "AnnotationManager could not create annotation!");
 201   addAnnotation(A);
 202   return A;
 203 }
 204
 205 #endif