Boost-Commit :

Date view	Thread view	Subject view	Author view

Subject: [Boost-commit] svn:boost r74808 - trunk/libs/timer/doc
From: bdawes_at_[hidden]
Date: 2011-10-08 11:05:18

Next message: bdawes_at_[hidden]: "[Boost-commit] svn:boost r74809 - trunk/libs/timer/doc"
Previous message: vicente.botet_at_[hidden]: "[Boost-commit] svn:boost r74807 - in branches/release/libs/chrono/test: . io"

Author: bemandawes
Date: 2011-10-08 11:05:18 EDT (Sat, 08 Oct 2011)
New Revision: 74808
URL: http://svn.boost.org/trac/boost/changeset/74808

Log:
Reword cpu_timer specs in terms of accumulating elapsed times.
Text files modified:
trunk/libs/timer/doc/cpu_timers.html | 138 ++++++++++++++++++++-------------------
1 files changed, 71 insertions(+), 67 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-08 11:05:18 EDT (Sat, 08 Oct 2011)
@@ -61,8 +61,7 @@
 synopsis</a> 
  Default format 
   Typedef nanosecond_type 
- 
- Non-member functions 
+  Namespace scope functions 
      format() 
  
 <a href="#Class-cpu_timer">Class <code>cpu_timer</code></a> 
@@ -79,17 +78,16 @@
 auto_cpu_timer</code> observers</a> 
    <code> auto_cpu_timer</code> actions 
 <a href="#History">History</a> 
- Acknowledgements 
- </tr>
+ Acknowledgements</tr>
</table>

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
+into wall clock time, CPU time spent by the user, and CPU time spent by the
operating system servicing user requests.

Class <code>cpu_timer</code> measures
-wall-clock time, user CPU process time, and system CPU process time. Class <code>
+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.
@@ -298,7 +296,7 @@
 <h3 dir="ltr"><a name="Recommendations">Recommendations</a></h3>

 Think about what is important to your application. For a
- production process, the wall-clock time may be what is most important. For
+ 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.

 A useful recommendation is to never trust timings unless they are
@@ -335,7 +333,7 @@
{
 namespace timer
 {
- class cpu_timer; // wall-clock, user, and system timer
+ class cpu_timer; // wall clock, user, and system timer
 class auto_cpu_timer; // automatic report() on destruction

 typedef boost::int_least64_t nanosecond_type;
@@ -384,65 +382,62 @@

<h3><a name="cpu_times">Struct <code>cpu_times</code></a></h3>

-Struct <code>cpu_times</code> packages three elapsed times:
+Struct <code>cpu_times</code> packages the elapsed wall clock time, user
+process CPU time, and system process CPU time. See
+Current time values for definitions of the
+source of these elapsed times.

-<ul>
- <li>Wall clock elapsed time, equivalent to the time that would be recorded by
- a stopwatch.</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>
+<pre>void clear();</pre>
+<blockquote>
+ Effects: <code>wall = user = system = 0LL</code>.
+</blockquote>

-<h3><a name="Non-member-functions">Non-member functions</a></h3>
+<h3><a name="Namespace-scope-functions">Namespace scope functions</a></h3>

<pre>std::string <a name="format">format</a>(const cpu_times& times, short places, const std::string& format);
std::string <a name="format">format</a>(const cpu_times& times, short places = default_places);</pre>
<blockquote>

-Overview: Converts the <code>times</code> argument's values to strings
-representing seconds to a given number of decimal <code>places</code>, and
-inserts them into a return string under control of the <code>format</code>
-string.
+Overview: 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>.

-Effects: If <code>places</code> is less than 0,  it is set to <code>default_places</code>. If <code>places</code> is
-more than 9, it is set to 9. For the overload without the <code>format</code>
+Remarks: For the overload without the <code>format</code>
argument, the default format is used as <code>format</code>.

Returns: 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>places</code> decimal places. Percentage is reported to one
+shown to <code>std::max(0, std::min(default_places, 9))</code> decimal places. Percentage is reported to one
decimal place. [Note: percentage may exceed 100% due to differences in
how operating systems measure various times. --end note]

<a name="Format-replacement-sequences">Format replacement sequences</a>

- <table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" width="39%">
+ <table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111">
 <tr>
- <td width="25%">Sequence</td>
- <td width="75%">Replacement value</td>
+ <td align="center" bgcolor="#D7EEFF">Sequence</td>
+ <td align="center" bgcolor="#D7EEFF">Replacement value</td>
 </tr>
 <tr>
- <td width="25%" align="center"><code>%w</code></td>
- <td width="75%"><code>times.wall</code></td>
+ <td align="center"><code>%w</code></td>
+ <td><code>times.wall</code></td>
 </tr>
 <tr>
- <td width="25%" align="center"><code>%u</code></td>
- <td width="75%"><code>times.user</code></td>
+ <td align="center"><code>%u</code></td>
+ <td><code>times.user</code></td>
 </tr>
 <tr>
- <td width="25%" align="center"><code>%s</code></td>
- <td width="75%"><code>times.system</code></td>
+ <td align="center"><code>%s</code></td>
+ <td><code>times.system</code></td>
 </tr>
 <tr>
- <td width="25%" align="center"><code>%t</code></td>
- <td width="75%"><code>times.user + times.system</code></td>
+ <td align="center"><code>%t</code></td>
+ <td><code>times.user + times.system</code></td>
 </tr>
 <tr>
- <td width="25%" align="center"><code>%p</code></td>
- <td width="75%">The percentage of <code>times.wall</code> represented by <code>
+ <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>
@@ -450,15 +445,25 @@

<h3><a name="Class-cpu_timer">Class <code>cpu_timer</code></a></h3>

- <code>cpu_timer</code> objects measure wall-clock elapsed time, process elapsed
-time charged to the user, and process elapsed time charged to the system.
+ <code>cpu_timer</code> objects measure wall clock elapsed time and process elapsed
+time charged to the user and system.

-<a name="Current-time-values">Current time values</a> are
-obtained as follows: Current wall-clock time is obtained from the Boost.Chrono <code>
-high_resolution_clock</code>. Current user and system time values are obtained
-from the appropriate operating system API functions such as <code>times()</code>
-on POSIX or <code>
-GetProcessTimes()</code> on Windows.
+<a name="Current-time-values">Current time values</a> are the
+current wall clock time, user process time, and system process time as provided
+by the operating system:
+
+<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>

@@ -503,20 +508,18 @@
observers</a></h3>
<pre>bool <a name="is_stopped">is_stopped</a>() const noexcept;</pre>
<blockquote>
- Returns: <code>true</code> if the most recent call to an
- action function was to stop(),
+ Returns: <code>true</code> if stop() was the most recent
+ action function called,
 otherwise <code>false</code>.
</blockquote>
<pre>cpu_times <a name="elapsed">elapsed</a>() const noexcept;</pre>
<blockquote>
- Overview: If the timer is running, returns the cumulative elapsed
- time. If the timer is stopped, returns the cumulative elapsed time previously
- stored by stop().
-
- Returns: If <code>is_stopped()</code>, the stored time values.
- Otherwise, the difference between the
- current time values and the stored time
- values.
+
+ Returns: If <code>is_stopped()</code>, the accumulated elapsed times
+ as of the previous stop(). Otherwise, the elapsed times
+ accumulated between the most recent call to start() or
+resume() and the <a href="#Current-time-values">current
+ time values</a>.

</blockquote>
<pre>std::string format(int places, const std::string& format) const;
@@ -531,7 +534,7 @@
<pre>void <a name="start">start</a>() noexcept;</pre>
<blockquote>

-Effects: Stores the current time values.
+Effects: Begins accumulating elapsed time as of the current time values.

Postconditions: <code>!is_stopped()</code>.

@@ -539,10 +542,14 @@
<pre>void <a name="stop">stop</a>() noexcept;</pre>
<blockquote>

-Effects: If <code>!is_stopped()</code>, stores the difference between
-the current time values and the time values
-stored by the most recent call to start() or
-resume().
+Effects: If <code>!is_stopped()</code>, stops accumulating elapsed
+time as of the current time values.
+
+<blockquote>
+
+[Note: This is observable via <code>elapsed()</code>. -- end note]
+
+</blockquote>

Postconditions: <code>is_stopped()</code>.

@@ -550,11 +557,8 @@
<pre>void <a name="resume">resume</a>() noexcept;</pre>
<blockquote>
 Overview: Restarts the timer, accumulating additional elapsed time.
- Effects: If is_stopped(), store the
-current time values less the previously
- stored cumulative elapsed times.  Otherwise, no effect. [Note:
- Subtracting the previous elapsed times has the effect of accumulating
- additional elapsed time. --end note]
+ Effects: If <code>is_stopped()</code>, resumes accumulating
+ additional elapsed time, as of the current time values. Otherwise, no effect.
</blockquote>
<h3><a name="Class-auto_cpu_timer">Class <code>auto_cpu_timer</code></a></h3>

@@ -678,7 +682,7 @@

<hr>
Revised:
-07 October 2011
+08 October 2011
© Copyright Beman Dawes, 2006 
© Copyright Beman Dawes and Robert Stewart, 2011
Distributed under the Boost Software License, Version 1.0. See www.boost.org/ LICENSE_1_0.txt

Next message: bdawes_at_[hidden]: "[Boost-commit] svn:boost r74809 - trunk/libs/timer/doc"
Previous message: vicente.botet_at_[hidden]: "[Boost-commit] svn:boost r74807 - in branches/release/libs/chrono/test: . io"

Date view	Thread view	Subject view	Author view

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