// bdlt_currenttime.h -*-C++-*-

#ifndef INCLUDED_BDLT_CURRENTTIME

#define INCLUDED_BDLT_CURRENTTIME

#include <bsls_ident.h>

BSLS_IDENT("$Id: $")

//@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:

//..

// 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));

// }

//..

#include <bdlscm_version.h>

#include <bdlt_datetime.h>

#include <bdlt_datetimetz.h>

#include <bdlt_epochutil.h>

#include <bdlt_localtimeoffset.h>

#include <bsls_assert.h>

#include <bsls_atomicoperations.h>

#include <bsls_timeinterval.h>

#include <bsls_types.h>

#ifndef BDE_DONT_ALLOW_TRANSITIVE_INCLUDES

#include <bdlt_intervalconversionutil.h>

#endif // BDE_DONT_ALLOW_TRANSITIVE_INCLUDES

namespace BloombergLP {

namespace bdlt {

// ==================

// struct CurrentTime

// ==================

struct CurrentTime {

// This 'struct' provides a namespace for current-time-retrieval procedures

// including a configurable global callback mechanism. The use of a

// *subset* of these procedures is thread-safe (see 'Thread Safety').

public:

// TYPES

typedef bsls::TimeInterval (*CurrentTimeCallback)();

// 'CurrentTimeCallback' is a callback function pointer for a callback

// function that returns a 'bsls::TimeInterval' object. This function

// must be thread-safe in multi-threaded builds.

private:

static bsls::AtomicOperations::AtomicTypes::Pointer

s_currenttimeCallback_p;

// address of current-time callback

public:

// CLASS METHODS

// ** now functions **

static Datetime local();

// Return the 'Datetime' value representing the current date/time in

// the local time zone, as provided by the installed callback function

// and the facilities of 'LocalTimeOffset'.

static bsls::TimeInterval now();

// Return the 'TimeInterval' value between 'EpochUtil::epoch()' and the

// current date/time as provided by the installed callback function.

// Note that this value is independent of time zone.

static Datetime utc();

// Return the 'Datetime' value representing the current date/time in

// Coordinated Universal Time (UTC) as provided by the installed

// callback function.

static DatetimeTz asDatetimeTz();

// Return the 'DatetimeTz' value representing the current date/time in

// the local time zone, and the local time zone's offset from UTC, as

// provided by the installed callback function and the facilities of

// 'LocalTimeOffset'.

// ** callback functions **

static CurrentTimeCallback currentTimeCallback();

// Return the installed function used to retrieve the interval between

// 'EpochUtil::epoch()' and the current date/time,

static CurrentTimeCallback

setCurrentTimeCallback(CurrentTimeCallback callback);

// Set the specified 'callback' as the function to be used to retrieve

// the interval between 'EpochUtil::epoch()' and the current date/time,

// and return the previously set function.

// ** default callback function **

static bsls::TimeInterval currentTimeDefault();

// Return the 'TimeInterval' value between 'EpochUtil::epoch()' and the

// current date/time. This is the default current-time callback

// implementation for current time retrieval. The obtained time is

// expressed as a time interval from '00:00 UTC, January 1, 1970'. On

// UNIX (Solaris, LINUX and DG-UNIX) this function provides a

// microsecond resolution. On Windows (NT, WIN2000, 95, 98 etc) it

// provides a resolution of 100 nanoseconds.

};

// ============================================================================

// INLINE DEFINITIONS

// ============================================================================

// -----------------

// class CurrentTime

// -----------------

// CLASS METHODS

// ** now functions **

inline

Datetime CurrentTime::local()

{

Datetime now = utc();

now.addSeconds(LocalTimeOffset::localTimeOffset(now).totalSeconds());

return now;

}

inline

bsls::TimeInterval CurrentTime::now()

{

return currentTimeCallback()();

}

inline

Datetime CurrentTime::utc()

{

return EpochUtil::epoch() + now();

}

// ** callback functions **

inline

CurrentTime::CurrentTimeCallback CurrentTime::currentTimeCallback()

{

return reinterpret_cast<CurrentTimeCallback>(

reinterpret_cast<bsls::Types::IntPtr>(

bsls::AtomicOperations::getPtrAcquire(&s_currenttimeCallback_p)));

}

inline

CurrentTime::CurrentTimeCallback

CurrentTime::setCurrentTimeCallback(CurrentTimeCallback callback)

{

BSLS_ASSERT_OPT(callback);

CurrentTimeCallback previousCallback = currentTimeCallback();

bsls::AtomicOperations::setPtrRelease(

&s_currenttimeCallback_p,

reinterpret_cast<void *>(

reinterpret_cast<bsls::Types::IntPtr>(callback)));

return previousCallback;

}

} // close package namespace

} // close enterprise namespace

#endif

// ----------------------------------------------------------------------------

// Copyright 2016 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 ----------------------------------