TraceMethodIntParameter Aspect
[CodeInstrumentation Group]

This aspect is defined in file: ../../AspectXLib/CodeInstrumentation/Base/aspects/TraceMethodIntParameter.ax

Aspect Description

Sample aspect program to insert tracing instructions when a method with one integer parameter is entered. This aspect program shows an example of how the implementation of selected methods in a certain code base can be modified to output a tracing message every time the method is entered. In this example, the tracing message is output using a printf instruction that writes a message to the output device stating the name of the method, the name of the class to which it belongs and the value of its int parameter.

In this example, the identification of the methods for which tracing is to be performed (and which therefore must be modified by the aspect) is done using examination of method parameters, namely their types.

This aspect defines four advices that describe four separate but related changes. The first advice inserts the tracing code in the target methods. The second advice inserts a new include statement to include the stdio library that is required by the printf method. The third advice modifies the comments of the classes that are affected by the change to include a statement that the class code has been automatically modified by an aspect program. The fourth advice modifies the comment of the methods that are affected by the change to include a description of the type of change that has been woven into the code.

This sample aspect program targets all methods with exactly one parameter of type int.
Author:
A. Pasetti, O. Rohlik
See also:
TraceMethodIntParametersOnly

Pointcuts

functiontargetMethodImplementation
 Points to the implementations of the methods that must be modified
function_decltargetMethodDeclaration
 Points to all declarations of the target methods
commenttargetMethodComment
 Points to the method comments that must be modified
classtargetClass
 Points to all classes that contain a target method
commenttargetClassComment
 Points to the class comments that must be modified
unittargetImplementationUnit
 Points to all the units that contain implementations of methods that must be modified

Advices

endinsertClassComment
 Add a comment at the end of the comment of the classes that are modified by other advices
endinsertMethodComment
 Add a comment at the end of the comment of the methods that are modified by other advices
begininsertTrace
 Insert the tracing instruction in the target methods
addaddInclude
 Add the #include statement for the stdio library

Pointcut Documentation

function targetMethodImplementation (source)
Points to the implementations of the methods that must be modified. The methods that must be modified are those that uses one int parameter.

Recall that in srcML, element name contains the whole list of parameters within parameter_list element. Then count() function can be used to specify number of allowed parameters. It is possible to target specific data type by querying subelements of the parameter. Note that "[1]" in param[1] targets the first parameter of the method. In this particular example "[1]" can be omitted since there is only one parameter (which is guaranteed by count() function) and therefore there is no possibility of ambiguities.

This pointcut only points to the method implementation. A second pointcut (targetMethodDeclaration) points to the method declarations.
function_decl targetMethodDeclaration (source)
Points to all declarations of the target methods. See the description of the pointcut (targetMethodImplementation) but note that the srcML element name in a declaration file may contain specifier virtual. This specifier means that there is a chance that the method is pure virtual method i.e. it does not have its implementation and therefore there is nothing woven in the function body. The pure virtual method can be identified by the assignment sign that follows the parameter_list element.
comment targetMethodComment (source)
Points to the method comments that must be modified. The method comments that must be modified are those that are followed by a targetMethodDeclaration pointcut.
class targetClass (source)
Points to all classes that contain a target method. The identification is done by taking all the classes that contains a targetMethodDeclaration pointcut
comment targetClassComment (source)
Points to the class comments that must be modified. The class comments that must be modified are those that are followed by a targetClass pointcut.
unit targetImplementationUnit (source)
Points to all the units that contain implementations of methods that must be modified. In srcML, a unit is a source file (a definition file, a declaration file, or an inline file). This pointcut therefore identifies all the source files that contain an implementation of the target method.

Advice Documentation

end insertClassComment (source)

Triplet: comment end comment

Add a comment at the end of the comment of the classes that are modified by other advices.

Refers to global pointcut: comment targetClassComment

end insertMethodComment (source)

Triplet: comment end comment

Add a comment at the end of the comment of the methods that are modified by other advices.

Refers to global pointcut: comment targetMethodComment

begin insertTrace (source)

Triplet: function begin codeFragment

Insert the tracing instruction in the target methods. This advice inserts a printf instruction at the beginning of the target method. The printf instruction prints a message stating the name of the target method, name of the target class and value of the method parameter. The names and values are accessed using "dollar variables".

Refers to global pointcut: function targetMethodImplementation

add addInclude (source)

Triplet: unit add include

Add the #include statement for the stdio library. Inclusion of this library is necessary because the code that is woven into the target methods calls the stdio function printf. Note that the code to be added by this advice is specified using the CDATA section because otherwise the braces around "stdio" would be interpreted as XML braces by the XWeaver program.

Refers to global pointcut: unit targetImplementationUnit