bdlt_currenttime

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Thread Safety
  • Usage
    • Example 1: Repeatable Tests Involving Current Time

Purpose

Provide utilities to retrieve the current time.

Classes

• bdlt::CurrentTime: namespace for current-time procedures

See also

bsls_timeinterval, bdlt_systemtimeutil

Description

This component, bdlt::CurrentTime, provides static methods for retrieving the current time in Coordinated Universal Time (UTC) and in the local time zone of the executing process. It also provides a facility for customizing the means by which the time is retrieved.

Thread Safety

The functions provided by bdlt::CurrentTime are thread-safe (meaning they may be called concurrently from multiple threads), including those that set and retrieve the callback function. In addition, user-supplied callback functions must be thread-safe.

Usage

This section illustrates intended use of this component.

Example 1: Repeatable Tests Involving Current Time

Suppose we are writing an application which involves dealing with the current time (for example, a clock displaying it). In order to test the application, we would like to be able to control the time it sees. We can use bdlt::CurrentTime for this purpose.

First, we create a sample application. For this example, we simply have it retrieve the current time in several formats:

/// Retrieve versions of the current time into the specified `local`,
/// `utc`, and `now` parameters.
void sampleApplication(bdlt::Datetime     *local,
                       bdlt::Datetime     *utc,
                       bsls::TimeInterval *now)
{
    *local = bdlt::CurrentTime::local();
    *utc   = bdlt::CurrentTime::utc();
    *now   = bdlt::CurrentTime::now();
}

Then, we create a method to test whether the application is producing the expected results:

// Return `true` iff `sampleApplication` returns values matching the
// specified expected values `expectedLocal`, `expectedUtc`, and
// `expectedNow`.
bool checkApplication(bdlt::Datetime     expectedLocal,
                      bdlt::Datetime     expectedUtc,
                      bsls::TimeInterval expectedNow)
{
    bdlt::Datetime     local;
    bdlt::Datetime     utc;
    bsls::TimeInterval now;
 
    sampleApplication(&local, &utc, &now);
    return expectedLocal == local &&
           expectedUtc   == utc   &&
           expectedNow   == now;
}

Next, we create a class allowing us to set the current time which will be seen by the application:

/// Maintain and return a "current time" value.
class TestCurrentTimeGuard {
  private:
    bdlt::CurrentTime::CurrentTimeCallback d_prev;  // old callback
 
  public:
    /// Create an object of this type, installing the handler.
    TestCurrentTimeGuard();
 
    /// Destroy an object of this type, restoring the handler.
    ~TestCurrentTimeGuard();
 
    /// Return `s_time`.
    static bsls::TimeInterval time();
 
    static bsls::TimeInterval s_time;               // the "current time"
};
 
bsls::TimeInterval TestCurrentTimeGuard::s_time;
 
TestCurrentTimeGuard::TestCurrentTimeGuard()
: d_prev(bdlt::CurrentTime::setCurrentTimeCallback(time))
{
}
 
TestCurrentTimeGuard::~TestCurrentTimeGuard()
{
    bdlt::CurrentTime::setCurrentTimeCallback(d_prev);
}
 
bsls::TimeInterval TestCurrentTimeGuard::time()
{
    return s_time;
}

Finally, we write a method that tests that our application is functioning correctly:

/// Test the application.
void testApplication()
{
    TestCurrentTimeGuard tct;
    TestCurrentTimeGuard::s_time = bdlt::EpochUtil::convertToTimeInterval(
                                                 bdlt::EpochUtil::epoch());
 
    bdlt::Datetime     local;
    bdlt::Datetime     utc;
    bsls::TimeInterval now;
 
    sampleApplication(&local, &utc, &now);
 
    TestCurrentTimeGuard::s_time += 1E6;
    local.addSeconds(1000000);
    utc.addSeconds(1000000);
    now += 1E6;
 
    assert(checkApplication(local, utc, now));
}