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 :
- Use
atuto
- Nice and simple
- But we can't control the type of result.
- 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.
