From f1b200b0fbada93044770088b96b3750739e0d0d Mon Sep 17 00:00:00 2001 From: Chris Lattner Date: Sat, 23 Apr 2005 17:27:36 +0000 Subject: [PATCH] add a bunch of documentation about the LLVM type resolution machinery git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@21475 91177308-0d34-0410-b5e6-96231b3b80d8 --- docs/ProgrammersManual.html | 166 ++++++++++++++++++++++++++++++++++++ docs/index.html | 2 +- 2 files changed, 167 insertions(+), 1 deletion(-) diff --git a/docs/ProgrammersManual.html b/docs/ProgrammersManual.html index 78ec2716340..82b263845c6 100644 --- a/docs/ProgrammersManual.html +++ b/docs/ProgrammersManual.html @@ -85,6 +85,14 @@ with another Value
  • Advanced Topics
    • @@ -930,8 +938,165 @@ 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. +

    +
    + +
    + 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 bytecode reader, +assembly parser, and linker also have to be aware of the inner workings of this +system. +

    + +
    + + +
    + 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*, 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 +
    + +
    +

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

    + +
    + + +
    + 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. 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 {\em +abstract} types. Concrete types (those that do not include an opaque objects +somewhere) can never be refined. +

    @@ -939,6 +1104,7 @@ ReplaceInstWithValue, ReplaceInstWithInst -->
    The SymbolTable class
    +

    This class provides a symbol table that the Function and diff --git a/docs/index.html b/docs/index.html index a7d3d92141d..c670fbc7887 100644 --- a/docs/index.html +++ b/docs/index.html @@ -23,7 +23,7 @@
    - +