Re: [boost] [Review] Formal Review of Proposed Boost.Chrono Library Starts TOMORROW

Subject: Re: [boost] [Review] Formal Review of Proposed Boost.Chrono Library Starts TOMORROW
From: vicente.botet (vicente.botet_at_[hidden])
Date: 2010-11-08 16:36:54

----- Original Message ----- 
From: "Roland Bock" <rbock_at_[hidden]>
To: <boost_at_[hidden]>
Sent: Monday, November 08, 2010 9:03 PM
Subject: Re: [boost] [Review] Formal Review of Proposed Boost.Chrono Library Starts TOMORROW

> 
> On 11/08/2010 06:32 PM, vicente.botet wrote:
>> Many thanks. Please, could you point to other documentation improvements?
> 
> here are some more items. I'm sure there's more, but I'm in a bit of a 
> hurry and did not go through the document line by line:

Please if you have sometime later on, I would apreciate if you can make a deep review of the documentation, better if you do it before the review, but I would take them in account even later. 

http://svn.boost.org/svn/boost/sandbox/chrono/libs/chrono/doc/html/boost_chrono/overview/description.html
> 
> *) "the extraction of read (wall clock) time," <= real? CPU time?
OK.
> *) "|process_real_cpu_clock| 
OK. <http://svn.boost.org/svn/boost/sandbox/chrono/libs/chrono/doc/html/boost_chrono/reference/other_clocks.html#boost_chrono.reference.other_clocks.process_cpu_clocks_hpp.process_real_cpu_clock>, 
> captures real (wall clock) CPU times." <= is this really CPU time? Isn't 
> it rather real process time?

Yes,  is the time since the process start-up. I will clarify this point.

> *) "A tuple-like class __process_cpuclock_, that" <= The link is broken.
OK.
 
> http://svn.boost.org/svn/boost/sandbox/chrono/libs/chrono/doc/html/boost_chrono/users_guide.html
> I'd prefer to see the same sequence of duration, timepoint, clocks, 
> other clocks etc. Currently every chapter is different:
> 
> - Description:
> duration, time_point, clocks, other clocks, io
> - Tutorial:
> duration, clocks, time_point, io
> - Examples:
> time_point, duration, clocks, conversions, reporting
> - Reference:
> duration, time_point, clocks, io, other clocks
> 
> Personally, I like Description and Reference best.

OK. I will make them uniform and take the Description order: duration, time_point, clocks, other clocks, io

http://svn.boost.org/svn/boost/sandbox/chrono/libs/chrono/doc/html/boost_chrono/users_guide/tutorial.html
> Taking a look at the table of contents for this section shows that 
> duration is covered in much detail, time_point, a bit less. Clock and IO 
> seem to be rather neglected. Given the sheer number of different clocks 
> available in Chrono, this seems unbalanced.
> And taking a closer look at the "Clocks" section shows: The tutorial 
> explains the interface of a clock, but not the clocks themselves. What 
> is a system clock, what's so cool about a monotonic_clock, what 
> distinguishes a high_precision_clock (another damaged link here).

You are right, the documentation pre-suposse that the user is familiar with the different kind of clocks. An explanation of when each clock could be used seems necessary.

The standard defines tree system-wide clocks that are associated to the computer time. The system_clock represents system-wide  realtime clock that can be synchronized with an external clock. monotonic_clock can not be changed explicitly and the time since the initial epoch increase in a monotonic way. high_resolution_clock intend to use the system-wide clock provided by the platform with the higest resolution.

The library adds some clocks that  are specific to a process or a thread, that is there is a clocks per process or per thread.

System clocks are useful when you need to correlate the time with a known epoch so you can convert it to a calendar time. Note the specific functions in the system_clock class.

Monotonic clocks are useful when you need to wait for a specific amount of time. As system_clock time can be reset, timers will not be safe. The clocks used for the Thread library should be monotonic, but the platform don't always provide monotonic thread interfaces.

When available, high resolution clocks are usualy more expensive than the other system-wide clocks, so they are used only when the provided resolution is required to the application.

I use process clocks and thread clocks to measure the time spent by them, for example they can be used to  basic time-spent profiling of different blocks of code (Boost.Stopwatch is clear example of this use) or by regulation mechanism.

I will include something that makes clear the distiction.
 
> In order to remove confusion about wall time and CPU time, a small 
> example using different clocks might be useful (if it is there, I missed 
> it). I would like to see this as part of the tutorial.

No, you don't missed it. I will add a specific section for each clock.

 http://svn.boost.org/svn/boost/sandbox/chrono/libs/chrono/doc/html/boost_chrono/users_guide/examples.html
> - Just stumbled over this: simaulation
> - There is no thread_clock mentioned here, even though there is a thread 
> interface demonstration program.

The intent of the simulation was not to show how thread cloks can be used but how the Thread interface can be modified to manage with a generic and scalable clock interface.
 
Thanks,
Vicente