1 //===-- llvm/Support/Annotation.h - Annotation classes ----------*- C++ -*-===//
3 // The LLVM Compiler Infrastructure
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
8 //===----------------------------------------------------------------------===//
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.
14 // Annotations are designed to be easily attachable to various classes.
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.
20 //===----------------------------------------------------------------------===//
22 #ifndef LLVM_SUPPORT_ANNOTATION_H
23 #define LLVM_SUPPORT_ANNOTATION_H
32 struct AnnotationManager;
34 //===----------------------------------------------------------------------===//
36 // AnnotationID - This class is a thin wrapper around an unsigned integer that
37 // is used to hopefully prevent errors using AnnotationID's. They may be copied
38 // freely around and passed byvalue with little or no overhead.
41 friend struct AnnotationManager;
44 AnnotationID(); // Default ctor is disabled
46 // AnnotationID is only creatable from AnnMgr.
47 explicit inline AnnotationID(unsigned i) : ID(i) {}
49 inline AnnotationID(const AnnotationID &A) : ID(A.ID) {}
51 inline bool operator==(const AnnotationID &A) const {
54 inline bool operator<(const AnnotationID &A) const {
60 //===----------------------------------------------------------------------===//
62 // Annotation Class - This class serves as a base class for any specific
63 // annotations that you might need. Simply subclass this to add extra
64 // information to the annotations.
67 friend class Annotable; // Annotable manipulates Next list
68 AnnotationID ID; // ID number, as obtained from AnnotationManager
69 Annotation *Next; // The next annotation in the linked list
71 explicit inline Annotation(AnnotationID id) : ID(id), Next(0) {}
72 virtual ~Annotation(); // Designed to be subclassed
74 // getID - Return the unique ID# of this annotation
75 inline AnnotationID getID() const { return ID; }
77 // getNext - Return the next annotation in the list...
78 inline Annotation *getNext() const { return Next; }
82 //===----------------------------------------------------------------------===//
84 // Annotable - This class is used as a base class for all objects that would
85 // like to have annotation capability.
87 // Annotable objects keep their annotation list sorted as annotations are
88 // inserted and deleted. This is used to ensure that annotations with identical
89 // ID#'s are stored sequentially.
92 mutable Annotation *AnnotationList;
94 Annotable(const Annotable &); // Do not implement
95 void operator=(const Annotable &); // Do not implement
97 Annotable() : AnnotationList(0) {}
100 // getAnnotation - Search the list for annotations of the specified ID. The
101 // pointer returned is either null (if no annotations of the specified ID
102 // exist), or it points to the first element of a potentially list of elements
103 // with identical ID #'s.
105 Annotation *getAnnotation(AnnotationID ID) const {
106 for (Annotation *A = AnnotationList; A; A = A->getNext())
107 if (A->getID() == ID) return A;
111 // getOrCreateAnnotation - Search through the annotation list, if there is
112 // no annotation with the specified ID, then use the AnnotationManager to
115 inline Annotation *getOrCreateAnnotation(AnnotationID ID) const;
117 // addAnnotation - Insert the annotation into the list in a sorted location.
119 void addAnnotation(Annotation *A) const {
120 assert(A->Next == 0 && "Annotation already in list?!?");
122 Annotation **AL = &AnnotationList;
123 while (*AL && (*AL)->ID < A->getID()) // Find where to insert annotation
125 A->Next = *AL; // Link the annotation in
129 // unlinkAnnotation - Remove the first annotation of the specified ID... and
130 // then return the unlinked annotation. The annotation object is not deleted.
132 inline Annotation *unlinkAnnotation(AnnotationID ID) const {
133 for (Annotation **A = &AnnotationList; *A; A = &((*A)->Next))
134 if ((*A)->getID() == ID) {
135 Annotation *Ret = *A;
143 // deleteAnnotation - Delete the first annotation of the specified ID in the
144 // list. Unlink unlinkAnnotation, this actually deletes the annotation object
146 bool deleteAnnotation(AnnotationID ID) const {
147 Annotation *A = unlinkAnnotation(ID);
154 //===----------------------------------------------------------------------===//
156 // AnnotationManager - This class is primarily responsible for maintaining a
157 // one-to-one mapping between string Annotation names and Annotation ID numbers.
159 // Compared to the rest of the Annotation system, these mapping methods are
160 // relatively slow, so they should be avoided by locally caching Annotation
161 // ID #'s. These methods are safe to call at any time, even by static ctors, so
162 // they should be used by static ctors most of the time.
164 // This class also provides support for annotations that are created on demand
165 // by the Annotable::getOrCreateAnnotation method. To get this to work, simply
166 // register an annotation handler
168 struct AnnotationManager {
169 typedef Annotation *(*Factory)(AnnotationID, const Annotable *, void*);
171 //===--------------------------------------------------------------------===//
172 // Basic ID <-> Name map functionality
174 static AnnotationID getID(const char *Name); // Name -> ID
175 static const char *getName(AnnotationID ID); // ID -> Name
177 // getID - Name -> ID + registration of a factory function for demand driven
178 // annotation support.
179 static AnnotationID getID(const char *Name, Factory Fact, void *Data = 0);
181 //===--------------------------------------------------------------------===//
182 // Annotation creation on demand support...
184 // registerAnnotationFactory - This method is used to register a callback
185 // function used to create an annotation on demand if it is needed by the
186 // Annotable::getOrCreateAnnotation method.
188 static void registerAnnotationFactory(AnnotationID ID, Factory Func,
189 void *ExtraData = 0);
191 // createAnnotation - Create an annotation of the specified ID for the
192 // specified object, using a register annotation creation function.
194 static Annotation *createAnnotation(AnnotationID ID, const Annotable *Obj);
199 // getOrCreateAnnotation - Search through the annotation list, if there is
200 // no annotation with the specified ID, then use the AnnotationManager to
203 inline Annotation *Annotable::getOrCreateAnnotation(AnnotationID ID) const {
204 Annotation *A = getAnnotation(ID); // Fast path, check for preexisting ann
207 // No annotation found, ask the annotation manager to create an annotation...
208 A = AnnotationManager::createAnnotation(ID, this);
209 assert(A && "AnnotationManager could not create annotation!");
214 } // End namespace llvm