type_transformation
Creates type transformations and examines properties
Format
TV::type_transformationaction [ object-id ] [ other-args]
Arguments
action
The action to perform, as follows:
commands
Displays the subcommands that you can use. The CLI responds by displaying the subcommands shown here. Do not use additional arguments with this subcommand.
create
Creates a new transformation object. The object-idargument is not used; other-argsis Array, List, Map, Set, Umap, Uset or Struct, indicating the type of transformation being created. You can change a transformation’s properties up to the time you install it. After being installed, you can longer change them.
get
Gets the values of one or more transformation properties. The other-argsargument can include one or more property names. The CLI returns these property values in a list whose order is the same as the property names you entered.
If you use the -alloption instead of object-id, the CLI returns a list containing one (sublist) element for the object.
properties
Displays the properties that the CLI can access. Do not use additional arguments with this option. These properties are discussed later in this section.
set
Sets the values of one or more properties. Theother-argsargument consists of pairs of property names and values. The argument pairs that you can set are listed later in this section.
object-id
The type transformation ID. This value is returned when you create a new transformation; for example, 1represents process 1. If you use the-all option, the operation executes upon all objects of this class in the current focus.
other-args
Arguments required by get and set subcommands.
Description
The TV::type_transformation command lets you define and examine properties of a type transformation. The states and properties you can set are:
Common Properties
id
The type transformation ID returned from a create operation.
language
The language property specifies source language for the code of the aggregate type (class) to transform. This is always C++.
name
Contains a regular expression that checks to see if a symbol is eligible for type transformation. This regular expression must match the definition of the aggregate type (class) being transformed.
type_callback
The type_callback property is used in two ways.
(1) When it is used within a list or vector transformation, it names the procedure that determines the type of the list or vector element. The callback procedure takes one parameter, the symbol ID of the symbol that was validated during the callback to the procedure specified by the validate_callback. The call structure for this callback is:
type_callback id
where id is the symbol ID of the symbol that was validated using the validate_callback procedure.
(2) When it is used within a struct transformation, it names the procedure that specifies the data type to be used when displaying the struct.
type_transformation_description
A string containing a description of what is being transformed; for example, you might enter “GNU Vector”.
validate_callback
Names a procedure that is called when a data type matches the regular expression specified in the name property. The call structure for this callback is:
validate_callback id
where id is the symbol ID of the symbol being validated.
Your callback procedure should check the symbol’s structure to insure that it should be transformed. While not required, most users will extract symbol information such as its type and its data members while validating the datatype. The callback procedure must return a Boolean value, where true means the symbol is valid and can be transformed.
compiler
Reserved for future use.
Array Properties
addressing_callback
Names the procedure that locates the address of the start of an array. The call structure for this callback is:
addressing_callback id
where id is the symbol ID of the symbol that was validated using the validate_callback procedure.
This callback defines a TotalView addressing expression that computes the starting address of an array’s first element.
lower_bounds_callback
Names the procedure that obtains a lower bound value for the array type being transformed. For C/C++ arrays, this value is always 0. The call structure for this callback is:
lower_bounds_callback id
where id is the symbol ID of the symbol that was validated using the validate_callback procedure.
upper_bounds_callback
Names the procedure that defines an addressing expression that computes the extent (number of elements) in an array. The call structure for this callback is:
upper_bounds_callback id
where id is the symbol ID of the symbol that was validated using the validate_callback procedure.
List Properties
list_element_count_addressing_callback
Names the procedure that determines the total number of elements in a list. The call structure for this callback is:
list_element_count_addressing_callback id
where id is the symbol ID of the symbol that was validated using the validate_callback procedure.
This callback defines an addressing expression that specifies how to get to the member of the symbol that specifies the number of elements in the list.
If your data structure does not have this element, you still must use this callback. In this case, simply return {nop}as the addressing expression and the transformation will count the elements by following all the pointers. This can be very time consuming.
list_element_data_addressing_callback
Names the procedure that defines an addressing expression that specifies how to access the data member of a list element. The call structure for this callback is:
list_element_data_addressing_callback id
where id is the symbol ID of the symbol that was validated using the validate_callback procedure.
list_element_next_addressing_callback
Names the procedure that defines an addressing expression that specifies how to access the next element of a list. The call structure for this callback is:
list_element_next_addressing_callback id
where id is the symbol ID of the symbol that was validated using the validate_callback procedure.
list_element_prev_addressing_callback
Names the procedure that defines an addressing expression that specifies how to access the previous element of a list. The call structure for this callback is:
list_element_prev_addressing_callback id
where id is the symbol ID of the symbol that was validated using the validate_callback procedure.
This property is optional. For example, you would not use it in a singly linked list.
list_end_value
Specifies if a list is terminated by NULL or the head of the list. Enter one of the following: NULL or ListHead
list_first_element_addressing_callback
Names the procedure that defines an addressing expression that specifies how to go from the head element of the list to the first element of the list. It is not always the case that the head element of the list is the first element of the list. The call structure for this callback is:
list_first_element_addressing_callback id
where id is the symbol ID of the symbol that was validated using the validate_callback procedure.
list_head_addressing_callback
Names the procedure that defines an addressing expression to obtain the head element of the linked list. The call structure for this callback is:
list_head_addressing_callback id
where id is the symbol ID of the symbol that was validated using the validate_callback procedure.
Struct Properties
struct_member_count_callback
Names the procedure that obtains the total number of members in a struct. The call structure for this callback is:
struct_member_count_callback id
where id is the symbol ID of the symbol that was validated using the validate_callback procedure.
struct_member_addressing_callback
Names the procedure that defines an addressing expression that specifies how to access the specified member of a struct. The call structure for this callback is:
struct_member_addressing_callback id index
where id is the symbol ID of the symbol that was validated using the validate_callback procedure and index specifies the zero-based position of the member within the struct.
struct_member_type_callback
Names the procedure that obtains the type id of the specified member of a struct. The call structure for this callback is:
struct_member_type_callback id index
where id is the symbol ID of the symbol that was validated using the validate_callback procedure and index specifies the zero-based position of the member within the struct.
struct_member_name_callback
Names the procedure that obtains the name of the specified member of a struct. The call structure for this callback is:
struct_member_name_callback id index
where id is the symbol ID of the symbol that was validated using the validate_callback procedure and index specifies the zero-based position of the member within the struct.
Red/Black Tree Properties
The implementation of map/multimap and set/multiset STL types uses red/black trees. These properties are common to all these types.
rbtree_head_addressing_callback
Names the procedure that defines an addressing expression to obtain the head element of the map. The call structure for this callback is:
rbtree_head_addressing_callback id
where id is the symbol ID of the symbol that was validated using the validate_callback procedure.
rbtree_head_type_callback
Names the procedure that obtains the type id of the head of a map. The call structure for this callback is:
rbtree_head_type_callback id
where id is the symbol ID of the symbol that was validated using the validate_callback procedure.
rbtree_element_left_addressing_callback
Names the procedure that defines an addressing expression that specifies how to access the left sub-tree of the current element of a map. The call structure for this callback is:
rbtree_element_left_addressing_callback id
where id is the symbol ID of the symbol that was validated using the validate_callback procedure.
rbtree_element_right_addressing_callback
Names the procedure that defines an addressing expression that specifies how to access the right sub-tree of the current element of a map. The call structure for this callback is:
rbtree_element_right_addressing_callback id
where id is the symbol ID of the symbol that was validated using the validate_callback procedure.
rbtree_element_parent_addressing_callback
Names the procedure that defines an addressing expression that specifies how to access the parent of the current element of a map. The call structure for this callback is:
rbtree_element_parent_addressing_callback id
where id is the symbol ID of the symbol that was validated using the validate_callback procedure.
rbtree_element_count_addressing_callback
Names the procedure that determines the total number of elements in a map. The call structure for this callback is:
rbtree_element_count_addressing_callback id
where id is the symbol ID of the symbol that was validated using the validate_callback procedure.
This callback defines an addressing expression that specifies how to get to the member of the symbol that specifies the number of elements in the map.
If your data structure does not have this element, you still must use this callback. In this case, simply return {nop} as the addressing expression and the transformation will count the elements by following all the pointers. Unfortunately, this can be very time consuming.
rbtree_element_count_type_callback
Names the procedure that obtains the type id of the member that specifies the number of elements in the map. The call structure for this callback is:
rbtree_element_count_type_callback id
where id is the symbol ID of the symbol that was validated using the validate_callback procedure.
If your data structure does not have a count element, this property is not required.
rbtree_left_most_addressing_callback
Names the procedure that defines an addressing expression to obtain the left-most element of the map. The call structure for this callback is:
rbtree_left_most_addressing_callback id
where id is the symbol ID of the symbol that was validated using the validate_callback procedure.
Map/Multimap Properties
For map and multimap STL types these properties are used in combination with those for red/black trees above.
map_element_key_data_addressing_callback
Names the procedure that defines an addressing expression that specifies how to access the key of an element of a map. The call structure for this callback is:
map_element_key_data_addressing_callback id
where id is the symbol ID of the symbol that was validated using the validate_callback procedure.
map_element_key_type_callback
Names the procedure that obtains the type id of the key of a map. The call structure for this callback is:
map_element_key_type_callback id
where id is the symbol ID of the symbol that was validated using the validate_callback procedure.
map_element_type_callback
Names the procedure that obtains the type id of the element in the red/black tree that contains the key/value pair. The call structure for this callback is:
map_element_type_callback id
where id is the symbol ID of the symbol that was validated using the validate_callback procedure.
map_element_value_data_addressing_callback
Names the procedure that defines an addressing expression that specifies how to access the value of an element of a map. The call structure for this callback is:
map_element_value_data_addressing_callback id
where id is the symbol ID of the symbol that was validated using the validate_callback procedure.
map_element_value_type_callback
Names the procedure that obtains the type id of the value of a map. The call structure for this callback is:
map_element_value_type_callback id
where id is the symbol ID of the symbol that was validated using the validate_callback procedure.
map_iterator_end_value
Specifies if a map is terminated by NULL or the head of the map. Enter one of the following: NULL or MapHead
Set/Multiset Properties
For set and multiset STL types these properties are used in combination with those for red/black trees above.
set_element_data_addressing_callback
Names the procedure that defines an addressing expression that specifies how to access an element of a set. The call structure for this callback is:
set_element_data_addressing_callback id
where id is the symbol ID of the symbol that was validated using the validate_callback procedure.
set_element_type_callback
Names the procedure that obtains the type id of an element in the set. The call structure for this callback is:
set_element_type_callback id
where id is the symbol ID of the symbol that was validated using the validate_callback procedure.
set_iterator_end_value
Specifies if a set is terminated by NULL or the head of the set. Enter one of the following: NULL or SetHead
Hashtable Properties
The implementations of unordered map/multimap and unordered set/multiset STL types use hash tables. These properties are common to all these types.
hashtable_head_addressing_callback
Names the procedure that defines an addressing expression to obtain the head element of the map. Depending on the implementation, this element may be the address of the bucket list or the beginning element of a forward list. The call structure for this callback is:
hashtable_head_addressing_callback id
where id is the symbol ID of the symbol that was validated using the validate_callback procedure.
hashtable_element_count_addressing_callback
Names the procedure that determines the total number of elements in a hashtable. The call structure for this callback is:
hashtable_element_count_addressing_callback id
where id is the symbol ID of the symbol that was validated using the validate_callback procedure.
This callback defines an addressing expression that specifies how to get to the member of the symbol that specifies the number of elements in the map.
hashtable_element_count_type_callback
Names the procedure that obtains the type id of the member that specifies the number of elements in the map. The call structure for this callback is:
hashtable_element_count_type_callback id
where id is the symbol ID of the symbol that was validated using the validate_callback procedure.
hashtable_element_addressing_callback
Names the procedure that defines an addressing expression that specifies how to access the next element. The call structure for this callback is:
hashtable_element_addressing_callback id
where id is the symbol ID of the symbol that was validated using the validate_callback procedure.
hashtable_begin_index_addressing_callback
Names the procedure that determines the index of the first used bucket in a hashtable. The call structure for this callback is:
hashtable_begin_index_addressing_callback id
where id is the symbol ID of the symbol that was validated using the validate_callback procedure.
This callback defines an addressing expression that specifies how to get to the member of the symbol that specifies the first used bucket in the hashtable. This allows a small optimization since the transformation can skip empty buckets at the start of the bucket table. If your data does not supply this value you can use {nop}.
hashtable_begin_index_type_callback
Names the procedure that determines the type of the value that contains the index of the first used bucket in a hashtable. The call structure for this callback is:
hashtable_begin_index_type_callback id
where id is the symbol ID of the symbol that was validated using the validate_callback procedure.
hashtable_bucket_count_addressing_callback
Names the procedure that determines the total number of buckets in a hash table. The call structure for this callback is:
hashtable_bucket_count_addressing_callback id
where id is the symbol ID of the symbol that was validated using the validate_callback procedure.
This callback defines an addressing expression that specifies how to get to the member of the symbol that specifies the number of buckets in a hashtable.
This property can be {nop} when the hash table elements can be found without scanning the bucket list, for example, when the elements are also stored in a forward list.
hashtable_bucket_count_type_callback
Names the procedure that obtains the type id of the member that specifies the number of buckets in a hash table. The call structure for this callback is:
hashtable_bucket_count_type_callback id
where id is the symbol ID of the symbol that was validated using the validate_callback procedure.
If you are not scanning the bucket list for the hashed values, this property is not required.
Unordered Map/Multimap Properties
For unordered map and unordered multimap STL types these properties are used in combination with those for hash tables above.
umap_element_key_data_addressing_callback
Names the procedure that defines an addressing expression that specifies how to access the key of an element of a map. The call structure for this callback is:
umap_element_key_data_addressing_callback id
where id is the symbol ID of the symbol that was validated using the validate_callback procedure.
umap_element_key_type_callback
Names the procedure that obtains the type id of the key of a map. The call structure for this callback is:
umap_element_key_type_callback id
where id is the symbol ID of the symbol that was validated using the validate_callback procedure.
umap_element_type_callback
Names the procedure that obtains the type id of the element in the hashtable that contains the key/value pair. The call structure for this callback is:
umap_element_type_callback id
where id is the symbol ID of the symbol that was validated using the validate_callback procedure.
umap_element_value_data_addressing_callback
Names the procedure that defines an addressing expression that specifies how to access the value of an element of a map. The call structure for this callback is:
umap_element_value_data_addressing_callback id
where id is the symbol ID of the symbol that was validated using the validate_callback procedure.
umap_element_value_type_callback
Names the procedure that obtains the type id of the value of a map. The call structure for this callback is:
umap_element_value_type_callback id
where id is the symbol ID of the symbol that was validated using the validate_callback procedure.
Unordered Set/Multiset Properties
For unordered set and unordered multiset STL types these properties are used in combination with those for hash tables above.
uset_element_key_data_addressing_callback
Names the procedure that defines an addressing expression that specifies how to access an element of a set. The call structure for this callback is:
uset_element_key_data_addressing_callback id
where id is the symbol ID of the symbol that was validated using the validate_callback procedure.
uset_element_key_type_callback
Names the procedure that obtains the type id of an element in the set. The call structure for this callback is:
uset_element_key_type_callback id
where id is the symbol ID of the symbol that was validated using the validate_callback procedure.
