mandag 7. juli 2014

[ C++11 - Part 2 ] Timing with chrono

std::chrono


The chrono library is a new part of C++11. It's used for timing functionality. It supports a variety of different operations and can be quite daunting in the beginning. I wrote a little about it in the previous part of my SDL2 tutorial, but I thought I'd add some more details and try to explain things a bit more throughly here. The library contains several new types, but I'll try to explain all of them shortly. But first a few practical tips that will make using std::chrono easier.

Some helpful tips


My first recommendation is that you write using namespace std::chrono somewhere your code ( preferably at the top ). Usually, using namespace statements are discouraged to avoid name collisions, but this is less likely to occur when you write using namespace std::[something] where something can be anything like string or cout or indeed chrono. The reason why we use this is quite simple. If we didn't use it, we'd end up with code with std::chrono all over the place. It's a lot easier ( at least for me ) to read

time_point p = high_resolution_clock::now();

Than it is to read

std::chrono::time_point p = std::chrono::high_resolution_clock::now();

Includes


To make sure everything compiles as it should, please add the headers and using to the top of your file :

#include
#include

using namespace std::chrono: // So we don't have to write std::chrono everywhere!

About this part


I also want to point out that this guide is rather comprehensive. This is because it's a good idea to have deep understanding how the various components of the chrono library works. Just writing this guide helped me to understand a lot of it. My hope is that it will help you to.

If you want more information, you can look at the en.cppreference documentation for chrono.

en.cppreference covers most, if not all of the features in C++11 with details information and good examples. It's very useful for learning and as a reference.

Overview


Here is a quick overview of the chrono library.


I will now go over each of these components, starting with the basic one, ratio

ratio


The ratio is actually not a direct part of chrono but it's very useful for working with chrono and just useful in genera. ration is define in it's own header file, simply called ratio

The class is self is template. The definition looks like the following :

template
<
    std::intmax_t Num,
    std::intmax_t Denom = 1
>
class ratio;
Even though this is a templated class, which can be complicated and hard to understand, this one is quite simple. The first part ( Num )is the numerator, or simply the top part of a fraction. And naturally, the second one, ( Denom ) is the denomerator. These two numbers forms a fractions : Num / Denom, usually these numbers are dividable by 10, so you end up with numbers like 1000 or 0.001

Both variables are of the type std::intmax_t, which means they are the biggest possible type of signed int available, usually at least 64 bits.

In the chrono library ticks are stored in fractions of second. A few examples :
  • A second : ratio < 1 /1 >
    • A second is 1 /1 of a second.  
    • Can also be written as std::ratio< 1 > since the denomerator defaults to 1
  • A millisecond :  ratio< 1 /1000 >
    • A millisecond is 1 / 1000 of a second
  • A minute : ratio< 60 /1 >
    • A minute is 60 / 1 seconds. 
    • Can also be written as ratio< 60 > since the denomerator defaults to 1

As a part of the ratio header, there's a lot of predefined ratios ( milli, nano, kilo, mega, ... ). Because ratio is not directly a part of the chrono library ( it has other uses than just chrono ), there is no predefined values for minutes, hours, etc. There's just the ones based on the standard units that's used for distance or weight. You can refer to either of these using the std:: prefix. Since the ratios are not part of the chrono library, it's just std:: and not std::chrono::.

For a full list of the predefined values, take a look at the documentation.

duration


duration( or std::chrono::duration ) is one of the basic classes of the chrono library. As the name suggests, it stores a time duration or a distance between to points in time if you like.

Member variables


It's quite simple in its structure, it only has two member variables :
  • rep
    • an arithmetic type ( basically any unit that can hold a number ) that stores the number of ticks.
  • period
    • a ration containing the type of unit rep stores. In effects this means "how many seconds is one tick."

Constructing a duration


The constructor for a duration is rather complex as it involves both rep ( the type of the variable to hold the tick ) And setting the period i.e. how long each tick is ( millisecond, second, minute, ... )

The actual constructor looks like this :
template
<
    class Rep,
    class Period = std::ratio<1>
>
class duration;
The ratio defaults to 1 / 1, meaning seconds. The number of ticks the duration should use are sent to the constructor in the ordinary way using the parenthesis after the variable name

So to create a duration for containing seconds, you can do :
duration< int64_t > durSec( 10 );
This duration is for 10 seconds. Nice and simple!

To create different durations we can use the ration like above.  For example 10 millisecond becomes :
duration< int64_t, std::ratio< 1, 1000 > > durMSec( 10 );
Okay, but how about 10 minutes? This is quite similar to the above :
duration< int64_t, std::ratio< 60, 1 > > durMin( 10 );

We do std::ratio< 60, 1 > because a minute is 60 / 1 seconds which is the same as 60 seconds.

As I mentioned above, there are predefined ratios already in C++11. So you can simplify a duration of 10 milliseconds to :
duration< int32_t, std::milli > dur( 10 );
But there is an even simpler way! Just like in ratio there are predefined values in duration And they're very simple to use.

So say you wanted a duration of 10 milliseconds :
milliseconds mSec( 10 );

Member functions


Duration has a few functions, but I'll just cover two of them now
  • count
    • Returns the number of ticks (rep , see the documentation above )
  • duration_cast 
    • Converts a duration of duration into another.

    duration_cast


    When we're working with two different types of durations things can get a bit weird. A simple example : what's 3 minutes minus 36 seconds. The answer is quite simple for a human to figure out. But the results in your program needs to be a duration but which unit? Since 3:24 can't be expressed exactly in minutes, we need to change either the 3 minutes to seconds, or the 36 seconds to minutes. Here's where duration_cast<> comes in.

    minutes min( 3 );
    seconds sec( 36 );
    minutes minToSec = duration_cast< std::chrono::seconds > ( min );
    This simply casts our 3 minutes into 180 seconds. After doing that, you can simply do

    seconds result = minToSec - sec;
    And you'll get the result in seconds ( 144. ) If you had converted this to minutes, it would take the whole minutes and strip the seconds. Meaning you would end up with 2

    Floating points


    Up until now, we've only used integer values for representing ticks. This means we can only represent whole tick. So a duration of seconds using an int to represent ticks means it can only represent whole seconds. Consider the following code :

    Create a duration of milliseconds represented as int :
    duration< int32_t, std::milli > msAsInt( 16 );c
    This is equal to the std::milliseconds

    Create a duration of seconds represented as int :
    duration< int32_t, std::ratio< 1, 1> > secAsInt( msAsInt );c
    This is equal to std::seconds. This will fail ( won't compile ) because you loose precision. You could use a duration_cast to fix this, but you'll loose the precision and end up with 0. duration_cast is way of telling the compiler "yeah, I know this will fail loose precision, just do it!"

    Create a duration of seconds represented as a double :
    duration< double, std::ratio< 1, 1> > secAsDouble(msAsInt);
    This is not the same as std::seconds because std::second uses int. If you did secondsAsFloat.count() you would get 0.016, because ticks are stored in a double.

    Unlike the previous line, this won't fail because you don't loose precision. In fact, you could change the std::ratio to store years :
    duration< double, std::ratio< 60 * 60 * 24 * 365, 1 > > yearsAsDouble( millisecondsAsInt ); // 0.016 sec
    This will convert the 16 ms to years. If you did yearsAsDouble.count() you would get roughly 5.07356672 × 10^-9 ( 0.00000000507356672 ) years.

    Clocks


    In order to set the time for a time_point you use clocks. Clocks are just object that has a starting point ( or epoch ) and a tick rate. The starting point is often 1.1.1970 ( UNIX timestamp ) and the tick rate can be 1 second for instance.

    There are three available clocks in the chrono library.
    • system_clock
      • The wall clock, use this if you just want to know the current time and date
      • This clock may be adjusted by either daylight saving time ( DST ) or leap seconds.
      • Can be mapped to C-style points and can therefore be easily printed.
    •  steady_clock
      • This clock is monotonic, this means will never be adjusted, so it'll never be affected by things like DST and leap seconds
      • Best suited for measuring intervals
    •  high_resolution_clock
      • Shortest tick available ( will be updated most often )
      • Might be alias of std::chrono::system_clock or std::chrono::steady_clock, or a third, independent clock.  
        • This means it's not guaranteed to be monotonic like steady_clock
      • Use this for benchmarking

    time_point


    time_point ( or std::chrono::time_point) is the central class of the chrono library. I'll spare the implementation details for now and just say that it contains various information about the current point it in time.

    Construction


    The constructor for a time point looks something like this :

    template
    <
        class Clock,
        class Duration = typename Clock::duration
    >
    class time_point;
    As you can see, its a templated class that takes both a clock, and a duration. The duration is the duration the time_point uses. This defaults to the duration of the clock ( as you can see from the n = typename Clock::duration part. ) Luckily though don't have to specify either of the arguments. SO a really simple way to construct a time_point is :
    high_resolution_clock::time_point timePoint1;
    You can use stady_clock or system_clock instead of high_resolution_clock.

    This is equal to writing :
    time_point < high_resolution_clock > timePoint1;
    A bit more complex, but it means the exact same time : a time_point that uses a high_resolution_clock and has the same duration as the high_resolution_clock. I see no reason to use this method as opposed to the simpler one, but I want to explain the template arguments as well as I can.

    But what if we wanted to specify our own duration? Well then we have to set the second template argument as well. Say we wanted to specify milliseconds as our duration time unit. Remember that duration has predefined constants for this. This means we can simply do :
    time_point < high_resolution_clock, milliseconds >
    Now let's do something even worse. Say we wanted a time_point that uses half minutes ( 30 seconds ) as the time units. I have no idea why anyone would want this, but it's just a ( somewhat contrived ) example. As with some other examples, I do not encourage writing code like this. It's horribly hard to read and very hard to understand unless you know the different part of the chrono librarer. Okay, here we go :
    time_point
    <
        high_resolution_clock,
        std::chrono::duration
        <
            int64_t,
            std::ratio
            <
                30,
                1000
            >
         >
    >
    Yup, that's a template argument, inside a template argument, inside a template argument! Don't write code like this! If you need a specific time ration, at least put the ration and duration in separate objects ( I've shown you how to use the constructors above. ) Also make sure they're well named like ratio30sec and duration30sec. That should give the reader at least a small hope at knowing what's going on.

    Functions


    With that out of the way, let's move on to some functions, shall we? Well actually there's just one member function in the three different clocks :
    now()
    The function returns the current time as a time_point. As a time_point, you say? Well that means we can just use auto to create one!
    auto time = high_resolution_clock::now()

    Simple as that, we've created a time point. The type of this object will be exactly the same as
    high_resolution_clock::time_point timePoint1;

    Only it's even simpler. And we've initialized it to the current point in time at the same time!

    Difference between two time_points


    Time points supports arithmetic operations. This means you can say time_point x - time_point y. This will result in a duration But what is the kind of duration. Seconds? Milliseconds? Years? Actually there is no one answer, it's implementation defined. But the result is almost certain to be less than one second.

    Since we can't know what the resulting value is, we have two options. Say we have the following code :

    clock::time_point t1 = std::chrono::system_clock::now() ;
    // ...
    clock::time_point t2 = std::chrono::system_clock::now() ;

    And wanted to know the result of t1 - t2 Our two options are :

    1. Use atuto
      •  auto result = t2 - t1 ;
        • Nice and simple
        • But we can't control the type of result.
    2. Use duration_cast
      •  milliseconds result =  duration_cast< milliseconds > ( t2 - t1 ) ;
        • Takes the result of t2 - t1 and casts it into a duration of milliseconds and uses it to set result
        • This is a bit harder, but now we have full control over the type of duration.


      For a full list of my tutorials / posts, click here.

      Feel free to comment if you have anything to say, any suggestion or any questions. I always appreciate getting comments.


      Ingen kommentarer:

      Legg inn en kommentar