-
C++
The C++ API is a set of macros that can be inserted in the C++ source code. An extension of the same API is available to instrument C and Fortran sources.
At the beginning of each instrumented source file, include the following header
#include <TAU.h>
-
C
The API for instrumenting C source code is similar to the C++ API. The primary difference is that the
TAU_PROFILE()
macro is not available for identifying an entire block of code or function. Instead, routine transitions are explicitly specified usingTAU_PROFILE_TIMER()
macro withTAU_PROFILE_START()
andTAU_PROFILE_STOP()
macros to indicate the entry and exit from a routine. Note that,TAU_TYPE_STRING()
and CT() macros are not applicable for C. It is important to declare theTAU_PROFILE_TIMER()
macro after all the variables have been declared in the function and before the execution of the first C statement.Example:
#include <TAU.h> int main (int argc, char **argv) { int ret; pthread_attr_t attr; pthread_t tid; TAU_PROFILE_TIMER(tautimer,"main()", "int (int, char **)", TAU_DEFAULT); TAU_PROFILE_START(tautimer); TAU_PROFILE_INIT(argc, argv); TAU_PROFILE_SET_NODE(0); pthread_attr_init(&attr); printf("Started Main...\n"); // other statements TAU_PROFILE_STOP(tautimer); return 0; }
-
Fortran 77/90/95
The Fortran90 TAU API allows source code written in Fortran to be instrumented for TAU. This API is comprised of Fortran routines. As explained in Chapter 2, the instrumentation can be disabled in the program by using the TAU stub makefile variable
TAU_DISABLE
on the link command line. This points to a library that contains empty TAU instrumentation routines.
-
Static timers
These are commonly used in most profilers where all invocations of a routine are recorded. The name and group registration takes place when the timer is created (typically the first time a routine is entered). A given timer is started and stopped at routine entry and exit points. A user defined timer can also measure the time spent in a group of statements. Timers may be nested but they may not overlap. The performance data generated can typically answer questions such as: what is the total time spent in MPI_Send() across all invocations?
-
Dynamic timers
To record the execution of each invocation of a routine, TAU provides dynamic timers where a unique name may be constructed for a dynamic timer for each iteration by embedding the iteration count in it. It uses the start/stop calls around the code to be examined, similar to static timers. The performance data generated can typically answer questions such as:what is the time spent in the routine foo() in iterations 24, 25, and 40?
-
Static phases
An application typically goes through several phases in its execution. To track the performance of the application based on phases, TAU provides static and dynamic phase profiling. A profile based on phases highlights the context in which a routine is called. An application has a default phase within which other routines and phases are invoked. A phase based profile shows the time spent in a routine when it was in a given phase. So, if a set of instrumented routines are called directly or indirectly by a phase, we'd see the time spent in each of those routines under the given phase. Since phases may be nested, a routine may belong to only one phase. When more than one phase is active for a given routine, the closest ancestor phase of a routine along its callstack is its phase for that invocation. The performance data generated can answer questions such as: what is the total time spent in MPI_Send() when it was invoked in all invocations of the IO (IO => MPI_Send()) phase?
-
Dynamic phases
Dynamic phases borrow from dynamic timers and static phases to create performance data for all routines that are invoked in a given invocation of a phase. If we instrument a routine as a dynamic phase, creating a unique name for each of its invocations (by embedding the invocation count in the name), we can examine the time spent in all routines and child phases invoked directly or indirectly from the given phase. The performance data generated can typically answer questions such as: what is the total time spent in MPI_Send() when it was invoked directly or indirectly in iteration 24? Dynamic phases are useful for tracking per-iteration profiles for an adaptive computation where iterations may differ in their execution times.
-
Callpaths
In phase-based profiles, we see the relationship between routines and parent phases. Phase profiles do not show the calling structure between different routines as is represented in a callgraph. To do so, TAU provides callpath profiling capabilities where the time spent in a routine along an edge of a callgraph is captured. Callpath profiles present the full flat profiles of routines (or nodes in the callgraph), as well as routines along a callpath. A callpath is represented syntactically as a list of routines separated by a delimiter. The maximum depth of a callpath is controlled by an environment variable.
-
User-defined Events
Besides timers and phases that measure the time spent between a pair of start and stop calls in the code, TAU also provides support for user-defined atomic events. After an event is registered with a name, it may be triggered with a value at a given point in the source code. At the application level, we can use user-defined events to track the progress of the simulation by keeping track of application specific parameters that explain program dynamics, for example, the number of iterations required for convergence of a solver at each time step, or the number of cells in each iteration of an adaptive mesh refinement application.
Table of Contents
- TAU_START - Starts a timer.
- TAU_STOP - Stops a timer.
- TAU_PROFILE - Profile a C++ function
- TAU_DYNAMIC_PROFILE - dynamic_profile a c++ function
- TAU_PROFILE_CREATE_DYNAMIC - Creates a dynamic timer
- TAU_CREATE_DYNAMIC_AUTO - Creates a dynamic timer for C/C++
- TAU_PROFILE_DYNAMIC_ITER - Creates a dynamic timer in Fortran.
- TAU_PHASE_DYNAMIC_ITER - Creates a dynamic phase in Fortran.
- TAU_PROFILE_TIMER - Defines a static timer.
- TAU_PROFILE_START - Starts a timer.
- TAU_PROFILE_STOP - Stops a timer.
- TAU_STATIC_TIMER_START - Starts a timer.
- TAU_STATIC_TIMER_STOP - Starts a timer.
- TAU_DYNAMIC_TIMER_START - Starts a dynamic timer.
- TAU_DYNAMIC_TIMER_STOP - Starts a dynamic timer.
- TAU_PROFILE_TIMER_DYNAMIC - Defines a dynamic timer.
- TAU_PROFILE_DECLARE_TIMER - Declares a timer for C
- TAU_PROFILE_CREATE_TIMER - Creates a timer for C
- TAU_GLOBAL_TIMER - Declares a global timer
- TAU_GLOBAL_TIMER_EXTERNAL - Declares a global timer from an external compilation unit
- TAU_GLOBAL_TIMER_START - Starts a global timer
- TAU_GLOBAL_TIMER_STOP - Stops a global timer
- TAU_PHASE - Profile a C++ function as a phase
- TAU_DYNAMIC_PHASE - Defines a dynamic phase.
- TAU_PHASE_CREATE_DYNAMIC - Defines a dynamic phase.
- TAU_PHASE_CREATE_STATIC - Defines a static phase.
- TAU_PHASE_START - Enters a phase.
- TAU_PHASE_STOP - Exits a phase.
- TAU_DYNAMIC_PHASE_START - Enters a DYNAMIC_PHASE.
- TAU_DYNAMIC_PHASE_STOP - Enters a DYNAMIC_PHASE.
- TAU_STATIC_PHASE_START - Enters a STATIC_PHASE.
- TAU_STATIC_PHASE_STOP - Enters a STATIC_PHASE.
- TAU_GLOBAL_PHASE - Declares a global phase
- TAU_GLOBAL_PHASE_EXTERNAL - Declares a global phase from an external compilation unit
- TAU_GLOBAL_PHASE_START - Starts a global phase
- TAU_GLOBAL_PHASE_STOP - Stops a global phase
- TAU_PROFILE_EXIT - Alerts the profiling system to an exit call
- TAU_REGISTER_THREAD - Register a thread with the profiling system
- TAU_PROFILE_GET_NODE - Returns the measurement system's node id
- TAU_PROFILE_GET_CONTEXT - Gives the measurement system's context id
- TAU_PROFILE_SET_THREAD - Informs the measurement system of the THREAD id
- TAU_PROFILE_GET_THREAD - Gives the measurement system's thread id
- TAU_PROFILE_SET_NODE - Informs the measurement system of the node id
- TAU_PROFILE_SET_CONTEXT - Informs the measurement system of the context id
- TAU_REGISTER_FORK - Informs the measurement system that a fork has taken place
- TAU_REGISTER_EVENT - Registers a user event
- TAU_PROFILER_REGISTER_EVENT - Registers a user event
- TAU_EVENT - Triggers a user event
- TAU_EVENT - Triggers a user event
- TAU_EVENT - Triggers a user event
- TAU_EVENT_THREAD - Triggers a user event on a given thread
- TAU_REGISTER_CONTEXT_EVENT - Registers a context event
- TAU_CONTEXT_EVENT - Triggers a context event
- TAU_TRIGGER_CONTEXT_EVENT - Triggers a context event
- TAU_EVENT - Triggers a context user event
- TAU_ENABLE_CONTEXT_EVENT - Enable a context event
- TAU_DISABLE_CONTEXT_EVENT - Disable a context event
- TAU_EVENT_SET_NAME - Sets the name of an event
- TAU_EVENT_DISABLE_MAX - Disables tracking of maximum statistic for a given event
- TAU_EVENT_DISABLE_MEAN - Disables tracking of mean statistic for a given event
- TAU_EVENT_DISABLE_MIN - Disables tracking of minimum statistic for a given event
- TAU_EVENT_DISABLE_STDDEV - Disables tracking of standard deviation statistic for a given event
- TAU_REPORT_STATISTICS - Outputs statistics
- TAU_REPORT_THREAD_STATISTICS - Outputs statistics, plus thread statistics
- TAU_ENABLE_INSTRUMENTATION - Enables instrumentation
- TAU_DISABLE_INSTRUMENTATION - Disables instrumentation
- TAU_ENABLE_GROUP - Enables tracking of a given group
- TAU_DISABLE_GROUP - Disables tracking of a given group
- TAU_PROFILE_TIMER_SET_GROUP - Change the group of a timer
- TAU_PROFILE_TIMER_SET_GROUP_NAME - Changes the group name for a timer
- TAU_PROFILE_TIMER_SET_NAME - Changes the name of a timer
- TAU_PROFILE_TIMER_SET_TYPE - Changes the type of a timer
- TAU_PROFILE_SET_GROUP_NAME - Changes the group name of a profiled section
- TAU_INIT - Processes command-line arguments for selective instrumentation
- TAU_PROFILE_INIT - Processes command-line arguments for selective instrumentation
- TAU_GET_PROFILE_GROUP - Creates groups based on names
- TAU_ENABLE_GROUP_NAME - Enables a group based on name
- TAU_DISABLE_GROUP_NAME - Disables a group based on name
- TAU_ENABLE_ALL_GROUPS - Enables instrumentation in all groups
- TAU_DISABLE_ALL_GROUPS - Disables instrumentation in all groups
- TAU_GET_EVENT_NAMES - Gets the registered user events.
- TAU_GET_EVENT_VALS - Gets user event data for given user events.
- TAU_GET_COUNTER_NAMES - Gets the counter names
- TAU_GET_FUNC_NAMES - Gets the function names
- TAU_GET_FUNC_VALS - Gets detailed performance data for given functions
- TAU_ENABLE_TRACKING_MEMORY - Enables memory tracking
- TAU_DISABLE_TRACKING_MEMORY - Disables memory tracking
- TAU_TRACK_POWER - Initializes POWER tracking system
- TAU_TRACK_POWER_HERE - Triggers power tracking at a given execution point
- TAU_ENABLE_TRACKING_POWER - Enables power headroom tracking
- TAU_DISABLE_TRACKING_POWER - Disables power headroom tracking
- TAU_TRACK_MEMORY - Initializes memory tracking system
- TAU_TRACK_MEMORY_HERE - Triggers memory tracking at a given execution point
- TAU_TRACK_MEMORY_FOOTPRINT - Initializes memory footprint tracking system
- TAU_TRACK_MEMORY_FOOTPRINT_HERE - Triggers memory footprint tracking at a given execution point
- TAU_ENABLE_TRACKING_MEMORY_HEADROOM - Enables memory headroom tracking
- TAU_DISABLE_TRACKING_MEMORY_HEADROOM - Disables memory headroom tracking
- TAU_TRACK_MEMORY_HEADROOM - Track the headroom (amount of memory for a process to grow) by periodically interrupting the program
- TAU_TRACK_MEMORY_HEADROOM_HERE - Takes a sample of the amount of memory available at a given point.
- TAU_SET_INTERRUPT_INTERVAL - Change the inter-interrupt interval for tracking memory and headroom
- CT - Returns the type information for a variable
- TAU_TYPE_STRING - Creates a type string
- TAU_DB_DUMP - Dumps the profile database to disk
- TAU_DB_MERGED_DUMP - Dumps the profile database to disk
- TAU_DB_DUMP_INCR - Dumps profile database into timestamped profiles on disk
- TAU_DB_DUMP_PREFIX - Dumps the profile database into profile files with a given prefix
- TAU_DB_DUMP_PREFIX_TASK - Dumps the profile database into profile files with a given task
- TAU_DB_PURGE - Purges the performance data.
- TAU_DUMP_FUNC_NAMES - Dumps function names to disk
- TAU_DUMP_FUNC_VALS - Dumps performance data for given functions to disk.
- TAU_DUMP_FUNC_VALS_INCR - Dumps function values with a timestamp
- TAU_PROFILE_STMT - Executes a statement only when TAU is used.
- TAU_PROFILE_CALLSTACK - Generates a callstack trace at a given location.
- TAU_TRACE_RECVMSG - Traces a receive operation
- TAU_TRACE_SENDMSG - Traces a receive operation
- TAU_PROFILE_PARAM1L - Creates a snapshot of the current apllication profile
- TAU_PROFILE_SNAPSHOT - Creates a snapshot of the current apllication profile
- TAU_PROFILE_SNAPSHOT_1L - Creates a snapshot of the current apllication profile
- TAU_PROFILER_CREATE - Creates a profiler object referenced as a standard pointer
- TAU_CREATE_TASK - Creates a task id.
- TAU_PROFILER_START - starts a profiler object created by
- TAU_PROFILER_START_TASK - Starts a profiler object created by on a given task.
- TAU_PROFILER_STOP - stops a profiler object created by
- TAU_PROFILER_STOP_TASK - Stops a profiler object on a task
- TAU_PROFILER_GET_CALLS - Gets the number of times this timer, created by , is started.
- TAU_PROFILER_GET_CALLS_TASK - Gets the number of times this timer, created by , is started on a given task.
- TAU_PROFILER_GET_CHILD_CALLS - Gets the number of calls made while this timer was running
- TAU_PROFILER_GET_CHILD_CALLS_TASK - Gets the number of child call for this timer, created by , is started on a task.
- TAU_PROFILER_GET_INCLUSIVE_VALUES - Returns the inclusive amount of a metric spend by this timer.
- TAU_PROFILER_GET_INCLUSIVE_VALUES_TASK - Returns the inclusive amount of a metric spend by this timer on a given task.
- TAU_PROFILER_GET_EXCLUSIVE_VALUES - Returns the exclusive amount of a metric spend by this timer.
- TAU_PROFILER_GET_EXCLUSIVE_VALUES_TASK - Returns the exclusive amount of a metric spend by this timer on a given task.
- TAU_PROFILER_GET_COUNTER_INFO - Returns information about all the timers created.
- TAU_PROFILER_GET_COUNTER_INFO_TASK - Returns information about all the timers created on a task.
- TAU_QUERY_DECLARE_EVENT - Returns a event handle.
- TAU_QUERY_GET_CURRENT_EVENT - set event to be the current TAU event.
- TAU_QUERY_GET_EVENT_NAME - Gets the name of a given event.
- TAU_QUERY_GET_PARENT_EVENT - gets the parent of the current event.