X-Git-Url: http://demsky.eecs.uci.edu/git/?a=blobdiff_plain;f=docs%2FProgrammersManual.html;h=464618aa37af24cfbb5acb942c15427290c6a729;hb=ca6aa2f70ca1325d8cc4af3d6a7d99ab693e5456;hp=eb3bde98a8bef86e9b88a7507226fcd67af46487;hpb=53f72b3bab0e8b474f6ded9ee46957fd89d01cda;p=oota-llvm.git diff --git a/docs/ProgrammersManual.html b/docs/ProgrammersManual.html index eb3bde98a8b..464618aa37a 100644 --- a/docs/ProgrammersManual.html +++ b/docs/ProgrammersManual.html @@ -82,6 +82,20 @@ with another Value --> + +
The "Support/Debug.h" +
The "llvm/Support/Debug.h" file provides a macro named DEBUG() that is a much nicer solution to this problem. Basically, you can put arbitrary code into the argument of the DEBUG macro, and it is only executed if 'opt' (or any other @@ -400,7 +407,7 @@ program hasn't been started yet, you can always just run it with
Of course, in practice, you should only set DEBUG_TYPE at the top of a file, to specify the debug type for the entire module (if you do this before -you #include "Support/Debug.h", you don't have to insert the ugly +you #include "llvm/Support/Debug.h", you don't have to insert the ugly #undef's). Also, you should use names more meaningful than "foo" and "bar", because there is no system in place to ensure that names do not conflict. If two different modules use the same string, they will all be turned @@ -439,7 +446,7 @@ even if the source lives in multiple files.
The "Support/Statistic.h" file +href="/doxygen/Statistic_8h-source.html">llvm/ADT/Statistic.h" file provides a template named Statistic that is used as a unified way to keep track of what the LLVM compiler is doing and how effective various optimizations are. It is useful to see what optimizations are contributing to @@ -924,6 +931,408 @@ ReplaceInstWithValue, ReplaceInstWithInst -->
+This section describes some of the advanced or obscure API's that most clients +do not need to be aware of. These API's tend manage the inner workings of the +LLVM system, and only need to be accessed in unusual circumstances. +
++The LLVM type system has a very simple goal: allow clients to compare types for +structural equality with a simple pointer comparison (aka a shallow compare). +This goal makes clients much simpler and faster, and is used throughout the LLVM +system. +
+ ++Unfortunately achieving this goal is not a simple matter. In particular, +recursive types and late resolution of opaque types makes the situation very +difficult to handle. Fortunately, for the most part, our implementation makes +most clients able to be completely unaware of the nasty internal details. The +primary case where clients are exposed to the inner workings of it are when +building a recursive type. In addition to this case, the LLVM bytecode reader, +assembly parser, and linker also have to be aware of the inner workings of this +system. +
+ ++For our purposes below, we need three concepts. First, an "Opaque Type" is +exactly as defined in the language +reference. Second an "Abstract Type" is any type which includes an +opaque type as part of its type graph (for example "{ opaque, int }"). +Third, a concrete type is a type that is not an abstract type (e.g. "[ int, +float }"). +
+ ++Because the most common question is "how do I build a recursive type with LLVM", +we answer it now and explain it as we go. Here we include enough to cause this +to be emitted to an output .ll file: +
+ ++ %mylist = type { %mylist*, int } ++ +
+To build this, use the following LLVM APIs: +
+ ++ // Create the initial outer struct. + PATypeHolder StructTy = OpaqueType::get(); + std::vector<const Type*> Elts; + Elts.push_back(PointerType::get(StructTy)); + Elts.push_back(Type::IntTy); + StructType *NewSTy = StructType::get(Elts); + + // At this point, NewSTy = "{ opaque*, int }". Tell VMCore that + // the struct and the opaque type are actually the same. + cast<OpaqueType>(StructTy.get())->refineAbstractTypeTo(NewSTy); + + // NewSTy is potentially invalidated, but StructTy (a PATypeHolder) is + // kept up-to-date. + NewSTy = cast<StructType>(StructTy.get()); + + // Add a name for the type to the module symbol table (optional). + MyModule->addTypeName("mylist", NewSTy); ++ +
+This code shows the basic approach used to build recursive types: build a +non-recursive type using 'opaque', then use type unification to close the cycle. +The type unification step is performed by the refineAbstractTypeTo method, which is +described next. After that, we describe the PATypeHolder class. +
+ ++The refineAbstractTypeTo method starts the type unification process. +While this method is actually a member of the DerivedType class, it is most +often used on OpaqueType instances. Type unification is actually a recursive +process. After unification, types can become structurally isomorphic to +existing types, and all duplicates are deleted (to preserve pointer equality). +
+ ++In the example above, the OpaqueType object is definitely deleted. +Additionally, if there is an "{ \2*, int}" type already created in the system, +the pointer and struct type created are also deleted. Obviously whenever +a type is deleted, any "Type*" pointers in the program are invalidated. As +such, it is safest to avoid having any "Type*" pointers to abstract types +live across a call to refineAbstractTypeTo (note that non-abstract +types can never move or be deleted). To deal with this, the PATypeHolder class is used to maintain a stable +reference to a possibly refined type, and the AbstractTypeUser class is used to update more +complex datastructures. +
+ ++PATypeHolder is a form of a "smart pointer" for Type objects. When VMCore +happily goes about nuking types that become isomorphic to existing types, it +automatically updates all PATypeHolder objects to point to the new type. In the +example above, this allows the code to maintain a pointer to the resultant +resolved recursive type, even though the Type*'s are potentially invalidated. +
+ ++PATypeHolder is an extremely light-weight object that uses a lazy union-find +implementation to update pointers. For example the pointer from a Value to its +Type is maintained by PATypeHolder objects. +
+ ++Some data structures need more to perform more complex updates when types get +resolved. The SymbolTable class, for example, needs +move and potentially merge type planes in its representation when a pointer +changes.
+ ++To support this, a class can derive from the AbstractTypeUser class. This class +allows it to get callbacks when certain types are resolved. To register to get +callbacks for a particular type, the DerivedType::{add/remove}AbstractTypeUser +methods can be called on a type. Note that these methods only work for +abstract types. Concrete types (those that do not include an opaque objects +somewhere) can never be refined. +
+This class provides a symbol table that the Function and +Module classes use for naming definitions. The symbol table can +provide a name for any Value or Type. SymbolTable is an abstract data +type. It hides the data it contains and provides access to it through a +controlled interface.
+ +Note that the symbol table class is should not be directly accessed by most +clients. It should only be used when iteration over the symbol table names +themselves are required, which is very special purpose. Note that not all LLVM +Values have names, and those without names (i.e. they have +an empty name) do not exist in the symbol table. +
+ +To use the SymbolTable well, you need to understand the +structure of the information it holds. The class contains two +std::map objects. The first, pmap, is a map of +Type* to maps of name (std::string) to Value*. +The second, tmap, is a map of names to Type*. Thus, Values +are stored in two-dimensions and accessed by Type and name. Types, +however, are stored in a single dimension and accessed only by name.
+ +The interface of this class provides three basic types of operations: +
The following functions describe three types of iterators you can obtain +the beginning or end of the sequence for both const and non-const. It is +important to keep track of the different kinds of iterators. There are +three idioms worth pointing out:
+Units | Iterator | Idiom |
---|---|---|
Planes Of name/Value maps | PI | ++for (SymbolTable::plane_const_iterator PI = ST.plane_begin(), + PE = ST.plane_end(); PI != PE; ++PI ) { + PI->first // This is the Type* of the plane + PI->second // This is the SymbolTable::ValueMap of name/Value pairs + |
+
All name/Type Pairs | TI | ++for (SymbolTable::type_const_iterator TI = ST.type_begin(), + TE = ST.type_end(); TI != TE; ++TI ) + TI->first // This is the name of the type + TI->second // This is the Type* value associated with the name + |
+
name/Value pairs in a plane | VI | ++for (SymbolTable::value_const_iterator VI = ST.value_begin(SomeType), + VE = ST.value_end(SomeType); VI != VE; ++VI ) + VI->first // This is the name of the Value + VI->second // This is the Value* value associated with the name + |
+
Using the recommended iterator names and idioms will help you avoid +making mistakes. Of particular note, make sure that whenever you use +value_begin(SomeType) that you always compare the resulting iterator +with value_end(SomeType) not value_end(SomeOtherType) or else you +will loop infinitely.
+ +This class provides a symbol table that the -Function and -Module classes use for naming definitions. The symbol table can -provide a name for any Value or -Type. SymbolTable is an abstract data -type. It hides the data it contains and provides access to it through a -controlled interface.
- -To use the SymbolTable well, you need to understand the -structure of the information it holds. The class contains two -std::map objects. The first, pmap, is a map of -Type* to maps of name (std::string) to Value*. -The second, tmap, is a map of names to Type*. Thus, Values -are stored in two-dimensions and accessed by Type and name. Types, -however, are stored in a single dimension and accessed only by name.
- -The interface of this class provides three basic types of operations: -
The following functions describe three types of iterators you can obtain -the beginning or end of the sequence for both const and non-const. It is -important to keep track of the different kinds of iterators. There are -three idioms worth pointing out:
-Units | Iterator | Idiom |
---|---|---|
Planes Of name/Value maps | PI | --for (SymbolTable::plane_const_iterator PI = ST.plane_begin(), - PE = ST.plane_end(); PI != PE; ++PI ) { - PI->first // This is the Type* of the plane - PI->second // This is the SymbolTable::ValueMap of name/Value pairs - |
-
All name/Type Pairs | TI | --for (SymbolTable::type_const_iterator TI = ST.type_begin(), - TE = ST.type_end(); TI != TE; ++TI ) - TI->first // This is the name of the type - TI->second // This is the Type* value associated with the name - |
-
name/Value pairs in a plane | VI | --for (SymbolTable::value_const_iterator VI = ST.value_begin(SomeType), - VE = ST.value_end(SomeType); VI != VE; ++VI ) - VI->first // This is the name of the Value - VI->second // This is the Value* value associated with the name - |
-
Using the recommended iterator names and idioms will help you avoid -making mistakes. Of particular note, make sure that whenever you use -value_begin(SomeType) that you always compare the resulting iterator -with value_end(SomeType) not value_end(SomeOtherType) or else you -will loop infinitely.
- -