Zoltan Developer's Guide  |  Next  |  Previous

High-Level Timing Services: ZOLTAN_TIMER

The ZOLTAN_TIMER provides high-level capability for instrumenting code with timers and reporting the execution times measured. The ZOLTAN_TIMER can store many separate timers within a single ZOLTAN_TIMER object and associate a name with each timer for ease of reporting. It can perform parallel synchronization among processors using a time to ensure that all time is attributed to the correct section of the timed code. Its output contains the maximum, minimum and average times over sets of processors.

The ZOLTAN_TIMER uses Zoltan_Time to obtain the current clock time.

NOTE: The current implementation of ZOLTAN_TIMER relies on two assumptions to work correctly.

  1. ZOLTAN_TIMER assumes that individual timers within a single ZOLTAN_TIMER object are initialized in the same order on all processors. Times over multiple processors are accrued based on the value of the timer_idx returned by Zoltan_Timer_Init, so for accurate timing, each processor should associate the same value of timer_idx with the same section of code.

  2. ZOLTAN_TIMER uses synchronization in Zoltan_Timer_Print and Zoltan_Timer_PrintAll, and optionally in ZOLTAN_TIMER_START and ZOLTAN_TIMER_STOP. For these routines to work properly, then, all processors must call them at the same place in the code to satisfy the synchronization. A possible workaround is to provide MPI_COMM_SELF as an argument to these functions for single-processor timing.

In future work, these constraints may be weakened so that, for instance, different processors may have different numbers of timers or skip synchronization points.

Source code location: Utilities/Timer
Function prototypes file: Utilities/Timer/zoltan_timer.h or include/zoltan_timer.h Utilities/Timer/zoltan_timer_cpp.h or include/zoltan_timer_cpp.h
Library name: libzoltan_timer.a
Other libraries used by this library: libmpi.a and libzoltan_mem.a.
Routines:
Zoltan_Timer_Create: Creates a ZOLTAN_TIMER object to store timers.
Zoltan_Timer_Init: Initializes a new timer.
ZOLTAN_TIMER_START: Starts a single timer.
ZOLTAN_TIMER_STOP: Stops a single timer.
Zoltan_Timer_Print: Prints the values of a single timer.
Zoltan_Timer_PrintAll: Prints the values of all timers.
Zoltan_Timer_Reset: Resets a single timer.
Zoltan_Timer_Copy: Copies a ZOLTAN_TIMER object to newly allocated memory.
Zoltan_Timer_Copy_To: Copies a ZOLTAN_TIMER object to existing memory.
Zoltan_Timer_Destroy: Frees a ZOLTAN_TIMER object.
Use in Zoltan:
The ZOLTAN_TIMER utilities are used in Zoltan's graph and hypergraph algorithms. It is activated by setting parameter use_timers to a positive integer value.

C: struct Zoltan_Timer *Zoltan_Timer_Create( int timer_flag);
C++: Zoltan_Timer_Object(int timer_flag);
Zoltan_Timer_Create allocates memory for storing information to be used by the Zoltan_Timer. The pointer returned by this function is passed to many subsequent functions. An application or Zoltan itself may allocate more than one Zoltan_Timer data structure; for example, a separate Zoltan_Timer may be used in different partitioning algorithms or in different routines.

In the C++ interface, the Zoltan_Timer_Object class represents a Zoltan_Timer data structure and the functions that operate on it. It is the constructor that allocates an instance of a Zoltan_Timer_Object. It has no return value.

Input Arguments:
    timer_flag A flag indicating the type of timer to be used; it is passed to calls to Zoltan_Time. Valid values are ZOLTAN_TIME_WALL, ZOLTAN_TIME_CPU, ZOLTAN_TIME_USER and ZOLTAN_TIME_DEF (the default timer). See the timing routines for more information about the timer_flag values.
Returned Value:
   struct Zoltan_Timer * Pointer to memory for storage of Zoltan_Timer information. If an error occurs, NULL will be returned in C.

C: int Zoltan_Timer_Init( struct Zoltan_Timer *zt, int use_barrier, const char *timer_name );
C++: int Zoltan_Timer_Object::Init( const int use_barrier, const std::string & timer_name);
Zoltan_Timer_Init initializes a single timer within a Zoltan_Timer object. Each timer in the Zoltan_Timer object is assigned a unique integer, which is returned by Zoltan_Timer_Init and is later used to indicate which timer to start or stop. It is also used to accrue times across multiple processors. Zoltan_Timer_Init may be called several times with the same Zoltan_Timer object to create many different times within the object.

Note that processors must initialize multiple timers within a Zoltan_Timer object in the same order to ensure that the returned timer index value is the same on each processor.

Input Arguments:
   zt Pointer to the Zoltan_Timer struct returned by Zoltan_Timer_Create.
   use_barrier Flag indicating whether to synchronize processors before starting or stopping a timer. A value of 1 causes MPI_Barrier to be invoked before the timer is started or stopped; a value of 0 provides no synchronization.
   timer_name A character string associated with the timer; it is printed as the timer name in Zoltan_Timer_Print and Zoltan_Timer_PrintAll.
Returned Value:
   int The unique integer identifier for this timer.

C: int ZOLTAN_TIMER_START( struct Zoltan_Timer *zt, int timer_idx, MPI_COMM communicator );
C++: int Zoltan_Timer_Object::Start( const int timer_idx, const MPI_COMM & communicator);
ZOLTAN_TIMER_START starts the timer with index timer_idx associated with the Zoltan_Timer struct zt. Error checking ensures that the timer is not already running before it is started. If the timer timer_idx was initialized with use_barrier=1, all processors should start the timer at the same point in the code.

Input Arguments:
   zt Pointer to the Zoltan_Timer struct returned by Zoltan_Timer_Create.
   timer_idx The integer timer index (returned by Zoltan_Timer_Init) of the timer to be started.
   communicator The MPI communicator to be used for synchronization is the timer was initialized with use_barrier=1.
Returned Value:
   int Error code indicating whether the timer started successfully.

C: int ZOLTAN_TIMER_STOP( struct Zoltan_Timer *zt, int timer_idx, MPI_COMM communicator );
C++: int Zoltan_Timer_Object::Stop( const int timer_idx, const MPI_COMM & communicator);
ZOLTAN_TIMER_STOP stops the timer with index timer_idx associated with the Zoltan_Timer struct zt. Error checking ensures that the timer is already running before it is stopped. If the timer timer_idx was initialized with use_barrier=1, all processors should stop the timer at the same point in the code.

Input Arguments:
   zt Pointer to the Zoltan_Timer struct returned by Zoltan_Timer_Create.
   timer_idx The integer timer index (returned by Zoltan_Timer_Init) of the timer to be stopped.
   communicator The MPI communicator to be used for synchronization is the timer was initialized with use_barrier=1.
Returned Value:
   int Error code indicating whether the timer stopped successfully.

C: int Zoltan_Timer_Print( struct Zoltan_Timer *zt, int timer_idx, int proc, MPI_Comm comm, FILE *fp );
C++: int Zoltan_Timer_Object::Print( const int timer_idx, const int proc, const MPI_Comm &comm, FILE *fp );
Zoltan_Timer_Print accrues accumulated times for a single timer timer_idx across a communicator and computes the minimum, maximum and average values across all processors of the MPI communicator comm. These values, as well as the timer index timer_idx and timer name, are then printed by processor proc. Because of the synchronization needed to compute the minimum, maximum and average values, Zoltan_Timer_Print must be called by all processors in the communicator comm. Communicator MPI_COMM_SELF can be used to print a single processor's timer values.

Input Arguments:
   zt Pointer to the Zoltan_Timer struct returned by Zoltan_Timer_Create.
   timer_idx The integer timer index (returned by Zoltan_Timer_Init) of the timer to be printed.
   proc The rank (within MPI communicator comm) of the processor that should print the timer's values.
   comm The MPI communicator across which minimum, maximum and average values of the timer should be computed.
   fp The file pointer to a open, writable file to which timer values should be printed. Special files stdout and stderr are also legal values for this argument.
Returned Value:
   int Error code.

C: int Zoltan_Timer_PrintAll( struct Zoltan_Timer *zt, int proc, MPI_Comm comm, FILE *fp );
C++: int Zoltan_Timer_Object::PrintAll( const int proc, const MPI_Comm &comm, FILE *fp );
Zoltan_Timer_PrintAll accrues accumulated times for all timers in zt across a communicator and computes the minimum, maximum and average values across all processors of the MPI communicator comm. The timer values for each timer, as well as its timer index and timer name, are then printed by processor proc. Because of the synchronization needed to compute the minimum, maximum and average values, Zoltan_Timer_PrintAll must be called by all processors in the communicator comm. Communicator MPI_COMM_SELF can be used to print a single processor's timer values.

Input Arguments:
   zt Pointer to the Zoltan_Timer struct returned by Zoltan_Timer_Create.
   proc The rank (within MPI communicator comm) of the processor that should print the timer's values.
   comm The MPI communicator across which minimum, maximum and average values of the timer should be computed.
   fp The file pointer to a open, writable file to which timer values should be printed. Special files stdout and stderr are also legal values for this argument.
Returned Value:
   int Error code.

C: int Zoltan_Timer_Reset( struct Zoltan_Timer *zt, int timer_idx, int use_barrier, const char *timer_name );
C++: int Zoltan_Timer_Object::Reset( const int timer_idx, const int use_barrier, const std::string & timer_name);
Zoltan_Timer_Reset resets the single timer represented by timer_idx within a Zoltan_Timer object. The accumulated time within the timer is reset to zero. The timer's name timer_name and the flag use_barrier indicating whether the timer should be started and stopped synchronously across processors may be changed as well.

Input Arguments:
   zt Pointer to the Zoltan_Timer struct returned by Zoltan_Timer_Create.
   timer_idx The integer timer index (returned by Zoltan_Timer_Init) of the timer to be reset.
   use_barrier Flag indicating whether to synchronize processors before starting or stopping a timer. A value of 1 causes MPI_Barrier to be invoked before the timer is started or stopped; a value of 0 provides no synchronization.
   timer_name A character string associated with the timer; it is printed as the timer name in Zoltan_Timer_Print and Zoltan_Timer_PrintAll.
Returned Value:
   int Error code indicating whether or not the timer was reset correctly.

C: struct Zoltan_Timer *Zoltan_Timer_Copy( struct Zoltan_Timer *from);
C++: Zoltan_Timer_Object(const Zoltan_Timer_Object &from);
Zoltan_Timer_Copy creates a new ZOLTAN_TIMER object and copies the state of the existing ZOLTAN_TIMER object from to the new object. It returns the new ZOLTAN_TIMER object.

In C++, there is no direct interface to Zoltan_Timer_Copy. Instead, the Zoltan_Timer_Object copy constructor invokes the C library function Zoltan_Timer_Copy.

Input Arguments:
   from Pointer to the Zoltan_Timer struct returned by Zoltan_Timer_Create whose state is to be copied to new memory.
Returned Value:
   struct Zoltan_Timer * Pointer to memory for storage of the copied Zoltan_Timer information. If an error occurs, NULL will be returned in C.

C: int Zoltan_Timer_Copy_To( struct Zoltan_Timer **to, struct Zoltan_Timer *from );
C++: Zoltan_Timer_Object & operator =(const Zoltan_Timer_Object &from);
Zoltan_Timer_Copy_To copies one ZOLTAN_TIMER object to another, after first freeing any memory used by the targe ZOLTAN_TIMER object and re-initilizing it.

The C++ interface to Zoltan_Timer_Copy_To is through the Zoltan_Timer_Object copy operator which invokes the C library function Zoltan_Timer_Copy_To.

Arguments:
   to Pointer to the Zoltan_Timer struct whose state is to be overwritten with the state of from.
   from Pointer to the Zoltan_Timer struct returned by Zoltan_Timer_Create whose state is to be copied to to.
Returned Value:
   int Error code.

C: void Zoltan_Timer_Destroy( struct Zoltan_Timer **zt);
C++: ~Zoltan_Timer_Object();
Zoltan_Timer_Destroy frees memory allocated by Zoltan_Timer_Create and in C, sets the timer pointer zt to NULL. Zoltan_Timer_Destroy should be called when an application is finished using a timer object.

In C++, the Zoltan_Timer_Object class represents a Zoltan_Timer data structure and the functions that operate on it. Zoltan_Timer_Destroy is called by the destructor for the Zoltan_Timer_Object.

Input Arguments:
   zt Pointer to the pointer to the Zoltan_Timer struct returned by Zoltan_Timer_Create. Upon return, zt is set to NULL.
Returned Value:
   None.


[Table of Contents  |  Next:  Debugging Services  |  Previous:  Timing Routines  |  Privacy and Security]