1 //===-- llvm/Annotation.h - Annotation classes -------------------*- C++ -*--=//
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.
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.
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
15 //===----------------------------------------------------------------------===//
17 #ifndef LLVM_ANNOTATION_H
18 #define LLVM_ANNOTATION_H
24 class AnnotationManager;
26 //===----------------------------------------------------------------------===//
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.
33 friend class AnnotationManager;
36 AnnotationID(); // Default ctor is disabled
37 inline AnnotationID(unsigned i) : ID(i) {} // Only creatable from AnnMgr
39 inline AnnotationID(const AnnotationID &A) : ID(A.ID) {}
41 inline bool operator==(const AnnotationID &A) const {
44 inline bool operator<(const AnnotationID &A) const {
50 //===----------------------------------------------------------------------===//
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.
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
61 inline Annotation(AnnotationID id) : ID(id), Next(0) {}
62 virtual ~Annotation() {} // Designed to be subclassed
64 // getID - Return the unique ID# of this annotation
65 inline AnnotationID getID() const { return ID; }
67 // getNext - Return the next annotation in the list...
68 inline Annotation *getNext() const { return Next; }
72 //===----------------------------------------------------------------------===//
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.
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.
83 mutable Annotation *AnnotationList;
85 Annotable() : AnnotationList(0) {}
86 virtual ~Annotable() { // Virtual because it's designed to be subclassed...
87 Annotation *A = AnnotationList;
89 Annotation *Next = A->getNext();
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.
100 Annotation *getAnnotation(AnnotationID ID) const {
101 for (Annotation *A = AnnotationList; A; A = A->getNext())
102 if (A->getID() == ID) return A;
106 // getOrCreateAnnotation - Search through the annotation list, if there is
107 // no annotation with the specified ID, then use the AnnotationManager to
110 inline Annotation *getOrCreateAnnotation(AnnotationID ID) const;
112 // addAnnotation - Insert the annotation into the list in a sorted location.
114 void addAnnotation(Annotation *A) const {
115 assert(A->Next == 0 && "Annotation already in list?!?");
117 Annotation **AL = &AnnotationList;
118 while (*AL && (*AL)->ID < A->getID()) // Find where to insert annotation
120 A->Next = *AL; // Link the annotation in
124 // unlinkAnnotation - Remove the first annotation of the specified ID... and
125 // then return the unlinked annotation. The annotation object is not deleted.
127 inline Annotation *unlinkAnnotation(AnnotationID ID) const {
128 for (Annotation **A = &AnnotationList; *A; A = &((*A)->Next))
129 if ((*A)->getID() == ID) {
130 Annotation *Ret = *A;
138 // deleteAnnotation - Delete the first annotation of the specified ID in the
139 // list. Unlink unlinkAnnotation, this actually deletes the annotation object
141 bool deleteAnnotation(AnnotationID ID) const {
142 Annotation *A = unlinkAnnotation(ID);
149 //===----------------------------------------------------------------------===//
151 // AnnotationManager - This class is primarily responsible for maintaining a
152 // one-to-one mapping between string Annotation names and Annotation ID numbers.
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.
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
163 struct AnnotationManager {
164 typedef Annotation *(*Factory)(AnnotationID, const Annotable *, void*);
166 //===--------------------------------------------------------------------===//
167 // Basic ID <-> Name map functionality
169 static AnnotationID getID (const string &Name); // Name -> ID
170 static const string &getName(AnnotationID ID); // ID -> Name
172 // getID - Name -> ID + registration of a factory function for demand driven
173 // annotation support.
174 static AnnotationID getID (const string &Name, Factory Fact, void *Data=0);
176 //===--------------------------------------------------------------------===//
177 // Annotation creation on demand support...
179 // registerAnnotationFactory - This method is used to register a callback
180 // function used to create an annotation on demand if it is needed by the
181 // Annotable::getOrCreateAnnotation method.
183 static void registerAnnotationFactory(AnnotationID ID, Factory Func,
184 void *ExtraData = 0);
186 // createAnnotation - Create an annotation of the specified ID for the
187 // specified object, using a register annotation creation function.
189 static Annotation *createAnnotation(AnnotationID ID, const Annotable *Obj);
194 // getOrCreateAnnotation - Search through the annotation list, if there is
195 // no annotation with the specified ID, then use the AnnotationManager to
198 inline Annotation *Annotable::getOrCreateAnnotation(AnnotationID ID) const {
199 Annotation *A = getAnnotation(ID); // Fast path, check for preexisting ann
202 // No annotation found, ask the annotation manager to create an annotation...
203 A = AnnotationManager::createAnnotation(ID, this);
204 assert(A && "AnnotationManager could not create annotation!");