Boost C++ Libraries

...one 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.
PrevUpHomeNext

Appendices

Appendix: History
Appendix: Rationale
Appendix: Implementation Notes
Appendix: FAQ
Appendix: Acknowledgements
Appendix: Future plans

Fixes:

  • Remove Stopwatches, which was never be delivered officially.

Fixes:

  • #11630 boost chrono documentation about boost chrono version & io API is wrong.
  • #12176 Chrono without linking to Boost.System
  • #12260 Bug: time_fmt does not support for wchar_t on windows

Fixes:

  • #11330 boost::chrono::duration default constructor doesn't initialize rep_
  • #11618 Chrono IO V2 doc ios_state.hpp does not exist
  • #11631 boost chrono io v2 does not let you support custom clocks

Fixes:

  • #10778 VC14 CTP4 Atomic don't compile with boost::chrono durations which are not TriviallyCopyable
  • #10840 Missing std:: qualifier for puts call in test_7868.cpp
  • #10851 Missing std:: qualifier for puts call in time_point_output.cpp
  • #10893 Minor doc typo in Boost.Chrono
  • #10992 Chrono IO state savers inconsistent with Boost.IO state savers
  • #10995 duration_put::put_value truncates fractional part
  • #11006 Impossible to instantiate time_fmt_io_saver due to several errors.
  • #11012 chrono_io v2 fail to compile with boost::chrono::duration< boost::rational<int> >

Fixes:

  • #6918 Boost Chrono compilation failure on HP uX due to undefined pthread_getcpuclockid
  • #8006 Boost::Chrono Assertion at startup - steady_clock::now() - Windows
  • #9337 chrono::process_cpu_clock time points wrong by factor 1000 on Linux
  • #9342 Regression on process_cpu_clock::timepoint io on V2
  • #9419 boost::chrono::floor()/round() and negative durations is wrong
  • #9698 boost::chrono::thread_clock not declared in OSX
  • #9720 boost::this_thread::sleep_for() sometimes returns immediately on win32
  • #9859 Remove references to gcc-mingw
  • #9918 chrono compilation error on Solaris, function timegm
  • #9811 boost/boost/chrono/duration.hpp:355:56: error: call to non-constexpr function 'static std::numeric_limits<float>::_Ty std::numeric_limits<float>::max()' /home/zosun/input_service/inputservices-core-service/other/boost/boost/chrono/duration.hpp: In static member function 'static constexpr double boost::chrono::detail::chrono_numeric_limits<double, true>::lowest()':
  • #10069 Overflow in chrono clocks on 32bit
  • #10151 timegm function not available on QNX

Fixes:

  • #7868 chrono_io parses time incorrectly (1.53 and 1.52)
  • #9028 Typo in boost/chrono/stopwatches/formatters/base_formatter.hpp
  • #9147 uninitialized std::tm
  • #9274 lost of precision on system_clock input.
  • #9276 output from a system_clock::time_point get a time_point that is one day later than expected.

Fixes:

  • #8079 Chrono memory leak
  • #8318 BOOST_FORCEINLINE constructors of time_point and duration
  • #8367 chrono does not compile with clang from XCode 4.5.2 with -std=c++11 -stdlib=libc++ and -arch armv7
  • #8370 typo in chrono reference
  • #8435 Can't compile Chrono on HP-UX due to no CLOCK_REALTIME macro.
  • #8690 duration_units_default - lost return types constness in overridden methods.
  • #8691 iostate is not checked after scan_keyword call.
  • #8696 chrono compilation error on Solaris/gcc.

Deprecated:

  • The chrono i/o version included in Boost.Chrono 1.2.x has been completly refactored in version 2.0.0
  • chrono I/O: The manipulators duration_short, duration_long are deprecated. You should use the parameterized form duration_fmt or the renamed manipulators __duration_symbol and __duration_prefix instead.
  • chrono I/O: The duration_punct<> facet is deprecated. You should use the get_duration_style free function to get the informations and use the duration_units facet for localization purposes.

When BOOST_CHRONO_VERSION==2 the preceding deprecated functions are not available.

Fixes:

  • #7546 time_point<system_clock> output version 2 fails to compile assigned viboes Bugs Boost 1.53.0 --
  • #7547 time_point<system_clock> input version 2 fails to compile assigned viboes Bugs Boost 1.53.0 --
  • #7868 chrono_io parses time incorrectly (1.53 and 1.52)

New Features:

  • Enhance chrono I/O
    • #5980 Enhance chrono I/O with H. Hinnant proposal proposal which has the advantage to provide I/O for system clocks using the Gregorian Calendar.
    • #5981 Add i/o state savers for duration and time_point formatting state.
    • #7059 Add low level i/o facilities.

Deprecated:

  • The chrono i/o version included in Boost.Chrono 1.2.x has been completly refactored in version 2.0.0
  • chrono I/O: The manipulators duration_short, duration_long are deprecated. You should use the parameterized form duration_fmt or the renamed manipulators __duration_symbol and __duration_prefix instead.
  • chrono I/O: The duration_punct<> facet is deprecated. You should use the get_duration_style free function to get the informations and use the duration_units facet for localization purposes.

When BOOST_CHRONO_VERSION==2 the preceding deprecated functions are not available.

Fixes:

  • #7381 C++11 compliance: unresolved symbol when assigning a constexpr duration to a non-const local variable.
  • #7479 Compiles fails with compilers supporting constexpr fails if the standard library doesn't provides the constexpr interface
  • #7493 compile fail on intel-linux-12.1.3.0x because of bug on explicit bool conversion
  • #7542 Missing -lpthread in chrono/io tester Sandia-clang-trunk

Would not fix:

  • #6871 chrono_io.hpp: operator<<(ostream& os, ...) modifies the state of os.
    • The new io interface provided in version 2 solves this issue. You should move to the new version.

Known bugs not fixed yet:

  • #7525 Wrong clock_string<system_clock>::since() on Windows

Fixes:

  • #6918 Boost Chrono compilation failure on HP uX due to undefined pthread_getcpuclockid.
  • #6241 boost::chrono compilation problems without std::wstring support.
  • #6987 Documentation & C++11.
  • #7041 time_point.hpp depends on Boost.System.
  • #7042 Avoiding time_point and duration dependency on time.h and CLOCK_REALTIME.
  • #7058 Make it work when BOOST_NO_EXCEPTIONS is defined.
  • #7069 Misspellings in clock_string<thread_clock>.
  • #7081 WinError.h capitalization in boost/detail/win/basic_types.hpp.

Fixes:

  • #6361 integer overflow in boost::chrono::process_real_cpu_clock::now() under Windows 32bits.
  • #6628 compiler warning in process_cpu_clocks.hpp.
  • #6666 thread_clock.hpp needs pthread.h.

Fixes:

  • #6092 Input from non integral durations makes the compiler fail.
  • #6093 [1/3]second fails as valid duration input.
  • #6113 duplicate symbol when BOOST_CHRONO_HEADER_ONLY is defined.
  • #6243 Sandia-pgi-11.9: more than one instance of overloaded function "min" matches.
  • #6257 process_cpu_clock::now() on linux gives time_points 1/1000 times.

New Features:

  • #5979 Added chrono rounding utilities as defined By Howard Hinnant here.
  • #5978 Added BOOST_CHRONO_HAS_PROCESS_CLOCKS to know if process clocks are available.
  • #5998 Make possible to don't provide hybrid error handling.
  • #5906 Take in account the constexpr as defined in the standard.
  • #5907 Take in account noexcept for compilers supporting it.

Fixes:

  • #2114 Enable visibility support (Boost.Chorno part)
  • #5669 Intel compiler failure to compile duration.hpp
  • #5909 process_cpu_clock::now() on MAC gives time_points 1/1000 times.
  • #5946 Process real cpu clock returns the system steady clock (windows).
  • #5974 Process real cpu clock should use clock() instead of times() in MAC which is twice faster and have better resolution.

Cleanup:

  • #5975 Reduce the combinations of header-only, shared, static link to reduce test time by 50%.
  • #5976 chrono_accuracy_test is not deterministic and should be removed from the regression tests
  • #5977 Remove old files from Beman's version. Some old files included in the Beman's version and not documented in the reviewed version that have been definitely removed from the repository as
    • boost/chrono/timer.hpp,
    • boost/chrono/process_times.hpp
    • boost/chrono/detail/process_clock.hpp,
    • boost/chrono/detail/mac/process_clock.hpp,
    • boost/chrono/detail/posix/process_clock.hpp,
    • boost/chrono/detail/win/process_clock.hpp,
    • boost/chrono/detail/run_timer.hpp,
    • boost/chrono/detail/run_timer_static.hpp,

New Features:

  • #???? Added time_point unary operators +,-,++,-- and binary operators +,- with Rep al RHS.
  • #5323 Add Associated type difference_type for chrono::time_point.

Fixes:

  • #5322 Explicit default constructed chrono::durations are uninitialized
  • Moved chrono to trunk taking in account the review remarks.
  • Documentation revision.

Features:

  • Boost_Chrono is now a configurable header-only library version (that also allows the user to choose if the windows.h file is included or not).
  • Added clock_string<> traits.
  • Define chrono-io for all the clocks.
  • Add input of process_times representation.

Implementation:

  • Use of detail/win files to avoid the use of windows.h file.
  • Completed the error_code handling.
  • Works now with BOOST_SYSTEM_NO_DEPRECATED.

Fixes:

  • Fix some warnings.
  • Fix original errors on Mac
  • Don't fix the link with boost_system to static.

Test:

  • Added test on process and thread clocks.
  • Moved to lightweight_test.hpp.
  • Able to test multiple configurations.

Doc:

  • Removed some not useful parts as the test and the tickets.

See N2661 - A Foundation to Sleep On which is very informative and provides motivation for key design decisions. This section contains some extracts from this document.

Why duration needs operator%

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:

class ClockTime
{
    typedef boost::chrono::hours hours;
    typedef boost::chrono::minutes minutes;
    typedef boost::chrono::seconds seconds;
public:
    hours hours_;
    minutes minutes_;
    seconds seconds_;

    template <class Rep, class Period>
      explicit ClockTime(const boost::chrono::duration<Rep, Period>& d)
        : hours_  (boost::chrono::duration_cast<hours>  (d)),
          minutes_(boost::chrono::duration_cast<minutes>(d % hours(1))),
          seconds_(boost::chrono::duration_cast<seconds>(d % minutes(1)))
          {}
};
Which APIs have been chosen to implement each clock on each platform?

The following table presents a resume of which API is used for each clock on each platform

Table 6.4. Clock API correspondence

Clock

Windows Platform

Posix Platform

Mac Platform

system_clock

GetSystemTimeAsFileTime

clock_gettime( CLOCK_REALTIME)

gettimeofday

steady_clock

QueryPerformanceCounter and QueryPerformanceFrequency

clock_gettime( CLOCK_STEADY)

mach_timebase_info,mach_absolute_time

process_real_cpu_clock

GetProcessTimes

times

times

process_system_cpu_clock

GetProcessTimes

times

times

process_user_cpu_clock

GetProcessTimes

times

times

process_cpu_clock

GetProcessTimes

times

times

thread_clock

GetThreadTimes

clock_gettime(pthread_getcpuclockid)

clock_gettime(pthread_getcpuclockid)


Why does process_cpu_clock sometimes give more cpu seconds than real seconds?

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.

Are integer overflows in the duration arithmetic detected and reported?

Boost.Ratio 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.

Which clocks should be used to benchmarking?

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.

Which clocks should be used for watching?

For trace purposes, it is probably best to use a system-wide clock.

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.

time2_demo contained this comment:

Much thanks to Andrei Alexandrescu, Walter Brown, Peter Dimov, Jeff Garland, Terry Golubiewski, Daniel Krugler, Anthony Williams.

The file <boost/chrono_io.hpp> has been adapted from the experimental header <chrono_io> from Howard Hinnant. Thanks for all Howard.

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 <chrono_io> from Howard Hinnant.

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.

Thanks to Ronald Bock, Andrew Chinoff, Paul A. Bristow and John Bytheway for his help polishing the documentation.

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 process_cpu_clock clock.

Thanks to Ronald Bock for reporting Valgind issues and for the many suggestions he made concerning the documentation.

For later releases
  • Add User defined literals for some durations.
  • Include chrono::date as defined by Howard Hinnant here.

PrevUpHomeNext