blob: b5cfff9cc899572c28db5300ba2e18471fe674b4 [file] [log] [blame]
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Appendices</title>
<link rel="stylesheet" href="../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
<link rel="home" href="../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset">
<link rel="up" href="../chrono.html" title="Chapter&#160;4.&#160;Boost.Chrono 1.1.0">
<link rel="prev" href="reference.html" title="Reference">
<link rel="next" href="../id318693-bb.html" title="Chapter&#160;5.&#160;Boost.Concept_Check">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td>
<td align="center"><a href="../../../index.html">Home</a></td>
<td align="center"><a href="../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="reference.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../chrono.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="../id318693-bb.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="chrono.appendices"></a><a class="link" href="appendices.html" title="Appendices">Appendices</a>
</h2></div></div></div>
<div class="toc"><dl>
<dt><span class="section"><a href="appendices.html#chrono.appendices.history">Appendix A: History</a></span></dt>
<dt><span class="section"><a href="appendices.html#chrono.appendices.rationale">Appendix B: Rationale</a></span></dt>
<dt><span class="section"><a href="appendices.html#chrono.appendices.implementation">Appendix C: Implementation
Notes</a></span></dt>
<dt><span class="section"><a href="appendices.html#chrono.appendices.faq">Appendix D: FAQ</a></span></dt>
<dt><span class="section"><a href="appendices.html#chrono.appendices.acknowledgements">Appendix E: Acknowledgements</a></span></dt>
<dt><span class="section"><a href="appendices.html#chrono.appendices.todo">Appendix F: Future plans</a></span></dt>
</dl></div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="chrono.appendices.history"></a><a class="link" href="appendices.html#chrono.appendices.history" title="Appendix A: History">Appendix A: History</a>
</h3></div></div></div>
<div class="toc"><dl>
<dt><span class="section"><a href="appendices.html#chrono.appendices.history.__version_1_1_0__mars_17__2011__"><span class="bold"><strong>Version 1.1.0, Mars 17, 2011</strong></span> </a></span></dt>
<dt><span class="section"><a href="appendices.html#chrono.appendices.history.__version_1_0_0__january_6__2011__"><span class="bold"><strong>Version 1.0.0, January 6, 2011</strong></span> </a></span></dt>
</dl></div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="chrono.appendices.history.__version_1_1_0__mars_17__2011__"></a><a class="link" href="appendices.html#chrono.appendices.history.__version_1_1_0__mars_17__2011__" title="Version 1.1.0, Mars 17, 2011"><span class="bold"><strong>Version 1.1.0, Mars 17, 2011</strong></span> </a>
</h4></div></div></div>
<p>
<span class="bold"><strong>New Features:</strong></span>
</p>
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
<li class="listitem">
<a href="http://svn.boost.org/trac/boost/ticket/????" target="_top">#????</a>
Added time_point unary operators +,-,++,-- and binary operators +<code class="literal">,-</code>
with Rep al RHS.
</li>
<li class="listitem">
<a href="http://svn.boost.org/trac/boost/ticket/5323" target="_top">#5323</a>
Add Associated type difference_type for chrono::time_point.
</li>
</ul></div>
<p>
<span class="bold"><strong>Fixes:</strong></span>
</p>
<div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
<a href="http://svn.boost.org/trac/boost/ticket/5322" target="_top">#5322</a>
Explicit default constructed chrono::durations are uninitialized
</li></ul></div>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="chrono.appendices.history.__version_1_0_0__january_6__2011__"></a><a class="link" href="appendices.html#chrono.appendices.history.__version_1_0_0__january_6__2011__" title="Version 1.0.0, January 6, 2011"><span class="bold"><strong>Version 1.0.0, January 6, 2011</strong></span> </a>
</h4></div></div></div>
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
<li class="listitem">
Moved chrono to trunk taking in account the review remarks.
</li>
<li class="listitem">
Documentation revision.
</li>
</ul></div>
<p>
<span class="bold"><strong>Features:</strong></span>
</p>
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
<li class="listitem">
Boost_Chrono is now a configurable header-only library version (that
also allows the user to choose if the <code class="computeroutput"><span class="identifier">windows</span><span class="special">.</span><span class="identifier">h</span></code>
file is included or not).
</li>
<li class="listitem">
Added clock_string&lt;&gt; traits.
</li>
<li class="listitem">
Define chrono-io for all the clocks.
</li>
<li class="listitem">
Add input of process_times representation.
</li>
</ul></div>
<p>
<span class="bold"><strong>Implementation:</strong></span>
</p>
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
<li class="listitem">
Use of detail/win files to avoid the use of windows.h file.
</li>
<li class="listitem">
Completed the error_code handling.
</li>
<li class="listitem">
Works now with BOOST_SYSTEM_NO_DEPRECATED.
</li>
</ul></div>
<p>
<span class="bold"><strong>Fixes:</strong></span>
</p>
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
<li class="listitem">
Fix some warnings.
</li>
<li class="listitem">
Fix original errors on Mac
</li>
<li class="listitem">
Don't fix the link with boost_system to static.
</li>
</ul></div>
<p>
<span class="bold"><strong>Test:</strong></span>
</p>
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
<li class="listitem">
Added test on process and thread clocks.
</li>
<li class="listitem">
Moved to lightweight_test.hpp.
</li>
<li class="listitem">
Able to test multiple configurations.
</li>
</ul></div>
<p>
<span class="bold"><strong>Doc:</strong></span>
</p>
<div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
Removed some not useful parts as the test and the tickets.
</li></ul></div>
</div>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="chrono.appendices.rationale"></a><a class="link" href="appendices.html#chrono.appendices.rationale" title="Appendix B: Rationale">Appendix B: Rationale</a>
</h3></div></div></div>
<p>
See <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2661.htm" target="_top"><span class="bold"><strong>N2661 - A Foundation to Sleep On</strong></span></a> which is
very informative and provides motivation for key design decisions. This section
contains some extracts from this document.
</p>
<a name="chrono.appendices.rationale.why_duration_needs_operator_"></a><h5>
<a name="chrono.appendices.rationale.why_duration_needs_operator_-heading"></a>
<a class="link" href="appendices.html#chrono.appendices.rationale.why_duration_needs_operator_">Why
duration needs operator%</a>
</h5>
<p>
This operator is convenient for computing where in a time frame a given duration
lies. A motivating example is converting a duration into a "broken-down"
time duration such as hours::minutes::seconds:
</p>
<pre class="programlisting"><span class="keyword">class</span> <span class="identifier">ClockTime</span>
<span class="special">{</span>
<span class="keyword">typedef</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">chrono</span><span class="special">::</span><span class="identifier">hours</span> <span class="identifier">hours</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">chrono</span><span class="special">::</span><span class="identifier">minutes</span> <span class="identifier">minutes</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">chrono</span><span class="special">::</span><span class="identifier">seconds</span> <span class="identifier">seconds</span><span class="special">;</span>
<span class="keyword">public</span><span class="special">:</span>
<span class="identifier">hours</span> <span class="identifier">hours_</span><span class="special">;</span>
<span class="identifier">minutes</span> <span class="identifier">minutes_</span><span class="special">;</span>
<span class="identifier">seconds</span> <span class="identifier">seconds_</span><span class="special">;</span>
<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">Rep</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Period</span><span class="special">&gt;</span>
<span class="keyword">explicit</span> <span class="identifier">ClockTime</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">chrono</span><span class="special">::</span><span class="identifier">duration</span><span class="special">&lt;</span><span class="identifier">Rep</span><span class="special">,</span> <span class="identifier">Period</span><span class="special">&gt;&amp;</span> <span class="identifier">d</span><span class="special">)</span>
<span class="special">:</span> <span class="identifier">hours_</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">duration_cast</span><span class="special">&lt;</span><span class="identifier">hours</span><span class="special">&gt;</span> <span class="special">(</span><span class="identifier">d</span><span class="special">)),</span>
<span class="identifier">minutes_</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">duration_cast</span><span class="special">&lt;</span><span class="identifier">minutes</span><span class="special">&gt;(</span><span class="identifier">d</span> <span class="special">%</span> <span class="identifier">hours</span><span class="special">(</span><span class="number">1</span><span class="special">))),</span>
<span class="identifier">seconds_</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">duration_cast</span><span class="special">&lt;</span><span class="identifier">seconds</span><span class="special">&gt;(</span><span class="identifier">d</span> <span class="special">%</span> <span class="identifier">minutes</span><span class="special">(</span><span class="number">1</span><span class="special">)))</span>
<span class="special">{}</span>
<span class="special">};</span>
</pre>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="chrono.appendices.implementation"></a><a class="link" href="appendices.html#chrono.appendices.implementation" title="Appendix C: Implementation Notes">Appendix C: Implementation
Notes</a>
</h3></div></div></div>
<a name="chrono.appendices.implementation.which_apis_have_been_chosen_to_implement_each_clock_on_each_platform_"></a><h5>
<a name="chrono.appendices.implementation.which_apis_have_been_chosen_to_implement_each_clock_on_each_platform_-heading"></a>
<a class="link" href="appendices.html#chrono.appendices.implementation.which_apis_have_been_chosen_to_implement_each_clock_on_each_platform_">Which
APIs have been chosen to implement each clock on each platform?</a>
</h5>
<p>
The following table presents a resume of which API is uused for each clock
on each platform
</p>
<div class="table">
<a name="chrono.appendices.implementation.clock_api_correspondence"></a><p class="title"><b>Table&#160;4.2.&#160;Clock API correspondence</b></p>
<div class="table-contents"><table class="table" summary="Clock API correspondence">
<colgroup>
<col>
<col>
<col>
<col>
</colgroup>
<thead><tr>
<th>
<p>
Clock
</p>
</th>
<th>
<p>
Windows Platform
</p>
</th>
<th>
<p>
Posix Platform
</p>
</th>
<th>
<p>
Mac Platform
</p>
</th>
</tr></thead>
<tbody>
<tr>
<td>
<p>
<a class="link" href="reference.html#chrono.reference.cpp0x.system_clocks_hpp.system_clock" title="Class system_clock"><code class="computeroutput"><span class="identifier">system_clock</span></code></a>
</p>
</td>
<td>
<p>
GetSystemTimeAsFileTime
</p>
</td>
<td>
<p>
clock_gettime( CLOCK_REALTIME)
</p>
</td>
<td>
<p>
gettimeofday
</p>
</td>
</tr>
<tr>
<td>
<p>
<a class="link" href="reference.html#chrono.reference.cpp0x.system_clocks_hpp.steady_clock" title="Class steady_clock"><code class="computeroutput"><span class="identifier">steady_clock</span></code></a>
</p>
</td>
<td>
<p>
QueryPerformanceCounter and QueryPerformanceFrequency
</p>
</td>
<td>
<p>
clock_gettime( CLOCK_STEADY)
</p>
</td>
<td>
<p>
mach_timebase_info,mach_absolute_time
</p>
</td>
</tr>
<tr>
<td>
<p>
<a class="link" href="reference.html#chrono.reference.other_clocks.process_cpu_clocks_hpp.process_real_cpu_clock" title="Class process_real_cpu_clock"><code class="computeroutput"><span class="identifier">process_real_cpu_clock</span></code></a>
</p>
</td>
<td>
<p>
GetProcessTimes
</p>
</td>
<td>
<p>
times
</p>
</td>
<td>
<p>
times
</p>
</td>
</tr>
<tr>
<td>
<p>
<a class="link" href="reference.html#chrono.reference.other_clocks.process_cpu_clocks_hpp.process_system_cpu_clock" title="Class process_system_cpu_clock"><code class="computeroutput"><span class="identifier">process_system_cpu_clock</span></code></a>
</p>
</td>
<td>
<p>
GetProcessTimes
</p>
</td>
<td>
<p>
times
</p>
</td>
<td>
<p>
times
</p>
</td>
</tr>
<tr>
<td>
<p>
<a class="link" href="reference.html#chrono.reference.other_clocks.process_cpu_clocks_hpp.process_user_cpu_clock" title="Class process_user_cpu_clock"><code class="computeroutput"><span class="identifier">process_user_cpu_clock</span></code></a>
</p>
</td>
<td>
<p>
GetProcessTimes
</p>
</td>
<td>
<p>
times
</p>
</td>
<td>
<p>
times
</p>
</td>
</tr>
<tr>
<td>
<p>
<a class="link" href="reference.html#chrono.reference.other_clocks.process_cpu_clocks_hpp.process_cpu_clock" title="Class process_cpu_clock"><code class="computeroutput"><span class="identifier">process_cpu_clock</span></code></a>
</p>
</td>
<td>
<p>
GetProcessTimes
</p>
</td>
<td>
<p>
times
</p>
</td>
<td>
<p>
times
</p>
</td>
</tr>
<tr>
<td>
<p>
<a class="link" href="reference.html#chrono.reference.other_clocks.thread_clock_hpp.thread_clock" title="Class thread_clock"><code class="computeroutput"><span class="identifier">thread_clock</span></code></a>
</p>
</td>
<td>
<p>
GetThreadTimes
</p>
</td>
<td>
<p>
clock_gettime(pthread_getcpuclockid)
</p>
</td>
<td>
<p>
clock_gettime(pthread_getcpuclockid)
</p>
</td>
</tr>
</tbody>
</table></div>
</div>
<br class="table-break">
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="chrono.appendices.faq"></a><a class="link" href="appendices.html#chrono.appendices.faq" title="Appendix D: FAQ">Appendix D: FAQ</a>
</h3></div></div></div>
<a name="chrono.appendices.faq.why_does_process_cpu_clock_sometimes_give_more_cpu_seconds_than_real_seconds_"></a><h5>
<a name="chrono.appendices.faq.why_does_process_cpu_clock_sometimes_give_more_cpu_seconds_than_real_seconds_-heading"></a>
<a class="link" href="appendices.html#chrono.appendices.faq.why_does_process_cpu_clock_sometimes_give_more_cpu_seconds_than_real_seconds_">Why
does process_cpu_clock sometimes give more cpu seconds than real seconds?</a>
</h5>
<p>
Ask your operating system supplier. The results have been inspected with
a debugger, and both for Windows and Linux, that's what the OS appears to
be reporting at times.
</p>
<a name="chrono.appendices.faq.are_integer_overflows_in_the_duration_arithmetic_detected_and_reported_"></a><h5>
<a name="chrono.appendices.faq.are_integer_overflows_in_the_duration_arithmetic_detected_and_reported_-heading"></a>
<a class="link" href="appendices.html#chrono.appendices.faq.are_integer_overflows_in_the_duration_arithmetic_detected_and_reported_">Are
integer overflows in the duration arithmetic detected and reported?</a>
</h5>
<p>
<span class="bold"><strong>Boost.Ratio</strong></span> avoids all kind of overflow
that could result of arithmetic operation and that can be simplified. The
typedefs durations don't detect overflow. You will need a duration representation
that handles overflow.
</p>
<a name="chrono.appendices.faq.which_clocks_should_be_used_to_benchmarking_"></a><h5>
<a name="chrono.appendices.faq.which_clocks_should_be_used_to_benchmarking_-heading"></a>
<a class="link" href="appendices.html#chrono.appendices.faq.which_clocks_should_be_used_to_benchmarking_">Which
clocks should be used to benchmarking?</a>
</h5>
<p>
Each clock has his own features. It depends on what do you need to benchmark.
Most of the time, you could be interested in using a thread clock, but if
you need to measure code subject to synchronization a process clock would
be better. If you have a multi-process application, a system-wide clock could
be needed.
</p>
<a name="chrono.appendices.faq.which_clocks_should_be_used_for_watching_"></a><h5>
<a name="chrono.appendices.faq.which_clocks_should_be_used_for_watching_-heading"></a>
<a class="link" href="appendices.html#chrono.appendices.faq.which_clocks_should_be_used_for_watching_">Which
clocks should be used for watching?</a>
</h5>
<p>
For trace purposes, it is probably best to use a system-wide clock.
</p>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="chrono.appendices.acknowledgements"></a><a class="link" href="appendices.html#chrono.appendices.acknowledgements" title="Appendix E: Acknowledgements">Appendix E: Acknowledgements</a>
</h3></div></div></div>
<p>
The library's code was derived from Howard Hinnant's time2_demo prototype.
Many thanks to Howard for making his code available under the Boost license.
The original code was modified by Beman Dawes to conform to Boost conventions.
</p>
<p>
time2_demo contained this comment:
</p>
<p>
Much thanks to Andrei Alexandrescu, Walter Brown, Peter Dimov, Jeff Garland,
Terry Golubiewski, Daniel Krugler, Anthony Williams.
</p>
<p>
The file &lt;boost/chrono_io.hpp&gt; has been adapted from the experimental
header <code class="computeroutput"><span class="special">&lt;</span><span class="identifier">chrono_io</span><span class="special">&gt;</span></code> from Howard Hinnant. Thanks for all Howard.
</p>
<p>
Howard Hinnant, who is the real author of the library, has provided valuable
feedback and suggestions during the development of the library. In particular,
The chrono_io_io.hpp source has been adapted from the experimental header
<code class="computeroutput"><span class="special">&lt;</span><span class="identifier">chrono_io</span><span class="special">&gt;</span></code> from Howard Hinnant.
</p>
<p>
The acceptance review of Boost.Ratio took place between November 5th and
15th 2010. Many thanks to Anthony Williams, the review manager, and to all
the reviewers: David Deakins, John Bytheway, Roland Bock and Paul A. Bristow.
</p>
<p>
Thanks to Ronald Bock, Andrew Chinoff, Paul A. Bristow and John Bytheway
for his help polishing the documentation.
</p>
<p>
Thanks to Tom Tan for reporting some compiler issues with MSVC V10 beta and
MinGW-gcc-4.4.0 and for the many pushing for an homogeneous <code class="computeroutput"><span class="identifier">process_cpu_clock</span></code> clock.
</p>
<p>
Thanks to Ronald Bock for reporting Valgind issues and for the many suggestions
he made concerning the documentation.
</p>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="chrono.appendices.todo"></a><a class="link" href="appendices.html#chrono.appendices.todo" title="Appendix F: Future plans">Appendix F: Future plans</a>
</h3></div></div></div>
<a name="chrono.appendices.todo.for_later_releases"></a><h5>
<a name="chrono.appendices.todo.for_later_releases-heading"></a>
<a class="link" href="appendices.html#chrono.appendices.todo.for_later_releases">For later releases</a>
</h5>
<div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
Add chrono utilities as defined By Howard Hinnant <a href="http://home.roadrunner.com/~hinnant/duration_io/chrono_util.html" target="_top">here</a>.
</li></ul></div>
</div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright &#169; 2008 Howard Hinnant<br>Copyright &#169; 2006, 2008 Beman Dawes<br>Copyright &#169; 2009-2011 Vicente J. Botet
Escriba<p>
Distributed under the Boost Software License, Version 1.0. (See accompanying
file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
</p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="reference.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../chrono.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="../id318693-bb.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>