include/llvm/Support/Annotation.h

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