Component bsls_systemtime [Package bsls]

Provide utilities to retrieve the system time. More...

Namespaces
namespace	bsls

---

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Reference Time Point
  • Thread Safety
  • Usage
    • Example 1: Getting Current Wall Clock Time

Purpose:

Provide utilities to retrieve the system time.

Classes:

bsls::SystemTime

namespace for system-time functions

See also:

Component bsls_timeinterval

Description:

This component provides a struct, bsls::SystemTime, in which are defined a series of static methods for retrieving the current system time. This component provides access to a monotonic clock and a real-time (wall) clock.

Reference Time Point:

The bsls::TimeInterval objects returned by functions in this component identify a time by providing a time interval from some fixed reference time point (or "epoch"). The clock types supported by bsls_systemtime (see bsls_systemclocktype) define a reference time point as described in the table below:

  bsls::SystemClockType::Enum  Reference Time Point
  ---------------------------  --------------------
  e_REALTIME                   January 1, 1970 00:00.000 UTC (POSIX epoch)
  e_MONOTONIC                  platform-dependent

The e_MONOTONIC clock's reference time point is an unspecified, platform-dependent, value. This means that the monotonic clock cannot be reliably used to determine the absolute wall clock time. Monotonic clock times are frequently used to specify a fixed point in the future relative to the current (monotonic) clock time (e.g., for a timed-wait on a condition variable). Note that the monotonic clock time may be (though certainly is not guaranteed to be) an arbitrary value relative to the process start time, meaning that bsls::TimeInterval values from the monotonic clock should not be shared between processes.

Thread Safety:

The functions provided by bsls::SystemTime are thread-safe.

Usage:

This section illustrates intended use of this component.

Example 1: Getting Current Wall Clock Time:

The following snippets of code illustrate how to use this utility component to obtain the system time by calling now and nowRealtimeClock.

First, we call nowRealtimeClock, and set t1, to the current time according to the real-time clock:

  bsls::TimeInterval t1 = bsls::SystemTime::nowRealtimeClock();

  assert(bsls::TimeInterval() != t1);

Next, we sleep for 1 second:

  sleep(1);

Now, we call now, and supply e_REALTIME to indicate a real-time clock value should be returned, and then set t2 to the current time according to the real-time clock:

  bsls::TimeInterval t2 = bsls::SystemTime::now(
                                          bsls::SystemClockType::e_REALTIME);

  assert(bsls::TimeInterval() != t2);

Finally, we verify the interval between t1 and t2 is close to 1 second:

  bsls::TimeInterval interval = t2 - t1;

  assert(bsls::TimeInterval(.9) <= interval &&
                                   interval <= bsls::TimeInterval(1.1));