bsls_timeutil.h

Go to the documentation of this file.

/// @file bsls_timeutil.h
///
/// The content of this file has been pre-processed for Doxygen.
///
 
 
// bsls_timeutil.h                                                    -*-C++-*-
#ifndef INCLUDED_BSLS_TIMEUTIL
#define INCLUDED_BSLS_TIMEUTIL
 
#include <bsls_ident.h>
BSLS_IDENT("$Id: $")
 
/// @defgroup bsls_timeutil bsls_timeutil
/// @brief  Provide a platform-neutral functional interface to system clocks.
/// @addtogroup bsl
/// @{
/// @addtogroup bsls
/// @{
/// @addtogroup bsls_timeutil
/// @{
///
/// <h1> Outline </h1>
/// * <a href="#bsls_timeutil-purpose"> Purpose</a>
/// * <a href="#bsls_timeutil-classes"> Classes </a>
/// * <a href="#bsls_timeutil-description"> Description </a>
///   * <a href="#bsls_timeutil-thread-timers"> Thread Timers </a>
///   * <a href="#bsls_timeutil-accuracy-and-precision"> Accuracy and Precision </a>
///     * <a href="#bsls_timeutil-accuracy-on-windows"> Accuracy on Windows </a>
///       * <a href="#bsls_timeutil-cpu-scaling"> CPU Scaling </a>
///       * <a href="#bsls_timeutil-multi-core-issues"> Multi-Core Issues </a>
///     * <a href="#bsls_timeutil-ensuring-accurate-timers-on-windows"> Ensuring Accurate Timers on Windows </a>
///     * <a href="#bsls_timeutil-precision-on-windows"> Precision on Windows </a>
///   * <a href="#bsls_timeutil-usage"> Usage </a>
///     * <a href="#bsls_timeutil-example-1-implementing-a-very-simple-timer"> Example 1: Implementing a Very Simple Timer </a>
///     * <a href="#bsls_timeutil-example-2-thread-timers"> Example 2: Thread Timers </a>
///
/// # Purpose {#bsls_timeutil-purpose}
/// Provide a platform-neutral functional interface to system clocks.
///
/// # Classes {#bsls_timeutil-classes}
///
/// -  bsls::TimeUtil: namespace for platform-neutral system-time pure procedures
///
/// @see  bsls_stopwatch
///
/// # Description {#bsls_timeutil-description}
/// This component provides a set of platform-neutral pure
/// procedures to access real-time system clock functionality.  High-resolution
/// time functions intended for interval-timing return a time interval in
/// nanoseconds (1 nsec = 1E-9 sec) as a 64-bit integer.  In addition to wall
/// time, this component provides process and thread CPU timers.  On platforms
/// where per-thread CPU timers are unavailable, thread timer methods return -1.
///
/// ## Thread Timers {#bsls_timeutil-thread-timers}
///
///
/// `bsls::TimeUtil::getThreadSystemTimer`,
/// `bsls::TimeUtil::getThreadUserTimer`, and
/// `bsls::TimeUtil::getThreadTimers` report CPU time consumed by the calling
/// thread.  On platforms where per-thread CPU timing APIs are unavailable,
/// these methods return -1 for each unavailable value.
///
/// ## Accuracy and Precision {#bsls_timeutil-accuracy-and-precision}
///
///
/// `bsls::TimeUtil` high-resolution functions return time values as absolute
/// nanoseconds from an arbitrary reference that will *in many cases* remain
/// fixed within a single process (and among running processes on a single
/// machine).  Absolute monotonic behavior is platform-dependent, however, as
/// are accuracy and useful precision, despite the nominal nanosecond precision
/// implied by the return value.  The user is advised to determine the actual
/// performance on each platform of interest.
///
/// ### Accuracy on Windows {#bsls_timeutil-accuracy-on-windows}
///
///
/// On certain windows platform configurations, `bsls::TimeUtil::getTimer` and
/// `bsls::TimeUtil::getRawTimer` can produce unreliable results.  On some
/// machines, these high-resolution functions have been observed to run at
/// inconsistent speeds, with worst cases as slow as half the speed of actual
/// wall time.  This is known behavior of the underlying high-performance timer
/// function `QueryPerformanceCounter`, upon which the Windows implementation of
/// `bsls::TimeUtil` relies.
///
/// Reference: https://msdn.microsoft.com/library/windows/desktop/dn553408
///
/// #### CPU Scaling {#bsls_timeutil-cpu-scaling}
///
///
/// The behavior of the timer on windows platforms depends on the interaction of
/// operating system, BIOS, and processor, and certain combinations of the three
/// (particularly older ones) are vulnerable to timer inaccuracy.  For example,
/// frequently the `QueryPerformanceCounter` function that `TimeUtil` uses on
/// Windows will utilize the CPU's timestamp counter (TSC), and CPUs with speed
/// scaling mechanisms such as SpeedStep (frequently used for power management)
/// will generally see the clock speed vary with the CPU frequency.  However,
/// newer processors often provide an `Invariant TSC` that solves this
/// problem.  Also versions of Windows starting with Vista may internally handle
/// the inconsistency by automatically using a lower resolution, but accurate,
/// counter on processors that do not provide an `Invariant TSC`.
///
/// #### Multi-Core Issues {#bsls_timeutil-multi-core-issues}
///
///
/// In addition, on multi-core machines, each call to `QueryPerformanceCounter`
/// may read the TSC from a different CPU.  The TSCs of the CPUs may be out of
/// sync, resulting in slightly inconsistent or even non-monotonic behavior.
///
/// Reference: http://support.microsoft.com/kb/895980
///
/// ### Ensuring Accurate Timers on Windows {#bsls_timeutil-ensuring-accurate-timers-on-windows}
///
///
/// If a Windows machine appears to have a slow and/or inconsistent
/// high-resolution timer, it can be reconfigured to avoid using the TSC.  On
/// Windows XP and earlier versions, add the parameter `/usepmtimer` to the
/// operating system's boot configuration in `boot.ini`.  On Windows Vista and
/// later, run the following command as an administrator:
/// @code
/// bcdedit /set useplatformclock true
/// @endcode
/// Note that unless the machine has a High Performance Event Timer (HPET) and
/// it has been enabled in the BIOS, these steps might reduce the resolution of
/// the `bsls::TimeUtil` high-resolution functions from the nanosecond range to
/// the microsecond range (or worse).
///
/// ### Precision on Windows {#bsls_timeutil-precision-on-windows}
///
///
/// Providing that the underlying timer is capable of supporting the
/// `QueryPerformanceCounter` interface, `getTimer` and `convertRawTime` will
/// perform their calculations to nanosecond precision based on the values
/// reported by `QueryPerformanceCounter`.  Because of overflow concerns, these
/// routines do not simply divide the result of `QueryPerformanceCounter` by the
/// result of `QueryPerformanceFrequency`.  In the course of calculating the
/// final nanosecond-precision time, there are two places where some precision
/// might be lost.  Therefore, the times reported by `getTimer` and
/// `convertRawTime` may be as much as two nanoseconds less than the actual time
/// expressed by the `QueryPerformanceCounter` interface.  Note that the times
/// will still be monotonically non-decreasing.
///
/// ## Usage {#bsls_timeutil-usage}
///
///
/// This section illustrates intended use of this component.
///
/// ### Example 1: Implementing a Very Simple Timer {#bsls_timeutil-example-1-implementing-a-very-simple-timer}
///
///
/// In this example we illustrate how to use `bsls::TimeUtil` functions to
/// implement a very simple timer.  Only the most primitive functionality is
/// illustrated.  See the `bsls::Stopwatch` component for a better example of a
/// timer interface.
/// @code
/// // my_timer.h
///
/// #ifndef INCLUDED_BSLS_TYPES
/// #include <bsls_types.h>   // bsls::Types::Int64
/// #endif
///
/// #ifndef INCLUDED_BSLS_TIMEUTIL
/// #include <bsls_timeutil.h>
/// #endif
///
/// class my_Timer {
///    // This class implements a simple interval timer that is created in
///    // the "running" state, and may be queried for its cumulative
///    // interval (as a 'double', in seconds) but never stopped or reset.
///
///    bsls::Types::Int64 d_startWallTime;   // time at creation (nsec)
///    bsls::Types::Int64 d_startUserTime;   // time at creation (nsec)
///    bsls::Types::Int64 d_startSystemTime; // time at creation (nsec)
///
///  public:
///    // CREATORS
///    my_Timer() {
///        d_startWallTime = bsls::TimeUtil::getTimer();
///        d_startUserTime = bsls::TimeUtil::getProcessUserTimer();
///        d_startSystemTime = bsls::TimeUtil::getProcessSystemTimer();
///    }
///        // Create a timer object initialized with the times at creation.
///        // All values returned by subsequent calls to 'elapsed<...>Time()'
///        // are with respect to this creation time.
///
///    ~my_Timer() {}
///
///    // ACCESSORS
///    double elapsedWallTime();
///        // Return the total elapsed time in seconds since the creation of
///        // this timer object.
///    double elapsedUserTime();
///        // Return the elapsed user time in seconds since the creation of
///        // this timer object.
///    double elapsedSystemTime();
///        // Return the elapsed system time in seconds since the creation of
///        // this timer object.
/// };
///
/// inline
/// double my_Timer::elapsedWallTime()
/// {
///    return (double) (bsls::TimeUtil::getTimer() - d_startWallTime) * 1.0E-9;
/// }
///
/// inline
/// double my_Timer::elapsedUserTime()
/// {
///    return (double) (bsls::TimeUtil::getProcessUserTimer()
///                                                - d_startUserTime) * 1.0E-9;
/// }
///
/// inline
/// double my_Timer::elapsedSystemTime()
/// {
///    return (double) (bsls::TimeUtil::getProcessSystemTimer()
///                                              - d_startSystemTime) * 1.0E-9;
/// }
/// // ...
/// @endcode
/// The `my_Timer` object may be used to time some section of code at runtime as
/// follows:
/// @code
/// // ...
/// {
///     my_Timer tw;
///     for (int i = 0; i < 1000000; ++i) {
///         // ...
///     }
///     double dTw = tw.elapsedWallTime();
///     my_Timer tu;
///     for (int i = 0; i < 1000000; ++i) {
///         // ...
///     }
///     double dTu = tu.elapsedUserTime();
///     my_Timer ts;
///     for (int i = 0; i < 1000000; ++i) {
///         // ...
///     }
///     double dTs = ts.elapsedSystemTime();
///     printf("elapsed wall time:   %g\n"
///            "elapsed user time:   %g\n"
///            "elapsed system time: %g\n",
///            dTw, dTu, dTs);
/// }
/// @endcode
///
/// ### Example 2: Thread Timers {#bsls_timeutil-example-2-thread-timers}
///
///
/// In this example we show how to use the thread CPU timers and how to detect
/// when they are unsupported on a given platform:
/// @code
/// bsls::Types::Int64 threadSystemStart;
/// bsls::Types::Int64 threadUserStart;
/// bsls::TimeUtil::getThreadTimers(&threadSystemStart, &threadUserStart);
///
/// if (threadSystemStart >= 0 && threadUserStart >= 0) {
///     // ... run code on the current thread ...
///
///     bsls::Types::Int64 threadSystemEnd;
///     bsls::Types::Int64 threadUserEnd;
///     bsls::TimeUtil::getThreadTimers(&threadSystemEnd, &threadUserEnd);
///
///     double dThreadSystem =
///         (double)(threadSystemEnd - threadSystemStart) * 1.0E-9;
///     double dThreadUser =
///         (double)(threadUserEnd - threadUserStart) * 1.0E-9;
///
///     printf("elapsed thread system time: %g\n"
///            "elapsed thread user time:   %g\n",
///            dThreadSystem,
///            dThreadUser);
/// }
/// else {
///     printf("thread CPU timers are not supported on this platform\n");
/// }
/// @endcode
/// @}
/** @} */
/** @} */
 
/** @addtogroup bsl
 * @{
 */
/** @addtogroup bsls
 * @{
 */
/** @addtogroup bsls_timeutil
 * @{
 */
 
#include <bsls_platform.h>
#include <bsls_types.h>
 
#ifdef BSLS_PLATFORM_OS_UNIX
    #include <time.h>
#endif
 
#if defined(BSLS_PLATFORM_OS_AIX) || defined(BSLS_PLATFORM_OS_FREEBSD)        \
 || defined(BSLS_PLATFORM_OS_DARWIN)
    #include <sys/time.h>
#endif
 
 
 
namespace bsls {
 
                            // ===============
                            // struct TimeUtil
                            // ===============
 
/// This `struct` provides a namespace for a set of platform-neutral pure
/// procedures to access real-time system clock functionality.
/// High-resolution time functions intended for interval-timing return an
/// interval in nanoseconds (1 nsec = 1E-9 sec) as a platform-independent
/// 64-bit integer.
///
/// For maximum performance on some platforms where fetching the native
/// clock is significantly faster than converting the fetched value to
/// nanoseconds, this class also provides a "raw" method returning an opaque
/// native time value and a conversion method returning a value in
/// nanoseconds.
///
/// See @ref bsls_timeutil 
struct TimeUtil {
 
    // TYPES
#if   defined BSLS_PLATFORM_OS_SOLARIS
    typedef struct { Types::Int64 d_opaque; }  OpaqueNativeTime;
#elif defined BSLS_PLATFORM_OS_AIX
    typedef timebasestruct_t                   OpaqueNativeTime;
#elif defined(BSLS_PLATFORM_OS_LINUX) || defined(BSLS_PLATFORM_OS_CYGWIN)
    typedef timespec                           OpaqueNativeTime;
#elif defined BSLS_PLATFORM_OS_DARWIN
    typedef struct { Types::Uint64 d_opaque; } OpaqueNativeTime;
#elif defined BSLS_PLATFORM_OS_UNIX
    typedef timeval                            OpaqueNativeTime;
#elif defined BSLS_PLATFORM_OS_WINDOWS
    typedef struct { Types::Int64 d_opaque; }  OpaqueNativeTime;
#endif
 
    // CLASS METHODS
 
                                  // Initializers
 
    /// Do a platform-dependent initialization for the utilities.  
    /// 
    /// \note Note that   the other methods in this component are guaranteed to be thread-safe
    /// only after calling this method.
    static void initialize();
 
                                  // Operations
 
    /// Convert the specified `rawTime` to a value in nanoseconds,
    /// referenced to an arbitrary but fixed origin, and return the result of the conversion.  
    /// 
    /// \note Note that   this method is thread-safe only if
    /// `initialize` has been called before.
    static Types::Int64 convertRawTime(OpaqueNativeTime rawTime);
 
    /// Return the instantaneous values of a platform-dependent timer for the
    /// current process system time in absolute nanoseconds referenced to an
    /// arbitrary but fixed origin.  If the system call fails return -1.  
    /// 
    /// \note Note that   this method is thread-safe only if `initialize` has been called
    /// before.
    static Types::Int64 getProcessSystemTimer();
 
    /// Load into the specified `systemTimer` and `userTimer` the
    /// instantaneous values of platform-dependent system timer and user
    /// timer in absolute nanoseconds referenced to an arbitrary but fixed
    /// origin.  If the system call fails fill both time arguments with -1. 
    /// 
    /// \note Note that   this method is thread-safe only if `initialize` has been
    /// called before.
    static void getProcessTimers(Types::Int64 *systemTimer,
                                 Types::Int64 *userTimer);
 
    /// Return the instantaneous values of a platform-dependent timer for the
    /// current process user time in absolute nanoseconds referenced to an
    /// arbitrary but fixed origin.  If the system call fails return -1.  
    /// 
    /// \note Note that   this method is thread-safe only if `initialize` has been called
    /// before.
    static Types::Int64 getProcessUserTimer();
 
    /// Return the instantaneous values of a platform-dependent timer for
    /// the current thread system time in absolute nanoseconds referenced
    /// to an arbitrary but fixed origin.  Return -1 on platforms where
    /// per-thread CPU timers are unavailable or in case of a system call failure.  
    /// 
    /// \note Note that   this method is thread-safe only if `initialize`
    /// has been called before.
    static Types::Int64 getThreadSystemTimer();
 
    /// Load into the specified `systemTimer` and `userTimer` the
    /// instantaneous values of platform-dependent system timer and user
    /// timer for the current thread, in absolute nanoseconds referenced
    /// to an arbitrary but fixed origin.  Load -1 into both timers on
    /// platforms where per-thread CPU timers are unavailable or in case of a system call failure.  
    /// 
    /// \note Note that   this method is thread-safe only if
    /// `initialize` has been called before.
    static void getThreadTimers(Types::Int64 *systemTimer,
                                Types::Int64 *userTimer);
 
    /// Return the instantaneous values of a platform-dependent timer for
    /// the current thread user time in absolute nanoseconds referenced to
    /// an arbitrary but fixed origin.  Return -1 on platforms where per-thread
    /// CPU timers are unavailable or in case of a system call failure.  
    /// 
    /// \note Note that   this method is thread-safe only if `initialize` has been called
    /// before.
    static Types::Int64 getThreadUserTimer();
 
    /// Return the instantaneous value of a platform-dependent system timer
    /// in absolute nanoseconds referenced to an arbitrary but fixed origin. 
    /// 
    /// \note Note that   this method is thread-safe only if `initialize` has been
    /// called before.
    static Types::Int64 getTimer();
 
    /// Load into the specified `timeValue` the value of an opaque,
    /// platform-dependent type representing the current time.  `timeValue`
    /// must be converted by the `convertRawTime` method to conventional
    /// units (nanoseconds).  This method is intended to facilitate accurate
    /// timing of small segments of code, and care must be used in interpreting the results.  
    /// 
    /// \note Note that   this method is thread-safe only
    /// if `initialize` has been called before.
    static void getTimerRaw(OpaqueNativeTime *timeValue);
 
};
 
}  // close package namespace
 
#ifndef BDE_OPENSOURCE_PUBLICATION  // BACKWARD_COMPATIBILITY
// ============================================================================
//                           BACKWARD COMPATIBILITY
// ============================================================================
 
/// This alias is defined for backward compatibility.
typedef bsls::TimeUtil bsls_TimeUtil;
#endif  // BDE_OPENSOURCE_PUBLICATION -- BACKWARD_COMPATIBILITY
 
 
 
#endif
 
// ----------------------------------------------------------------------------
// Copyright 2013 Bloomberg Finance L.P.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
// ----------------------------- END-OF-FILE ----------------------------------
 
/** @} */
/** @} */
/** @} */