diff --git a/docs/ProgrammersManual.html b/docs/ProgrammersManual.html index eb3bde98a8b..78ec2716340 100644 --- a/docs/ProgrammersManual.html +++ b/docs/ProgrammersManual.html @@ -82,6 +82,12 @@ with another Value --> + +
  • Advanced Topics +
    • +
  • The Core LLVM Class Hierarchy Reference
    • -
  • The SymbolTable class
    • -
  • The ilist and iplist classes - -
    • -
  • Important iterator invalidation semantics to be aware of.
    • @@ -924,6 +923,241 @@ ReplaceInstWithValue, ReplaceInstWithInst -->
    + +
    + Advanced Topics +
    + + +
    + + +
    + + + +
    + The SymbolTable class +
    +
    +

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

      +
    1. Accessors. Accessors provide read-only access to information + such as finding a value for a name with the + lookup method.
      2. +
    2. Mutators. Mutators allow the user to add information to the + SymbolTable with methods like + insert.
      3. +
    3. Iterators. Iterators allow the user to traverse the content + of the symbol table in well defined ways, such as the method + type_begin.
      4. +
    + +

    Accessors

    +
    +
    Value* lookup(const Type* Ty, const std::string& name) const: +
    +
    The lookup method searches the type plane given by the + Ty parameter for a Value with the provided name. + If a suitable Value is not found, null is returned.
    + +
    Type* lookupType( const std::string& name) const:
    +
    The lookupType method searches through the types for a + Type with the provided name. If a suitable Type + is not found, null is returned.
    + +
    bool hasTypes() const:
    +
    This function returns true if an entry has been made into the type + map.
    + +
    bool isEmpty() const:
    +
    This function returns true if both the value and types maps are + empty
    +
    + +

    Mutators

    +
    +
    void insert(Value *Val):
    +
    This method adds the provided value to the symbol table. The Value must + have both a name and a type which are extracted and used to place the value + in the correct type plane under the value's name.
    + +
    void insert(const std::string& Name, Value *Val):
    +
    Inserts a constant or type into the symbol table with the specified + name. There can be a many to one mapping between names and constants + or types.
    + +
    void insert(const std::string& Name, Type *Typ):
    +
    Inserts a type into the symbol table with the specified name. There + can be a many-to-one mapping between names and types. This method + allows a type with an existing entry in the symbol table to get + a new name.
    + +
    void remove(Value* Val):
    +
    This method removes a named value from the symbol table. The + type and name of the Value are extracted from \p N and used to + lookup the Value in the correct type plane. If the Value is + not in the symbol table, this method silently ignores the + request.
    + +
    void remove(Type* Typ):
    +
    This method removes a named type from the symbol table. The + name of the type is extracted from \P T and used to look up + the Type in the type map. If the Type is not in the symbol + table, this method silently ignores the request.
    + +
    Value* remove(const std::string& Name, Value *Val):
    +
    Remove a constant or type with the specified name from the + symbol table.
    + +
    Type* remove(const std::string& Name, Type* T):
    +
    Remove a type with the specified name from the symbol table. + Returns the removed Type.
    + +
    Value *value_remove(const value_iterator& It):
    +
    Removes a specific value from the symbol table. + Returns the removed value.
    + +
    bool strip():
    +
    This method will strip the symbol table of its names leaving + the type and values.
    + +
    void clear():
    +
    Empty the symbol table completely.
    +
    + +

    Iteration

    +

    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:

    + + + + + + + + + + + + + + +
    UnitsIteratorIdiom
    Planes Of name/Value mapsPI
    
+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 PairsTI
    
+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 planeVI
    
+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.

    + +
    + +
    plane_iterator plane_begin():
    +
    Get an iterator that starts at the beginning of the type planes. + The iterator will iterate over the Type/ValueMap pairs in the + type planes.
    + +
    plane_const_iterator plane_begin() const:
    +
    Get a const_iterator that starts at the beginning of the type + planes. The iterator will iterate over the Type/ValueMap pairs + in the type planes.
    + +
    plane_iterator plane_end():
    +
    Get an iterator at the end of the type planes. This serves as + the marker for end of iteration over the type planes.
    + +
    plane_const_iterator plane_end() const:
    +
    Get a const_iterator at the end of the type planes. This serves as + the marker for end of iteration over the type planes.
    + +
    value_iterator value_begin(const Type *Typ):
    +
    Get an iterator that starts at the beginning of a type plane. + The iterator will iterate over the name/value pairs in the type plane. + Note: The type plane must already exist before using this.
    + +
    value_const_iterator value_begin(const Type *Typ) const:
    +
    Get a const_iterator that starts at the beginning of a type plane. + The iterator will iterate over the name/value pairs in the type plane. + Note: The type plane must already exist before using this.
    + +
    value_iterator value_end(const Type *Typ):
    +
    Get an iterator to the end of a type plane. This serves as the marker + for end of iteration of the type plane. + Note: The type plane must already exist before using this.
    + +
    value_const_iterator value_end(const Type *Typ) const:
    +
    Get a const_iterator to the end of a type plane. This serves as the + marker for end of iteration of the type plane. + Note: the type plane must already exist before using this.
    + +
    type_iterator type_begin():
    +
    Get an iterator to the start of the name/Type map.
    + +
    type_const_iterator type_begin() cons:
    +
    Get a const_iterator to the start of the name/Type map.
    + +
    type_iterator type_end():
    +
    Get an iterator to the end of the name/Type map. This serves as the + marker for end of iteration of the types.
    + +
    type_const_iterator type_end() const:
    +
    Get a const-iterator to the end of the name/Type map. This serves + as the marker for end of iteration of the types.
    + +
    plane_const_iterator find(const Type* Typ ) const:
    +
    This method returns a plane_const_iterator for iteration over + the type planes starting at a specific plane, given by \p Ty.
    + +
    plane_iterator find( const Type* Typ :
    +
    This method returns a plane_iterator for iteration over the + type planes starting at a specific plane, given by \p Ty.
    + +
    +
    + + +
    The Core LLVM Class Hierarchy Reference @@ -1816,220 +2050,6 @@ arguments. An argument has a pointer to the parent Function.

    - -
    - The SymbolTable class -
    -
    -

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

      -
    1. Accessors. Accessors provide read-only access to information - such as finding a value for a name with the - lookup method.
      2. -
    2. Mutators. Mutators allow the user to add information to the - SymbolTable with methods like - insert.
      3. -
    3. Iterators. Iterators allow the user to traverse the content - of the symbol table in well defined ways, such as the method - type_begin.
      4. -
    - -

    Accessors

    -
    -
    Value* lookup(const Type* Ty, const std::string& name) const: -
    -
    The lookup method searches the type plane given by the - Ty parameter for a Value with the provided name. - If a suitable Value is not found, null is returned.
    - -
    Type* lookupType( const std::string& name) const:
    -
    The lookupType method searches through the types for a - Type with the provided name. If a suitable Type - is not found, null is returned.
    - -
    bool hasTypes() const:
    -
    This function returns true if an entry has been made into the type - map.
    - -
    bool isEmpty() const:
    -
    This function returns true if both the value and types maps are - empty
    -
    - -

    Mutators

    -
    -
    void insert(Value *Val):
    -
    This method adds the provided value to the symbol table. The Value must - have both a name and a type which are extracted and used to place the value - in the correct type plane under the value's name.
    - -
    void insert(const std::string& Name, Value *Val):
    -
    Inserts a constant or type into the symbol table with the specified - name. There can be a many to one mapping between names and constants - or types.
    - -
    void insert(const std::string& Name, Type *Typ):
    -
    Inserts a type into the symbol table with the specified name. There - can be a many-to-one mapping between names and types. This method - allows a type with an existing entry in the symbol table to get - a new name.
    - -
    void remove(Value* Val):
    -
    This method removes a named value from the symbol table. The - type and name of the Value are extracted from \p N and used to - lookup the Value in the correct type plane. If the Value is - not in the symbol table, this method silently ignores the - request.
    - -
    void remove(Type* Typ):
    -
    This method removes a named type from the symbol table. The - name of the type is extracted from \P T and used to look up - the Type in the type map. If the Type is not in the symbol - table, this method silently ignores the request.
    - -
    Value* remove(const std::string& Name, Value *Val):
    -
    Remove a constant or type with the specified name from the - symbol table.
    - -
    Type* remove(const std::string& Name, Type* T):
    -
    Remove a type with the specified name from the symbol table. - Returns the removed Type.
    - -
    Value *value_remove(const value_iterator& It):
    -
    Removes a specific value from the symbol table. - Returns the removed value.
    - -
    bool strip():
    -
    This method will strip the symbol table of its names leaving - the type and values.
    - -
    void clear():
    -
    Empty the symbol table completely.
    -
    - -

    Iteration

    -

    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:

    - - - - - - - - - - - - - - -
    UnitsIteratorIdiom
    Planes Of name/Value mapsPI
    
-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 PairsTI
    
-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 planeVI
    
-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.

    - -
    - -
    plane_iterator plane_begin():
    -
    Get an iterator that starts at the beginning of the type planes. - The iterator will iterate over the Type/ValueMap pairs in the - type planes.
    - -
    plane_const_iterator plane_begin() const:
    -
    Get a const_iterator that starts at the beginning of the type - planes. The iterator will iterate over the Type/ValueMap pairs - in the type planes.
    - -
    plane_iterator plane_end():
    -
    Get an iterator at the end of the type planes. This serves as - the marker for end of iteration over the type planes.
    - -
    plane_const_iterator plane_end() const:
    -
    Get a const_iterator at the end of the type planes. This serves as - the marker for end of iteration over the type planes.
    - -
    value_iterator value_begin(const Type *Typ):
    -
    Get an iterator that starts at the beginning of a type plane. - The iterator will iterate over the name/value pairs in the type plane. - Note: The type plane must already exist before using this.
    - -
    value_const_iterator value_begin(const Type *Typ) const:
    -
    Get a const_iterator that starts at the beginning of a type plane. - The iterator will iterate over the name/value pairs in the type plane. - Note: The type plane must already exist before using this.
    - -
    value_iterator value_end(const Type *Typ):
    -
    Get an iterator to the end of a type plane. This serves as the marker - for end of iteration of the type plane. - Note: The type plane must already exist before using this.
    - -
    value_const_iterator value_end(const Type *Typ) const:
    -
    Get a const_iterator to the end of a type plane. This serves as the - marker for end of iteration of the type plane. - Note: the type plane must already exist before using this.
    - -
    type_iterator type_begin():
    -
    Get an iterator to the start of the name/Type map.
    - -
    type_const_iterator type_begin() cons:
    -
    Get a const_iterator to the start of the name/Type map.
    - -
    type_iterator type_end():
    -
    Get an iterator to the end of the name/Type map. This serves as the - marker for end of iteration of the types.
    - -
    type_const_iterator type_end() const:
    -
    Get a const-iterator to the end of the name/Type map. This serves - as the marker for end of iteration of the types.
    - -
    plane_const_iterator find(const Type* Typ ) const:
    -
    This method returns a plane_const_iterator for iteration over - the type planes starting at a specific plane, given by \p Ty.
    - -
    plane_iterator find( const Type* Typ :
    -
    This method returns a plane_iterator for iteration over the - type planes starting at a specific plane, given by \p Ty.
    - -
    -
    -