include/llvm/Support/Annotation.h

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