|
|
Boost-Commit : |
Subject: [Boost-commit] svn:boost r74780 - trunk/libs/timer/doc
From: bdawes_at_[hidden]
Date: 2011-10-07 11:02:02
Author: bemandawes
Date: 2011-10-07 11:02:02 EDT (Fri, 07 Oct 2011)
New Revision: 74780
URL: http://svn.boost.org/trac/boost/changeset/74780
Log:
More docs fixes from Robert.
Text files modified:
trunk/libs/timer/doc/cpu_timers.html | 289 ++++++++++++++++++++-------------------
trunk/libs/timer/doc/index.html | 9
2 files changed, 151 insertions(+), 147 deletions(-)
Modified: trunk/libs/timer/doc/cpu_timers.html
==============================================================================
--- trunk/libs/timer/doc/cpu_timers.html (original)
+++ trunk/libs/timer/doc/cpu_timers.html 2011-10-07 11:02:02 EDT (Fri, 07 Oct 2011)
@@ -52,6 +52,10 @@
<a href="#Example">Using the timers</a><br>
Using auto_cpu_timer<br>
Using cpu_timer<br>
+ Timer accuracy<br>
+ Resolution<br>
+ Other concerns<br>
+ Recommendations<br>
<a href="#Reference">Reference</a><br>
<code> <boost/timer/timer.hpp></code><a href="#Synopsis">
synopsis</a><br>
@@ -74,10 +78,6 @@
<a href="#auto_cpu_timer-observers"><code>
auto_cpu_timer</code> observers</a><br>
<code> auto_cpu_timer</code> actions<br>
- Timer accuracy<br>
- Resolution<br>
- Other concerns<br>
- Recommendations<br>
<a href="#History">History</a><br>
<a href="#Acknowledgements">Acknowledgements</a><br>
</tr>
@@ -100,13 +100,13 @@
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 been done.</p>
+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 high-lighted below
+<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_example.cpp">auto_cpu_timer_example.cpp</a></code>
for the source code. </p>
@@ -127,7 +127,7 @@
<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, run with a debug build on a circa 2006 desktop processor:</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
@@ -142,8 +142,8 @@
<table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111">
<tr>
- <td><i><b>Constructor</b></i></td>
- <td><i><b>Resulting Output</b></i></td>
+ <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>
@@ -171,23 +171,145 @@
</table>
<p> The processing of the format string is described here.</p>
<h3> Using <code><a name="using-cpu_timer">cpu_timer</a></code></h3>
-<p> The following code creates a checkpoint every 20 seconds of user CPU time:</p>
+<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 last_checkpoint_time = 0;
-cpu_timer checkpoint_timer; // start the timer
-
+nanosecond_type const twenty_seconds(20 * 1000000000LL);
+nanosecond_type last(0);
+cpu_timer timer;
while (more_transactions)
{
process_a_transaction();
- if (checkpoint_timer.elapsed().user - last_checkpoint_time > 20*1000000000LL)
+ 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_checkpoint_time = checkpoint_timer.elapsed().user;
+ 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>
+ cpu_timer_info.cpp</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">O/S</td>
+ <td rowspan="2">Processor</td>
+ <td colspan="2" align="center">Wall-clock</td>
+ <td colspan="2" align="center">CPU</td>
+ </tr>
+ <tr>
+ <td>Resolution</td>
+ <td>Comments</td>
+ <td align="center">User<br>
+ Resolution</td>
+ <td align="center">System<br>
+ Resolution</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>
+ <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>
+</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", but may not be steady on other platforms. <code>
+ cpu_timer_info.cpp</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 by release builds. 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. For
+ studying 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 further investigate.</p>
+
+ <p>Shared libraries (DLL'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
@@ -204,8 +326,7 @@
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>
+<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">
@@ -225,7 +346,7 @@
nanosecond_type user;
nanosecond_type system;
- void clear() { wall = user = system = 0LL; }
+ void clear();
};
const int <a name="default_places">default_places</a> = 6;
@@ -248,7 +369,7 @@
<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_</code>t.</p>
+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
@@ -268,10 +389,10 @@
<ul>
<li>Wall clock elapsed time, equivalent to the time that would be recorded by
a stopwatch.</li>
- <li>User central processing unit (CPU) time used by the process, as charged by
- the operating system.</li>
- <li>System central processing unit (CPU) time used by the process, as charged
- by the operating system.</li>
+ <li>User elapsed CPU time. Defined by POSIX as "the CPU time charged for the
+ execution of user instructions of the calling process."</li>
+ <li>System elapsed CPU time. Defined by POSIX as "the CPU time charged for
+ execution by the system on behalf of the calling process."</li>
</ul>
<h3><a name="Non-member-functions">Non-member functions</a></h3>
@@ -355,8 +476,8 @@
// compiler generated; shown for exposition only
~cpu_timer() noexcept = default;
- cpu_timer(const cpu_timer&) = default;
- cpu_timer& operator=(const cpu_timer&) = default;
+ cpu_timer(const cpu_timer&) noexcept = default;
+ cpu_timer& operator=(const cpu_timer&) noexcept = default;
// observers
bool is_stopped() const noexcept;
@@ -460,7 +581,7 @@
<a href="#auto_cpu_timer-destructor">~auto_cpu_timer</a>() noexcept;
- // compiler generated special member functions
+ // compiler generated; shown for exposition only
auto_cpu_timer(const auto_cpu_timer&) = default;
auto_cpu_timer& operator=(const auto_cpu_timer&) = default;
@@ -543,122 +664,6 @@
</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>
- cpu_timer_info.cpp</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">O/S</td>
- <td rowspan="2">Processor</td>
- <td colspan="2" align="center">Wall-clock</td>
- <td colspan="2" align="center">CPU</td>
- </tr>
- <tr>
- <td>Resolution</td>
- <td>Comments</td>
- <td align="center">User<br>
- Resolution</td>
- <td align="center">System<br>
- Resolution</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>
- <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>
-</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", but may not be steady on other platforms. <code>
- cpu_timer_info.cpp</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 by release builds. 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. For
- studying 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 further investigate.</p>
-
- <p>Shared libraries (DLL'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="History">History</a></h2>
<p>Beman Dawes and Rob Stewart developed version 2 of the library.</p>
Modified: trunk/libs/timer/doc/index.html
==============================================================================
--- trunk/libs/timer/doc/index.html (original)
+++ trunk/libs/timer/doc/index.html 2011-10-07 11:02:02 EDT (Fri, 07 Oct 2011)
@@ -40,12 +40,11 @@
</table>
<p>"How long does my C++ code take to run?"<p>The Boost Timer library
-answers that question - portably, and with as little as one #include and one
+answers that question and does so portably, with as little as one #include and one
additional line of code.<p>The Boost Timer library has two distinct sets of
-components.<ul>
+components:<ul>
<li>If you are new to the library, please go directly to the version 2
- CPU timers page.<br>
- </li>
+ CPU timers page.</li>
<li>If you are interested in
the original library, now deprecated, read on below.</li>
</ul>
@@ -74,7 +73,7 @@
</ul>
<hr>
<p><font size="2">Revised:
-<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B %Y" startspan -->04 October 2011<!--webbot bot="Timestamp" endspan i-checksum="32185" --></font></p>
+<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B %Y" startspan -->07 October 2011<!--webbot bot="Timestamp" endspan i-checksum="32191" --></font></p>
<p><font size="2">© Copyright Beman Dawes 2001, 2011</font></p>
Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk