123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693 |
- <html>
- <head>
- <meta http-equiv="Content-Language" content="en-us">
- <meta name="GENERATOR" content="Microsoft FrontPage 5.0">
- <meta name="ProgId" content="FrontPage.Editor.Document">
- <meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
- <title>CPU Timers</title>
- <style type="text/css">
- ins {background-color:#A0FFA0}
- del {background-color:#FFA0A0}
- body
- {
- font-family: sans-serif;
- max-width : 8.5in;
- margin: 1em;
- }
- </style>
- </head>
- <body>
- <table border="0" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" width="750">
- <tr>
- <td width="300">
- <a href="../../../index.htm">
- <img src="../../../boost.png" alt="boost.png (6897 bytes)" align="middle" width="300" height="86" border="0"></a></td>
- <td align="middle" width="430">
- <font size="7">Timer Library<br>
- CPU Timers</font></td>
- </tr>
- </table>
- <table border="0" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" bgcolor="#D7EEFF" width="100%">
- <tr>
- <td><a href="index.html">Timer Home</a>
- <a href="cpu_timers.html">CPU timers</a>
- <a href="original_timer.html">Original timers</a>
- </td>
- </tr>
- </table>
- <h2><a name="Introduction">Introduction</a></h2>
- <table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" align="right">
- <tr>
- <td width="100%" bgcolor="#D7EEFF" align="center">
- <i><b>Contents</b></i></td>
- </tr>
- <tr>
- <td width="100%" bgcolor="#E8F5FF">
- <a href="#Introduction">Introduction</a><br>
- <a href="#Example">Using the timers</a><br>
- <a href="#using-auto_cpu_timer">Using <code>auto_cpu_timer</code></a><br>
- <a href="#using-cpu_timer">Using <code>cpu_timer</code></a><br>
- <a href="#Timer-accuracy">Timer accuracy</a><br>
- <a href="#Resolution">Resolution</a><br>
- <a href="#Other-concerns">Other concerns</a><br>
- <a href="#Recommendations">Recommendations</a><br>
- <a href="#Reference">Reference</a><br>
- <code> <a href="#Synopsis"><boost/timer/timer.hpp></a></code><a href="#Synopsis">
- synopsis</a><br>
- <a href="#Default-format">Default format</a><br>
- <a href="#nanosecond_type">Typedef <code>nanosecond_type</code></a><br>
- <a href="#Namespace-scope-functions">Namespace scope functions</a><br>
- <a href="#format"><code>format()</code></a><br>
-
- <a href="#Class-cpu_timer">Class <code>cpu_timer</code></a><br>
- <code> <a href="#cpu_timer-constructors">cpu_timer</a></code><a href="#cpu_timer-constructors">
- constructors, destructor</a><br>
- <code><a href="#cpu_timer-observers">cpu_timer</a></code><a href="#cpu_timer-observers">
- observers</a><br>
- <code> <a href="#cpu_timer-actions">cpu_timer</a></code><a href="#cpu_timer-actions">
- actions</a><br>
- <a href="#Class-auto_cpu_timer">Class <code>auto_cpu_timer</code></a><br>
- <code> <a href="#auto_cpu_timer-constructors">auto_cpu_timer</a></code><a href="#auto_cpu_timer-constructors"> constructors</a><br>
- <code> <a href="#auto_cpu_timer-destructor">auto_cpu_timer</a></code><a href="#auto_cpu_timer-destructor"> destructor</a><br>
- <a href="#auto_cpu_timer-observers"><code>
- auto_cpu_timer</code> observers</a><br>
- <code> <a href="#auto_cpu_timer-actions">auto_cpu_timer</a></code><a href="#auto_cpu_timer-actions"> actions</a><br>
- <a href="#History">History</a><br>
- <a href="#Acknowledgements">Acknowledgements</a></tr>
- </table>
- <p>Knowing how long a program takes to execute is useful in both test and
- production environments. It may also be helpful if such timing information is broken down
- into wall clock time, CPU time spent by the user, and CPU time spent by the
- operating system servicing user requests.</p>
- <p>Class <code><a href="#Class-cpu_timer">cpu_timer</a></code> measures
- wall clock time, user CPU process time, and system CPU process time. Class <code>
- <a href="#Class-auto_cpu_timer">auto_cpu_timer</a></code> is a refinement of
- <code>cpu_timer</code> that automatically reports the elapsed times when an <code>
- auto_cpu_timer</code> object is destroyed.</p>
- <h2><a name="Setup">Setup</a></h2>
- <p>Boost.Timer is implemented as a separately compiled library, so you must
- install binaries in a location that can be found by your linker. If you followed
- the
- <a href="http://www.boost.org/doc/libs/release/more/getting_started/index.html">
- Boost Getting Started</a> instructions, that's already done for you.</p>
- <h2><a name="Example">Using the timers</a></h2>
- <h3>Using <code><a name="using-auto_cpu_timer">auto_cpu_timer</a></code></h3>
- <p>The simplest and most common use is to add the two lines highlighted below
- to a scope you want to time. See <code>
- <a href="../example/auto_cpu_timer_example.cpp">auto_cpu_timer_example.cpp</a></code>
- for the source code. </p>
- <blockquote>
- <pre><span style="background-color: #D7EEFF">#include <boost/timer/</span><span style="background-color: #D7EEFF">timer.hpp</span><span style="background-color: #D7EEFF">></span>
- #include <cmath>
- int main()
- {
- <span style="background-color: #D7EEFF">boost::timer::auto_cpu_timer</span><span style="background-color: #D7EEFF"> t;</span>
- for (long i = 0; i < 100000000; ++i)
- std::sqrt(123.456L); // burn some time
- return 0;
- }</pre>
- </blockquote>
- <p>When the <code>auto_cpu_timer</code> object is created, it starts timing. When
- it is destroyed at the end of the scope, its destructor stops the timer and
- displays timing information on the default output stream, <code>std::cout</code>.</p>
- <p>The output of this program will look something like this:</p>
- <p><code> 5.713010s wall, 5.709637s user + 0.000000s system =
- 5.709637s CPU (99.9%)</code></p>
- <p>In other words, this program ran in <code>5.713010</code> seconds as would be measured by a
- clock on the wall, the operating system charged it for <code>5.709637</code> seconds of user CPU
- time and 0 seconds of system CPU time, the total of these two was <code>5.709637</code>, and that
- represented <code>99.9</code> percent of the wall clock time.</p>
- <p>The output stream, number of decimal places reported, and reporting format
- can be controlled by <code>auto_cpu_timer</code> constructor arguments. Here is
- what the output from the above program would look like for several different
- sets of constructor arguments:</p>
- <table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111">
- <tr>
- <td><i><b>Construction</b></i></td>
- <td><i><b>Output</b></i></td>
- </tr>
- <tr>
- <td><code><font size="1">t</font></code></td>
- <td><code><font size="1">5.713010s wall, 5.709637s user + 0.000000s system = 5.709637s
- CPU (99.9%)</font></code></td>
- </tr>
- <tr>
- <td><code><font size="1">t(std::cerr</font><font size="1">, 2)</font></code></td>
- <td><code><font size="1">5.71s wall, 5.70s user + 0.00s system = 5.70s CPU (99.9%)</font></code></td>
- </tr>
- <tr>
- <td><code><font size="1">t(1)</font></code></td>
- <td><code><font size="1">5.7s wall, 5.7s user + 0.0s system = 5.7s CPU (99.9%)</font></code></td>
- </tr>
- <tr>
- <td><code><font size="1">t(3, "%w seconds\n")</font></code></td>
- <td><code><font size="1">5.713 seconds<br>
- </font></code></td>
- </tr>
- <tr>
- <td><code><font size="1">t("%t</font><font size="1"> sec CPU, %w sec real")
- </font> </code></td>
- <td><code><font size="1">5.709637 sec CPU, 5.713010 sec real</font></code></td>
- </tr>
- </table>
- <p> The processing of the format string is described <a href="#format">here</a>.</p>
- <h3> Using <code><a name="using-cpu_timer">cpu_timer</a></code></h3>
- <p> The following code creates a checkpoint every 20 CPU seconds:</p>
- <blockquote>
- <pre>using boost::timer::cpu_timer;
- using boost::timer::cpu_times;
- using boost::timer::nanosecond_type;
- ...
- nanosecond_type const twenty_seconds(20 * 1000000000LL);
- nanosecond_type last(0);
- cpu_timer timer;
- while (more_transactions)
- {
- process_a_transaction();
- cpu_times const elapsed_times(timer.elapsed());
- nanosecond_type const elapsed(elapsed_times.system
- + elapsed_times.user);
- if (elapsed >= twenty_seconds)
- {
- ... create a checkpoint ...
- last = elapsed;
- }
- }</pre>
- </blockquote>
- <h2><a name="Timer-accuracy">Timer accuracy</a></h2>
- <p>How accurate are these timers? </p>
- <h3><a name="Resolution">Resolution</a></h3>
- <p dir="ltr">The resolution of a clock, and thus timers built on that clock,
- is the minimum period time that can be measured. The program <code>
- <a href="../test/cpu_timer_info.cpp">cpu_timer_info.cpp</a></code> measures
- the resolution of <code>cpu_timer</code>.</p>
- <table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111">
- <tr>
- <td rowspan="2" bgcolor="#D7EEFF">O/S</td>
- <td rowspan="2" bgcolor="#D7EEFF">Processor</td>
- <td colspan="2" align="center" bgcolor="#D7EEFF">Wall-clock</td>
- <td colspan="2" align="center" bgcolor="#D7EEFF">CPU</td>
- </tr>
- <tr>
- <td bgcolor="#D7EEFF">Resolution</td>
- <td bgcolor="#D7EEFF">Comments</td>
- <td align="center" bgcolor="#D7EEFF">User<br>
- Resolution</td>
- <td align="center" bgcolor="#D7EEFF">System<br>
- Resolution</td>
- </tr>
- <tr>
- <td>Mac OS X Lion</td>
- <td>Intel circa 2007</td>
- <td align="right">2100ns<br>
- 2200ns</td>
- <td>Some variation within a range.</td>
- <td>10000000ns</td>
- <td>10000000ns</td>
- </tr>
- <tr>
- <td>Ubuntu Linux 11.4</td>
- <td>Intel circa 2005</td>
- <td align="right">516ns</td>
- <td>Very little variation, typically less than 5ns </td>
- <td>10000000ns</td>
- <td>10000000ns</td>
- </tr>
- <tr>
- <td>Windows 7</td>
- <td>Intel Core i7 860 @ 2.9 GHz</td>
- <td align="right">366ns</td>
- <td>Some variation, usually in multiples of 366ns</td>
- <td>15600100ns</td>
- <td>15600100ns</td>
- </tr>
- <tr>
- <td>Windows 7</td>
- <td>Intel Mobile T7200 @ 2.0 GHz</td>
- <td align="right">2050ns</td>
- <td>Much variation. Resolution degrades when processor slows, probably due
- to known chipset errata. </td>
- <td>15600100ns</td>
- <td>15600100ns</td>
- </tr>
- <tr>
- <td>Windows XP</td>
- <td>Intel Atom N2800 @ 1.0 GHz</td>
- <td align="right">1437ns</td>
- <td>Some variation.</td>
- <td>15625000ns</td>
- <td>15625000ns</td>
- </tr>
- </table>
- <h3><a name="Other-concerns">Other concerns</a></h3>
- <p>Wall-clock timings are subject to many outside influences, such as the impact
- of other processes.</p>
- <blockquote>
- <p><code>cpu_timer</code> and <code>auto_cpu_timer</code> obtain Wall-clock
- timings from Boost.Chrono's <code>high_resolution_clock</code>. On Intel
- compatible CPU's running Windows, Linux, and Mac OS X, this is a "steady
- clock" [C++11 20.11.3], but may not be steady on other platforms. <code>
- <a href="../test/cpu_timer_info.cpp">cpu_timer_info.cpp</a></code> reports
- whether or not the <code>high_resolution_clock</code> is steady on a
- particular platform.</p>
- <p><i><b><a name="Steady-clocks">Steady clocks</a></b></i> are defined by the
- C++11 standard as clocks for which values never decrease as physical time
- advances and for which values advance at a steady rate relative to real time.
- That is, the clock may not be adjusted. Clocks that are steady never run
- backwards, even when the operating system's clock is reset backwards such as
- during a daylight saving time transition.</p>
- </blockquote>
- <p>Timings of debug builds are often several times slower
- than release builds, because compiler optimization is turned off and
- because libraries often supply very expensive error checks on debug builds.</p>
- <p>Synthetic benchmark code may be optimized way, particularly if NDEBUG is
- defined. It may be
- necessary to inspect generated code to verify this isn't happening.</p>
- <h3 dir="ltr"><a name="Recommendations">Recommendations</a></h3>
- <p dir="ltr">Think about what is important to your application. For a
- production process, the wall clock time may be what is most important. To
- study the efficiency of code, total CPU time (user + system) is often a much better measure.</p>
- <p dir="ltr">A useful recommendation is to never trust timings unless they are
- (1) at least 100 times longer than the CPU time resolution, (2) run multiple
- times, and (3) run on release builds. And results that are too good to be true
- need to be should be investigated skeptically.</p>
- <p>Shared libraries (DLLs and .so's) may incur extra time delays, including expensive
- disk accesses, the first time a timer or other function is called. If that
- would be misleading, static linking should be considered.</p>
- <h2> <a name="Reference">Reference</a></h2>
- <p> Specifications are given in the style of the C++ standard library (C++11,
- 17.5.1.4 [structure.specifications]). An additional <i>Overview</i> element may
- be provided to aid understanding. <i>Overview</i> elements are only informative
- - actual semantics are given by the other detailed specification elements.</p>
- <p dir="ltr"> Functions not specified as <code>noexcept</code> will throw <code>
- std::bad_alloc</code> exceptions if a memory allocation error occurs. Other
- errors are reported by time values of -1. [<i>Note:</i> Modern hardware and
- operating systems have robust clock subsystems, so such errors are unusual if
- even possible at all. <i>-- end note</i>]</p>
- <p dir="ltr"> The Timer library meets the same data race avoidance requirements
- as the C++11 standard library (17.6.5.9 [res.on.data.races]). Shared objects of
- Timer library types risk undefined behavior unless the user supplies a locking
- mechanism. See C++11, 17.6.4.10 [res.on.objects], <i>Shared objects and the
- library</i>. </p>
- <h3>
- <code><boost/timer/timer.hpp></code> <a name="Synopsis">synopsis</a></h3>
- <table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" width="100%">
- <tr>
- <td bgcolor="#D7EEFF">
- <blockquote>
- <pre>namespace boost
- {
- namespace timer
- {
- class <a href="#Class-cpu_timer">cpu_timer</a>; // wall clock, user, and system timer
- class <a href="#Class-auto_cpu_timer">auto_cpu_timer</a>; // automatic report() on destruction
- typedef boost::int_least64_t nanosecond_type;
- struct cpu_times
- {
- nanosecond_type wall;
- nanosecond_type user;
- nanosecond_type system;
- void clear();
- };
-
- const int <a name="default_places">default_places</a> = 6;
- std::string format(const cpu_times& times, short places, const std::string& format);
- std::string format(const cpu_times& times, short places = default_places);
- } // namespace timer
- } // namespace boost</pre>
- </blockquote>
- </td>
- </tr>
- </table>
- <h3><a name="Default-format">Default format</a></h3>
- <p>The default format is " %ws wall, %us user + %ss system = %ts CPU (%p%)\n".</p>
- <h3>Typedef <a name="nanosecond_type"><code>nanosecond_type</code></a></h3>
- <p>The typedef <code>nanosecond_type</code> provides an implementation defined type capable
- of representing nanoseconds. For POSIX and Windows systems, <code>
- nanoseconds_type</code> is <code>boost::int_least64_t</code>.</p>
- <p>The underlying type is not based on the Boost Date-Time or Chrono library to avoid a
- dependency on a large library. This design choice may change at some future
- date.</p>
- <p>Although <code>nanosecond_type</code> is capable of representing one <b>
- nanosecond</b>, the actual resolution of common operating system timers may be
- much lower. For wall clock time on desktop systems circa 2010, resolution is
- often no better than than one <b>microsecond</b>. For user and system time, typical
- resolution is 15 <b>milliseconds</b> on Windows and 10 <b>milliseconds</b> on
- POSIX.</p>
- <h3><a name="cpu_times">Struct <code>cpu_times</code></a></h3>
- <p>Struct <code>cpu_times</code> packages the elapsed wall clock time, user
- process CPU time, and system process CPU time. See
- <a href="#Current-time-values">Current time values</a> for definitions of the
- source of these elapsed times.</p>
- <pre><span style="background-color: #D7EEFF">void clear();</span></pre>
- <blockquote>
- <p><i>Effects:</i> <code>wall = user = system = 0LL</code>.</p>
- </blockquote>
- <h3><a name="Namespace-scope-functions">Namespace scope functions</a></h3>
- <pre><span style="background-color: #D7EEFF">std::string </span><a name="format"><span style="background-color: #D7EEFF">format</span></a><span style="background-color: #D7EEFF">(const </span><a href="#cpu_times"><span style="background-color: #D7EEFF">cpu_times</span></a><span style="background-color: #D7EEFF">& times, short places, const std::string& format);
- std::string </span><a name="format-2"><span style="background-color: #D7EEFF">format</span></a><span style="background-color: #D7EEFF">(const </span><a href="#cpu_times"><span style="background-color: #D7EEFF">cpu_times</span></a><span style="background-color: #D7EEFF">& times, short places = default_places);</span></pre>
- <blockquote>
- <p><i>Overview: </i>Converts <code>times</code>'s values to strings representing
- seconds to <code>places</code> decimal places, and inserts them into the return
- string as controlled by <code>format</code>.</p>
- <p><i>Remarks:</i> For the overload without the <code>format</code>
- argument, the <a href="#Default-format">default format</a> is used as <code>format</code>.</p>
- <p><i>Returns:</i> A string that is a copy of <code>format</code>, except that any
- instances of the sequences shown below are replaced by the indicated value.
- Times are reported in seconds,
- shown to <code>std::max(0, std::min(default_places, 9))</code> decimal places. Percentage is reported to one
- decimal place. [<i>Note:</i> percentage may exceed 100% due to differences in
- how operating systems measure various times. <i>--end note</i>]</p>
- <p><i><b><a name="Format-replacement-sequences">Format replacement sequences</a></b></i></p>
- <table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111">
- <tr>
- <td align="center" bgcolor="#D7EEFF"><b><i>Sequence</i></b></td>
- <td align="center" bgcolor="#D7EEFF"><b><i>Replacement value</i></b></td>
- </tr>
- <tr>
- <td align="center"><code>%w</code></td>
- <td><code>times.wall</code></td>
- </tr>
- <tr>
- <td align="center"><code>%u</code></td>
- <td><code>times.user</code></td>
- </tr>
- <tr>
- <td align="center"><code>%s</code></td>
- <td><code>times.system</code></td>
- </tr>
- <tr>
- <td align="center"><code>%t</code></td>
- <td><code>times.user + times.system</code></td>
- </tr>
- <tr>
- <td align="center"><code>%p</code></td>
- <td>The percentage of <code>times.wall</code> represented by <code>
- times.user + times.system</code></td>
- </tr>
- </table>
- </blockquote>
- <h3><a name="Class-cpu_timer">Class <code>cpu_timer</code></a></h3>
- <p> <code>cpu_timer</code> objects measure wall clock elapsed time and process elapsed
- time charged to the user and system.</p>
- <p><i><b><a name="Current-time-values">Current time values</a></b></i> are the
- current wall clock time, user process time, and system process time as provided
- by the operating system:</p>
- <ul>
- <li>Wall clock time is time as would be measured by
- an ordinary wristwatch or clock on the wall.</li>
- <li>User process time is "the CPU time charged for the
- execution of user instructions of the calling process." See
- <a href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/times.html">
- POSIX</a>.</li>
- <li>System process time is "the CPU time charged for
- execution by the system on behalf of the calling process." See
- <a href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/times.html">
- POSIX</a>.</li>
- </ul>
- <h3> <a name="cpu_timer-synopsis"> <code>cpu_timer</code> synopsis</a></h3>
- <table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" width="100%">
- <tr>
- <td bgcolor="#D7EEFF">
- <pre>
- class <a name="cpu_timer">cpu_timer</a>
- {
- public:
- // constructor
- <a href="#cpu_timer-ctor">cpu_timer</a>() noexcept;
-
- // compiler generated; shown for exposition only
- ~cpu_timer() noexcept = default;
- cpu_timer(const cpu_timer&) noexcept = default;
- cpu_timer& operator=(const cpu_timer&) noexcept = default;
- // observers
- bool <a href="#is_stopped">is_stopped</a>() const noexcept;
- cpu_times <a href="#elapsed">elapsed</a>() const noexcept;
- std::string <a href="#cpu_timer-format">format</a>(int places, const std::string& format) const;
- std::string <a href="#cpu_timer-format">format</a>(int places = default_places) const;
- // actions
- void <a href="#start">start</a>() noexcept;
- void <a href="#stop">stop</a>() noexcept;
- void <a href="#resume">resume</a>() noexcept;
- };</pre>
- </td>
- </tr>
- </table>
- <h3><a name="cpu_timer-constructors"><code>cpu_timer</code> constructor</a></h3>
- <pre><span style="background-color: #D7EEFF"><a name="cpu_timer-ctor">cpu_timer</a>() noexcept;</span></pre>
- <blockquote>
- <p><i>Effects:</i> Constructs an object of type <code>
- cpu_timer</code>. Calls<code> start()</code>.</p>
- </blockquote>
- <h3><a name="cpu_timer-observers"><code>cpu_timer</code>
- observers</a></h3>
- <pre><span style="background-color: #D7EEFF">bool</span><span style="background-color: #D7EEFF"> <a name="is_stopped">is_stopped</a>() const noexcept;</span></pre>
- <blockquote>
- <p><i>Returns:</i> <code>true</code> if <a href="#stop">stop()</a> was the most recent
- <a href="#cpu_timer-actions">action</a> function called,
- otherwise <code>false</code>.</p>
- </blockquote>
- <pre><span style="background-color: #D7EEFF">cpu_times</span><span style="background-color: #D7EEFF"> <a name="elapsed">elapsed</a>() const noexcept;</span></pre>
- <blockquote>
- <p><i>Returns:</i> If <code>is_stopped()</code>, the accumulated elapsed times
- as of the previous <a href="#stop">stop()</a>. Otherwise, the elapsed times
- accumulated between the most recent call to <a href="#start">start()</a> or
- <a href="#resume">resume()</a> and the <a href="#Current-time-values">current
- time values</a>.</p>
- </blockquote>
- <pre><span style="background-color: #D7EEFF">std::string </span><a name="cpu_timer-format"><span style="background-color: #D7EEFF">format</span></a><span style="background-color: #D7EEFF">(int</span><span style="background-color: #D7EEFF"> places, const std::string& format) const;
- std::string </span><a name="cpu_timer-format-2"><span style="background-color: #D7EEFF">format</span></a><span style="background-color: #D7EEFF">(int</span><span style="background-color: #D7EEFF"> places = </span><span style="background-color: #D7EEFF">default_places</span><span style="background-color: #D7EEFF">) const;</span></pre>
- <blockquote>
- <p><i>Overview:</i> Returns a string for the current elapsed time as formatted
- by the <a href="#format">format non-member function</a>.</p>
- <p><i>Returns:</i> <code>boost::<a href="#format">timer::format</a>(<a href="#elapsed">elapsed</a>(), places<i>[, format]</i>)</code>.</p>
- </blockquote>
- <h3><a name="cpu_timer-actions"><code>cpu_timer</code>
- actions</a></h3>
- <pre><span style="background-color: #D7EEFF">void <a name="start">start</a>() noexcept;</span></pre>
- <blockquote>
- <p dir="ltr"><i>Effects:</i> Begins accumulating elapsed time as of the <a href="#Current-time-values">current time values</a>.</p>
- <p><i>Postconditions:</i> <code>!is_stopped()</code>.</p>
- </blockquote>
- <pre><span style="background-color: #D7EEFF">void <a name="stop">stop</a>() noexcept;</span></pre>
- <blockquote>
- <p><i>Effects:</i> If <code>!is_stopped()</code>, stops accumulating elapsed
- time as of the <a href="#Current-time-values">current time values</a>.</p>
- <blockquote>
- <p>[<i>Note:</i> This is observable via <code>elapsed()</code>. <i>-- end note</i>]</p>
- </blockquote>
- <p><i>Postconditions:</i> <code>is_stopped()</code>.</p>
- </blockquote>
- <pre><span style="background-color: #D7EEFF">void <a name="resume">resume</a>() noexcept;</span></pre>
- <blockquote>
- <p><i>Overview:</i> Restarts the timer, accumulating additional elapsed time.</p>
- <p><i>Effects:</i> If <code>is_stopped()</code>, resumes accumulating
- additional elapsed time, as of the <a href="#Current-time-values">current time values</a>. Otherwise, no effect.</p>
- </blockquote>
- <h3><a name="Class-auto_cpu_timer">Class <code>auto_cpu_timer</code></a></h3>
- <p>Class <code>auto_cpu_timer</code> adds a <code>report()</code>
- function to <code>class cpu_timer</code>, and automatically calls <code>report()</code>
- on destruction.</p>
- <h3> <a name="auto_cpu_timer-synopsis"> <code>auto_cpu_timer</code> synopsis</a></h3>
- <table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" width="100%">
- <tr>
- <td bgcolor="#D7EEFF">
- <pre>
- class <a name="auto_cpu_timer">auto_cpu_timer</a> : public <a href="#cpu_timer">cpu_timer</a>
- {
- public:
- explicit <a href="#auto_cpu_timer-1">auto_cpu_timer</a>(short places = default_places);
- <a href="#auto_cpu_timer-2">auto_cpu_timer</a>(short places, const std::string& format);
- explicit <a href="#auto_cpu_timer-3">auto_cpu_timer</a>(const std::string& format);
- <a href="#auto_cpu_timer-4">auto_cpu_timer</a>(std::ostream& os, short places, const std::string& format);
- explicit <a href="#auto_cpu_timer-5">auto_cpu_timer</a>(std::ostream& os, short places = default_places);
- <a href="#auto_cpu_timer-6">auto_cpu_timer</a>(std::ostream& os, const std::string& format);
- <a href="#auto_cpu_timer-destructor">~auto_cpu_timer</a>() noexcept;
- // compiler generated; shown for exposition only
- auto_cpu_timer(const auto_cpu_timer&) = default;
- auto_cpu_timer& operator=(const auto_cpu_timer&) = default;
- // <a href="#auto_cpu_timer-observers">observers</a>
- std::ostream& <a href="#ostream">ostream</a>() const noexcept;
- short <a href="#places">places</a>() const noexcept;
- const std::string& <a href="#format_string">format_string</a>() const noexcept;
- // <a href="#auto_cpu_timer-actions">actions</a>
- void <a href="#report">report</a>();
- };</pre>
- </td>
- </tr>
- </table>
- <p dir="ltr">[<i>Note:</i> Constructors without a <code>std::ostream&</code>
- argument argument imply <code>
- std::cout</code>. An argument default is avoided as it would require including <code><iostream></code>,
- with its high costs, even when the standard streams are not used. <i>--end note</i>]</p>
- <h3><a name="auto_cpu_timer-constructors"><code>auto_cpu_timer</code> constructors</a></h3>
- <pre><span style="background-color: #D7EEFF">explicit <a name="auto_cpu_timer-1">auto_cpu_timer</a>(short</span><span style="background-color: #D7EEFF"> places = </span><span style="background-color: #D7EEFF">default_places</span><span style="background-color: #D7EEFF">);
- <a name="auto_cpu_timer-2">auto_cpu_timer</a>(short</span><span style="background-color: #D7EEFF"> places, const std::string& format);
- explicit <a name="auto_cpu_timer-3">auto_cpu_timer</a>(const</span><span style="background-color: #D7EEFF"> std::string& format);
- <a name="auto_cpu_timer-4">auto_cpu_timer</a>(std::ostream</span><span style="background-color: #D7EEFF">& </span><span style="background-color: #D7EEFF">os</span><span style="background-color: #D7EEFF">, short places, const std::string& format);<br>explicit <a name="auto_cpu_timer-5">auto_cpu_timer</a>(std::ostream</span><span style="background-color: #D7EEFF">& </span><span style="background-color: #D7EEFF">os</span><span style="background-color: #D7EEFF">, short places = </span><span style="background-color: #D7EEFF">default_places</span><span style="background-color: #D7EEFF">);<br> <a name="auto_cpu_timer-6">auto_cpu_timer</a>(std::ostream</span><span style="background-color: #D7EEFF">& </span><span style="background-color: #D7EEFF">os</span><span style="background-color: #D7EEFF">, const std::string& format);
- </span></pre>
- <blockquote>
- <p><i>Effects:</i> Constructs an object of type <code>
- auto_cpu_timer</code> and stores the ostream, places, and format string data
- needed to establish the postconditions.</p>
- <p><i>Postconditions:</i></p>
- <ul>
- <li>For overloads with an <code>os</code> argument, <code>ostream() == os</code>.
- Otherwise <code>ostream() == std::cout</code>.</li>
- <li><code>places() == places</code>.</li>
- <li>For overloads with a <code>format</code> argument, <code>format_string()
- == format</code>. Otherwise <code>format_string() == std::cout</code></li>
- </ul>
- </blockquote>
- <h3><a name="auto_cpu_timer-destructor"><code>auto_cpu_timer</code> destructor</a></h3>
- <pre><span style="background-color: #D7EEFF">~</span><span style="background-color: #D7EEFF">auto_cpu_timer</span><span style="background-color: #D7EEFF">() noexcept;</span></pre>
- <blockquote>
- <p dir="ltr"><i>Effects: </i>If <code>!is_stopped()</code>, stop(), <a href="#report">
- report()</a>.</p>
- <p dir="ltr">[<i>Note:</i> Because the function is <code>noexcept</code>,
- implementation must ensure no exception
- escapes. <i>--end note</i>]</p>
- </blockquote>
- <h3><a name="auto_cpu_timer-observers">auto_cpu_timer observers</a></h3>
- <p>The observers allow testing of constructor postconditions and specification
- of other functionality without resorting to "for exposition only" private
- members.</p>
- <pre><span style="background-color: #D7EEFF">std::ostream& <a name="ostream">ostream</a>() const noexcept;</span></pre>
- <blockquote>
- <p><i>Returns:</i> The ostream stored by construction or subsequent copy
- assignment.</p>
- </blockquote>
- <pre><span style="background-color: #D7EEFF">short <a name="places">places</a>() const noexcept;</span></pre>
- <blockquote>
- <p><i>Returns:</i> The places stored by construction or subsequent copy
- assignment.</p>
- </blockquote>
- <pre><span style="background-color: #D7EEFF">const std::string& <a name="format_string">format_string</a>() const noexcept;</span></pre>
- <blockquote>
- <p><i>Returns:</i> The format string stored by construction or subsequent copy
- assignment.</p>
- </blockquote>
- <h3><a name="auto_cpu_timer-actions"><code>auto_cpu_timer</code> actions</a></h3>
- <pre><span style="background-color: #D7EEFF">void <a name="report">report</a>();</span></pre>
- <blockquote>
- <p><i>Effects: </i>As if:</p>
- <blockquote>
- <pre>ostream() << timer::format(elapsed(), places(), format_string());</pre>
- </blockquote>
- <p>[<i>Note: </i>It may be desirable to call <code>stop()</code> before
- calling <code>report()</code> because doing I/O while the
- timer is running might produce misleading results. <code>resume()</code> may
- be called afterwards to continue timing. <i>--end note</i>]</p>
- </blockquote>
- <h2><a name="History">History</a></h2>
- <p>Beman Dawes and Rob Stewart developed version 2 of the library.</p>
- <p>Beman did the initial development. Rob contributed many corrections, comments, and suggestions. In
- particular, he suggested the <code>resume()</code> and <code>format()</code>
- functions, resulting in improved ease-of-use for several use cases.</p>
- <h2><a name="Acknowledgements">Acknowledgements</a></h2>
- <p>Comments and suggestions came from Greg Rubino, Dave Abrahams, Vicente
- Botet, and John Maddock.</p>
- <hr>
- <p><font size="2">Revised:
- <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B %Y" startspan -->08 October 2011<!--webbot bot="Timestamp" endspan i-checksum="32193" --></font></p>
- <p><font size="2">© Copyright Beman Dawes, 2006<br>
- © Copyright Beman Dawes and Robert Stewart, 2011</font></p>
- <p><font size="2">Distributed under the Boost Software License, Version 1.0. See <a href="http://www.boost.org/LICENSE_1_0.txt">www.boost.org/ LICENSE_1_0.txt</a></font></p>
- </body>
- </html>
|