You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
1042 lines
25 KiB
1042 lines
25 KiB
<!-------- @HEADER
|
|
!
|
|
! !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
!
|
|
! Zoltan Toolkit for Load-balancing, Partitioning, Ordering and Coloring
|
|
! Copyright 2012 Sandia Corporation
|
|
!
|
|
! Under the terms of Contract DE-AC04-94AL85000 with Sandia Corporation,
|
|
! the U.S. Government retains certain rights in this software.
|
|
!
|
|
! Redistribution and use in source and binary forms, with or without
|
|
! modification, are permitted provided that the following conditions are
|
|
! met:
|
|
!
|
|
! 1. Redistributions of source code must retain the above copyright
|
|
! notice, this list of conditions and the following disclaimer.
|
|
!
|
|
! 2. Redistributions in binary form must reproduce the above copyright
|
|
! notice, this list of conditions and the following disclaimer in the
|
|
! documentation and/or other materials provided with the distribution.
|
|
!
|
|
! 3. Neither the name of the Corporation nor the names of the
|
|
! contributors may be used to endorse or promote products derived from
|
|
! this software without specific prior written permission.
|
|
!
|
|
! THIS SOFTWARE IS PROVIDED BY SANDIA CORPORATION "AS IS" AND ANY
|
|
! EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
! IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
|
|
! PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL SANDIA CORPORATION OR THE
|
|
! CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
|
|
! EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
|
|
! PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
|
|
! PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
|
|
! LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
|
|
! NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
|
|
! SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
!
|
|
! Questions? Contact Karen Devine kddevin@sandia.gov
|
|
! Erik Boman egboman@sandia.gov
|
|
!
|
|
! !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
|
!
|
|
! @HEADER
|
|
------->
|
|
<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
|
|
<html>
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
|
<meta name="GENERATOR" content="Mozilla/4.7 [en] (X11; U; SunOS 5.7 sun4u) [Netscape]">
|
|
<meta name="sandia.approved" content="SAND99-1376">
|
|
<meta name="author" content="karen devine, kddevin@sandia.gov">
|
|
<title> Zoltan Developer's Guide: ZoltanTimer Utilities</title>
|
|
|
|
</head>
|
|
<body bgcolor="#FFFFFF">
|
|
|
|
<div align=right><b><i><a href="dev.html">Zoltan Developer's Guide</a>
|
|
| <a href="dev_services_debug.html">Next</a> | <a href="dev_services_time.html">Previous</a></i></b></div>
|
|
<!------------------------------------------------------------------------->
|
|
|
|
<h2>
|
|
<a NAME="ZOLTANTIMER"></a>High-Level Timing Services: ZOLTAN_TIMER</h2>
|
|
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.
|
|
<p>
|
|
The ZOLTAN_TIMER uses
|
|
<b><a href="dev_services_time.html#Zoltan_Time">Zoltan_Time</a></b>
|
|
to obtain the current clock time.
|
|
<p>
|
|
NOTE: The current implementation of ZOLTAN_TIMER relies on two assumptions
|
|
to work correctly.
|
|
<ol>
|
|
<li>
|
|
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
|
|
<i>timer_idx</i> returned by <b><a href="#Init">Zoltan_Timer_Init</a></b>,
|
|
so for accurate timing,
|
|
each processor should associate the same value of <i>timer_idx</i> with
|
|
the same section of code.
|
|
<p>
|
|
<li>
|
|
ZOLTAN_TIMER uses synchronization in
|
|
<b><a href="#Print">Zoltan_Timer_Print</a></b> and
|
|
<b><a href="#PrintAll">Zoltan_Timer_PrintAll</a></b>, and optionally in
|
|
<b><a href="#Start">ZOLTAN_TIMER_START</a></b> and
|
|
<b><a href="#Stop">ZOLTAN_TIMER_STOP</a></b>. 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.
|
|
</ol>
|
|
<p>
|
|
In future work, these constraints may be weakened so that, for instance,
|
|
different processors may have different numbers of timers or skip
|
|
synchronization points.
|
|
<p>
|
|
<p>
|
|
<hr>
|
|
<table>
|
|
<tr VALIGN=TOP>
|
|
<td WIDTH="50%">
|
|
<b>Source code location:</b>
|
|
</td>
|
|
<td WIDTH="50%">
|
|
<i>Utilities/Timer</i>
|
|
</td>
|
|
</tr>
|
|
<tr VALIGN=TOP>
|
|
<td>
|
|
<b>Function prototypes file:</b>
|
|
</td>
|
|
<td>
|
|
<i>Utilities/Timer/zoltan_timer.h</i> or <i>include/zoltan_timer.h</i>
|
|
<i>Utilities/Timer/zoltan_timer_cpp.h</i> or <i>include/zoltan_timer_cpp.h</i>
|
|
</td>
|
|
</tr>
|
|
<tr VALIGN=TOP>
|
|
<td>
|
|
<b>Library name:</b>
|
|
</td>
|
|
<td>
|
|
libzoltan_timer.a
|
|
</td>
|
|
</tr>
|
|
<tr VALIGN=TOP>
|
|
<td>
|
|
<b>Other libraries used by this library:</b>
|
|
</td>
|
|
<td>
|
|
libmpi.a and libzoltan_mem.a.
|
|
</td>
|
|
</tr>
|
|
<tr VALIGN=TOP>
|
|
<td COLSPAN="2">
|
|
<b>Routines:</b>
|
|
<blockquote>
|
|
<a href="#Create">Zoltan_Timer_Create</a>: Creates a ZOLTAN_TIMER object to store timers.<br>
|
|
<a href="#Init">Zoltan_Timer_Init</a>: Initializes a new timer.<br>
|
|
<a href="#Start">ZOLTAN_TIMER_START</a>: Starts a single timer.<br>
|
|
<a href="#Stop">ZOLTAN_TIMER_STOP</a>: Stops a single timer.<br>
|
|
<a href="#Print">Zoltan_Timer_Print</a>: Prints the values of a single timer.<br>
|
|
<a href="#PrintAll">Zoltan_Timer_PrintAll</a>: Prints the values of all timers.<br>
|
|
<a href="#Reset">Zoltan_Timer_Reset</a>: Resets a single timer.<br>
|
|
<a href="#Copy">Zoltan_Timer_Copy</a>: Copies a ZOLTAN_TIMER object to newly
|
|
allocated memory.<br>
|
|
<a href="#CopyTo">Zoltan_Timer_Copy_To</a>: Copies a ZOLTAN_TIMER object to existing memory.<br>
|
|
<a href="#Destroy">Zoltan_Timer_Destroy</a>: Frees a ZOLTAN_TIMER object.<br>
|
|
</blockquote>
|
|
</td>
|
|
</tr>
|
|
<tr VALIGN=TOP>
|
|
<td COLSPAN="2">
|
|
<b>Use in Zoltan:</b>
|
|
<blockquote>
|
|
The ZOLTAN_TIMER utilities are used in Zoltan's graph and hypergraph
|
|
algorithms. It is activated
|
|
by setting parameter <i>use_timers</i> to a positive integer value.
|
|
<p>
|
|
</blockquote>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<!------------------------------------------------------------------------->
|
|
<hr>
|
|
<a NAME="Create"></a>
|
|
<hr>
|
|
<table width="100%">
|
|
<tr>
|
|
<td width="20%" valign=top>
|
|
C:
|
|
</td>
|
|
<td width="80%" valign=top>
|
|
struct Zoltan_Timer *<b>Zoltan_Timer_Create</b>(
|
|
int <i>timer_flag</i>);
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign=top>
|
|
C++:
|
|
</td>
|
|
<td valign=top>
|
|
<b>Zoltan_Timer_Object(int <i>timer_flag</i>);</b>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<hr>
|
|
<b>Zoltan_Timer_Create</b> 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.
|
|
<p>
|
|
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.
|
|
<p>
|
|
<table WIDTH="100%" >
|
|
<tr VALIGN=TOP>
|
|
<td VALIGN=TOP WIDTH="20%"><b>Input Arguments:</b></td>
|
|
|
|
<td WIDTH="80%"></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP><i> timer_flag</i>
|
|
</td>
|
|
<td>
|
|
A flag indicating the type of timer to be used; it is passed to
|
|
calls to <b><a href="dev_services_time.html#Zoltan_Time">Zoltan_Time</a></b>.
|
|
Valid values are
|
|
<i>ZOLTAN_TIME_WALL</i>, <i>ZOLTAN_TIME_CPU</i>, <i>ZOLTAN_TIME_USER</i>
|
|
and <i>ZOLTAN_TIME_DEF</i> (the default timer). See the
|
|
<a href="dev_services_time.html">timing routines</a> for more information
|
|
about the timer_flag values.
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><b>Returned Value:</b></td>
|
|
|
|
<td></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP> struct Zoltan_Timer *</td>
|
|
|
|
<td>
|
|
Pointer to memory for storage of Zoltan_Timer information. If an error occurs,
|
|
NULL will be returned in C.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p>
|
|
|
|
<!------------------------------------------------------------------------->
|
|
<hr>
|
|
<a NAME="Init"></a>
|
|
<hr>
|
|
<table width="100%">
|
|
<tr>
|
|
<td width="20%" valign=top>
|
|
C:
|
|
</td>
|
|
<td width="80%" valign=top>
|
|
int <b>Zoltan_Timer_Init</b>(
|
|
struct Zoltan_Timer *<i>zt</i>,
|
|
int <i>use_barrier</i>,
|
|
const char *<i>timer_name</i>
|
|
);
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign=top>
|
|
C++:
|
|
</td>
|
|
<td valign=top>
|
|
int <b>Zoltan_Timer_Object::Init</b>(
|
|
const int <i>use_barrier</i>,
|
|
const std::string & timer_name);
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<hr>
|
|
<b>Zoltan_Timer_Init</b> 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
|
|
<b>Zoltan_Timer_Init</b> and is later used to indicate which timer to start or
|
|
stop. It is also used to accrue times across multiple processors.
|
|
<b>Zoltan_Timer_Init</b> may be called several times with the
|
|
same Zoltan_Timer object to create many different times within the object.
|
|
<p>
|
|
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.
|
|
<p>
|
|
<table WIDTH="100%" >
|
|
<tr VALIGN=TOP>
|
|
<td VALIGN=TOP WIDTH="20%"><b>Input Arguments:</b></td>
|
|
|
|
<td WIDTH="80%"></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP><i> <i>zt</i>
|
|
</td>
|
|
<td>
|
|
Pointer to the Zoltan_Timer struct returned by <b><a
|
|
href="#Create">Zoltan_Timer_Create</a></b>.
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP><i> <i>use_barrier</i>
|
|
</td>
|
|
<td>
|
|
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.
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP><i> <i>timer_name</i>
|
|
</td>
|
|
<td>
|
|
A character string associated with the timer; it is printed as the timer
|
|
name in <b><a href="#Print">Zoltan_Timer_Print</a></b> and
|
|
<b><a href="#PrintAll">Zoltan_Timer_PrintAll</a></b>.
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><b>Returned Value:</b></td>
|
|
|
|
<td></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP> int</td>
|
|
|
|
<td>
|
|
The unique integer identifier for this timer.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<!------------------------------------------------------------------------->
|
|
<hr>
|
|
<a NAME="Start"></a>
|
|
<hr>
|
|
<table width="100%">
|
|
<tr>
|
|
<td width="20%" valign=top>
|
|
C:
|
|
</td>
|
|
<td width="80%" valign=top>
|
|
int <b>ZOLTAN_TIMER_START</b>(
|
|
struct Zoltan_Timer *<i>zt</i>,
|
|
int <i>timer_idx</i>,
|
|
MPI_COMM <i>communicator</i>
|
|
);
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign=top>
|
|
C++:
|
|
</td>
|
|
<td valign=top>
|
|
int <b>Zoltan_Timer_Object::Start</b>(
|
|
const int <i>timer_idx</i>,
|
|
const MPI_COMM & communicator);
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<hr>
|
|
<b>ZOLTAN_TIMER_START</b> starts the timer with index <i>timer_idx</i>
|
|
associated with the Zoltan_Timer struct <i>zt</i>. Error checking ensures
|
|
that the timer is not already running before it is started. If the timer
|
|
timer_idx
|
|
was initialized with <i>use_barrier</i>=1, all processors should start
|
|
the timer at the same point in the code.
|
|
<p>
|
|
<table WIDTH="100%" >
|
|
<tr VALIGN=TOP>
|
|
<td VALIGN=TOP WIDTH="20%"><b>Input Arguments:</b></td>
|
|
|
|
<td WIDTH="80%"></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP><i> <i>zt</i>
|
|
</td>
|
|
<td>
|
|
Pointer to the Zoltan_Timer struct returned by <b><a
|
|
href="#Create">Zoltan_Timer_Create</a></b>.
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP><i> <i>timer_idx</i>
|
|
</td>
|
|
<td>
|
|
The integer timer index
|
|
(returned by <b><a href="#Init">Zoltan_Timer_Init</a></b>)
|
|
of the timer to be started.
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP><i> <i>communicator</i>
|
|
</td>
|
|
<td>
|
|
The MPI communicator to be used for synchronization is the timer was
|
|
initialized with <i>use_barrier</i>=1.
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><b>Returned Value:</b></td>
|
|
|
|
<td></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP> int</td>
|
|
|
|
<td>
|
|
Error code indicating whether the timer started successfully.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<!------------------------------------------------------------------------->
|
|
<hr>
|
|
<a NAME="Stop"></a>
|
|
<hr>
|
|
<table width="100%">
|
|
<tr>
|
|
<td width="20%" valign=top>
|
|
C:
|
|
</td>
|
|
<td width="80%" valign=top>
|
|
int <b>ZOLTAN_TIMER_STOP</b>(
|
|
struct Zoltan_Timer *<i>zt</i>,
|
|
int <i>timer_idx</i>,
|
|
MPI_COMM <i>communicator</i>
|
|
);
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign=top>
|
|
C++:
|
|
</td>
|
|
<td valign=top>
|
|
int <b>Zoltan_Timer_Object::Stop</b>(
|
|
const int <i>timer_idx</i>,
|
|
const MPI_COMM & communicator);
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<hr>
|
|
<b>ZOLTAN_TIMER_STOP</b> stops the timer with index <i>timer_idx</i>
|
|
associated with the Zoltan_Timer struct <i>zt</i>. Error checking ensures
|
|
that the timer is already running before it is stopped. If the timer
|
|
timer_idx
|
|
was initialized with <i>use_barrier</i>=1, all processors should stop
|
|
the timer at the same point in the code.
|
|
<p>
|
|
<table WIDTH="100%" >
|
|
<tr VALIGN=TOP>
|
|
<td VALIGN=TOP WIDTH="20%"><b>Input Arguments:</b></td>
|
|
|
|
<td WIDTH="80%"></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP><i> <i>zt</i>
|
|
</td>
|
|
<td>
|
|
Pointer to the Zoltan_Timer struct returned by <b><a
|
|
href="#Create">Zoltan_Timer_Create</a></b>.
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP><i> <i>timer_idx</i>
|
|
</td>
|
|
<td>
|
|
The integer timer index
|
|
(returned by <b><a href="#Init">Zoltan_Timer_Init</a></b>)
|
|
of the timer to be stopped.
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP><i> <i>communicator</i>
|
|
</td>
|
|
<td>
|
|
The MPI communicator to be used for synchronization is the timer was
|
|
initialized with <i>use_barrier</i>=1.
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><b>Returned Value:</b></td>
|
|
|
|
<td></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP> int</td>
|
|
|
|
<td>
|
|
Error code indicating whether the timer stopped successfully.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<!------------------------------------------------------------------------->
|
|
<hr>
|
|
<a NAME="Print"></a>
|
|
<hr>
|
|
<table width="100%">
|
|
<tr>
|
|
<td width="20%" valign=top>
|
|
C:
|
|
</td>
|
|
<td width="80%" valign=top>
|
|
int <b>Zoltan_Timer_Print</b>(
|
|
struct Zoltan_Timer *<i>zt</i>,
|
|
int <i>timer_idx</i>,
|
|
int <i>proc</i>,
|
|
MPI_Comm <i>comm</i>,
|
|
FILE *<i>fp</i>
|
|
);
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign=top>
|
|
C++:
|
|
</td>
|
|
<td valign=top>
|
|
int <b>Zoltan_Timer_Object::Print</b>(
|
|
const int <i>timer_idx</i>,
|
|
const int <i>proc</i>,
|
|
const MPI_Comm &<i>comm</i>,
|
|
FILE *<i>fp</i>
|
|
);
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<hr>
|
|
<b>Zoltan_Timer_Print</b> accrues accumulated times for a single timer
|
|
<i>timer_idx</i> across a communicator and computes the minimum, maximum and
|
|
average values across all processors of the MPI communicator <i>comm</i>.
|
|
These values, as well as the timer index <i>timer_idx</i> and timer name,
|
|
are then printed by processor <i>proc</i>.
|
|
Because of the synchronization needed to compute the minimum, maximum and
|
|
average values, <b>Zoltan_Timer_Print</b> must be called by all processors in
|
|
the communicator <i>comm</i>. Communicator MPI_COMM_SELF can be used to print
|
|
a single processor's timer values.
|
|
<p>
|
|
<table WIDTH="100%" >
|
|
<tr VALIGN=TOP>
|
|
<td VALIGN=TOP WIDTH="20%"><b>Input Arguments:</b></td>
|
|
|
|
<td WIDTH="80%"></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP><i> <i>zt</i>
|
|
</td>
|
|
<td>
|
|
Pointer to the Zoltan_Timer struct returned by <b><a
|
|
href="#Create">Zoltan_Timer_Create</a></b>.
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP><i> <i>timer_idx</i>
|
|
</td>
|
|
<td>
|
|
The integer timer index
|
|
(returned by <b><a href="#Init">Zoltan_Timer_Init</a></b>)
|
|
of the timer to be printed.
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP><i> <i>proc</i>
|
|
</td>
|
|
<td>
|
|
The rank (within MPI communicator <i>comm</i>) of the processor that should
|
|
print the timer's values.
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP><i> <i>comm</i>
|
|
</td>
|
|
<td>
|
|
The MPI communicator across which minimum, maximum and average values
|
|
of the timer should be computed.
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP><i> <i>fp</i>
|
|
</td>
|
|
<td>
|
|
The file pointer to a open, writable file to which timer values
|
|
should be printed.
|
|
Special files <i>stdout</i>
|
|
and <i>stderr</i> are also legal values for this argument.
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><b>Returned Value:</b></td>
|
|
|
|
<td></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP> int</td>
|
|
|
|
<td>
|
|
Error code.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<!------------------------------------------------------------------------->
|
|
<hr>
|
|
<a NAME="PrintAll"></a>
|
|
<hr>
|
|
<table width="100%">
|
|
<tr>
|
|
<td width="20%" valign=top>
|
|
C:
|
|
</td>
|
|
<td width="80%" valign=top>
|
|
int <b>Zoltan_Timer_PrintAll</b>(
|
|
struct Zoltan_Timer *<i>zt</i>,
|
|
int <i>proc</i>,
|
|
MPI_Comm <i>comm</i>,
|
|
FILE *<i>fp</i>
|
|
);
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign=top>
|
|
C++:
|
|
</td>
|
|
<td valign=top>
|
|
int <b>Zoltan_Timer_Object::PrintAll</b>(
|
|
const int <i>proc</i>,
|
|
const MPI_Comm &<i>comm</i>,
|
|
FILE *<i>fp</i>
|
|
);
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<hr>
|
|
<b>Zoltan_Timer_PrintAll</b> accrues accumulated times for all timers
|
|
in <i>zt</i> across a communicator and computes the minimum, maximum and
|
|
average values across all processors of the MPI communicator <i>comm</i>.
|
|
The timer values for each timer, as well as its timer index and timer name,
|
|
are then printed by processor <i>proc</i>.
|
|
Because of the synchronization needed to compute the minimum, maximum and
|
|
average values, <b>Zoltan_Timer_PrintAll</b> must be called by all processors in
|
|
the communicator <i>comm</i>. Communicator MPI_COMM_SELF can be used to print
|
|
a single processor's timer values.
|
|
<p>
|
|
<table WIDTH="100%" >
|
|
<tr VALIGN=TOP>
|
|
<td VALIGN=TOP WIDTH="20%"><b>Input Arguments:</b></td>
|
|
|
|
<td WIDTH="80%"></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP><i> <i>zt</i>
|
|
</td>
|
|
<td>
|
|
Pointer to the Zoltan_Timer struct returned by <b><a
|
|
href="#Create">Zoltan_Timer_Create</a></b>.
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP><i> <i>proc</i>
|
|
</td>
|
|
<td>
|
|
The rank (within MPI communicator <i>comm</i>) of the processor that should
|
|
print the timer's values.
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP><i> <i>comm</i>
|
|
</td>
|
|
<td>
|
|
The MPI communicator across which minimum, maximum and average values
|
|
of the timer should be computed.
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP><i> <i>fp</i>
|
|
</td>
|
|
<td>
|
|
The file pointer to a open, writable file to which timer values
|
|
should be printed.
|
|
Special files <i>stdout</i>
|
|
and <i>stderr</i> are also legal values for this argument.
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><b>Returned Value:</b></td>
|
|
|
|
<td></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP> int</td>
|
|
|
|
<td>
|
|
Error code.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<!------------------------------------------------------------------------->
|
|
<hr>
|
|
<a NAME="Reset"></a>
|
|
<hr>
|
|
<table width="100%">
|
|
<tr>
|
|
<td width="20%" valign=top>
|
|
C:
|
|
</td>
|
|
<td width="80%" valign=top>
|
|
int <b>Zoltan_Timer_Reset</b>(
|
|
struct Zoltan_Timer *<i>zt</i>,
|
|
int <i>timer_idx</i>,
|
|
int <i>use_barrier</i>,
|
|
const char *<i>timer_name</i>
|
|
);
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign=top>
|
|
C++:
|
|
</td>
|
|
<td valign=top>
|
|
int <b>Zoltan_Timer_Object::Reset</b>(
|
|
const int <i>timer_idx</i>,
|
|
const int <i>use_barrier</i>,
|
|
const std::string & timer_name);
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<hr>
|
|
<b>Zoltan_Timer_Reset</b> resets the single timer represented by
|
|
<i>timer_idx</i> within a Zoltan_Timer
|
|
object. The accumulated time within the timer is reset to zero.
|
|
The timer's name <i>timer_name</i> and the flag <i>use_barrier</i>
|
|
indicating whether the
|
|
timer should be started and stopped synchronously across processors
|
|
may be changed as well.
|
|
<p>
|
|
<table WIDTH="100%" >
|
|
<tr VALIGN=TOP>
|
|
<td VALIGN=TOP WIDTH="20%"><b>Input Arguments:</b></td>
|
|
|
|
<td WIDTH="80%"></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP><i> <i>zt</i>
|
|
</td>
|
|
<td>
|
|
Pointer to the Zoltan_Timer struct returned by <b><a
|
|
href="#Create">Zoltan_Timer_Create</a></b>.
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP><i> <i>timer_idx</i>
|
|
</td>
|
|
<td>
|
|
The integer timer index
|
|
(returned by <b><a href="#Init">Zoltan_Timer_Init</a></b>)
|
|
of the timer to be reset.
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP><i> <i>use_barrier</i>
|
|
</td>
|
|
<td>
|
|
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.
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP><i> <i>timer_name</i>
|
|
</td>
|
|
<td>
|
|
A character string associated with the timer; it is printed as the timer
|
|
name in <b><a href="#Print">Zoltan_Timer_Print</a></b> and
|
|
<b><a href="#PrintAll">Zoltan_Timer_PrintAll</a></b>.
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><b>Returned Value:</b></td>
|
|
|
|
<td></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP> int</td>
|
|
|
|
<td>
|
|
Error code indicating whether or not the timer was reset correctly.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<!------------------------------------------------------------------------->
|
|
<hr>
|
|
<a NAME="Copy"></a>
|
|
<hr>
|
|
<table width="100%">
|
|
<tr>
|
|
<td width="20%" valign=top>
|
|
C:
|
|
</td>
|
|
<td width="80%" valign=top>
|
|
struct Zoltan_Timer *<b>Zoltan_Timer_Copy</b>(
|
|
struct Zoltan_Timer *<i>from</i>);
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign=top>
|
|
C++:
|
|
</td>
|
|
<td valign=top>
|
|
<b>Zoltan_Timer_Object</b>(const Zoltan_Timer_Object &<i>from</i>);
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<hr>
|
|
<b>Zoltan_Timer_Copy</b> creates a new ZOLTAN_TIMER object and copies the
|
|
state of the existing ZOLTAN_TIMER object <i>from</i> to the new object.
|
|
It returns the new ZOLTAN_TIMER object.
|
|
<p>
|
|
In C++, there is no direct interface to <b>Zoltan_Timer_Copy</b>.
|
|
Instead, the Zoltan_Timer_Object copy constructor invokes the C library
|
|
function <b>Zoltan_Timer_Copy</b>.
|
|
<p>
|
|
<table WIDTH="100%" >
|
|
<tr VALIGN=TOP>
|
|
<td VALIGN=TOP WIDTH="20%"><b>Input Arguments:</b></td>
|
|
|
|
<td WIDTH="80%"></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP><i> <i>from</i>
|
|
</td>
|
|
<td>
|
|
Pointer to the Zoltan_Timer struct returned by <b><a
|
|
href="#Create">Zoltan_Timer_Create</a></b> whose state is to be copied to
|
|
new memory.
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><b>Returned Value:</b></td>
|
|
|
|
<td></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP> struct Zoltan_Timer *</td>
|
|
|
|
<td>
|
|
Pointer to memory for storage of the copied Zoltan_Timer information.
|
|
If an error occurs, NULL will be returned in C.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
|
|
<!------------------------------------------------------------------------->
|
|
<hr>
|
|
<a NAME="CopyTo"></a>
|
|
<hr>
|
|
<table width="100%">
|
|
<tr>
|
|
<td width="20%" valign=top>
|
|
C:
|
|
</td>
|
|
<td width="80%" valign=top>
|
|
int <b>Zoltan_Timer_Copy_To</b>(
|
|
struct Zoltan_Timer **<i>to</i>,
|
|
struct Zoltan_Timer *<i>from</i>
|
|
);
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign=top>
|
|
C++:
|
|
</td>
|
|
<td valign=top>
|
|
<b>Zoltan_Timer_Object</b> & operator =(const Zoltan_Timer_Object &<i>from</i>);
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<hr>
|
|
<b>Zoltan_Timer_Copy_To</b> copies one ZOLTAN_TIMER object to another, after
|
|
first freeing any memory used by the targe ZOLTAN_TIMER object and
|
|
re-initilizing it.
|
|
<p>
|
|
The C++ interface to <b>Zoltan_Timer_Copy_To</b> is through the
|
|
Zoltan_Timer_Object copy operator
|
|
which invokes the C library
|
|
function <b>Zoltan_Timer_Copy_To</b>.
|
|
<p>
|
|
<table WIDTH="100%" >
|
|
<tr VALIGN=TOP>
|
|
<td VALIGN=TOP WIDTH="20%"><b>Arguments:</b></td>
|
|
|
|
<td WIDTH="80%"></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP><i> <i>to</i>
|
|
</td>
|
|
<td>
|
|
Pointer to the Zoltan_Timer struct
|
|
whose state is to be overwritten with the state of <i>from</i>.
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP><i> <i>from</i>
|
|
</td>
|
|
<td>
|
|
Pointer to the Zoltan_Timer struct returned by <b><a
|
|
href="#Create">Zoltan_Timer_Create</a></b> whose state is to be copied to
|
|
<i>to</i>.
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><b>Returned Value:</b></td>
|
|
|
|
<td></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP> int</td>
|
|
|
|
<td>
|
|
Error code.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<!------------------------------------------------------------------------->
|
|
<hr>
|
|
<a NAME="Destroy"></a>
|
|
<hr>
|
|
<table width="100%">
|
|
<tr>
|
|
<td width="20%" valign=top>
|
|
C:
|
|
</td>
|
|
<td width="80%" valign=top>
|
|
void <b>Zoltan_Timer_Destroy</b>(
|
|
struct Zoltan_Timer **<i>zt</i>);
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign=top>
|
|
C++:
|
|
</td>
|
|
<td valign=top>
|
|
<b>~Zoltan_Timer_Object();</b>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<hr>
|
|
<b>Zoltan_Timer_Destroy</b> frees memory allocated by
|
|
<a href="#Create"><b>Zoltan_Timer_Create</b></a> and in C, sets the
|
|
timer pointer <i>zt</i> to NULL. <b>Zoltan_Timer_Destroy</b> should be
|
|
called when an application is finished using a timer object.
|
|
<p>
|
|
In C++, the Zoltan_Timer_Object class represents a Zoltan_Timer
|
|
data
|
|
structure and the functions that operate on it. <b>Zoltan_Timer_Destroy</b>
|
|
is called by the
|
|
destructor for the Zoltan_Timer_Object.
|
|
<p>
|
|
<table WIDTH="100%" >
|
|
<tr VALIGN=TOP>
|
|
<td VALIGN=TOP WIDTH="20%"><b>Input Arguments:</b></td>
|
|
|
|
<td WIDTH="80%"></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP><i> <i>zt</i>
|
|
</td>
|
|
<td>
|
|
Pointer to the pointer to the Zoltan_Timer struct returned by <b><a
|
|
href="#Create">Zoltan_Timer_Create</a></b>. Upon return, zt is set to NULL.
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><b>Returned Value:</b></td>
|
|
|
|
<td></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP> None. </td>
|
|
|
|
<td>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p>
|
|
|
|
<!------------------------------------------------------------------------->
|
|
<p>
|
|
|
|
<hr WIDTH="100%">
|
|
<br>[<a href="ug.html">Table of Contents</a> | <a href="dev_services_debug.html">Next:
|
|
Debugging Services</a> | <a href="dev_services_time.html">Previous:
|
|
Timing Routines</a> | <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
|
|
</body>
|
|
</html>
|
|
|