LLVM API Documentation

Metadata.h
Go to the documentation of this file.
00001 //===-- llvm/Metadata.h - Metadata definitions ------------------*- C++ -*-===//
00002 //
00003 //                     The LLVM Compiler Infrastructure
00004 //
00005 // This file is distributed under the University of Illinois Open Source
00006 // License. See LICENSE.TXT for details.
00007 //
00008 //===----------------------------------------------------------------------===//
00009 //
00010 /// @file
00011 /// This file contains the declarations for metadata subclasses.
00012 /// They represent the different flavors of metadata that live in LLVM.
00013 //
00014 //===----------------------------------------------------------------------===//
00015 
00016 #ifndef LLVM_IR_METADATA_H
00017 #define LLVM_IR_METADATA_H
00018 
00019 #include "llvm/ADT/ArrayRef.h"
00020 #include "llvm/ADT/FoldingSet.h"
00021 #include "llvm/ADT/ilist_node.h"
00022 #include "llvm/ADT/iterator_range.h"
00023 #include "llvm/IR/Value.h"
00024 
00025 namespace llvm {
00026 class LLVMContext;
00027 class Module;
00028 template<typename ValueSubClass, typename ItemParentClass>
00029   class SymbolTableListTraits;
00030 
00031 
00032 enum LLVMConstants : uint32_t {
00033   DEBUG_METADATA_VERSION = 1  // Current debug info version number.
00034 };
00035 
00036 //===----------------------------------------------------------------------===//
00037 /// MDString - a single uniqued string.
00038 /// These are used to efficiently contain a byte sequence for metadata.
00039 /// MDString is always unnamed.
00040 class MDString : public Value {
00041   virtual void anchor();
00042   MDString(const MDString &) LLVM_DELETED_FUNCTION;
00043 
00044   explicit MDString(LLVMContext &C);
00045 public:
00046   static MDString *get(LLVMContext &Context, StringRef Str);
00047   static MDString *get(LLVMContext &Context, const char *Str) {
00048     return get(Context, Str ? StringRef(Str) : StringRef());
00049   }
00050 
00051   StringRef getString() const { return getName(); }
00052 
00053   unsigned getLength() const { return (unsigned)getName().size(); }
00054 
00055   typedef StringRef::iterator iterator;
00056 
00057   /// begin() - Pointer to the first byte of the string.
00058   iterator begin() const { return getName().begin(); }
00059 
00060   /// end() - Pointer to one byte past the end of the string.
00061   iterator end() const { return getName().end(); }
00062 
00063   /// Methods for support type inquiry through isa, cast, and dyn_cast:
00064   static bool classof(const Value *V) {
00065     return V->getValueID() == MDStringVal;
00066   }
00067 };
00068 
00069 
00070 class MDNodeOperand;
00071 
00072 //===----------------------------------------------------------------------===//
00073 /// MDNode - a tuple of other values.
00074 class MDNode : public Value, public FoldingSetNode {
00075   MDNode(const MDNode &) LLVM_DELETED_FUNCTION;
00076   void operator=(const MDNode &) LLVM_DELETED_FUNCTION;
00077   friend class MDNodeOperand;
00078   friend class LLVMContextImpl;
00079   friend struct FoldingSetTrait<MDNode>;
00080 
00081   /// Hash - If the MDNode is uniqued cache the hash to speed up lookup.
00082   unsigned Hash;
00083 
00084   /// NumOperands - This many 'MDNodeOperand' items are co-allocated onto the
00085   /// end of this MDNode.
00086   unsigned NumOperands;
00087 
00088   // Subclass data enums.
00089   enum {
00090     /// FunctionLocalBit - This bit is set if this MDNode is function local.
00091     /// This is true when it (potentially transitively) contains a reference to
00092     /// something in a function, like an argument, basicblock, or instruction.
00093     FunctionLocalBit = 1 << 0,
00094 
00095     /// NotUniquedBit - This is set on MDNodes that are not uniqued because they
00096     /// have a null operand.
00097     NotUniquedBit    = 1 << 1,
00098 
00099     /// DestroyFlag - This bit is set by destroy() so the destructor can assert
00100     /// that the node isn't being destroyed with a plain 'delete'.
00101     DestroyFlag      = 1 << 2
00102   };
00103 
00104   // FunctionLocal enums.
00105   enum FunctionLocalness {
00106     FL_Unknown = -1,
00107     FL_No = 0,
00108     FL_Yes = 1
00109   };
00110 
00111   /// replaceOperand - Replace each instance of F from the operand list of this
00112   /// node with T.
00113   void replaceOperand(MDNodeOperand *Op, Value *NewVal);
00114   ~MDNode();
00115 
00116   MDNode(LLVMContext &C, ArrayRef<Value*> Vals, bool isFunctionLocal);
00117 
00118   static MDNode *getMDNode(LLVMContext &C, ArrayRef<Value*> Vals,
00119                            FunctionLocalness FL, bool Insert = true);
00120 public:
00121   // Constructors and destructors.
00122   static MDNode *get(LLVMContext &Context, ArrayRef<Value*> Vals);
00123   // getWhenValsUnresolved - Construct MDNode determining function-localness
00124   // from isFunctionLocal argument, not by analyzing Vals.
00125   static MDNode *getWhenValsUnresolved(LLVMContext &Context,
00126                                        ArrayRef<Value*> Vals,
00127                                        bool isFunctionLocal);
00128 
00129   static MDNode *getIfExists(LLVMContext &Context, ArrayRef<Value*> Vals);
00130 
00131   /// getTemporary - Return a temporary MDNode, for use in constructing
00132   /// cyclic MDNode structures. A temporary MDNode is not uniqued,
00133   /// may be RAUW'd, and must be manually deleted with deleteTemporary.
00134   static MDNode *getTemporary(LLVMContext &Context, ArrayRef<Value*> Vals);
00135 
00136   /// deleteTemporary - Deallocate a node created by getTemporary. The
00137   /// node must not have any users.
00138   static void deleteTemporary(MDNode *N);
00139 
00140   /// replaceOperandWith - Replace a specific operand.
00141   void replaceOperandWith(unsigned i, Value *NewVal);
00142 
00143   /// getOperand - Return specified operand.
00144   Value *getOperand(unsigned i) const LLVM_READONLY;
00145 
00146   /// getNumOperands - Return number of MDNode operands.
00147   unsigned getNumOperands() const { return NumOperands; }
00148 
00149   /// isFunctionLocal - Return whether MDNode is local to a function.
00150   bool isFunctionLocal() const {
00151     return (getSubclassDataFromValue() & FunctionLocalBit) != 0;
00152   }
00153 
00154   // getFunction - If this metadata is function-local and recursively has a
00155   // function-local operand, return the first such operand's parent function.
00156   // Otherwise, return null. getFunction() should not be used for performance-
00157   // critical code because it recursively visits all the MDNode's operands.
00158   const Function *getFunction() const;
00159 
00160   /// Profile - calculate a unique identifier for this MDNode to collapse
00161   /// duplicates
00162   void Profile(FoldingSetNodeID &ID) const;
00163 
00164   /// Methods for support type inquiry through isa, cast, and dyn_cast:
00165   static bool classof(const Value *V) {
00166     return V->getValueID() == MDNodeVal;
00167   }
00168 
00169   /// Check whether MDNode is a vtable access.
00170   bool isTBAAVtableAccess() const;
00171 
00172   /// Methods for metadata merging.
00173   static MDNode *getMostGenericTBAA(MDNode *A, MDNode *B);
00174   static MDNode *getMostGenericFPMath(MDNode *A, MDNode *B);
00175   static MDNode *getMostGenericRange(MDNode *A, MDNode *B);
00176 private:
00177   // destroy - Delete this node.  Only when there are no uses.
00178   void destroy();
00179 
00180   bool isNotUniqued() const {
00181     return (getSubclassDataFromValue() & NotUniquedBit) != 0;
00182   }
00183   void setIsNotUniqued();
00184 
00185   // Shadow Value::setValueSubclassData with a private forwarding method so that
00186   // any future subclasses cannot accidentally use it.
00187   void setValueSubclassData(unsigned short D) {
00188     Value::setValueSubclassData(D);
00189   }
00190 };
00191 
00192 //===----------------------------------------------------------------------===//
00193 /// NamedMDNode - a tuple of MDNodes. Despite its name, a NamedMDNode isn't
00194 /// itself an MDNode. NamedMDNodes belong to modules, have names, and contain
00195 /// lists of MDNodes.
00196 class NamedMDNode : public ilist_node<NamedMDNode> {
00197   friend class SymbolTableListTraits<NamedMDNode, Module>;
00198   friend struct ilist_traits<NamedMDNode>;
00199   friend class LLVMContextImpl;
00200   friend class Module;
00201   NamedMDNode(const NamedMDNode &) LLVM_DELETED_FUNCTION;
00202 
00203   std::string Name;
00204   Module *Parent;
00205   void *Operands; // SmallVector<TrackingVH<MDNode>, 4>
00206 
00207   void setParent(Module *M) { Parent = M; }
00208 
00209   explicit NamedMDNode(const Twine &N);
00210 
00211   template<class T1, class T2>
00212   class op_iterator_impl :
00213       public std::iterator<std::bidirectional_iterator_tag, T2> {
00214     const NamedMDNode *Node;
00215     unsigned Idx;
00216     op_iterator_impl(const NamedMDNode *N, unsigned i) : Node(N), Idx(i) { }
00217 
00218     friend class NamedMDNode;
00219 
00220   public:
00221     op_iterator_impl() : Node(nullptr), Idx(0) { }
00222 
00223     bool operator==(const op_iterator_impl &o) const { return Idx == o.Idx; }
00224     bool operator!=(const op_iterator_impl &o) const { return Idx != o.Idx; }
00225     op_iterator_impl &operator++() {
00226       ++Idx;
00227       return *this;
00228     }
00229     op_iterator_impl operator++(int) {
00230       op_iterator_impl tmp(*this);
00231       operator++();
00232       return tmp;
00233     }
00234     op_iterator_impl &operator--() {
00235       --Idx;
00236       return *this;
00237     }
00238     op_iterator_impl operator--(int) {
00239       op_iterator_impl tmp(*this);
00240       operator--();
00241       return tmp;
00242     }
00243 
00244     T1 operator*() const { return Node->getOperand(Idx); }
00245   };
00246 
00247 public:
00248   /// eraseFromParent - Drop all references and remove the node from parent
00249   /// module.
00250   void eraseFromParent();
00251 
00252   /// dropAllReferences - Remove all uses and clear node vector.
00253   void dropAllReferences();
00254 
00255   /// ~NamedMDNode - Destroy NamedMDNode.
00256   ~NamedMDNode();
00257 
00258   /// getParent - Get the module that holds this named metadata collection.
00259   inline Module *getParent() { return Parent; }
00260   inline const Module *getParent() const { return Parent; }
00261 
00262   /// getOperand - Return specified operand.
00263   MDNode *getOperand(unsigned i) const;
00264 
00265   /// getNumOperands - Return the number of NamedMDNode operands.
00266   unsigned getNumOperands() const;
00267 
00268   /// addOperand - Add metadata operand.
00269   void addOperand(MDNode *M);
00270 
00271   /// getName - Return a constant reference to this named metadata's name.
00272   StringRef getName() const;
00273 
00274   /// print - Implement operator<< on NamedMDNode.
00275   void print(raw_ostream &ROS, AssemblyAnnotationWriter *AAW = nullptr) const;
00276 
00277   /// dump() - Allow printing of NamedMDNodes from the debugger.
00278   void dump() const;
00279 
00280   // ---------------------------------------------------------------------------
00281   // Operand Iterator interface...
00282   //
00283   typedef op_iterator_impl<MDNode*, MDNode> op_iterator;
00284   op_iterator op_begin() { return op_iterator(this, 0); }
00285   op_iterator op_end()   { return op_iterator(this, getNumOperands()); }
00286 
00287   typedef op_iterator_impl<const MDNode*, MDNode> const_op_iterator;
00288   const_op_iterator op_begin() const { return const_op_iterator(this, 0); }
00289   const_op_iterator op_end()   const { return const_op_iterator(this, getNumOperands()); }
00290 
00291   inline iterator_range<op_iterator>  operands() {
00292     return iterator_range<op_iterator>(op_begin(), op_end());
00293   }
00294   inline iterator_range<const_op_iterator> operands() const {
00295     return iterator_range<const_op_iterator>(op_begin(), op_end());
00296   }
00297 };
00298 
00299 } // end llvm namespace
00300 
00301 #endif