|
|
Boost-Commit : |
Subject: [Boost-commit] svn:boost r64788 - in sandbox/chrono/libs/chrono/doc: . html html/boost_chrono html/boost_chrono/appendices html/boost_chrono/overview html/boost_chrono/reference html/boost_chrono/users_guide
From: vicente.botet_at_[hidden]
Date: 2010-08-13 12:56:13
Author: viboes
Date: 2010-08-13 12:56:10 EDT (Fri, 13 Aug 2010)
New Revision: 64788
URL: http://svn.boost.org/trac/boost/changeset/64788
Log:
Update doc
Text files modified:
sandbox/chrono/libs/chrono/doc/chrono.qbk | 84 ++++++++++++++++++---------------
sandbox/chrono/libs/chrono/doc/html/boost_chrono/appendices/faq.html | 12 ++--
sandbox/chrono/libs/chrono/doc/html/boost_chrono/appendices/perf.html | 4
sandbox/chrono/libs/chrono/doc/html/boost_chrono/appendices/rationale.html | 83 ++++++++++++++++++++++++++++++++-
sandbox/chrono/libs/chrono/doc/html/boost_chrono/appendices/todo.html | 4
sandbox/chrono/libs/chrono/doc/html/boost_chrono/overview.html | 5 -
sandbox/chrono/libs/chrono/doc/html/boost_chrono/overview/description.html | 2
sandbox/chrono/libs/chrono/doc/html/boost_chrono/overview/motivation.html | 98 ++++++++-------------------------------
sandbox/chrono/libs/chrono/doc/html/boost_chrono/reference/reporters.html | 7 +-
sandbox/chrono/libs/chrono/doc/html/boost_chrono/users_guide/getting_started.html | 16 +++---
sandbox/chrono/libs/chrono/doc/html/boost_chrono/users_guide/tutorial.html | 5 -
sandbox/chrono/libs/chrono/doc/html/index.html | 2
12 files changed, 171 insertions(+), 151 deletions(-)
Modified: sandbox/chrono/libs/chrono/doc/chrono.qbk
==============================================================================
--- sandbox/chrono/libs/chrono/doc/chrono.qbk (original)
+++ sandbox/chrono/libs/chrono/doc/chrono.qbk 2010-08-13 12:56:10 EDT (Fri, 13 Aug 2010)
@@ -239,10 +239,13 @@
Finally, you can mentally add the following to any code fragments in this document:
// Include all of Chrono files
+ #include <boost/stopwatches.hpp>
+
+[/
#include <boost/type_traits/common_type.hpp>
#include <boost/ratio.hpp>
#include <boost/chrono.hpp>
- #include <boost/stopwatches.hpp>
+]
[/=================]
[section Motivation]
@@ -317,49 +320,15 @@
Knowing how long a program, a function or a specific code block takes to execute is useful in both test and production environments.
__Boost_Chrono__ introduces the __Stopwatch__ concept which is a mechanism to measure the elapsed time.
-A Stopwatch allows to start, stop, suspend and resume the measure of the elapsed time.
+A Stopwatch allows to start, stop, suspend and resume measuring the elapsed time.
__stopwatch__`<>` is the basic model of __Stopwatch__.
-At the user level, the main use case of measuring the elapsed time is to report these measures on the display.
-__stopwatch_reporter__`<>` provides a run time reporting package that can be invoked in a single line of code to report the usage of a Clock.
-
-
-
+It is often necessary to report elapsed time on a user display or in a log file. __stopwatch_reporter__<> provides a runtime reporting mechanism for this purpose which can be invoked in just one line of code.
[heading How reliable are these measures?]
-[/note this section need to be reworked, the ideas are there, but ...]
-
-There are three cases which can lead to get unreliable measures:
-
-* precision of your clock. It is not possible to measure events that transpire at rates of the same order of magnitude as the clock's precision with any reliability. For example, a 10ms clock cannot be used reliably to measure elapsed times of tens of milliseconds. The library provides a [high_resolution_clock] that gives you the highest resolution time available on your platform. That will give the best precision, but can only be used for reliable measurement of events that elapse about an order of magnitude slower than that clock's precision.
-
-
-``
-#include <boost/chrono/chrono.hpp>
- ...
- __stopclock__<__high_resolution_clock__> _;
-``
-
-* Using a process clock in a multithreaded application will give elapsed time for the process as a whole, including threads other than the calling thread. To get time elapsed for a specific thread, use the supplied __thread_clock__ which returns time elapsed for the calling thread only, if supported by the platform.
-
-* When stopclocks are nested, usually from stopclocks appearing in each of several nested function calls, the overhead of the stopclock processing begins to be significant relative to run time of the code being measured. The innermost measurements remain accurate, but those in the outermost layers can measure too much overhead to be trustworthy.
-
-* Nested stopclocks (usually nested function calls where each function contains a stopclock). When the nesting is deep enough, the cumulative overhead of all the stopclock functionality make the data unreliable except for the inner-most trace points. The question is, how much time is related to the application code we want to measure and how much to the fact we are meassuring and logging in inner blocks?
-
-
-Most of the stopclock overhead is likely due to logging. There are two things we can do to make the difference :
-
-* Don't flush log information while measuring elapsed time. A __stopwatch_accumulator__ can make that possible, because it don't report until all the measures have been compiled and then report some statistics. Alternatively, an asynchronous stream would permit normal logging but by a thread other than the one being measured.
-
-* Add a mechanism to track the difference between the application time and stopclock time. If a __Clock__ models __SuspendibleClock__ and its precision is sufficiently fine, this mechanism could suspend the __Clock_s__ counting while reporting measurements and resume it thereafter.
-
-[/
- stopclock<suspendible_clock<Clock> > _;
-
+There are a number of things that can lead to unreliable measurement (see [link boost_chrono.appendices.rationale here] for more details), but they mostly amount to reporting overhead. Boost.Chrono provides two ways to improve reliability of time measurements. A __stopwatch_accumulator__ only reports statistics once all measurements have been acquired, which removes reporting overhead from the measurements. The other approach is to use a __SuspendibleClock__ such that the reporting overhead can be ignored by suspending elapsed time tracking during reporting operations
-See the performances section for more deep details.
-]
[endsect]
[/==================]
@@ -1042,7 +1011,7 @@
Knowing how long a program, a function or a specific block takes to execute is useful in both test and production environments.
__Boost_Chrono__ introduces the __Stopwatch__ concept which captures the mechanism to measure the elapsed time.
-A __Stopwatch__ allows to `start`, `stop`, `suspend` and `resume` the measure of the elapsed time.
+A __Stopwatch__ allows to `start`, `stop`, `suspend` and `resume` measuring the elapsed time.
__stopwatch__`<>` is the basic model of __Stopwatch__ allowing to make a single measure.
At the user level, the main use case of measuring the elapsed time is to report these measures on the display.
@@ -4984,6 +4953,7 @@
[section:stopclock Template Class `stopclock<>`]
+A stopclock is a stopwatch with the ability to report elapsed time on an output stream.
`stopclock<Clock>` template class is a shortcut of `basic_stopclock<Clock, typename stopwatch_reporter_default_formatter<stopwatch<Clock>>::type>` with a specific default formatter.
template
@@ -6232,6 +6202,42 @@
r1 = r2; // compiles as both types are the same.
+[heading How reliable are these measures?]
+
+[/note this section need to be reworked, the ideas are there, but ...]
+
+
+There are three cases which can lead to get unreliable measures:
+
+* It is not possible to measure events that transpire at rates of the same order of magnitude as the clock's precision with any reliability. For example, a 10ms clock cannot be used reliably to measure elapsed times of tens of milliseconds. The library provides a [high_resolution_clock] that gives you the highest resolution time available on your platform. That will give the best precision, but can only be used for reliable measurement of events that elapse about an order of magnitude slower than that clock's precision.
+
+
+``
+#include <boost/chrono/chrono.hpp>
+ ...
+ __stopclock__<__high_resolution_clock__> _;
+``
+
+* Using a process clock in a multithreaded application will give elapsed time for the process as a whole, including threads other than the calling thread. To get time elapsed for a specific thread, use the supplied __thread_clock__ which returns time elapsed for the calling thread only, if supported by the platform.
+
+* When stopclocks are nested, usually from stopclocks appearing in each of several nested function calls, the overhead of the stopclock processing begins to be significant relative to run time of the code being measured. The innermost measurements remain accurate, but those in the outermost layers can measure too much overhead to be trustworthy.
+
+* Nested stopclocks (usually nested function calls where each function contains a stopclock). When the nesting is deep enough, the cumulative overhead of all the stopclock functionality make the data unreliable except for the inner-most trace points. The question is, how much time is related to the application code we want to measure and how much to the fact we are meassuring and logging in inner blocks?
+
+
+Most of the stopclock overhead is likely due to logging. There are two things we can do to make the difference :
+
+* Don't flush log information while measuring elapsed time. A __stopwatch_accumulator__ can make that possible, because it don't report until all the measures have been compiled and then report some statistics. Alternatively, an asynchronous stream would permit normal logging but by a thread other than the one being measured.
+
+* Add a mechanism to track the difference between the application time and stopclock time. If a __Clock__ models __SuspendibleClock__ and its precision is sufficiently fine, this mechanism could suspend the __Clock_s__ counting while reporting measurements and resume it thereafter.
+
+[/
+ stopclock<suspendible_clock<Clock> > _;
+
+
+See the performances section for more deep details.
+]
+
[endsect]
[/======================================================]
Modified: sandbox/chrono/libs/chrono/doc/html/boost_chrono/appendices/faq.html
==============================================================================
--- sandbox/chrono/libs/chrono/doc/html/boost_chrono/appendices/faq.html (original)
+++ sandbox/chrono/libs/chrono/doc/html/boost_chrono/appendices/faq.html 2010-08-13 12:56:10 EDT (Fri, 13 Aug 2010)
@@ -29,7 +29,7 @@
<a name="boost_chrono.appendices.faq"></a> Appendix D: FAQ
</h3></div></div></div>
<a name="boost_chrono.appendices.faq.how_important_is_the_order_of_the___link_linkend__boost_chrono_reference_cpp0x_common_type_hpp_common_type___code__phrase_role__identifier__common_type__phrase___code___link__lt__gt__template_arguments_"></a><h4>
-<a name="id4947115"></a>
+<a name="id4946910"></a>
<a href="faq.html#boost_chrono.appendices.faq.how_important_is_the_order_of_the___link_linkend__boost_chrono_reference_cpp0x_common_type_hpp_common_type___code__phrase_role__identifier__common_type__phrase___code___link__lt__gt__template_arguments_">How
important is the order of the <a href="../reference/cpp0x.html#boost_chrono.reference.cpp0x.common_type_hpp.common_type" title="
Class Template common_type<>"><code class="computeroutput"><span class="identifier">common_type</span></code></a><> template arguments?</a>
@@ -70,7 +70,7 @@
also undefined.
</p>
<a name="boost_chrono.appendices.faq.why_does_stopwatch_reporter_only_display_millisecond_place_precision_when_the_underlying_clock_has_nanosecond_precision_"></a><h4>
-<a name="id4947668"></a>
+<a name="id4947464"></a>
<a href="faq.html#boost_chrono.appendices.faq.why_does_stopwatch_reporter_only_display_millisecond_place_precision_when_the_underlying_clock_has_nanosecond_precision_">Why
does stopwatch_reporter only display millisecond place precision when the
underlying Clock has nanosecond precision?</a>
@@ -81,7 +81,7 @@
dangerously.
</p>
<a name="boost_chrono.appendices.faq.why_does_stopwatch_reporter_sometimes_report_more_cpu_seconds_than_real_seconds_"></a><h4>
-<a name="id4947710"></a>
+<a name="id4947505"></a>
<a href="faq.html#boost_chrono.appendices.faq.why_does_stopwatch_reporter_sometimes_report_more_cpu_seconds_than_real_seconds_">Why
does stopwatch_reporter sometimes report more cpu seconds than real seconds?</a>
</h4>
@@ -91,7 +91,7 @@
be reporting at times.
</p>
<a name="boost_chrono.appendices.faq.can_i_obtain_statistics_of_the_time_elapsed_between_calls_to_a_function_"></a><h4>
-<a name="id4947744"></a>
+<a name="id4947539"></a>
<a href="faq.html#boost_chrono.appendices.faq.can_i_obtain_statistics_of_the_time_elapsed_between_calls_to_a_function_">Can
I obtain statistics of the time elapsed between calls to a function?</a>
</h4>
@@ -99,13 +99,13 @@
The library do not provides this feature.
</p>
<a name="boost_chrono.appendices.faq.what_happens_if_i_press_ctrl_c_and_program_terminates__what_log_would_boost_chrono_output_"></a><h4>
-<a name="id4947772"></a>
+<a name="id4947567"></a>
<a href="faq.html#boost_chrono.appendices.faq.what_happens_if_i_press_ctrl_c_and_program_terminates__what_log_would_boost_chrono_output_">What
happens if I press Ctrl+C and program terminates? What log would Boost.chrono
output?</a>
</h4>
<a name="boost_chrono.appendices.faq.can_you_explain_the_pros_cons_of___link_linkend__boost_chrono_reference_cpp0x_common_type_hpp_common_type___code__phrase_role__identifier__common_type__phrase___code___link__against_boost_typeof_"></a><h4>
-<a name="id4947801"></a>
+<a name="id4947597"></a>
<a href="faq.html#boost_chrono.appendices.faq.can_you_explain_the_pros_cons_of___link_linkend__boost_chrono_reference_cpp0x_common_type_hpp_common_type___code__phrase_role__identifier__common_type__phrase___code___link__against_boost_typeof_">Can
you explain the pros/cons of <a href="../reference/cpp0x.html#boost_chrono.reference.cpp0x.common_type_hpp.common_type" title="
Class Template common_type<>"><code class="computeroutput"><span class="identifier">common_type</span></code></a> against Boost.Typeof?</a>
Modified: sandbox/chrono/libs/chrono/doc/html/boost_chrono/appendices/perf.html
==============================================================================
--- sandbox/chrono/libs/chrono/doc/html/boost_chrono/appendices/perf.html (original)
+++ sandbox/chrono/libs/chrono/doc/html/boost_chrono/appendices/perf.html 2010-08-13 12:56:10 EDT (Fri, 13 Aug 2010)
@@ -69,7 +69,7 @@
with a variable lifetime.
</p>
<a name="boost_chrono.appendices.perf.single_threaded_recursive_function"></a><h4>
-<a name="id4951642"></a>
+<a name="id4951445"></a>
<a href="perf.html#boost_chrono.appendices.perf.single_threaded_recursive_function">Single-Threaded
Recursive function</a>
</h4>
@@ -92,7 +92,7 @@
and thread_clock.
</p>
<a name="boost_chrono.appendices.perf.multi_threaded_recursive_function"></a><h4>
-<a name="id4951692"></a>
+<a name="id4951495"></a>
<a href="perf.html#boost_chrono.appendices.perf.multi_threaded_recursive_function">Multi-Threaded
Recursive function</a>
</h4>
Modified: sandbox/chrono/libs/chrono/doc/html/boost_chrono/appendices/rationale.html
==============================================================================
--- sandbox/chrono/libs/chrono/doc/html/boost_chrono/appendices/rationale.html (original)
+++ sandbox/chrono/libs/chrono/doc/html/boost_chrono/appendices/rationale.html 2010-08-13 12:56:10 EDT (Fri, 13 Aug 2010)
@@ -33,7 +33,7 @@
are an extract from this document.
</p>
<a name="boost_chrono.appendices.rationale.is_it_possible_for_the_user_to_pass_a___link_linkend__boost_chrono_reference_cpp0x_chrono_chrono_hpp_duration___code__phrase_role__identifier__duration__phrase___code___link__to_a_function_with_the_units_being_ambiguous_"></a><h4>
-<a name="id4945746"></a>
+<a name="id4945238"></a>
<a href="rationale.html#boost_chrono.appendices.rationale.is_it_possible_for_the_user_to_pass_a___link_linkend__boost_chrono_reference_cpp0x_chrono_chrono_hpp_duration___code__phrase_role__identifier__duration__phrase___code___link__to_a_function_with_the_units_being_ambiguous_">Is
it possible for the user to pass a <a href="../reference/cpp0x.html#boost_chrono.reference.cpp0x.chrono_chrono_hpp.duration" title="
Class template duration<>"><code class="computeroutput"><span class="identifier">duration</span></code></a> to a function with the
@@ -46,7 +46,7 @@
<pre class="programlisting"><span class="identifier">f</span><span class="special">(</span><span class="number">3</span><span class="special">);</span> <span class="comment">// Will not compile, 3 is not implicitly convertible to any __duration__
</span></pre>
<a name="boost_chrono.appendices.rationale.why_duration_needs_operator_"></a><h4>
-<a name="id4945845"></a>
+<a name="id4945338"></a>
<a href="rationale.html#boost_chrono.appendices.rationale.why_duration_needs_operator_">Why
duration needs operator%</a>
</h4>
@@ -74,7 +74,7 @@
<span class="special">};</span>
</pre>
<a name="boost_chrono.appendices.rationale.why_ratio_needs_copyconstruction_and_assignment_from_ratios_having_the_same_normalized_form"></a><h4>
-<a name="id4946426"></a>
+<a name="id4945918"></a>
<a href="rationale.html#boost_chrono.appendices.rationale.why_ratio_needs_copyconstruction_and_assignment_from_ratios_having_the_same_normalized_form">Why
ratio needs CopyConstruction and Assignment from ratios having the same normalized
form</a>
@@ -109,7 +109,7 @@
succeeds.
</p>
<a name="boost_chrono.appendices.rationale.why_ratio_needs_the_nested_normalizer_typedef_type"></a><h4>
-<a name="id4946835"></a>
+<a name="id4946327"></a>
<a href="rationale.html#boost_chrono.appendices.rationale.why_ratio_needs_the_nested_normalizer_typedef_type">Why
ratio needs the nested normalizer typedef type</a>
</h4>
@@ -139,6 +139,81 @@
Template ratio<>"><code class="computeroutput"><span class="identifier">ratio</span></code></a><span class="special"><</span><span class="number">3</span><span class="special">,</span><span class="number">9</span><span class="special">>::</span><span class="identifier">type</span> <span class="identifier">r2</span><span class="special">;</span>
<span class="identifier">r1</span> <span class="special">=</span> <span class="identifier">r2</span><span class="special">;</span> <span class="comment">// compiles as both types are the same.
</span></pre>
+<a name="boost_chrono.appendices.rationale.how_reliable_are_these_measures_"></a><h4>
+<a name="id4946572"></a>
+ <a href="rationale.html#boost_chrono.appendices.rationale.how_reliable_are_these_measures_">How
+ reliable are these measures?</a>
+ </h4>
+<p>
+ There are three cases which can lead to get unreliable measures:
+ </p>
+<div class="itemizedlist"><ul type="disc"><li>
+ It is not possible to measure events that transpire at rates of the same
+ order of magnitude as the clock's precision with any reliability. For example,
+ a 10ms clock cannot be used reliably to measure elapsed times of tens of
+ milliseconds. The library provides a [high_resolution_clock] that gives
+ you the highest resolution time available on your platform. That will give
+ the best precision, but can only be used for reliable measurement of events
+ that elapse about an order of magnitude slower than that clock's precision.
+ </li></ul></div>
+<p>
+
+</p>
+<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">chrono</span><span class="special">/</span><span class="identifier">chrono</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span>
+ <span class="special">...</span>
+ <a href="../reference/reporters.html#boost_chrono.reference.reporters.stopclock_hpp.stopclock" title="
+ Template Class stopclock<>"><code class="computeroutput"><span class="identifier">stopclock</span></code></a><span class="special"><</span> <a href="../reference/cpp0x.html#boost_chrono.reference.cpp0x.chrono_chrono_hpp.high_resolution_clock" title="
+ Class high_resolution_clock"><code class="computeroutput"><span class="identifier">high_resolution_clock</span></code></a><span class="special">></span> <span class="identifier">_</span><span class="special">;</span>
+</pre>
+<p>
+ </p>
+<div class="itemizedlist"><ul type="disc">
+<li>
+ Using a process clock in a multithreaded application will give elapsed
+ time for the process as a whole, including threads other than the calling
+ thread. To get time elapsed for a specific thread, use the supplied <a href="../reference/other_clocks.html#boost_chrono.reference.other_clocks.thread_clock_hpp.thread_clock" title="
+ Class thread_clock"><code class="computeroutput"><span class="identifier">thread_clock</span></code></a> which returns time
+ elapsed for the calling thread only, if supported by the platform.
+ </li>
+<li>
+ When stopclocks are nested, usually from stopclocks appearing in each of
+ several nested function calls, the overhead of the stopclock processing
+ begins to be significant relative to run time of the code being measured.
+ The innermost measurements remain accurate, but those in the outermost
+ layers can measure too much overhead to be trustworthy.
+ </li>
+<li>
+ Nested stopclocks (usually nested function calls where each function contains
+ a stopclock). When the nesting is deep enough, the cumulative overhead
+ of all the stopclock functionality make the data unreliable except for
+ the inner-most trace points. The question is, how much time is related
+ to the application code we want to measure and how much to the fact we
+ are meassuring and logging in inner blocks?
+ </li>
+</ul></div>
+<p>
+ Most of the stopclock overhead is likely due to logging. There are two things
+ we can do to make the difference :
+ </p>
+<div class="itemizedlist"><ul type="disc">
+<li>
+ Don't flush log information while measuring elapsed time. A <a href="../reference/stopwatches.html#boost_chrono.reference.stopwatches.stopwatch_accumulator_hpp.stopwatch_accumulator" title="
+ Template Class stopwatch_accumulator<>"><code class="computeroutput"><span class="identifier">stopwatch_accumulator</span></code></a> can make
+ that possible, because it don't report until all the measures have been
+ compiled and then report some statistics. Alternatively, an asynchronous
+ stream would permit normal logging but by a thread other than the one being
+ measured.
+ </li>
+<li>
+ Add a mechanism to track the difference between the application time and
+ stopclock time. If a <a href="../reference/cpp0x.html#boost_chrono.reference.cpp0x.chrono_chrono_hpp.clock" title="
+ Clock Requirements"><code class="computeroutput"><span class="identifier">Clock</span></code></a> models <a href="../reference/other_clocks.html#boost_chrono.reference.other_clocks.suspendible_clock_req" title="
+ SuspendibleClock Requirements"><code class="computeroutput"><span class="identifier">SuspendibleClock</span></code></a> and its precision
+ is sufficiently fine, this mechanism could suspend the <a href="../reference/cpp0x.html#boost_chrono.reference.cpp0x.chrono_chrono_hpp.clock" title="
+ Clock Requirements"><code class="computeroutput"><span class="identifier">Clock</span></code>'s</a> counting while reporting
+ measurements and resume it thereafter.
+ </li>
+</ul></div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
Modified: sandbox/chrono/libs/chrono/doc/html/boost_chrono/appendices/todo.html
==============================================================================
--- sandbox/chrono/libs/chrono/doc/html/boost_chrono/appendices/todo.html (original)
+++ sandbox/chrono/libs/chrono/doc/html/boost_chrono/appendices/todo.html 2010-08-13 12:56:10 EDT (Fri, 13 Aug 2010)
@@ -26,7 +26,7 @@
<a name="boost_chrono.appendices.todo"></a> Appendix I: Future plans
</h3></div></div></div>
<a name="boost_chrono.appendices.todo.tasks_to_do_before_review"></a><h4>
-<a name="id4951758"></a>
+<a name="id4951562"></a>
<a href="todo.html#boost_chrono.appendices.todo.tasks_to_do_before_review">Tasks
to do before review</a>
</h4>
@@ -42,7 +42,7 @@
</li>
</ul></div>
<a name="boost_chrono.appendices.todo.for_later_releases"></a><h4>
-<a name="id4951798"></a>
+<a name="id4951601"></a>
<a href="todo.html#boost_chrono.appendices.todo.for_later_releases">For later
releases</a>
</h4>
Modified: sandbox/chrono/libs/chrono/doc/html/boost_chrono/overview.html
==============================================================================
--- sandbox/chrono/libs/chrono/doc/html/boost_chrono/overview.html (original)
+++ sandbox/chrono/libs/chrono/doc/html/boost_chrono/overview.html 2010-08-13 12:56:10 EDT (Fri, 13 Aug 2010)
@@ -97,10 +97,7 @@
Finally, you can mentally add the following to any code fragments in this document:
</p>
<pre class="programlisting"><span class="comment">// Include all of Chrono files
-</span><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">type_traits</span><span class="special">/</span><span class="identifier">common_type</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span>
-<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">ratio</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span>
-<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">chrono</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span>
-<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">stopwatches</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span>
+</span><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">stopwatches</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span>
</pre>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
Modified: sandbox/chrono/libs/chrono/doc/html/boost_chrono/overview/description.html
==============================================================================
--- sandbox/chrono/libs/chrono/doc/html/boost_chrono/overview/description.html (original)
+++ sandbox/chrono/libs/chrono/doc/html/boost_chrono/overview/description.html 2010-08-13 12:56:10 EDT (Fri, 13 Aug 2010)
@@ -185,7 +185,7 @@
auto with C++03 compilers.
</p>
<a name="boost_chrono.overview.description.caveat_emptor"></a><h4>
-<a name="id4758927"></a>
+<a name="id4758567"></a>
<a href="description.html#boost_chrono.overview.description.caveat_emptor">Caveat emptor</a>
</h4>
<p>
Modified: sandbox/chrono/libs/chrono/doc/html/boost_chrono/overview/motivation.html
==============================================================================
--- sandbox/chrono/libs/chrono/doc/html/boost_chrono/overview/motivation.html (original)
+++ sandbox/chrono/libs/chrono/doc/html/boost_chrono/overview/motivation.html 2010-08-13 12:56:10 EDT (Fri, 13 Aug 2010)
@@ -27,7 +27,7 @@
<a name="boost_chrono.overview.motivation"></a>Motivation
</h3></div></div></div>
<a name="boost_chrono.overview.motivation.time"></a><h4>
-<a name="id4803513"></a>
+<a name="id4803389"></a>
<a href="motivation.html#boost_chrono.overview.motivation.time">Time</a>
</h4>
<p>
@@ -46,7 +46,7 @@
of a good deal of information in this documentation.
</p>
<a name="boost_chrono.overview.motivation.wall_clock_versus_system_and_user_time"></a><h4>
-<a name="id4803571"></a>
+<a name="id4803446"></a>
<a href="motivation.html#boost_chrono.overview.motivation.wall_clock_versus_system_and_user_time">Wall
clock versus system and user time</a>
</h4>
@@ -58,7 +58,7 @@
this relies on times(). On Windows, it relies on GetProcessTimes().)
</p>
<a name="boost_chrono.overview.motivation.reporting_elapsed_time"></a><h4>
-<a name="id4803615"></a>
+<a name="id4803478"></a>
<a href="motivation.html#boost_chrono.overview.motivation.reporting_elapsed_time">Reporting
elapsed time</a>
</h4>
@@ -68,93 +68,35 @@
introduces the <a href="../reference/stopwatches.html#boost_chrono.reference.stopwatches.stopwatch_req" title="
Stopwatch Requirements"><code class="computeroutput"><span class="identifier">Stopwatch</span></code></a> concept which is a mechanism
to measure the elapsed time. A Stopwatch allows to start, stop, suspend and
- resume the measure of the elapsed time. <a href="../reference/stopwatches.html#boost_chrono.reference.stopwatches.stopwatch_hpp.stopwatch" title="
+ resume measuring the elapsed time. <a href="../reference/stopwatches.html#boost_chrono.reference.stopwatches.stopwatch_hpp.stopwatch" title="
Template Class stopwatch<>"><code class="computeroutput"><span class="identifier">stopwatch</span></code></a><code class="computeroutput"><span class="special"><></span></code>
is the basic model of <a href="../reference/stopwatches.html#boost_chrono.reference.stopwatches.stopwatch_req" title="
Stopwatch Requirements"><code class="computeroutput"><span class="identifier">Stopwatch</span></code></a>.
</p>
<p>
- At the user level, the main use case of measuring the elapsed time is to
- report these measures on the display. <a href="../reference/reporters.html#boost_chrono.reference.reporters.stopwatch_reporter_hpp.stopwatch_reporter" title="
- Template Class stopwatch_reporter<>"><code class="computeroutput"><span class="identifier">stopwatch_reporter</span></code></a><code class="computeroutput"><span class="special"><></span></code> provides a run time reporting package
- that can be invoked in a single line of code to report the usage of a Clock.
+ It is often necessary to report elapsed time on a user display or in a log
+ file. <a href="../reference/reporters.html#boost_chrono.reference.reporters.stopwatch_reporter_hpp.stopwatch_reporter" title="
+ Template Class stopwatch_reporter<>"><code class="computeroutput"><span class="identifier">stopwatch_reporter</span></code></a><> provides
+ a runtime reporting mechanism for this purpose which can be invoked in just
+ one line of code.
</p>
<a name="boost_chrono.overview.motivation.how_reliable_are_these_measures_"></a><h4>
-<a name="id4803738"></a>
+<a name="id4803594"></a>
<a href="motivation.html#boost_chrono.overview.motivation.how_reliable_are_these_measures_">How
reliable are these measures?</a>
</h4>
<p>
- There are three cases which can lead to get unreliable measures:
+ There are a number of things that can lead to unreliable measurement (see
+ here for more details),
+ but they mostly amount to reporting overhead. Boost.Chrono provides two ways
+ to improve reliability of time measurements. A <a href="../reference/stopwatches.html#boost_chrono.reference.stopwatches.stopwatch_accumulator_hpp.stopwatch_accumulator" title="
+ Template Class stopwatch_accumulator<>"><code class="computeroutput"><span class="identifier">stopwatch_accumulator</span></code></a> only reports
+ statistics once all measurements have been acquired, which removes reporting
+ overhead from the measurements. The other approach is to use a <a href="../reference/other_clocks.html#boost_chrono.reference.other_clocks.suspendible_clock_req" title="
+ SuspendibleClock Requirements"><code class="computeroutput"><span class="identifier">SuspendibleClock</span></code></a> such that the reporting
+ overhead can be ignored by suspending elapsed time tracking during reporting
+ operations
</p>
-<div class="itemizedlist"><ul type="disc"><li>
- precision of your clock. It is not possible to measure events that transpire
- at rates of the same order of magnitude as the clock's precision with any
- reliability. For example, a 10ms clock cannot be used reliably to measure
- elapsed times of tens of milliseconds. The library provides a [high_resolution_clock]
- that gives you the highest resolution time available on your platform.
- That will give the best precision, but can only be used for reliable measurement
- of events that elapse about an order of magnitude slower than that clock's
- precision.
- </li></ul></div>
-<p>
-
-</p>
-<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">chrono</span><span class="special">/</span><span class="identifier">chrono</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span>
- <span class="special">...</span>
- <a href="../reference/reporters.html#boost_chrono.reference.reporters.stopclock_hpp.stopclock" title="
- Template Class stopclock<>"><code class="computeroutput"><span class="identifier">stopclock</span></code></a><span class="special"><</span> <a href="../reference/cpp0x.html#boost_chrono.reference.cpp0x.chrono_chrono_hpp.high_resolution_clock" title="
- Class high_resolution_clock"><code class="computeroutput"><span class="identifier">high_resolution_clock</span></code></a><span class="special">></span> <span class="identifier">_</span><span class="special">;</span>
-</pre>
-<p>
- </p>
-<div class="itemizedlist"><ul type="disc">
-<li>
- Using a process clock in a multithreaded application will give elapsed
- time for the process as a whole, including threads other than the calling
- thread. To get time elapsed for a specific thread, use the supplied <a href="../reference/other_clocks.html#boost_chrono.reference.other_clocks.thread_clock_hpp.thread_clock" title="
- Class thread_clock"><code class="computeroutput"><span class="identifier">thread_clock</span></code></a> which returns time
- elapsed for the calling thread only, if supported by the platform.
- </li>
-<li>
- When stopclocks are nested, usually from stopclocks appearing in each of
- several nested function calls, the overhead of the stopclock processing
- begins to be significant relative to run time of the code being measured.
- The innermost measurements remain accurate, but those in the outermost
- layers can measure too much overhead to be trustworthy.
- </li>
-<li>
- Nested stopclocks (usually nested function calls where each function contains
- a stopclock). When the nesting is deep enough, the cumulative overhead
- of all the stopclock functionality make the data unreliable except for
- the inner-most trace points. The question is, how much time is related
- to the application code we want to measure and how much to the fact we
- are meassuring and logging in inner blocks?
- </li>
-</ul></div>
-<p>
- Most of the stopclock overhead is likely due to logging. There are two things
- we can do to make the difference :
- </p>
-<div class="itemizedlist"><ul type="disc">
-<li>
- Don't flush log information while measuring elapsed time. A <a href="../reference/stopwatches.html#boost_chrono.reference.stopwatches.stopwatch_accumulator_hpp.stopwatch_accumulator" title="
- Template Class stopwatch_accumulator<>"><code class="computeroutput"><span class="identifier">stopwatch_accumulator</span></code></a> can make
- that possible, because it don't report until all the measures have been
- compiled and then report some statistics. Alternatively, an asynchronous
- stream would permit normal logging but by a thread other than the one being
- measured.
- </li>
-<li>
- Add a mechanism to track the difference between the application time and
- stopclock time. If a <a href="../reference/cpp0x.html#boost_chrono.reference.cpp0x.chrono_chrono_hpp.clock" title="
- Clock Requirements"><code class="computeroutput"><span class="identifier">Clock</span></code></a> models <a href="../reference/other_clocks.html#boost_chrono.reference.other_clocks.suspendible_clock_req" title="
- SuspendibleClock Requirements"><code class="computeroutput"><span class="identifier">SuspendibleClock</span></code></a> and its precision
- is sufficiently fine, this mechanism could suspend the <a href="../reference/cpp0x.html#boost_chrono.reference.cpp0x.chrono_chrono_hpp.clock" title="
- Clock Requirements"><code class="computeroutput"><span class="identifier">Clock</span></code>'s</a> counting while reporting
- measurements and resume it thereafter.
- </li>
-</ul></div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
Modified: sandbox/chrono/libs/chrono/doc/html/boost_chrono/reference/reporters.html
==============================================================================
--- sandbox/chrono/libs/chrono/doc/html/boost_chrono/reference/reporters.html (original)
+++ sandbox/chrono/libs/chrono/doc/html/boost_chrono/reference/reporters.html 2010-08-13 12:56:10 EDT (Fri, 13 Aug 2010)
@@ -602,8 +602,9 @@
Template Class <code class="computeroutput"><span class="identifier">stopclock</span><span class="special"><></span></code></a>
</h5></div></div></div>
<p>
- <code class="computeroutput"><span class="identifier">stopclock</span><span class="special"><</span><span class="identifier">Clock</span><span class="special">></span></code>
- template class is a shortcut of <code class="computeroutput"><span class="identifier">basic_stopclock</span><span class="special"><</span><span class="identifier">Clock</span><span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">stopwatch_reporter_default_formatter</span><span class="special"><</span><span class="identifier">stopwatch</span><span class="special"><</span><span class="identifier">Clock</span><span class="special">>>::</span><span class="identifier">type</span><span class="special">></span></code> with a specific default formatter.
+ A stopclock is a stopwatch with the ability to report elapsed time on
+ an output stream. <code class="computeroutput"><span class="identifier">stopclock</span><span class="special"><</span><span class="identifier">Clock</span><span class="special">></span></code> template class is a shortcut of
+ <code class="computeroutput"><span class="identifier">basic_stopclock</span><span class="special"><</span><span class="identifier">Clock</span><span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">stopwatch_reporter_default_formatter</span><span class="special"><</span><span class="identifier">stopwatch</span><span class="special"><</span><span class="identifier">Clock</span><span class="special">>>::</span><span class="identifier">type</span><span class="special">></span></code> with a specific default formatter.
</p>
<pre class="programlisting"><span class="keyword">template</span>
<span class="special"><</span> <span class="keyword">class</span> <span class="identifier">Clock</span><span class="special">=</span><span class="identifier">process_cpu_clock</span>
@@ -1070,7 +1071,7 @@
<span class="special">}</span>
</pre>
<a name="boost_chrono.reference.reporters.scoped_stopclock_hpp.scoped_stopclock.synopsis"></a><h6>
-<a name="id4930340"></a>
+<a name="id4929834"></a>
<a href="reporters.html#boost_chrono.reference.reporters.scoped_stopclock_hpp.scoped_stopclock.synopsis">Synopsis</a>
</h6>
<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span> <span class="keyword">class</span> <span class="identifier">Clock</span><span class="special">=</span><span class="identifier">process_cpu_clock</span>
Modified: sandbox/chrono/libs/chrono/doc/html/boost_chrono/users_guide/getting_started.html
==============================================================================
--- sandbox/chrono/libs/chrono/doc/html/boost_chrono/users_guide/getting_started.html (original)
+++ sandbox/chrono/libs/chrono/doc/html/boost_chrono/users_guide/getting_started.html 2010-08-13 12:56:10 EDT (Fri, 13 Aug 2010)
@@ -39,7 +39,7 @@
Installing Chrono</a>
</h4></div></div></div>
<a name="boost_chrono.users_guide.getting_started.install.getting__emphasis_role__bold__boost_chrono__emphasis__"></a><h5>
-<a name="id4759002"></a>
+<a name="id4758659"></a>
<a href="getting_started.html#boost_chrono.users_guide.getting_started.install.getting__emphasis_role__bold__boost_chrono__emphasis__">Getting
<span class="bold"><strong>Boost.Chrono</strong></span> </a>
</h5>
@@ -54,7 +54,7 @@
and follow the instructions there for anonymous SVN access.
</p>
<a name="boost_chrono.users_guide.getting_started.install.where_to_install__emphasis_role__bold__boost_chrono__emphasis___"></a><h5>
-<a name="id4759074"></a>
+<a name="id4758731"></a>
<a href="getting_started.html#boost_chrono.users_guide.getting_started.install.where_to_install__emphasis_role__bold__boost_chrono__emphasis___">Where
to install <span class="bold"><strong>Boost.Chrono</strong></span>? </a>
</h5>
@@ -70,7 +70,7 @@
variable. Any help is welcome.
</p>
<a name="boost_chrono.users_guide.getting_started.install.building__emphasis_role__bold__boost_chrono__emphasis__"></a><h5>
-<a name="id4759389"></a>
+<a name="id4758766"></a>
<a href="getting_started.html#boost_chrono.users_guide.getting_started.install.building__emphasis_role__bold__boost_chrono__emphasis__">Building
<span class="bold"><strong>Boost.Chrono</strong></span> </a>
</h5>
@@ -81,7 +81,7 @@
<pre class="programlisting"><span class="identifier">bjam</span> <span class="identifier">libs</span><span class="special">/</span><span class="identifier">chrono</span><span class="special">/</span><span class="identifier">build</span>
</pre>
<a name="boost_chrono.users_guide.getting_started.install.requirements"></a><h5>
-<a name="id4759461"></a>
+<a name="id4758838"></a>
<a href="getting_started.html#boost_chrono.users_guide.getting_started.install.requirements">Requirements</a>
</h5>
<p>
@@ -144,7 +144,7 @@
</dl>
</div>
<a name="boost_chrono.users_guide.getting_started.install.building_an_executable_that_uses__emphasis_role__bold__boost_chrono__emphasis__"></a><h5>
-<a name="id4759716"></a>
+<a name="id4759094"></a>
<a href="getting_started.html#boost_chrono.users_guide.getting_started.install.building_an_executable_that_uses__emphasis_role__bold__boost_chrono__emphasis__">Building
an executable that uses <span class="bold"><strong>Boost.Chrono</strong></span>
</a>
@@ -154,7 +154,7 @@
with the Boost System library.
</p>
<a name="boost_chrono.users_guide.getting_started.install.exceptions_safety_"></a><h5>
-<a name="id4759751"></a>
+<a name="id4759128"></a>
<a href="getting_started.html#boost_chrono.users_guide.getting_started.install.exceptions_safety_">Exceptions
safety </a>
</h5>
@@ -163,7 +163,7 @@
of exception safety as long as the underlying parameters provide it.
</p>
<a name="boost_chrono.users_guide.getting_started.install.thread_safety_"></a><h5>
-<a name="id4759779"></a>
+<a name="id4759156"></a>
<a href="getting_started.html#boost_chrono.users_guide.getting_started.install.thread_safety_">Thread
safety </a>
</h5>
@@ -171,7 +171,7 @@
All functions in the library are thread-unsafe except when noted explicitly.
</p>
<a name="boost_chrono.users_guide.getting_started.install.tested_compilers_"></a><h5>
-<a name="id4759804"></a>
+<a name="id4759181"></a>
<a href="getting_started.html#boost_chrono.users_guide.getting_started.install.tested_compilers_">Tested
compilers </a>
</h5>
Modified: sandbox/chrono/libs/chrono/doc/html/boost_chrono/users_guide/tutorial.html
==============================================================================
--- sandbox/chrono/libs/chrono/doc/html/boost_chrono/users_guide/tutorial.html (original)
+++ sandbox/chrono/libs/chrono/doc/html/boost_chrono/users_guide/tutorial.html 2010-08-13 12:56:10 EDT (Fri, 13 Aug 2010)
@@ -477,7 +477,7 @@
fractional part gets silently discarded.
</p>
<a name="boost_chrono.users_guide.tutorial.duration.what_happens_if_i_assign__m3___us3__to__minutes__instead_of__microseconds__.but_what_if_the_truncation_behavior_is_what_i_want_to_do_"></a><h6>
-<a name="id4816056"></a>
+<a name="id4815604"></a>
<a href="tutorial.html#boost_chrono.users_guide.tutorial.duration.what_happens_if_i_assign__m3___us3__to__minutes__instead_of__microseconds__.but_what_if_the_truncation_behavior_is_what_i_want_to_do_">But
what if the truncation behavior is what I want to do?</a>
</h6>
@@ -1046,8 +1046,7 @@
Stopwatch Requirements"><code class="computeroutput"><span class="identifier">Stopwatch</span></code></a> concept which captures
the mechanism to measure the elapsed time. A <a href="../reference/stopwatches.html#boost_chrono.reference.stopwatches.stopwatch_req" title="
Stopwatch Requirements"><code class="computeroutput"><span class="identifier">Stopwatch</span></code></a> allows to <code class="computeroutput"><span class="identifier">start</span></code>, <code class="computeroutput"><span class="identifier">stop</span></code>,
- <code class="computeroutput"><span class="identifier">suspend</span></code> and <code class="computeroutput"><span class="identifier">resume</span></code> the measure of the elapsed time.
- <a href="../reference/stopwatches.html#boost_chrono.reference.stopwatches.stopwatch_hpp.stopwatch" title="
+ <code class="computeroutput"><span class="identifier">suspend</span></code> and <code class="computeroutput"><span class="identifier">resume</span></code> measuring the elapsed time. <a href="../reference/stopwatches.html#boost_chrono.reference.stopwatches.stopwatch_hpp.stopwatch" title="
Template Class stopwatch<>"><code class="computeroutput"><span class="identifier">stopwatch</span></code></a><code class="computeroutput"><span class="special"><></span></code>
is the basic model of <a href="../reference/stopwatches.html#boost_chrono.reference.stopwatches.stopwatch_req" title="
Stopwatch Requirements"><code class="computeroutput"><span class="identifier">Stopwatch</span></code></a> allowing to make a single
Modified: sandbox/chrono/libs/chrono/doc/html/index.html
==============================================================================
--- sandbox/chrono/libs/chrono/doc/html/index.html (original)
+++ sandbox/chrono/libs/chrono/doc/html/index.html 2010-08-13 12:56:10 EDT (Fri, 13 Aug 2010)
@@ -98,7 +98,7 @@
</table></div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
-<td align="left"><p><small>Last revised: August 13, 2010 at 08:06:51 GMT</small></p></td>
+<td align="left"><p><small>Last revised: August 13, 2010 at 16:53:45 GMT</small></p></td>
<td align="right"><div class="copyright-footer"></div></td>
</tr></table>
<hr>
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