Threads Module User's Guide : PART III Foundation Packages : Chapter 6 The Execution Tracing Package : Using Set Declaration Macros : Function Declaration Macros
Function Declaration Macros
The function declaration macros declare functions to be traceable. In addition, the macros automatically generate ENTRY and EXIT trace events upon entry and exit of the function. Every function that requires tracing must have one of these macros, normally as the first line of the function. Attempting to use more than one function declaration macro in a function results in compile or link errors.
The macro families come in sets of four macros, including an INLINE version for inline functions, a TEMPLATE version for template functions, a INLINE_TEMPLATE version for inline template functions, and a basic version for all other functions. Using the incorrect version results in compile and link errors.
Function declaration macros can take these parameters:
• functionTag is used as the environment variable to control trace event generation for this function. It also appears in the trace output. The -functionTag parameter must be a valid C++ identifier, and it must be enclosed in quotation marks, as a string. The functionTag is usually the name of the function (for a global function) or a string of the form “ClassName_functionName”(for a member function). See “Assigning functionTag Names” for more on assigning tag names.
• className specifies the name of the class to which the member or friend function belongs. It must match the className used in the RW_USER_DECLARE_TRACEABLE_CLASS macro for the class.
Macros for Global Functions
RW_USER_TRACEABLE_FUNCTION("functionTag”)
RW_USER_TRACEABLE_INLINE_FUNCTION("functionTag”)
RW_USER_TRACEABLE_TEMPLATE_FUNCTION("functionTag”)
RW_USER_TRACEABLE_INLINE_TEMPLATE_FUNCTION("functionTag”)
This macro family is used in global (non-member) functions. The functionTag is usually the name of the function.
Macros for Member Functions
RW_USER_TRACEABLE_MEMBER("functionTag”, className)
RW_USER_TRACEABLE_INLINE_MEMBER("functionTag”, className)
RW_USER_TRACEABLE_TEMPLATE_MEMBER("functionTag”, className)
RW_USER_TRACEABLE_INLINE_TEMPLATE_MEMBER("functionTag”, className)
This macro family is used in member functions. The functionTag is usually the string “ClassName_functionName”.
Macros for Static Member Functions
RW_USER_TRACEABLE_STATIC_MEMBER("functionTag”, className)
RW_USER_TRACEABLE_INLINE_STATIC_MEMBER("functionTag”, className)
RW_USER_TRACEABLE_TEMPLATE_STATIC_MEMBER("functionTag”, className)
RW_USER_TRACEABLE_INLINE_TEMPLATE_STATIC_MEMBER ("functionTag”, className)
This macro family is used in static member functions. The functionTag is usually the string “ClassName_functionName”.
Macros for Friend Functions
RW_USER_TRACEABLE_FRIEND("functionTag”, className)
RW_USER_TRACEABLE_INLINE_FRIEND("functionTag”, className)
RW_USER_TRACEABLE_TEMPLATE_FRIEND("functionTag”, className)
RW_USER_TRACEABLE_INLINE_TEMPLATE_FRIEND("functionTag”, className)
This macro family is used in friend functions. The functionTag is usually the function name.
NOTE >> Each function in an application may be traceable as a friend to only one class. Friend functions can also be traced as global functions.
Implications for Template Classes
Because you can place only one function declaration macro in each template function, you get only one environment variable, which controls the trace output from every instantiation of that particular template function. It is not trivial to determine which instantiation of a template function produced a particular trace message. If this information is required, you need to get it yourself, using a mechanism such as RTTI, and include it in the trace macro call. This is a known limitation of the Execution Tracing package.
Assigning functionTag Names
The function declaration macros take a functionTag parameter (in quotes) to uniquely identify every traceable function. The tag appears in the trace output, so you can quickly find the function that generated a particular message.
Function names with special characters. The functionTag parameter must be a valid C++ identifier, so you need some convention to handle functions with characters that are invalid in C++ identifiers. Table 4 shows the convention used throughout Threads Module. You are not required to follow this convention in your code.
Table 4 – Conventions for functionTag parameters 
Function Name
Suggested Trace functionTag
ClassName::ClassName() (constructors)
"ClassName_ctor”
ClassName::~ClassName() (destructor)
"ClassName_dtor”
ClassName::operator==()
"ClassName_opEQ”
ClassName::operator!=()
"ClassName_opNE”
ClassName::operator<()
"ClassName_opLT”
ClassName::operator<=()
"ClassName_opLE”
ClassName::operator>()
"ClassName_opGT”
ClassName::operator>=()
"ClassName_opGE”
ClassName::operator=()
"ClassName_opAssign”
ClassName::operator>>()
"ClassName_opExtract”
ClassName::operator<<()
"ClassName_opInsert”
ClassName::operator()()
"ClassName_opFunctionCall”
ClassName::operator Type()
"ClassName_opType”
The limitation of functionTags to be valid C++ identifiers stems from the fact that some shells (ksh in particular) do not permit the creation of environment variables that do not follow C++ identifier conventions.
Overloaded functions. This functionTag convention overloads tags. For example, all constructors for a class have the same functionTag. If multiple functions have the same functionTag, the single environment variable controls every version of the function. For distinguishing among overloaded functions, extra characters indicating the signature of the function can be included in the tag name. For example, “ClassName_ctor_ic” could be used for ClassName::ClassName(int, char). Because Trace outputs the filename and line number of the location of each trace event, the function that generated a trace event can be determined.