From 1afcace3a3a138b1b18e5c6270caa8dae2261ae2 Mon Sep 17 00:00:00 2001 From: Chris Lattner Date: Sat, 9 Jul 2011 17:41:24 +0000 Subject: Land the long talked about "type system rewrite" patch. This patch brings numerous advantages to LLVM. One way to look at it is through diffstat: 109 files changed, 3005 insertions(+), 5906 deletions(-) Removing almost 3K lines of code is a good thing. Other advantages include: 1. Value::getType() is a simple load that can be CSE'd, not a mutating union-find operation. 2. Types a uniqued and never move once created, defining away PATypeHolder. 3. Structs can be "named" now, and their name is part of the identity that uniques them. This means that the compiler doesn't merge them structurally which makes the IR much less confusing. 4. Now that there is no way to get a cycle in a type graph without a named struct type, "upreferences" go away. 5. Type refinement is completely gone, which should make LTO much MUCH faster in some common cases with C++ code. 6. Types are now generally immutable, so we can use "Type *" instead "const Type *" everywhere. Downsides of this patch are that it removes some functions from the C API, so people using those will have to upgrade to (not yet added) new API. "LLVM 3.0" is the right time to do this. There are still some cleanups pending after this, this patch is large enough as-is. git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@134829 91177308-0d34-0410-b5e6-96231b3b80d8 --- docs/ProgrammersManual.html | 196 ++------------------------------------------ 1 file changed, 6 insertions(+), 190 deletions(-) (limited to 'docs/ProgrammersManual.html') diff --git a/docs/ProgrammersManual.html b/docs/ProgrammersManual.html index 49a76ee414..c1edd2a60a 100644 --- a/docs/ProgrammersManual.html +++ b/docs/ProgrammersManual.html @@ -160,15 +160,8 @@ with another Value
  • Advanced Topics
    • @@ -2645,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

    @@ -2820,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 @@ -2832,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.

    @@ -3128,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.
    • @@ -3192,14 +3016,6 @@ the lib/VMCore directory.

    number of formal parameters. -
    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.
    -- cgit v1.2.3