include/llvm/Support/Annotation.h

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