<!-------- @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.76 [en] (X11; U; Linux 2.4.2-2smp i686) [Netscape]"> <meta name="sandia.approved" content="SAND99-1376"> <meta name="author" content="karen devine, kddevin@sandia.gov"> <title> Zoltan Developer's Guide: Timing Routines</title> </head> <body bgcolor="#FFFFFF"> <div align=right><b><i><a href="dev.html">Zoltan Developer's Guide</a> | <a href="dev_services_zoltantimer.html">Next</a> | <a href="dev_services_hash.html">Previous</a></i></b></div> <!-------------------------------------------------------------------------> <h2> <a NAME="Timing"></a>Timing Routines</h2> To assist in performance measurements and profiling, several timing routines are included in the Zoltan library. The main timer function, <b><a href="#Zoltan_Time">Zoltan_Time</a></b>, provides access to at least two portable timers: one CPU clock and one wall clock. On most systems, user time can also be measured. A higher-level timing capability built using <b><a href="#Zoltan_Time">Zoltan_Time</a></b> is also available; see <b><a href="dev_services_zoltantimer.html">ZOLTAN_TIMER</a></b> for more details. <p> The routines included in the utility are listed below. <blockquote><b><a href="#Zoltan_Time">Zoltan_Time</a></b>: Returns the time (in seconds) after some fixed reference point in time. <br><b><a href="#Zoltan_Time_Resolution">Zoltan_Time_Resolution</a></b>: The resolution of the specified timer.</blockquote> Currently, the following timers are supported: <ul> <li> <i>ZOLTAN_TIME_WALL </i>: wall-clock time.</li> <br>On most systems, this timer calls MPI_Wtime. <li> <i>ZOLTAN_TIME_CPU </i>: cpu time.</li> <br>On most systems, this timer calls the ANSI C function clock(). Note that this timer may roll over at just 71 minutes. <b><a href="#Zoltan_Time">Zoltan_Time</a></b> attempts to keep track of the number of roll-overs but this feature will work only if <b><a href="#Zoltan_Time">Zoltan_Time</a></b> is called at least once during every period between roll-overs. <li> <i>ZOLTAN_TIME_USER </i>: user time.</li> <br>On most systems, this timer calls times(). Note that times() is required by POSIX and is widely available, but it is not required by ANSI C so may be unavailable on some systems. Compile Zoltan with -DNO_TIMES in this case.</ul> Within Zoltan, it is recommended to select which timer to use by setting the <a href="../ug_html/ug_param.html#TIMER">TIMER</a> general parameter via <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Param">Zoltan_Set_Param</a></b>. The default value of <a href="../ug_html/ug_param.html#TIMER">TIMER</a> is <i>wall</i>. Zoltan stores an integer representation of the selected timing method in <i>zz->Timer</i>. This value should be passed to <b><a href="#Zoltan_Time">Zoltan_Time</a></b>, as in <b><a href="#Zoltan_Time">Zoltan_Time</a></b>(<i>zz->Timer</i>). <p><!-------------------------------------------------------------------------> <hr><a NAME="Zoltan_Time"></a> <hr>double <b>Zoltan_Time</b>(int <i>timer</i>); <hr> <p><b>Zoltan_Time</b> returns the time in seconds, measured from some fixed reference time. Note that the time is <i>not </i>synchronized among different processors or processes. The time may be either CPU time or wall-clock time. The timer is selected through <b><a href="../ug_html/ug_interface_init.html#Zoltan_Set_Param">Zoltan_Set_Param</a></b>. <br> <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>timer</i></td> <td>The timer type (e.g., wall or cpu) represented as an integer. See <a href="#Timing">top of page</a> for a list of valid values.</td> </tr> <tr> <td><b>Returned Value:</b></td> <td></td> </tr> <tr> <td VALIGN=TOP> double </td> <td>The time in seconds. The time is always positive; a negative value indicates an error.</td> </tr> </table> <p><!-------------------------------------------------------------------------> <hr><a NAME="Zoltan_Time_Resolution"></a> <hr>double <b>Zoltan_Time_Resolution</b>(int <i>timer</i>) ; <hr> <br><b>Zoltan_Time_Resolution</b> returns the resolution of the current timer. The returned resolution is a lower bound on the actual resolution. <br> <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>timer</i></td> <td>The timer type (e.g., wall or cpu) represented as an integer. See <a href="#Timing">top of page</a> for a list of valid values.</td> </tr> <tr> <td><b>Returned Value:</b></td> <td></td> </tr> <tr> <td VALIGN=TOP> double </td> <td>The timer resolution in seconds. If the resolution is unknown, -1 is returned.</td> </tr> </table> <br> <p><!-------------------------------------------------------------------------> <hr><a NAME="Example"></a> <br><b>Example:</b> <br>Here is a simple example for how to use the timer routines: <ul><tt>double t0, t1, t2;</tt> <br><tt>Zoltan_Set_Param(zz, "TIMER", "wall");</tt> <br><tt>t0 = Zoltan_Time(zz->Timer);</tt> <br><tt>/* code segment 1 */</tt> <br><tt>t1 = Zoltan_Time(zz->Timer);</tt> <br><tt>/* code segment 2 */</tt> <br><tt>t2 = Zoltan_Time(zz->Timer);</tt> <br><tt>/* Print timing results */</tt> <br><tt>Zoltan_Print_Stats(zz->Communicator, zz->Debug_Proc, t1-t0, "Time for part 1:");</tt> <br><tt>Zoltan_Print_Stats(zz->Communicator, zz->Debug_Proc, t2-t1, "Time for part 2:");</tt> <br><tt>Zoltan_Print_Stats(zz->Communicator, zz->Debug_Proc, t2-t0, "Total time :");</tt></ul> <hr WIDTH="100%"> <br>[<a href="dev.html">Table of Contents</a> | <a href="dev_services_debug.html">Next: Debugging Services</a> | <a href="dev_services_hash.html">Previous: Hash Function</a> | <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>] </body> </html>