Boost C++ Libraries of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

This is the documentation for an old version of Boost. Click here to view this page for the latest version.

Chapter 4. Boost.Chrono 1.1.0

Howard Hinnant

Beman Dawes

Vicente J. Botet Escriba

Distributed under the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at

Table of Contents

User's Guide
Getting Started
External Resources
Included on the C++0x Recommendation
Chrono I/O
Other Clocks
Appendix A: History
Appendix B: Rationale
Appendix C: Implementation Notes
Appendix D: FAQ
Appendix E: Acknowledgements
Appendix F: Future plans

What is time, then? If nobody asks me, I know; if I have to explain it to someone who has asked me, I do not know."

-- Augustine

How to Use This Documentation

This documentation makes use of the following naming and formatting conventions.

  • Code is in fixed width font and is syntax-highlighted.
  • Replaceable text that you will need to supply is in italics.
  • Free functions are rendered in the code font followed by (), as in free_function().
  • If a name refers to a class template, it is specified like this: class_template<>; that is, it is in code font and its name is followed by <> to indicate that it is a class template.
  • If a name refers to a function-like macro, it is specified like this: MACRO(); that is, it is uppercase in code font and its name is followed by () to indicate that it is a function-like macro. Object-like macros appear without the trailing ().
  • Names that refer to concepts in the generic programming sense are specified in CamelCase.
[Note] Note

In addition, notes such as this one specify non-essential information that provides additional background or rationale.

Finally, you can mentally add the following to any code fragments in this document:

// Include all of Chrono files
#include <boost/chrono.hpp>

We all deal with time every day of our lives. We've intuitively known it since birth. Thus we are all very familiar with it and believe it to be a simple matter. The modeling of time in computer programs should be similarly simple. The unfortunate truth is that this perceived simplicity is only skin deep. Fortunately, we do not need a terribly complicated solution to meet the bulk of our needs. However, overly simplistic solutions can be dangerous and inefficient, and won't adapt as the computer industry evolves.

Boost.Chrono aims to implement the new time facilities in C++0x, as proposed in N2661 - A Foundation to Sleep On. That document provides background and motivation for key design decisions and is the source of a good deal of information in this documentation.

Wall clock versus system and user time

To make the timing facilities of Boost.Chrono more generally useful, the library provides a number of clocks that are thin wrappers around the operating system's process time API, thereby allowing the extraction of wall clock time, user CPU time, and system CPU time of the process. Wall clock time is the sum of CPU time and system CPU time. (On POSIX-like systems, this relies on times(). On Windows, it relies on GetProcessTimes().)

The Boost.Chrono library provides:

Other clocks

To make the timing facilities more generally useful, Boost.Chrono provides a number of clocks that are thin wrappers around the operating system's time APIs, thereby allowing the extraction of wall clock time, user CPU time, system CPU time spent by the process,

Lastly, Boost.Chrono includes typeof registration for duration and time_point to permit using emulated auto with C++03 compilers.


It provides I/O for duration and time_point. It builds on <boost/ratio/ratio_io.hpp> to provide readable and flexible formatting and parsing for types in <boost/chrono.hpp>. The duration unit names can be customized through a new facet: duration_punct.

Caveat Emptor

The underlying clocks provided by operating systems are subject to many seemingly arbitrary policies and implementation irregularities. That's a polite way of saying they tend to be flakey, and each operating system or even each clock has its own cruel and unusual forms of flakiness. Don't bet the farm on their accuracy, unless you have become deeply familiar with exactly what the specific operating system is guaranteeing, which is often very little.

Last revised: July 05, 2011 at 15:25:31 GMT