From: Chris Lattner Date: Sun, 23 May 2004 21:06:58 +0000 (+0000) Subject: Lots of minor cleanups and clarifications X-Git-Url: http://demsky.eecs.uci.edu/git/?a=commitdiff_plain;h=69bf8a9b80a6e6a064e631a55d5140027e659128;p=oota-llvm.git Lots of minor cleanups and clarifications git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@13674 91177308-0d34-0410-b5e6-96231b3b80d8 --- diff --git a/docs/ProgrammersManual.html b/docs/ProgrammersManual.html index 18b0571ae75..ec97e332f67 100644 --- a/docs/ProgrammersManual.html +++ b/docs/ProgrammersManual.html @@ -98,14 +98,6 @@ with another Value
  • The Module class
  • The Constant class - -
    • -
  • The Type class
  • The Argument class
    • @@ -117,15 +109,15 @@ with another Value
  • Creating, inserting, moving and deleting from LLVM lists
    • -
  • Important iterator invalidation semantics to be aware of
    • +
  • Important iterator invalidation semantics to be aware of.
    • -
    -

    Written by Chris Lattner, - Dinakar Dhurjati, and Joel Stanley

    +
    +

    Written by Chris Lattner, + Dinakar Dhurjati, and + Joel Stanley

    @@ -283,13 +275,14 @@ file (note that you very rarely have to include this file directly).

    that something is of the right type. An example of the isa<> and cast<> template is: - 
    static bool isLoopInvariant(const Value *V, const
-  Loop *L) {
     if (isa<Constant>(V) || isa<Argument>(V) || isa<GlobalValue>(V))
     return true;

     //
-  Otherwise, it must be an instruction...
     return
-  !L->contains(cast<Instruction>(V)->getParent());
    + 
    +  static bool isLoopInvariant(const Value *V, const Loop *L) {
+    if (isa<Constant>(V) || isa<Argument>(V) || isa<GlobalValue>(V))
+      return true;
+
+  // Otherwise, it must be an instruction...
+  return !L->contains(cast<Instruction>(V)->getParent());
+

    Note that you should not use an isa<> test followed by a cast<>, for that use the dyn_cast<> @@ -307,8 +300,11 @@ file (note that you very rarely have to include this file directly).

    same circumstances. Typically, the dyn_cast<> operator is used in an if statement or some other flow control statement like this: - 
     if (AllocationInst *AI = dyn_cast<AllocationInst>(Val)) {
     ...
     }
    + 
    +     if (AllocationInst *AI = dyn_cast<AllocationInst>(Val)) {
+       ...
+     }
+

    This form of the if statement effectively combines together a call to isa<> and a call to cast<> into one @@ -316,10 +312,12 @@ file (note that you very rarely have to include this file directly).

    Another common example is:

    - 
     // Loop over all of the phi nodes in a basic block
    
-   BasicBlock::iterator BBI = BB->begin();
     for (; PHINode *PN = dyn_cast<PHINode>(BBI); ++BBI)
     cerr << *PN;
    + 
    +     // Loop over all of the phi nodes in a basic block
+     BasicBlock::iterator BBI = BB->begin();
+     for (; PHINode *PN = dyn_cast<PHINode>(BBI); ++BBI)
+       std::cerr << *PN;
+

    Note that the dyn_cast<> operator, like C++'s dynamic_cast or Java's instanceof operator, can be abused. @@ -525,7 +523,7 @@ structures are traversed in very similar ways.

    -
    +
    Iterating over the BasicBlocks in a Function @@ -551,7 +549,7 @@ exactly equivalent to (*i).size() just like you'd expect.

    -
    +
    Iterating over the Instructions in a BasicBlock @@ -580,7 +578,7 @@ now, you must cast to void*.

    -
    +
    Iterating over the Instructions in a Function @@ -593,11 +591,9 @@ now, you must cast to void*.

    InstIterator should be used instead. You'll need to include llvm/Support/InstIterator.h, and then instantiate InstIterators explicitly in your code. Here's a -small example that shows how to dump all instructions in a function to stderr -(Note: Dereferencing an InstIterator yields an -Instruction*, not an Instruction&!):

    +small example that shows how to dump all instructions in a function to the standard error stream:

    - 

    #include "llvm/Support/InstIterator.h"
    ...
    // Suppose F is a ptr to a function
    for (inst_iterator i = inst_begin(F), e = inst_end(F); i != e; ++i)
      cerr << **i << "\n";
    + 
    #include "llvm/Support/InstIterator.h"
    ...
    // Suppose F is a ptr to a function
    for (inst_iterator i = inst_begin(F), e = inst_end(F); i != e; ++i)
      cerr << *i << "\n";
    Easy, isn't it? You can also use InstIterators to fill a worklist with its initial contents. For example, if you wanted to initialize a worklist to contain all instructions in a Function @@ -619,7 +615,7 @@ F, all you would need to do is something like:

    Sometimes, it'll be useful to grab a reference (or pointer) to a class instance when all you've got at hand is an iterator. Well, extracting -a reference or a pointer from an iterator is very straightforward. +a reference or a pointer from an iterator is very straight-forward. Assuming that i is a BasicBlock::iterator and j is a BasicBlock::const_iterator:

    @@ -639,17 +635,14 @@ the last line of the last example,

    Instruction* pinst = i;
    -

    It's also possible to turn a class pointer into the corresponding iterator. -Usually, this conversion is quite inexpensive. The following code snippet -illustrates use of the conversion constructors provided by LLVM iterators. By -using these, you can explicitly grab the iterator of something without actually -obtaining it via iteration over some structure:

    +

    It's also possible to turn a class pointer into the corresponding iterator, +and this is a constant time operation (very efficient). The following code +snippet illustrates use of the conversion constructors provided by LLVM +iterators. By using these, you can explicitly grab the iterator of something +without actually obtaining it via iteration over some structure:

    void printNextInstruction(Instruction* inst) {
        BasicBlock::iterator it(inst);
        ++it; // after this line, it refers to the instruction after *inst.
        if (it != inst->getParent()->end()) cerr << *it << "\n";
    }
    -

    Of course, this example is strictly pedagogical, because it'd be much -better to explicitly grab the next instruction directly from inst.

    -
    @@ -664,7 +657,7 @@ better to explicitly grab the next instruction directly from inst.

    locations in the entire module (that is, across every Function) where a certain function (i.e., some Function*) is already in scope. As you'll learn later, you may want to use an InstVisitor to accomplish this in a -much more straightforward manner, but this example will allow us to explore how +much more straight-forward manner, but this example will allow us to explore how you'd do it if you didn't have InstVisitor around. In pseudocode, this is what we want to do:

    @@ -694,17 +687,16 @@ this, and in other situations, you may find that you want to treat most-specific common base class is Instruction, which includes lots of less closely-related things. For these cases, LLVM provides a handy wrapper class called CallSite -. It is essentially a wrapper around an Instruction pointer, -with some methods that provide functionality common to CallInsts and +href="http://llvm.cs.uiuc.edu/doxygen/classCallSite.html">CallSite. +It is essentially a wrapper around an Instruction pointer, with some +methods that provide functionality common to CallInsts and InvokeInsts.

    -

    This class is supposed to have "value semantics". So it should be passed by -value, not by reference; it should not be dynamically allocated or deallocated -using operator new or operator delete. It is efficiently -copyable, assignable and constructable, with costs equivalents to that of a bare -pointer. (You will notice, if you look at its definition, that it has only a -single data member.)

    +

    This class has "value semantics": it should be passed by value, not by +reference and it should not be dynamically allocated or deallocated using +operator new or operator delete. It is efficiently copyable, +assignable and constructable, with costs equivalents to that of a bare pointer. +If you look at its definition, it has only a single pointer member.

    @@ -767,7 +759,7 @@ and gives example code.

    Instantiating Instructions

    -

    Creation of Instructions is straightforward: simply call the +

    Creation of Instructions is straight-forward: simply call the constructor for the kind of instruction to instantiate and provide the necessary parameters. For example, an AllocaInst only requires a (const-ptr-to) Type. Thus:

    @@ -851,7 +843,7 @@ instructions and adding them to BasicBlocks.

    Deleting an instruction from an existing sequence of instructions that form a -BasicBlock is very straightforward. First, +BasicBlock is very straight-forward. First, you must have a pointer to the instruction that you wish to delete. Second, you need to obtain the pointer to that instruction's basic block. You use the pointer to the basic block to get its list of instructions and then use the @@ -1726,9 +1718,6 @@ types.

      -
    • PrimitiveID getPrimitiveID() const: Returns the base type of the - type.
      • -
    • bool isSigned() const: Returns whether an integral numeric type is signed. This is true for SByteTy, ShortTy, IntTy, LongTy. Note that this is not true for Float and Double.
      • @@ -1747,29 +1736,11 @@ types.

    • bool isFloatingPoint(): Return true if this is one of the two floating point types.
      • -
    • bool isRecursive() const: Returns rue if the type graph contains - a cycle.
      • -
    • isLosslesslyConvertableTo (const Type *Ty) const: Return true if this type can be converted to 'Ty' without any reinterpretation of bits. For - example, uint to int.
      • - -
    • bool isPrimitiveType() const: Returns true if it is a primitive - type.
      • - -
    • bool isDerivedType() const: Returns true if it is a derived - type.
      • + example, uint to int or one pointer type to another. -
    • const Type * getContainedType (unsigned i) const: This method is - used to implement the type iterator. For derived types, this returns the types - 'contained' in the derived type, returning 0 when 'i' becomes invalid. This - allows the user to iterate over the types in a struct, for example, really - easily.
      • - -
    • unsigned getNumContainedTypes() const: Return the number of types - in the derived type. - -
      +

      Derived Types