From 1176aa52646fe641a4243a246aa7f960c708a274 Mon Sep 17 00:00:00 2001 From: dim Date: Sun, 17 Jul 2011 15:36:56 +0000 Subject: Vendor import of llvm trunk r135360: http://llvm.org/svn/llvm-project/llvm/trunk@135360 --- docs/ProgrammersManual.html | 243 ++++++++++---------------------------------- 1 file changed, 51 insertions(+), 192 deletions(-) (limited to 'docs/ProgrammersManual.html') diff --git a/docs/ProgrammersManual.html b/docs/ProgrammersManual.html index 6af922b..ed43f1f 100644 --- a/docs/ProgrammersManual.html +++ b/docs/ProgrammersManual.html @@ -64,6 +64,7 @@ option
  • <deque>
  • <list>
  • llvm/ADT/ilist.h
    • +
  • llvm/ADT/PackedVector.h
  • Other Sequential Container Options
  • Set-Like Containers (std::set, SmallSet, SetVector, etc) @@ -159,15 +160,8 @@ with another Value
  • Advanced Topics
    • @@ -811,6 +805,10 @@ found at Graph Attributes.) If you want to restart and clear all the current graph attributes, then you can call DAG.clearGraphAttrs().

    +

    Note that graph visualization features are compiled out of Release builds +to reduce file size. This means that you need a Debug+Asserts or +Release+Asserts build to use these features.

    + @@ -1065,6 +1063,44 @@ Related classes of interest are explained in the following subsections:

    + llvm/ADT/PackedVector.h +

    + +
    +

    +Useful for storing a vector of values using only a few number of bits for each +value. Apart from the standard operations of a vector-like container, it can +also perform an 'or' set operation. +

    + +

    For example:

    + +
    +
    +enum State {
+    None = 0x0,
+    FirstCondition = 0x1,
+    SecondCondition = 0x2,
+    Both = 0x3
+};
+
+State get() {
+    PackedVector<State, 2> Vec1;
+    Vec1.push_back(FirstCondition);
+
+    PackedVector<State, 2> Vec2;
+    Vec2.push_back(SecondCondition);
+
+    Vec1 |= Vec2;
+    return Vec1[0]; // returns 'Both'.
+}
+
    +
    + +
    + + +

    ilist_traits

    @@ -2602,173 +2638,10 @@ 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.

    +

    - LLVM Type Resolution -

    - -
    - -

    -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 bitcode 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, i32 }"). -Third, a concrete type is a type that is not an abstract type (e.g. "{ i32, -float }"). -

    - - -

    - Basic Recursive Type Construction -

    - -
    - -

    -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*, i32 }
-
    -
    - -

    -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::getUnqual(StructTy));
-Elts.push_back(Type::Int32Ty);
-StructType *NewSTy = StructType::get(Elts);
-
-// At this point, NewSTy = "{ opaque*, i32 }". 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 -

    - -
    -

    -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*, i32}" 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. -

    - -
    - - -

    - The PATypeHolder Class -

    - -
    -

    -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. -

    - -
    - - -

    - The AbstractTypeUser Class -

    - -
    - -

    -Some data structures need more to perform more complex updates when types get -resolved. 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 any opaque -objects) can never be refined. -

    -
    - -
    - - -

    - The ValueSymbolTable and - TypeSymbolTable classes + The ValueSymbolTable class

    @@ -2777,9 +2650,7 @@ ValueSymbolTable class provides a symbol table that the Function and Module classes use for naming value definitions. The symbol table can provide a name for any Value. -The -TypeSymbolTable class is used by the Module class to store -names for types.

    +

    Note that the SymbolTable class should not be directly accessed by most clients. It should only be used when iteration over the symbol table @@ -2789,13 +2660,12 @@ all LLVM an empty name) do not exist in the symbol table.

    -

    These symbol tables support iteration over the values/types in the symbol +

    Symbol tables support iteration over the values in the symbol table with begin/end/iterator and supports querying to see if a specific name is in the symbol table (with lookup). The ValueSymbolTable class exposes no public mutator methods, instead, simply call setName on a value, which will autoinsert it into the -appropriate symbol table. For types, use the Module::addTypeName method to -insert entries into the symbol table.

    +appropriate symbol table.

    @@ -3085,9 +2955,6 @@ the lib/VMCore directory.

  • bool isFloatingPointTy(): Return true if this is one of the five floating point types.
    • -
  • bool isAbstract(): Return true if the type is abstract (contains - an OpaqueType anywhere in its definition).
    • -
  • bool isSized(): Return true if the type has known size. Things that don't have a size are abstract types, labels and void.
    • @@ -3112,7 +2979,7 @@ the lib/VMCore directory.

    SequentialType
    -
    This is subclassed by ArrayType and PointerType +
    This is subclassed by ArrayType, PointerType and VectorType.
    -
    OpaqueType
    -
    Sublcass of DerivedType for abstract types. This class - defines no content and is used as a placeholder for some other type. Note - that OpaqueType is used (temporarily) during type resolution for forward - references of types. Once the referenced type is resolved, the OpaqueType - is replaced with the actual type. OpaqueType can also be used for data - abstraction. At link time opaque types can be resolved to actual types - of the same name.
    @@ -4008,7 +3867,7 @@ arguments. An argument has a pointer to the parent Function.

    Dinakar Dhurjati and Chris Lattner
    The LLVM Compiler Infrastructure
    - Last modified: $Date: 2011-04-23 02:30:22 +0200 (Sat, 23 Apr 2011) $ + Last modified: $Date: 2011-07-12 13:37:02 +0200 (Tue, 12 Jul 2011) $ -- cgit v1.1