Component bdlt_currenttime [Package bdlt]

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

Namespaces
namespace	bdlt

---

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:

Component 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:

  void sampleApplication(bdlt::Datetime     *local,
                         bdlt::Datetime     *utc,
                         bsls::TimeInterval *now)
      // Retrieve versions of the current time into the specified 'local',
      // 'utc', and 'now' parameters.
  {
      *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:

  bool checkApplication(bdlt::Datetime     expectedLocal,
                        bdlt::Datetime     expectedUtc,
                        bsls::TimeInterval expectedNow)
      // Return 'true' iff 'sampleApplication' returns values matching the
      // specified expected values 'expectedLocal', 'expectedUtc', and
      // '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:

  class TestCurrentTimeGuard {
      // Maintain and return a "current time" value.
    private:
      bdlt::CurrentTime::CurrentTimeCallback d_prev;  // old callback

    public:
      TestCurrentTimeGuard();
          // Create an object of this type, installing the handler.

      ~TestCurrentTimeGuard();
          // Destroy an object of this type, restoring the handler.

      static bsls::TimeInterval time();
          // Return 's_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:

  void testApplication()
      // Test the application.
  {
      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));
  }