TraceMethodLeave Aspect
[CodeInstrumentation Group]

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

Aspect Description

Sample aspect program to insert tracing instructions when a selected method is left either by return statement or by reaching end of its body. 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 return statement. This aspect defines seven advices that describe seven separate but related changes. The first two advices inserts comments to describe the changes made in the base code. The next three advices inserts tracing instructions in the methods and the sixth advice inserts declaration of helper variable needed for temporal storage of the return value. The last advice inserts a new include statement to include the stdio library that is required by the printf method.

This sample aspect program targets all method definitions.
Author:
A. Pasetti, O. Rohlik
See also:
TraceMethodIntParameter

Pointcuts

functiontargetIntMethodImplementation
 Points to the implementations of the methods that must be modified
functiontargetNonIntMethodImplementation
 Points to the implementations of the methods that must be modified
returntargetIntMethodReturn
 Points to return statement that must be modified
returntargetNonIntMethodReturn
 >Points to return statement that must be modified
function_decltargetMethodDeclaration
 Points to all declarations of the target methods
commenttargetMethodDeclarationComment
 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
replaceinsertIntTraceBeforeReturn
 Insert the tracing instruction in the target methods
beforeinsertNonIntTraceBeforeReturn
 Insert the tracing instruction in the target methods
endinsertTraceAtFunctionEnd
 Insert the tracing instruction in the target methods
endinsertTraceAtContructorEnd
 Insert the tracing instruction in the target constructor
begininsertVariableDeclaration
 Insert the declaration of integer local variable at the beginning of target methods
addaddInclude
 Add the #include statement for the stdio library

Pointcut Documentation

function targetIntMethodImplementation (source)
Points to the implementations of the methods that must be modified. This pointcut in particular points to methods whose return type is int. This pointcut only points to the method implementation. A second pointcut (targetMethodDeclaration) points to the method declarations.
function targetNonIntMethodImplementation (source)
Points to the implementations of the methods that must be modified. This pointcut in particular points to methods whose return type is other than int. This pointcut only points to the method implementation. A second pointcut (targetMethodDeclaration) points to the method declarations.
return targetIntMethodReturn (source)
Points to return statement that must be modified. It only target return statements that return type int.
return targetNonIntMethodReturn (source)
>Points to return statement that must be modified. It only target return statements that returns other type than int.
function_decl targetMethodDeclaration (source)
Points to all declarations of the target methods. See the description of the pointcut (targetMethodImplementation).

Note that this pointcut also excludes pure virtual declarations using examination of the specifier subelement of the function_decl element.
comment targetMethodDeclarationComment (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 targetMethodDeclarationComment

replace insertIntTraceBeforeReturn (source)

Triplet: return replace codeFragment

Insert the tracing instruction in the target methods. This advice inserts three instructions in the target method.

The first instruction evaluates the expression in the return statement and stores the result in the helper variable. The second instruction prints the value returned by the method (which is temporarily stored in the helper variable). The third instruction is the return statement that returns the value stored in the helper variable. The code modifier is implemented in three steps since the return expression may contain construction that changes it value whenever evaluated. Therefore it is not possible to use the same expression twice -- in printf instruction and in return statement.

The names of the target method and target class are accessed using "dollar variables". The return expression is accessed using XSL language instruction xsl:value-of.

Refers to global pointcut: return targetIntMethodReturn

before insertNonIntTraceBeforeReturn (source)

Triplet: return before codeFragment

Insert the tracing instruction in the target methods. This advice inserts a printf instruction at the end of the target method. The printf instruction prints the expression returned by the function. The names of the target method and target class are NOT accessed using "dollar variables" here. Instead the xsl:value-of XSLT instruction is used to access the method name and calss name. Dollar variables cannot be used within the xsl element.

Refers to global pointcut: return targetNonIntMethodReturn

end insertTraceAtFunctionEnd (source)

Triplet: function end codeFragment

Insert the tracing instruction in the target methods. This advice inserts a printf instruction at the very end of every method. It may happen that the inserted function call will be unreachable. The names of the target method and target class are accessed using "dollar variables".

Local Pointcut: function (source)

end insertTraceAtContructorEnd (source)

Triplet: constructor end codeFragment

Insert the tracing instruction in the target constructor. This advice inserts a printf instruction at the very end of every constructor. The name of the target class is not accessed using "dollar variables" because at the time of writing of this sample aspect dollar variables for constructors were not implemented. As a workaround XSL function substring-before(src:name,'::') is used to query srcML for the name of of the class.

Local Pointcut: constructor (source)

begin insertVariableDeclaration (source)

Triplet: function begin codeFragment

Insert the declaration of integer local variable at the beginning of target methods.

Refers to global pointcut: function targetIntMethodImplementation

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