bdlmt_eventscheduler.h

// bdlmt_eventscheduler.h                                             -*-C++-*-

// ----------------------------------------------------------------------------
//                                   NOTICE
//
// This component is not up to date with current BDE coding standards, and
// should not be used as an example for new development.
// ----------------------------------------------------------------------------

#ifndef INCLUDED_BDLMT_EVENTSCHEDULER
#define INCLUDED_BDLMT_EVENTSCHEDULER

#include <bsls_ident.h>
BSLS_IDENT("$Id: $")

//@PURPOSE: Provide a thread-safe recurring and one-time event scheduler.
//
//@CLASSES:
//  bdlmt::EventScheduler: a thread-safe event scheduler
//  bdlmt::EventSchedulerEventHandle: handle to a single scheduled event
//  bdlmt::EventSchedulerRecurringEventHandle: handle to a recurring event
//  bdlmt::EventSchedulerTestTimeSource: class for testing time changes
//
//@SEE_ALSO: bdlmt_timereventscheduler
//
//@DESCRIPTION: This component provides a thread-safe event scheduler.
// 'bdlmt::EventScheduler', that implements methods to schedule and cancel
// recurring and one-time events.  All of the callbacks for these events are
// processed by a separate thread (called the dispatcher thread).  By default
// the callbacks are also executed in the dispatcher thread, but that behavior
// can be altered by providing a dispatcher functor at creation time (see the
// section {The Dispatcher Thread and the Dispatcher Functor}).
//
// Events may be referred to by 'bdlmt::EventSchedulerEventHandle' and
// 'bdlmt::EventSchedulerRecurringEventHandle' objects, which clean up after
// themselves when they go out of scope, or by 'Event' and 'RecurringEvent'
// pointers, which must be released using 'releaseEventRaw'.  Such pointers are
// used in the "Raw" API of this class and must be used carefully.  Note that
// the Handle objects have an implicit conversion to the corresponding 'Event'
// or 'RecurringEvent' pointer types, effectively providing extra overloads for
// methods that take a 'const Event*' to also take a 'const EventHandle&'.
//
///Comparison to 'bdlmt::TimerEventScheduler'
/// - - - - - - - - - - - - - - - - - - - - -
// This component was written after 'bdlmt_timereventscheduler', which suffered
// from a couple of short-comings: 1) there was a maximum number of events it
// could manage, and 2) it was inefficient at dealing with large numbers of
// events.  This component addresses both those problems -- there is no limit
// on the number of events it can manage, and it is more efficient at dealing
// with large numbers of events.  The disadvantage of this component relative
// to 'bdlmt_timereventscheduler' is that handles referring to managed events
// in a 'bdlmt::EventScheduler' are reference-counted and need to be released,
// while handles of events in a 'bdlmt::TimerEventScheduler' are integral types
// that do not need to be released.
//
///Thread Safety and "Raw" Event Pointers
///--------------------------------------
// 'bdlmt::EventScheduler' is thread-safe and thread-enabled, meaning that
// multiple threads may use their own instances of the class or use a shared
// instance without further synchronization.  The thread safety and correct
// behavior of the component depend on the correct usage of 'Event' pointers,
// which refer to scheduled events in the "Raw" API of this class.  In
// particular:
//..
//   * Every 'Event*'  and 'RecurringEvent*' populated by 'scheduleEventRaw'
// and 'scheduleRecurringEventRaw' must be released using 'releaseEventRaw.'
//       - Pointers are not released automatically when events are completed.
//       - Pointers are not released automatically when events are canceled.
//       - Events are not canceled when pointers to them are released.
//   * Pointers must not be used after being released.
//   * Pointers must never be shared or duplicated without using
//    'addEventRefRaw' and 'addRecurringEventRefRaw' to get additional
//     references; *each* such added reference must be released separately.
//..
// 'bdlmt::EventSchedulerEventHandle' and
// 'bdlmt::EventSchedulerRecurringEventHandle' are *const* *thread-safe*.  It
// is not safe for multiple threads to invoke non-'const' methods on the same
// 'EventHandle' or 'RecurringEventHandle' object concurrently.
//
///The Dispatcher Thread and the Dispatcher Functor
///------------------------------------------------
// The scheduler creates a single separate thread (called the *dispatcher*
// *thread*) to process all the callbacks.  The dispatcher thread executes the
// callbacks by passing them to the dispatcher functor (optionally specified at
// creation time).  The default dispatcher functor simply invokes the passed
// callback, effectively executing it in the dispatcher thread.  Users can
// alter this behavior by defining their own dispatcher functor (for example in
// order to use a thread pool or a separate thread to run the callbacks).  Note
// that the user-supplied functor will still be run in the dispatcher thread.
//
// CAVEAT: Using a dispatcher functor such as the example above (to execute the
// callback in a separate thread) violates the guarantees of
// cancelEventAndWait().  Users who specify a dispatcher functor that transfers
// the event to another thread for execution should not use
// cancelEventAndWait(), and should instead ensure that the lifetime of any
// object bound to an event exceeds the lifetime of the mechanism used by the
// customized dispatcher functor.
//
///Timer Resolution and Order of Execution
///---------------------------------------
// It is intended that recurring and one-time events are processed as closely
// as possible to their respective time values, and that they are processed in
// the order scheduled.  However, this component *guarantees* only that events
// will not be executed before their scheduled time.  Generally, events that
// are scheduled more than 1 microsecond apart will be executed in the order
// scheduled; but different behavior may be observed when events are submitted
// after (or shortly before) their scheduled time.
//
// When events are executed in the dispatcher thread and take longer to
// complete than the time between events, the dispatcher can fall behind.  In
// this case, events will be executed in the correct order as soon as the
// dispatcher thread becomes available; once the backlog is worked off, events
// will be executed at or near their scheduled times.
//
///Supported Clock Types
///---------------------
// An 'EventScheduler' optionally accepts a clock type at construction
// indicating the clock by which it will internally schedule events.  The clock
// type may be indicated by either a 'bsls::SystemClockType::Enum' value, a
// 'bsl::chrono::system_clock' object (which is equivalent to specifying
// 'e_REALTIME'), or a 'bsl::chrono::steady_clock' object (equivalent to
// specifying 'e_MONOTONIC').  If a clock type is not specified, 'e_REALTIME'
// is used.
//
///Scheduling Using a 'bsl::chrono::time_point'
/// - - - - - - - - - - - - - - - - - - - - - -
// When creating either a one-time or recurring event, clients may pass a
// 'bsl::chrono::time_point' indicating the time the event should occur.  This
// 'time_point' object can be associated with an arbitrary clock.  If the
// 'time_point' is associated with a different clock than was indicated at
// construction of the event scheduler, those time points are converted to be
// relative to the event scheduler's clock for processing.  A possible
// implementation of such a conversion would be:
//..
//  bsls::TimeInterval(time - CLOCK::now()) + eventScheduler.now()
//..
// where 'time' is a 'time_point', 'CLOCK' is the clock associated with 'time',
// and 'eventScheduler' is the 'EventScheduler' on which the event is being
// scheduled.  Notice that the conversion adds some imprecision and overhead to
// evaluation of the event.  An event scheduler guarantees an event will occur
// at or after the supplied 'time_point', even if that 'time_point' is defined
// in terms of a 'CLOCK' different from the one used by the event scheduler.
// If there is a discontinuity between the clock for a 'time_point' and the
// event scheduler's clock, additional processing overhead may result (because
// the event may need to be rescheduled), and the event may also occur later
// than what one might otherwise expect.
//
///Scheduling Using a 'bsls::TimeInterval'
///- - - - - - - - - - - - - - - - - - - -
// When creating either a one-time or recurring event, clients may pass a
// 'bsls::TimeInterval' indicating the time the event should occur as an offset
// from an epoch.  If the clock type indicated at construction is
// 'bsls::SystemClockType::e_REALTIME', time should be expressed as an absolute
// offset since 00:00:00 UTC, January 1, 1970 (which matches the epoch used in
// 'bdlt::CurrentTime::now(bsls::SystemClockType::e_REALTIME)', and
// 'bsl::chrono::system_clock::now()').  If the clock type indicated at
// construction is 'bsls::SystemClockType::e_MONOTONIC', time should be
// expressed as an absolute offset since the epoch of this clock (which matches
// the epoch used in
// 'bdlt::CurrentTime::now(bsls::SystemClockType::e_MONOTONIC)' and
// 'bsl::chrono::steady_clock').
//
///Event Clock Substitution
///------------------------
// For testing purposes, a class 'bdlmt::EventSchedulerTestTimeSource' is
// provided to allow manual manipulation of the system-time observed by a
// 'bdlmt::EventScheduler'.  A test driver that interacts with a
// 'bdlmt::EventScheduler' can use a 'bdlmt::EventSchedulerTestTimeSource'
// object to control when scheduled events are triggered, allowing more
// reliable tests.
//
// A 'bdlmt::EventSchedulerTestTimeSource' can be constructed for any existing
// 'bdlmt::EventScheduler' object that has not been started and has not had any
// events scheduled.  When the 'bdlmt::EventSchedulerTestTimeSource' is
// constructed, it will replace the clock of the 'bdlmt::EventScheduler' to
// which it is attached.  The internal clock of the
// 'bdlmt::EventSchedulerTestTimeSource' will be initialized with an arbitrary
// value on construction, and will advance only when explicitly instructed to
// do so by a call to 'bdlt::EventSchedulerTestTimeSource::advanceTime'.  The
// current value of the internal clock can be accessed by calling
// 'bdlt::EventSchedulerTestTimeSource::now', or 'bdlmt::EventScheduler::now'
// on the instance supplied to the 'bdlmt::EventSchedulerTestTimeSource'.
//
// Note that the initial value of 'bdlt::EventSchedulerTestTimeSource::now' is
// intentionally not synchronized with 'bsls::SystemTime::nowRealtimeClock'.
// All test events scheduled for a 'bdlmt::EventScheduler' that is instrumented
// with a 'bdlt::EventSchedulerTestTimeSource' should be scheduled in terms of
// an offset from whatever arbitrary time is reported by
// 'bdlt::EventSchedulerTestTimeSource'.  See Example 3 below for an
// illustration of how this is done.
//
///Thread Name for Dispatcher Thread
///---------------------------------
// To facilitate debugging, users can provide a thread name as the 'threadName'
// attribute of the 'bslmt::ThreadAttributes' argument passed to the 'start'
// method, that will be used for the dispatcher thread.  The thread name should
// not be used programmatically, but will appear in debugging tools on
// platforms that support naming threads to help users identify the source and
// purpose of a thread.  If no 'ThreadAttributes' object is passed, or if the
// 'threadName' attribute is not set, the default value "bdl.EventSched" will
// be used.
//
///Usage
///-----
// This section illustrates intended use of this component.
//
///Example 1: Simple Clock
///- - - - - - - - - - - -
// In this example we wish to log some statistics periodically.  We define a
// method to store the value of a variable into an array, and set up a
// scheduler to call that as a recurring event.
//..
//   bsls::AtomicInt  g_data;  // Some global data we want to track
//   typedef pair<bsls::TimeInterval, int> Value;
//
//   void saveData(vector<Value> *array)
//   {
//      array->push_back(Value(bsls::SystemTime::nowRealtimeClock(), g_data));
//   }
//..
// We allow the scheduler to run for a short time while changing this value and
// observe that the callback is executed:
//..
//   bdlmt::EventScheduler scheduler;
//   vector<Value> values;
//
//   scheduler.scheduleRecurringEvent(bsls::TimeInterval(1.5),
//                                  bdlf::BindUtil::bind(&saveData, &values)));
//   scheduler.start();
//   bsls::TimeInterval start = bsls::SystemTime::nowRealtimeClock();
//   while ((bsls::SystemTime::nowRealtimeClock() -
//                                         start).totalSecondsAsDouble() < 7) {
//     ++g_data;
//   }
//   scheduler.stop();
//   assert(values.size() >= 4);
//   for (int i = 0; i < (int) values.size(); ++i) {
//       cout << "At " << bdlt::EpochUtil::convertFromTimeInterval(
//                                                          values[i].first) <<
//               " g_data was " << values[i].second << endl;
//   }
//..
// This will display, e.g.:
//..
//  At 26OCT2020_23:51:51.097283 g_data was 8008406
//  At 26OCT2020_23:51:52.597287 g_data was 16723918
//  At 26OCT2020_23:51:54.097269 g_data was 24563722
//  At 26OCT2020_23:51:55.597262 g_data was 30291748
//..
//
///Example 2: Server Timeouts
/// - - - - - - - - - - - - -
// The following example shows how to use a 'bdlmt::EventScheduler' to
// implement a timeout mechanism in a server.  'my_Session' maintains several
// connections.  It closes a connection if the data for it does not arrive
// before a timeout (specified at the server creation time).
//
// Because the timeout is relative to the arrival of data, it is best to use a
// "monotonic" clock that advances at a steady rate, rather than a "wall" clock
// that may fluctuate to reflect real time adjustments.
//..
//    class my_Session{
//        // This class encapsulates the data and state associated with a
//        // connection and provides a method 'processData' to process the
//        // incoming data for the connection.
//      public:
//        int processData(void *data, int length);
//            // Process the specified 'data' of the specified 'length'.  (TBD)
//    };
//
//    class my_Server {
//     // This class implements a server maintaining several connections.
//     // A connection is closed if the data for it does not arrive
//     // before a timeout (specified at the server creation time).
//
//     struct Connection {
//         bdlmt::EventSchedulerEventHandle d_timerId;   // handle for timeout
//                                                     // event
//
//         my_Session *d_session_p;                    // session for this
//                                                     // connection
//     };
//
//     bsl::vector<Connection*> d_connections; // maintained connections
//     bdlmt::EventScheduler    d_scheduler;   // timeout event scheduler
//     bsls::TimeInterval       d_ioTimeout;   // time out
//
//     void newConnection(Connection *connection);
//         // Add the specified 'connection' to this server and schedule
//         // the timeout event that closes this connection if the data
//         // for this connection does not arrive before the timeout.
//
//     void closeConnection(Connection *connection);
//         // Close the specified 'connection' and remove it from this server.
//
//     void dataAvailable(Connection *connection, void *data, int length);
//         // Return if the specified 'connection' has already timed-out.
//         // If not, cancel the existing timeout event for the 'connection',
//         // process the specified 'data' of the specified 'length' and
//         // schedule a new timeout event that closes the 'connection' if
//         // the data does not arrive before the timeout.
//
//   public:
//     my_Server(const bsls::TimeInterval&  ioTimeout,
//               bslma::Allocator         *allocator = 0);
//         // Create a 'my_Server' object with a timeout value of
//         // 'ioTimeout' seconds.  Optionally specify a 'allocator' used to
//         // supply memory.  If 'allocator' is 0, the currently installed
//         // default allocator is used.
//
//     ~my_Server();
//         // Perform the required clean-up and destroy this object.
// };
//
// my_Server::my_Server(const bsls::TimeInterval&  ioTimeout,
//                      bslma::Allocator          *alloc)
// : d_connections(alloc)
// , d_scheduler(bsls::SystemClockType::e_MONOTONIC, alloc)
// , d_ioTimeout(ioTimeout)
// {
//      // TBD: logic to start monitoring the arriving connections or data
//
//      d_scheduler.start();
// }
//
// my_Server::~my_Server()
// {
//     // TBD: logic to clean up
//
//     d_scheduler.stop();
// }
//
// void my_Server::newConnection(my_Server::Connection *connection)
// {
//     // TBD: logic to add 'connection' to 'd_connections'
//
//     // setup the timeout for data arrival
//     d_scheduler.scheduleEvent(
//        &connection->d_timerId,
//        d_scheduler.now() + d_ioTimeout,
//        bdlf::BindUtil::bind(&my_Server::closeConnection, this, connection));
// }
//
// void my_Server::closeConnection(my_Server::Connection *connection)
// {
//     // TBD: logic to close the 'connection' and remove it from 'd_ioTimeout'
// }
//
// void my_Server::dataAvailable(my_Server::Connection *connection,
//                               void                  *data,
//                               int                    length)
// {
//     // If connection has already timed out and closed, simply return.
//     if (d_scheduler.cancelEvent(connection->d_timerId)) {
//         return;                                                    // RETURN
//     }
//
//     // process the data
//     connection->d_session_p->processData(data, length);
//
//     // setup the timeout for data arrival
//     d_scheduler.scheduleEvent(
//        &connection->d_timerId,
//        d_scheduler.now() + d_ioTimeout,
//        bdlf::BindUtil::bind(&my_Server::closeConnection, this, connection));
// }
//..
//
///Example 3: Using the Test Time Source
///- - - - - - - - - - - - - - - - - - -
// For testing purposes, the class 'bdlmt::EventSchedulerTestTimeSource' is
// provided to allow a test to manipulate the system-time observed by a
// 'bdlmt::EventScheduler' in order to control when events are triggered.
// After a scheduler is constructed, a 'bdlmt::EventSchedulerTestTimeSource'
// object can be created atop the scheduler.  A test can then use the test
// time-source to advance the scheduler's observed system-time in order to
// dispatch events in a manner coordinated by the test.  Note that a
// 'bdlmt::EventSchedulerTestTimeSource' *must* be created on an
// event-scheduler before any events are scheduled, or the event-scheduler is
// started.
//
// This example shows how the clock may be altered:
//
//..
// void myCallbackFunction() {
//     puts("Event triggered!");
// }
//
// void testCase() {
//     // Create the scheduler
//     bdlmt::EventScheduler scheduler;
//
//     // Create the time-source.
//     // Install the time-source in the scheduler.
//     bdlmt::EventSchedulerTestTimeSource timeSource(&scheduler);
//
//     // Retrieve the initial time held in the time-source.
//     bsls::TimeInterval initialAbsoluteTime = timeSource.now();
//
//     // Schedule a single-run event at a 35s offset.
//     scheduler.scheduleEvent(initialAbsoluteTime + 35,
//                             bsl::function<void()>(&myCallbackFunction));
//
//     // Schedule a 30s recurring event.
//     scheduler.scheduleRecurringEvent(bsls::TimeInterval(30),
//                                      bsl::function<void()>(
//                                                       &myCallbackFunction));
//
//     // Start the dispatcher thread.
//     scheduler.start();
//
//     // Advance the time by 40 seconds so that each
//     // event will run once.
//     timeSource.advanceTime(bsls::TimeInterval(40));
//
//     // The line "Event triggered!" should now have
//     // been printed to the console twice.
//
//     scheduler.stop();
// }
//..
//
// Note that this feature should be used only for testing purposes, never in
// production code.

#include <bdlscm_version.h>

#include <bdlcc_skiplist.h>

#include <bdlf_bind.h>
#include <bdlf_placeholder.h>

#include <bslma_allocator.h>
#include <bslma_usesbslmaallocator.h>

#include <bslmf_allocatorargt.h>
#include <bslmf_nestedtraitdeclaration.h>

#include <bslmt_condition.h>
#include <bslmt_lockguard.h>
#include <bslmt_mutex.h>
#include <bslmt_threadattributes.h>
#include <bslmt_threadutil.h>

#include <bsls_assert.h>
#include <bsls_atomic.h>
#include <bsls_libraryfeatures.h>
#include <bsls_review.h>
#include <bsls_systemclocktype.h>
#include <bsls_timeinterval.h>
#include <bsls_types.h>

#include <bsl_functional.h>
#include <bsl_memory.h>
#include <bsl_utility.h>

#ifdef BSLS_LIBRARYFEATURES_HAS_CPP11_BASELINE_LIBRARY
#include <bslmt_chronoutil.h>

#include <bsl_chrono.h>
#endif

namespace BloombergLP {
namespace bdlmt {

class EventSchedulerEventHandle;
class EventSchedulerRecurringEventHandle;
class EventSchedulerTestTimeSource_Data;

                            // ====================
                            // class EventScheduler
                            // ====================

class EventScheduler {
    // This class provides a thread-safe event scheduler that executes
    // callbacks in a separate "dispatcher thread."  'start' must be invoked to
    // start dispatching the callbacks.  'stop' pauses the dispatching of the
    // callbacks without removing the pending events.

  private:
    // PRIVATE TYPES

                               // ================
                               // struct EventData
                               // ================

    struct EventData {
        // This 'struct' encapsulates all of the information for a
        // non-recurring event.

      public:
        // DATA
        bsl::function<void()>               d_callback;
            // user-supplied callback invoked when associated event triggers

        bsl::function<bsls::Types::Int64()> d_nowOffset;
            // a function that returns the difference, in microseconds, between
            // when the scheduled event is meant to occur and the current time

      private:
        // NOT IMPLEMENTED
        EventData& operator=(const EventData&);

      public:
        // TRAITS
        BSLMF_NESTED_TRAIT_DECLARATION(EventData, bslma::UsesBslmaAllocator);

        // CREATORS
        EventData(
                const bsl::function<void()>&                callback,
                const bsl::function<bsls::Types::Int64()>&  nowOffset,
                bslma::Allocator                           *basicAllocator = 0)
            // Create an 'EventData' from the specified 'callback' and
            // 'nowOffset'.  Optionally specify a 'basicAllocator' used to
            // supply memory.  If 'basicAllocator' is 0, the currently
            // installed default allocator is used.
        : d_callback(bsl::allocator_arg, basicAllocator, callback)
        , d_nowOffset(bsl::allocator_arg, basicAllocator, nowOffset)
        {
        }

        EventData(const EventData&  original,
                  bslma::Allocator *basicAllocator = 0)
            // Create an 'EventData' object having the value of the specified
            // 'original' object.  Optionally specify a 'basicAllocator' used
            // to supply memory.  If 'basicAllocator' is 0, the currently
            // installed default allocator is used.
        : d_callback(bsl::allocator_arg, basicAllocator, original.d_callback)
        , d_nowOffset(bsl::allocator_arg, basicAllocator, original.d_nowOffset)
        {
        }
    };

                         // =========================
                         // struct RecurringEventData
                         // =========================

    struct RecurringEventData {
        // This 'struct' encapsulates all of the information for a recurring
        // event.

      public:
        // DATA
        bsls::TimeInterval                     d_interval;
            // the time between calls (in microseconds)

        bsl::function<void()>                  d_callback;
            // user-supplied callback invoked when associated event triggers

        bsl::function<bsls::Types::Int64(int)> d_nowOffset;
            // a function that returns the difference, in microseconds, between
            // when the scheduled event is meant to occur and the current time

        int                                    d_eventIdx;
            // the index of the recurring event (starting with 0); passed to
            // 'd_nowOffset' to determine the time of the next invocation of
            // 'd_callback'

      private:
        // NOT IMPLEMENTED
        RecurringEventData& operator=(const RecurringEventData&);

      public:
        // TRAITS
        BSLMF_NESTED_TRAIT_DECLARATION(RecurringEventData,
                                       bslma::UsesBslmaAllocator);

        // CREATORS
        RecurringEventData(
             const bsls::TimeInterval&                      interval,
             const bsl::function<void()>&                   callback,
             const bsl::function<bsls::Types::Int64(int)>&  nowOffset,
             bslma::Allocator                              *basicAllocator = 0)
            // Create a 'RecurringEventData' from the specified 'interval',
            // 'callback', and 'nowOffset'.  Optionally specify a
            // 'basicAllocator' used to supply memory.  If 'basicAllocator' is
            // 0, the currently installed default allocator is used.
        : d_interval(interval)
        , d_callback(bsl::allocator_arg, basicAllocator, callback)
        , d_nowOffset(bsl::allocator_arg, basicAllocator, nowOffset)
        , d_eventIdx(0)
        {
        }

        RecurringEventData(const RecurringEventData&  original,
                           bslma::Allocator          *basicAllocator = 0)
            // Create a 'RecurringEventData' object having the value of the
            // specified 'original' object.  Optionally specify a
            // 'basicAllocator' used to supply memory.  If 'basicAllocator' is
            // 0, the currently installed default allocator is used.
        : d_interval(original.d_interval)
        , d_callback(bsl::allocator_arg, basicAllocator, original.d_callback)
        , d_nowOffset(bsl::allocator_arg, basicAllocator, original.d_nowOffset)
        , d_eventIdx(original.d_eventIdx)
        {
        }
    };

    typedef bdlcc::SkipList<bsls::Types::Int64,
                            RecurringEventData>            RecurringEventQueue;

    typedef bdlcc::SkipList<bsls::Types::Int64, EventData> EventQueue;

    typedef bsl::function<bsls::TimeInterval()>            CurrentTimeFunctor;

    // FRIENDS
    friend class EventSchedulerEventHandle;
    friend class EventSchedulerRecurringEventHandle;
    friend class EventSchedulerTestTimeSource;

  public:
    // PUBLIC TYPES
    struct Event {};
    struct RecurringEvent {};
        // Pointers to the opaque structures 'Event' and 'RecurringEvent' are
        // populated by the "Raw" API of 'EventScheduler'.

    typedef EventSchedulerEventHandle          EventHandle;

    typedef EventSchedulerRecurringEventHandle RecurringEventHandle;

    typedef bsl::function<void(const bsl::function<void()>&)>
                                               Dispatcher;
        // Defines a type alias for the dispatcher functor type.

  private:
    // NOT IMPLEMENTED
    EventScheduler(const EventScheduler&);
    EventScheduler& operator=(const EventScheduler&);

  private:
    // PRIVATE CLASS DATA
    static const char     s_defaultThreadName[16];  // Thread name to use when
                                                    // none is specified.

    // PRIVATE DATA
    CurrentTimeFunctor    d_currentTimeFunctor; // when called, returns the
                                                // current time the scheduler
                                                // should use for the event
                                                // timeline

    EventQueue            d_eventQueue;         // events

    RecurringEventQueue   d_recurringQueue;     // recurring events

    Dispatcher            d_dispatcherFunctor;  // dispatch events

    bslmt::ThreadUtil::Handle
                          d_dispatcherThread;   // dispatcher thread handle

    bsls::AtomicUint64    d_dispatcherThreadId; // dispatcher thread id used to
                                                // implement function
                                                // 'isInDispatcherThread'

    bslmt::Mutex          d_dispatcherMutex;    // serialize starting/stopping
                                                // dispatcher thread

    mutable bslmt::Mutex  d_mutex;              // synchronizes access to
                                                // condition variables

    bslmt::Condition      d_queueCondition;     // condition variable used to
                                                // signal when the queues need
                                                // to be checked again (when
                                                // they become non-empty or get
                                                // a new front member)

    bslmt::Condition      d_iterationCondition; // condition variable used to
                                                // signal when the dispatcher
                                                // is ready to enter next
                                                // iteration (synchronizes
                                                // 'wait' methods)

    bool                  d_running;            // controls the looping of the
                                                // dispatcher thread

    bool                  d_dispatcherAwaited;  // A thread is waiting for the
                                                // dispatcher to complete an
                                                // iteration

    RecurringEventQueue::Pair
                         *d_currentRecurringEvent;
                                                // Raw reference to the
                                                // scheduled event being
                                                // executed
    EventQueue::Pair     *d_currentEvent;
                                                // Raw reference to the
                                                // scheduled recurring event
                                                // being executed

    unsigned int          d_waitCount;          // count of the number of waits
                                                // performed in the main
                                                // dispatch loop, used in
                                                // 'advanceTime' to determine
                                                // when to return

    bsls::SystemClockType::Enum
                          d_clockType;          // clock type used



    // PRIVATE CLASS METHODS
    static bsls::Types::Int64 returnZero();
        // Return 0.

    static bsls::Types::Int64 returnZeroInt(int);
        // Return 0.  The 'int' argument is ignored.

#ifdef BSLS_LIBRARYFEATURES_HAS_CPP11_BASELINE_LIBRARY
    template <class CLOCK, class DURATION>
    static bsls::Types::Int64
    timeUntilTrigger(const bsl::chrono::time_point<CLOCK, DURATION>& absTime);
        // Return the number of microseconds between the current time and the
        // specified 'absTime'.  'absTime' is an *absolute* time represented as
        // an interval from some epoch, which is determined by the clock
        // associated with the time point.  Note that this method is used when
        // the 'CLOCK' type used to schedule the event differs from that of the
        // event scheduler itself.  Also note that a negative value is returned
        // if 'absTime' is in the past.

    template <class CLOCK, class DURATION, class REP_TYPE, class PERIOD_TYPE>
    static bsls::Types::Int64 timeUntilTriggerRecurring(
               const bsl::chrono::time_point<CLOCK, DURATION>&     absTime,
               const bsl::chrono::duration<REP_TYPE, PERIOD_TYPE>& interval,
               int                                                 eventIndex);
        // Return the number of microseconds between the current time and the
        // scheduled time of the specified 'eventIndex'th recurring event,
        // which starts at the specified 'absTime' and repeats at the specified
        // 'interval'.  'absTime' is an *absolute* time represented as an
        // interval from some epoch, which is determined by the clock
        // associated with the time point.  The behavior is undefined unless
        // '0 <= eventIndex'.  Note that this method is used when the 'CLOCK'
        // type used to schedule the event differs from that of the event
        // scheduler itself.
#endif

    // PRIVATE MANIPULATORS
    bsls::Types::Int64 chooseNextEvent(bsls::Types::Int64 *now);
        // Pick either 'd_currentEvent' or 'd_currentRecurringEvent' as the
        // next event to be executed, given that the current time is the
        // specified (absolute) 'now' interval, and return the (absolute)
        // interval of the chosen event.  If both 'd_currentEvent' and
        // 'd_currentRecurringEvent' are valid, release whichever one was not
        // chosen.  If both 'd_currentEvent' and 'd_currentRecurringEvent' are
        // scheduled before 'now', choose 'd_currentEvent'.  The behavior is
        // undefined if neither 'd_currentEvent' nor 'd_currentRecurringEvent'
        // is valid.  Note that the argument and return value of this method
        // are expressed in terms of the number of microseconds elapsed since
        // some epoch, which is determined by the clock indicated at
        // construction (see {Supported Clock Types} in the component
        // documentation).  Also note that this method may update the value of
        // 'now' with the current system time if necessary.

    void dispatchEvents();
        // While d_running is true, execute events in the event and recurring
        // event queues at their scheduled times.  Note that this method
        // implements the dispatching thread.

    void releaseCurrentEvents();
        // Release 'd_currentRecurringEvent' and 'd_currentEvent', if they
        // refer to valid events.

    void scheduleEvent(EventHandle               *event,
                       const bsls::TimeInterval&  epochTime,
                       const EventData&           eventData);
        // Schedule the callback of the specified 'eventData' to be dispatched
        // at the specified 'epochTime' truncated to microseconds.  Load into
        // the specified 'event' pointer a handle that can be used to cancel
        // the event (by invoking 'cancelEvent').  The 'epochTime' is an
        // absolute time represented as an interval from some epoch, which is
        // determined by the clock indicated at construction (see {Supported
        // Clock Types} in the component documentation).  Note that if
        // 'epochTime' is in the past, the event is dispatched immediately.

    void scheduleEvent(const bsls::TimeInterval&   epochTime,
                       const EventData&            eventData);
        // Schedule the callback of the specified 'eventData' to be dispatched
        // at the specified 'epochTime' truncated to microseconds.  The
        // 'epochTime' is an absolute time represented as an interval from some
        // epoch, which is determined by the clock indicated at construction
        // (see {Supported Clock Types} in the component documentation).  Note
        // that if 'epochTime' is in the past, the event is dispatched
        // immediately.

    void scheduleRecurringEvent(RecurringEventHandle      *event,
                                const RecurringEventData&  eventData,
                                const bsls::TimeInterval&  startEpochTime);
        // Schedule a recurring event that invokes the callback of the
        // specified 'eventData' with the first event dispatched at the
        // specified 'startEpochTime' truncated to microseconds.  Load into the
        // specified 'event' pointer a handle that can be used to cancel the
        // event (by invoking 'cancelEvent').  The 'startEpochTime' is an
        // absolute time represented as an interval from some epoch, which is
        // determined by the clock indicated at construction (see {Supported
        // Clock Types} in the component documentation).  The behavior is
        // undefined unless the interval of 'eventData' is at least one
        // microsecond.  Note that if 'startEpochTime' is in the past, the
        // first event is dispatched immediately, and additional
        // '(now() - startEpochTime) / eventData.d_interval' events will be
        // submitted serially.

    void scheduleRecurringEventRaw(RecurringEvent            **event,
                                   const RecurringEventData&   eventData,
                                   const bsls::TimeInterval&   startEpochTime);
        // Schedule a recurring event that invokes the callback of the
        // specified 'eventData' with the first event dispatched at the
        // specified 'startEpochTime' truncated to microseconds.  Load into the
        // specified 'event' pointer a handle that can be used to cancel the
        // event (by invoking 'cancelEvent').  The 'startEpochTime' is an
        // *absolute* time represented as an interval from some epoch, which is
        // determined by the clock indicated at construction (see {Supported
        // Clock Types} in the component documentation).  The 'event' pointer
        // must be released by invoking 'releaseEventRaw' when it is no longer
        // needed.  The behavior is undefined unless the interval of
        // 'eventData' is at least one microsecond.  Note that if
        // 'startEpochTime' is in the past, the first event is dispatched
        // immediately, and additional
        // '(now() - startEpochTime) / eventData.d_interval' events will be
        // submitted serially.

  public:
    // TRAITS
    BSLMF_NESTED_TRAIT_DECLARATION(EventScheduler, bslma::UsesBslmaAllocator);

    // CREATORS
    explicit EventScheduler(bslma::Allocator *basicAllocator = 0);
        // Create an event scheduler using the default dispatcher functor (see
        // {The Dispatcher Thread and the Dispatcher Functor} in the
        // component-level documentation) and using the system realtime clock
        // to indicate the epoch used for all time intervals.  Optionally
        // specify a 'basicAllocator' used to supply memory.  If
        // 'basicAllocator' is 0, the currently installed default allocator is
        // used.

    explicit EventScheduler(bsls::SystemClockType::Enum  clockType,
                            bslma::Allocator            *basicAllocator = 0);
        // Create an event scheduler using the default dispatcher functor (see
        // {The Dispatcher Thread and the Dispatcher Functor} in the
        // component-level documentation) and using the specified 'clockType'
        // to indicate the epoch used for all time intervals (see {Supported
        // Clock Types} in the component documentation).  Optionally specify a
        // 'basicAllocator' used to supply memory.  If 'basicAllocator' is 0,
        // the currently installed default allocator is used.

#ifdef BSLS_LIBRARYFEATURES_HAS_CPP11_BASELINE_LIBRARY
    explicit EventScheduler(
                         const bsl::chrono::system_clock&,
                         bslma::Allocator                 *basicAllocator = 0);
        // Create an event scheduler using the default dispatcher functor (see
        // {The Dispatcher Thread and the Dispatcher Functor} in the
        // component-level documentation) and using the system realtime clock
        // to indicate the epoch used for all time intervals.  Optionally
        // specify a 'basicAllocator' used to supply memory.  If
        // 'basicAllocator' is 0, the currently installed default allocator is
        // used.

    explicit EventScheduler(
                         const bsl::chrono::steady_clock&,
                         bslma::Allocator                 *basicAllocator = 0);
        // Create an event scheduler using the default dispatcher functor (see
        // {The Dispatcher Thread and the Dispatcher Functor} in the
        // component-level documentation) and using the system monotonic clock
        // to indicate the epoch used for all time intervals.  Optionally
        // specify a 'basicAllocator' used to supply memory.  If
        // 'basicAllocator' is 0, the currently installed default allocator is
        // used.
#endif

    explicit EventScheduler(const Dispatcher&  dispatcherFunctor,
                            bslma::Allocator  *basicAllocator = 0);
        // Create an event scheduler using the specified 'dispatcherFunctor'
        // (see {The Dispatcher Thread and the Dispatcher Functor} in the
        // component-level documentation) and using the system realtime clock
        // to indicate the epoch used for all time intervals.  Optionally
        // specify a 'basicAllocator' used to supply memory.  If
        // 'basicAllocator' is 0, the currently installed default allocator is
        // used.

    EventScheduler(const Dispatcher&            dispatcherFunctor,
                   bsls::SystemClockType::Enum  clockType,
                   bslma::Allocator            *basicAllocator = 0);
        // Create an event scheduler using the specified 'dispatcherFunctor'
        // (see {The Dispatcher Thread and the Dispatcher Functor} in the
        // component-level documentation) and using the specified 'clockType'
        // to indicate the epoch used for all time intervals (see {Supported
        // Clock Types} in the component documentation).  Optionally specify a
        // 'basicAllocator' used to supply memory.  If 'basicAllocator' is 0,
        // the currently installed default allocator is used.

#ifdef BSLS_LIBRARYFEATURES_HAS_CPP11_BASELINE_LIBRARY
    EventScheduler(const Dispatcher&                 dispatcherFunctor,
                   const bsl::chrono::system_clock&,
                   bslma::Allocator                 *basicAllocator = 0);
        // Create an event scheduler using the specified 'dispatcherFunctor'
        // (see {The Dispatcher Thread and the Dispatcher Functor} in the
        // component-level documentation) and using the system realtime clock
        // to indicate the epoch used for all time intervals.  Optionally
        // specify a 'basicAllocator' used to supply memory.  If
        // 'basicAllocator' is 0, the currently installed default allocator is
        // used.

    EventScheduler(const Dispatcher&                 dispatcherFunctor,
                   const bsl::chrono::steady_clock&,
                   bslma::Allocator                 *basicAllocator = 0);
        // Create an event scheduler using the specified 'dispatcherFunctor'
        // (see {The Dispatcher Thread and the Dispatcher Functor} in the
        // component-level documentation) and using the system monotonic clock
        // to indicate the epoch used for all time intervals.  Optionally
        // specify a 'basicAllocator' used to supply memory.  If
        // 'basicAllocator' is 0, the currently installed default allocator is
        // used.
#endif

    ~EventScheduler();
        // Discard all unprocessed events and destroy this object.  The
        // behavior is undefined unless the scheduler is stopped.

    // MANIPULATORS
    void cancelAllEvents();
        // Cancel all recurring and one-time events scheduled in this
        // EventScheduler.

    void cancelAllEventsAndWait();
        // Cancel all recurring and one-time events scheduled in this
        // EventScheduler.  Block until all events have either been cancelled
        // or dispatched before this call returns.  The behavior is undefined
        // if this method is invoked from the dispatcher thread.

    int cancelEvent(const Event          *handle);
    int cancelEvent(const RecurringEvent *handle);
        // Cancel the event having the specified 'handle'.  Return 0 on
        // successful cancellation, and a non-zero value if the 'handle' is
        // invalid *or* if the event has already been dispatched or canceled.
        // Note that due to the implicit conversion from Handle types, these
        // methods also match the following:
        //..
        //  int cancelEvent(const EventHandle&          handle);
        //  int cancelEvent(const RecurringEventHandle& handle);
        //..
        // Compared to the version taking a pointer to Handle, the managed
        // reference to the event is not released until the Handle goes out of
        // scope.

    int cancelEvent(EventHandle          *handle);
    int cancelEvent(RecurringEventHandle *handle);
        // Cancel the event having the specified 'handle' and release the
        // handle.  Return 0 on successful cancellation, and a non-zero value
        // if the 'handle' is invalid *or* if the event has already been
        // dispatched or canceled.  Note that 'handle' is released whether this
        // call is successful or not.

    int cancelEventAndWait(const Event          *handle);
    int cancelEventAndWait(const RecurringEvent *handle);
        // Cancel the event having the specified 'handle'.  Block until the
        // event having 'handle' (if it is valid) is either successfully
        // canceled or dispatched before the call returns.  Return 0 on
        // successful cancellation, and a non-zero value if 'handle' is invalid
        // *or* if the event has already been dispatched or canceled.  The
        // behavior is undefined if this method is invoked from the dispatcher
        // thread.  Note that if the event is being executed when this method
        // is invoked, this method will block until it is completed and then
        // return a nonzero value.

    int cancelEventAndWait(EventHandle          *handle);
    int cancelEventAndWait(RecurringEventHandle *handle);
        // Cancel the event having the specified 'handle' and release
        // '*handle'.  Block until the event having 'handle' (if it is valid)
        // is either successfully canceled or dispatched before the call
        // returns.  Return 0 on successful cancellation, and a non-zero value
        // if 'handle' is invalid *or* if the event has already been dispatched
        // or canceled.  The behavior is undefined if this method is invoked
        // from the dispatcher thread.  Note that if the event is being
        // executed when this method is invoked, this method will block until
        // it is completed and then return a nonzero value.  Also note that it
        // is guaranteed that '*handle' will be released whether this call is
        // successful or not.

    void releaseEventRaw(Event          *handle);
    void releaseEventRaw(RecurringEvent *handle);
        // Release the specified 'handle'.  Every handle reference added by
        // 'scheduleEventRaw', 'addEventRefRaw', 'scheduleRecurringEventRaw',
        // or 'addRecurringEventRefRaw' must be released using this method to
        // avoid leaking resources.  The behavior is undefined if the value of
        // 'handle' is used for any purpose after being released.

    int rescheduleEvent(const Event               *handle,
                        const bsls::TimeInterval&  newEpochTime);
        // Reschedule the event referred to by the specified 'handle' at the
        // specified 'newEpochTime' truncated to microseconds.  Return 0 on
        // successful reschedule, and a non-zero value if the 'handle' is
        // invalid *or* if the event has already been dispatched.  The
        // 'newEpochTime' is an absolute time represented as an interval from
        // some epoch, which is determined by the clock indicated at
        // construction (see {Supported Clock Types} in the component
        // documentation).

#ifdef BSLS_LIBRARYFEATURES_HAS_CPP11_BASELINE_LIBRARY
    template <class CLOCK, class DURATION>
    int rescheduleEvent(
                const Event                                     *handle,
                const bsl::chrono::time_point<CLOCK, DURATION>&  newEpochTime);
        // Reschedule the event referred to by the specified 'handle' at the
        // specified 'newEpochTime' truncated to microseconds.  Return 0 on
        // successful reschedule, and a non-zero value if the 'handle' is
        // invalid *or* if the event has already been dispatched.  The
        // 'newEpochTime' is an absolute time represented as an interval from
        // some epoch, determined by the clock associated with the time point.
#endif

    int rescheduleEventAndWait(const Event               *handle,
                               const bsls::TimeInterval&  newEpochTime);
        // Reschedule the event referred to by the specified 'handle' at the
        // specified 'newEpochTime' truncated to microseconds.  Block until the
        // event having 'handle' (if it is valid) is either successfully
        // rescheduled or dispatched before the call returns.  Return 0 on
        // successful reschedule, and a non-zero value if 'handle' is invalid
        // *or* if the event has already been dispatched.  The 'newEpochTime'
        // is an absolute time represented as an interval from some epoch,
        // which is determined by the clock indicated at construction (see
        // {Supported Clock Types} in the component documentation).  The
        // behavior is undefined if this method is invoked from the dispatcher
        // thread.

#ifdef BSLS_LIBRARYFEATURES_HAS_CPP11_BASELINE_LIBRARY
    template <class CLOCK, class DURATION>
    int rescheduleEventAndWait(
                const Event                                     *handle,
                const bsl::chrono::time_point<CLOCK, DURATION>&  newEpochTime);
        // Reschedule the event referred to by the specified 'handle' at the
        // specified 'newEpochTime' truncated to microseconds.  Block until the
        // event having 'handle' (if it is valid) is either successfully
        // rescheduled or dispatched before the call returns.  Return 0 on
        // successful reschedule, and a non-zero value if 'handle' is invalid
        // *or* if the event has already been dispatched.  The 'newEpochTime'
        // is an absolute time represented as an interval from some epoch,
        // which is determined by the clock associated with the time point.
        // The behavior is undefined if this method is invoked from the
        // dispatcher thread.
#endif

    void scheduleEvent(const bsls::TimeInterval&    epochTime,
                       const bsl::function<void()>& callback);
    void scheduleEvent(EventHandle                  *event,
                       const bsls::TimeInterval&     epochTime,
                       const bsl::function<void()>&  callback);
        // Schedule the specified 'callback' to be dispatched at the specified
        // 'epochTime' truncated to microseconds.  Load into the optionally
        // specified 'event' a handle that can be used to cancel the event (by
        // invoking 'cancelEvent').  The 'epochTime' is an absolute time
        // represented as an interval from some epoch, which is determined by
        // the clock indicated at construction (see {Supported Clock Types} in
        // the component documentation).  This method guarantees that the
        // event will occur at or after 'epochTime'.  'epochTime' may be in the
        // past, in which case the event will be executed as soon as possible.

#ifdef BSLS_LIBRARYFEATURES_HAS_CPP11_BASELINE_LIBRARY
    template <class CLOCK, class DURATION>
    void scheduleEvent(
                     const bsl::chrono::time_point<CLOCK, DURATION>& epochTime,
                     const bsl::function<void()>&                    callback);
    template <class CLOCK, class DURATION>
    void scheduleEvent(
                    EventHandle                                     *event,
                    const bsl::chrono::time_point<CLOCK, DURATION>&  epochTime,
                    const bsl::function<void()>&                     callback);
        // Schedule the specified 'callback' to be dispatched at the specified
        // 'epochTime' truncated to microseconds.  Load into the optionally
        // specified 'event' a handle that can be used to cancel the event (by
        // invoking 'cancelEvent').  The 'epochTime' is an absolute time
        // represented as an interval from some epoch, which is determined by
        // the clock associated with the time point.  This method guarantees
        // that the event will occur at or after 'epochTime'.  'epochTime' may
        // be in the past, in which case the event will be executed as soon as
        // possible.
#endif

    void scheduleEventRaw(Event                        **event,
                          const bsls::TimeInterval&      epochTime,
                          const bsl::function<void()>&   callback);
        // Schedule the specified 'callback' to be dispatched at the specified
        // 'epochTime' truncated to microseconds.  Load into the specified
        // 'event' pointer a handle that can be used to cancel the event (by
        // invoking 'cancelEvent').  The 'epochTime' is an *absolute* time
        // represented as an interval from some epoch, which is determined by
        // the clock indicated at construction (see {Supported Clock Types} in
        // the component documentation).  The 'event' pointer must be released
        // invoking 'releaseEventRaw' when it is no longer needed.

#ifdef BSLS_LIBRARYFEATURES_HAS_CPP11_BASELINE_LIBRARY
    template <class CLOCK, class DURATION>
    void scheduleEventRaw(
                   Event                                           **event,
                   const bsl::chrono::time_point<CLOCK, DURATION>&   epochTime,
                   const bsl::function<void()>&                      callback);
        // Schedule the specified 'callback' to be dispatched at the specified
        // 'epochTime' truncated to microseconds.  Load into the specified
        // 'event' pointer a handle that can be used to cancel the event (by
        // invoking 'cancelEvent').  The 'epochTime' is an absolute time
        // represented as an interval from some epoch, which is determined by
        // the clock associated with the time point.  The 'event' pointer must
        // be released invoking 'releaseEventRaw' when it is no longer needed.
#endif

    void scheduleRecurringEvent(const bsls::TimeInterval&    interval,
                                const bsl::function<void()>& callback,
                                const bsls::TimeInterval&    startEpochTime
                                                      = bsls::TimeInterval(0));
    void scheduleRecurringEvent(RecurringEventHandle         *event,
                                const bsls::TimeInterval&     interval,
                                const bsl::function<void()>&  callback,
                                const bsls::TimeInterval&     startEpochTime
                                                      = bsls::TimeInterval(0));
        // Schedule a recurring event that invokes the specified 'callback' at
        // every specified 'interval' truncated to microseconds, with the first
        // event dispatched at the optionally specified 'startEpochTime'
        // truncated to microseconds.  If 'startEpochTime' is not specified,
        // the first event is dispatched at one 'interval' from now.  Load into
        // the optionally specified 'event' a handle that can be used to cancel
        // the event (by invoking 'cancelEvent').  The 'startEpochTime' is an
        // absolute time represented as an interval from some epoch, which is
        // determined by the clock indicated at construction (see {Supported
        // Clock Types} in the component documentation).  The behavior is
        // undefined unless 'interval' is at least one microsecond.  Note that
        // if 'startEpochTime' is in the past, the first event is dispatched
        // immediately, and additional '(now() - startEpochTime) / interval'
        // events will be submitted serially.

#ifdef BSLS_LIBRARYFEATURES_HAS_CPP11_BASELINE_LIBRARY
    template <class CLOCK, class REP_TYPE, class PERIOD_TYPE, class DURATION>
    void scheduleRecurringEvent(
             const bsl::chrono::duration<REP_TYPE, PERIOD_TYPE>& interval,
             const bsl::function<void()>&                        callback,
             const bsl::chrono::time_point<CLOCK, DURATION>&     startEpochTime
                      = CLOCK::now());
    template <class CLOCK, class REP_TYPE, class PERIOD_TYPE, class DURATION>
    void scheduleRecurringEvent(
            RecurringEventHandle                                *event,
            const bsl::chrono::duration<REP_TYPE, PERIOD_TYPE>&  interval,
            const bsl::function<void()>&                         callback,
            const bsl::chrono::time_point<CLOCK, DURATION>&      startEpochTime
                      = CLOCK::now());
        // Schedule a recurring event that invokes the specified 'callback' at
        // every specified 'interval' truncated to microseconds, with the first
        // event dispatched at the optionally specified 'startEpochTime'
        // truncated to microseconds.  If 'startEpochTime' is not specified,
        // the first event is dispatched at one 'interval' from now.  Load into
        // the optionally specified 'event' a handle that can be used to cancel
        // the event (by invoking 'cancelEvent').  The 'startEpochTime' is an
        // absolute time represented as an interval from some epoch, which is
        // determined by the clock associated with the time point.  The
        // behavior is undefined unless 'interval' is at least one microsecond.
        // Note that if 'startEpochTime' is in the past, the first event is
        // dispatched immediately, and additional
        // '(now() - startEpochTime) / interval' events will be submitted
        // serially.
#endif

    void scheduleRecurringEventRaw(
                                  RecurringEvent               **event,
                                  const bsls::TimeInterval&      interval,
                                  const bsl::function<void()>&   callback,
                                  const bsls::TimeInterval&      startEpochTime
                                                      = bsls::TimeInterval(0));
        // Schedule a recurring event that invokes the specified 'callback' at
        // every specified 'interval' truncated to microseconds, with the first
        // event dispatched at the optionally specified 'startEpochTime'
        // truncated to microseconds.  If 'startEpochTime' is not specified,
        // the first event is dispatched at one 'interval' from now.  Load into
        // the specified 'event' pointer a handle that can be used to cancel
        // the event (by invoking 'cancelEvent').  The 'startEpochTime' is an
        // absolute time represented as an interval from some epoch, which is
        // determined by the clock indicated at construction (see {Supported
        // Clock Types} in the component documentation).  The 'event' pointer
        // must be released by invoking 'releaseEventRaw' when it is no longer
        // needed.  The behavior is undefined unless 'interval' is at least one
        // microsecond.  Note that if 'startEpochTime' is in the past, the
        // first event is dispatched immediately, and additional
        // '(now() - startEpochTime) / interval' events will be submitted
        // serially.

#ifdef BSLS_LIBRARYFEATURES_HAS_CPP11_BASELINE_LIBRARY
    template <class CLOCK, class REP_TYPE, class PERIOD_TYPE, class DURATION>
    void scheduleRecurringEventRaw(
           RecurringEvent                                      **event,
           const bsl::chrono::duration<REP_TYPE, PERIOD_TYPE>&   interval,
           const bsl::function<void()>&                          callback,
           const bsl::chrono::time_point<CLOCK, DURATION>&       startEpochTime
                                                               = CLOCK::now());
        // Schedule a recurring event that invokes the specified 'callback' at
        // every specified 'interval' truncated to microseconds, with the first
        // event dispatched at the optionally specified 'startEpochTime'
        // truncated to microseconds.  If 'startEpochTime' is not specified,
        // the first event is dispatched at one 'interval' from now.  Load into
        // the specified 'event' pointer a handle that can be used to cancel
        // the event (by invoking 'cancelEvent').  The 'startEpochTime' is an
        // absolute time represented as an interval from some epoch, which is
        // determined by the clock associated with the time point.  The 'event'
        // pointer must be released by invoking 'releaseEventRaw' when it is no
        // longer needed.  The behavior is undefined unless 'interval' is at
        // least one microsecond.  Note that if 'startEpochTime' is in the
        // past, the first event is dispatched immediately, and additional
        // '(now() - startEpochTime) / interval' events will be submitted
        // serially.
#endif

    int start();
        // Begin dispatching events on this scheduler using default attributes
        // for the dispatcher thread.  Return 0 on success, and a nonzero value
        // otherwise.  If another thread is currently executing 'stop', wait
        // until the dispatcher thread stops before starting a new one.  If
        // this scheduler has already started (and is not currently being
        // stopped by another thread) then this invocation has no effect and 0
        // is returned.  The behavior is undefined if this method is invoked in
        // the dispatcher thread (i.e., in a job executed by this scheduler).
        // Note that any event whose time has already passed is pending and
        // will be dispatched immediately.

    int start(const bslmt::ThreadAttributes& threadAttributes);
        // Begin dispatching events on this scheduler using the specified
        // 'threadAttributes' for the dispatcher thread (except that the
        // DETACHED attribute is ignored).  Return 0 on success, and a nonzero
        // value otherwise.  If another thread is currently executing 'stop',
        // wait until the dispatcher thread stops before starting a new one.
        // If this scheduler has already started (and is not currently being
        // stopped by another thread) then this invocation has no effect and 0
        // is returned.  The behavior is undefined if this method is invoked in
        // the dispatcher thread (i.e., in a job executed by this scheduler).
        // Note that any event whose time has already passed is pending and
        // will be dispatched immediately.

    void stop();
        // End the dispatching of events on this scheduler (but do not remove
        // any pending events), and wait for any (one) currently executing
        // event to complete.  If the scheduler is already stopped then this
        // method has no effect.  This scheduler can be restarted by invoking
        // 'start'.  The behavior is undefined if this method is invoked from
        // the dispatcher thread.

    // ACCESSORS
    Event *addEventRefRaw(Event *handle) const;
        // Increment the reference count for the event referred to by the
        // specified 'handle' and return 'handle'.  There must be a
        // corresponding call to 'releaseEventRaw' when the reference is no
        // longer needed.

    RecurringEvent *addRecurringEventRefRaw(RecurringEvent *handle) const;
        // Increment the reference count for the recurring event referred to by
        // the specified 'handle' and return 'handle'.  There must be a
        // corresponding call to 'releaseEventRaw' when the reference is no
        // longer needed.

    bsls::SystemClockType::Enum clockType() const;
        // Return the value of the clock type that this object was created
        // with.

    bool isStarted() const;
        // Return 'true' if a call to 'start' has finished successfully more
        // recently than any call to 'stop', and 'false' otherwise.

    bsls::TimeInterval now() const;
        // Return the current epoch time, an absolute time represented as an
        // interval from some epoch, which is determined by the clock indicated
        // at construction (see {Supported Clock Types} in the component
        // documentation).

    int numEvents() const;
        // Return the number of pending one-time events in this scheduler.

    int numRecurringEvents() const;
        // Return the number of recurring events registered with this
        // scheduler.

    bool isInDispatcherThread() const;
        // Return 'true' if the calling thread is the dispatcher thread of this
        // scheduler, and 'false' otherwise.

                                  // Aspects

    bslma::Allocator *allocator() const;
        // Return the allocator used by this object to supply memory.
};

                      // ===============================
                      // class EventSchedulerEventHandle
                      // ===============================

class EventSchedulerEventHandle
{
    // Objects of this type refer to events in the 'EventScheduler' API.  They
    // are convertible to 'const Event*' references and may be used in any
    // method that expects them.

    // PRIVATE TYPES
    typedef EventScheduler::EventQueue EventQueue;

    // DATA
    EventQueue::PairHandle  d_handle;

    // FRIENDS
    friend class EventScheduler;

  public:
    // PUBLIC TYPES
    typedef EventScheduler::Event Event;

    // CREATORS
    EventSchedulerEventHandle();
        // Create a new handle object that does not refer to an event.

    EventSchedulerEventHandle(const EventSchedulerEventHandle& original);
        // Create a new handle object referring to the same event as the
        // specified 'rhs' handle.

    ~EventSchedulerEventHandle();
        // Destroy this object and release the managed reference, if any.

    // MANIPULATORS
    EventSchedulerEventHandle& operator=(const EventSchedulerEventHandle& rhs);
        // Release this handle's reference, if any; then make this handle refer
        // to the same event as the specified 'rhs' handle.  Return a
        // modifiable reference to this handle.

    void release();
        // Release the reference (if any) held by this object.

    // ACCESSORS
    operator const Event*() const;
        // Return a "raw" pointer to the event managed by this handle, or 0 if
        // this handle does not manage a reference.
};

                  // ========================================
                  // class EventSchedulerRecurringEventHandle
                  // ========================================

class EventSchedulerRecurringEventHandle
{
    // Objects of this type refer to recurring events in the 'EventScheduler'
    // API.  They are convertible to 'const RecurringEvent*' references and may
    // be used in any method which expects these.

    // PRIVATE TYPES
    typedef EventScheduler::RecurringEventData         RecurringEventData;
    typedef bdlcc::SkipList<bsls::Types::Int64,
                            RecurringEventData>        RecurringEventQueue;

    // DATA
    RecurringEventQueue::PairHandle  d_handle;

    // FRIENDS
    friend class EventScheduler;

  public:
    // PUBLIC TYPES
    typedef EventScheduler::RecurringEvent RecurringEvent;

    // CREATORS
    EventSchedulerRecurringEventHandle();
        // Create a new handle object.

    EventSchedulerRecurringEventHandle(
                           const EventSchedulerRecurringEventHandle& original);
        // Create a new handle object referring to the same recurring event as
        // the specified 'rhs' handle.

    ~EventSchedulerRecurringEventHandle();
        // Destroy this object and release the managed reference, if any.

    // MANIPULATORS
    EventSchedulerRecurringEventHandle& operator=(
                                const EventSchedulerRecurringEventHandle& rhs);
        // Release the reference managed by this handle, if any; then make this
        // handle refer to the same recurring event as the specified 'rhs'
        // handle.  Return a modifiable reference to this event handle.

    void release();
        // Release the reference managed by this handle, if any.

    // ACCESSORS
    operator const RecurringEvent*() const;
        // Return a "raw" pointer to the recurring event managed by this
        // handle, or 0 if this handle does not manage a reference.

};

                     // ==================================
                     // class EventSchedulerTestTimeSource
                     // ==================================

class EventSchedulerTestTimeSource {
    // This class provides a means to change the clock that is used by a given
    // event-scheduler to determine when events should be triggered.
    // Constructing a 'EventSchedulerTestTimeSource' alters the behavior of the
    // supplied event-scheduler.  After a test time-source is created, the
    // underlying scheduler will run events according to a discrete timeline,
    // whose successive values are determined by calls to 'advanceTime' on the
    // test time-source, and can be retrieved by calling 'now' on that test
    // time-source.  Note that the "system-time" held by a test time-source
    // *does* *not* correspond to the current system time.  Test writers must
    // use caution when scheduling absolute-time events so that they are
    // scheduled relative to the test time-source's value for 'now'.

  private:
    // DATA
    bsl::shared_ptr<EventSchedulerTestTimeSource_Data>
                          d_data_p;       // shared pointer to the state whose
                                          // lifetime must be as long as
                                          // '*this' and '*d_scheduler_p'

    EventScheduler       *d_scheduler_p;  // pointer to the scheduler that we
                                          // are augmenting

  public:
    // CREATORS
    explicit
    EventSchedulerTestTimeSource(EventScheduler *scheduler);
        // Create a test time-source object that will control the
        // "system-time" observed by the specified 'scheduler'.  Initialize
        // 'now' to be an arbitrary time value.  The behavior is undefined if
        // any methods have previously been called on 'scheduler'.

    // MANIPULATORS
    bsls::TimeInterval advanceTime(bsls::TimeInterval amount);
        // Advance this object's current-time value by the specified 'amount'
        // of time, notify the scheduler that the time has changed, and wait
        // for the scheduler to process the events triggered by this change in
        // time.  Return the updated current-time value.  The behavior is
        // undefined unless 'amount' is positive, and 'now + amount' is within
        // the range that can be represented with a 'bsls::TimeInterval'.

    // ACCESSORS
    bsls::TimeInterval now() const;
        // Return this object's current-time value.  Upon construction, this
        // method will return an arbitrary value.  Subsequent calls to
        // 'advanceTime' will adjust the arbitrary value forward.
};

// ============================================================================
//                            INLINE DEFINITIONS
// ============================================================================

                      // -------------------------------
                      // class EventSchedulerEventHandle
                      // -------------------------------

// CREATORS
inline
EventSchedulerEventHandle::EventSchedulerEventHandle()
{
}

inline
EventSchedulerEventHandle::EventSchedulerEventHandle(
                                     const EventSchedulerEventHandle& original)
: d_handle(original.d_handle)
{
}

inline
EventSchedulerEventHandle::~EventSchedulerEventHandle()
{
}

// MANIPULATORS
inline
EventSchedulerEventHandle&
EventSchedulerEventHandle::operator=(const EventSchedulerEventHandle& rhs)
{
    d_handle = rhs.d_handle;
    return *this;
}

inline
void EventSchedulerEventHandle::release()
{
    d_handle.release();
}
}  // close package namespace

// ACCESSORS

// The scoping of "Event" below should not be necessary, but xlc (versions 8
// and 9) requires it
inline
bdlmt::EventSchedulerEventHandle::
operator const bdlmt::EventSchedulerEventHandle::Event*() const
{
    return (const Event*)((const EventQueue::Pair*)d_handle);
}

namespace bdlmt {

                  // ----------------------------------------
                  // class EventSchedulerRecurringEventHandle
                  // ----------------------------------------

// CREATORS
inline
EventSchedulerRecurringEventHandle::EventSchedulerRecurringEventHandle()
{
}

inline
EventSchedulerRecurringEventHandle::EventSchedulerRecurringEventHandle(
                            const EventSchedulerRecurringEventHandle& original)
: d_handle(original.d_handle)
{
}

inline
EventSchedulerRecurringEventHandle::~EventSchedulerRecurringEventHandle()
{
}

// MANIPULATORS
inline
void EventSchedulerRecurringEventHandle::release()
{
    d_handle.release();
}

inline
EventSchedulerRecurringEventHandle&
EventSchedulerRecurringEventHandle::operator=(
                                 const EventSchedulerRecurringEventHandle& rhs)
{
    d_handle = rhs.d_handle;
    return *this;
}
}  // close package namespace

// ACCESSORS

// The scoping of "RecurringEvent" below should not be necessary, but xlc
// (versions 8 and 9) requires it
inline
bdlmt::EventSchedulerRecurringEventHandle::operator
       const bdlmt::EventSchedulerRecurringEventHandle::RecurringEvent*() const
{
    return (const RecurringEvent*)((const RecurringEventQueue::Pair*)d_handle);
}

namespace bdlmt {

                            // --------------------
                            // class EventScheduler
                            // --------------------

#ifdef BSLS_LIBRARYFEATURES_HAS_CPP11_BASELINE_LIBRARY
// PRIVATE CLASS METHODS
template <class CLOCK, class DURATION>
// not inline because it gets put into a bsl::function
bsls::Types::Int64 EventScheduler::timeUntilTrigger(
                       const bsl::chrono::time_point<CLOCK, DURATION>& absTime)
{
    using namespace bsl::chrono;

    auto         now = CLOCK::now();
    microseconds offset = duration_cast<microseconds>(absTime - now);
    // If the time to fire is less than one microsecond in the future, then
    // report it as 1us.
    return 0 == offset.count() && absTime > now
           ? 1
           : static_cast<bsls::Types::Int64>(offset.count());
}

template <class CLOCK, class DURATION, class REP_TYPE, class PERIOD_TYPE>
// not inline because it gets put into a bsl::function
bsls::Types::Int64 EventScheduler::timeUntilTriggerRecurring(
                const bsl::chrono::time_point<CLOCK, DURATION>&     absTime,
                const bsl::chrono::duration<REP_TYPE, PERIOD_TYPE>& interval,
                int                                                 eventIndex)
{
    BSLS_ASSERT(0 <= eventIndex);

    return timeUntilTrigger(absTime + eventIndex * interval);
}
#endif

// MANIPULATORS
inline
int EventScheduler::cancelEvent(const Event *handle)
{
    const EventQueue::Pair *itemPtr =
                       reinterpret_cast<const EventQueue::Pair*>(
                                       reinterpret_cast<const void*>(handle));

    return d_eventQueue.remove(itemPtr);
}

inline
int EventScheduler::cancelEvent(const RecurringEvent *handle)
{
    const RecurringEventQueue::Pair *itemPtr =
               reinterpret_cast<const RecurringEventQueue::Pair*>(
                                       reinterpret_cast<const void*>(handle));

    return d_recurringQueue.remove(itemPtr);
}

inline
void EventScheduler::releaseEventRaw(Event *handle)
{
    d_eventQueue.releaseReferenceRaw(reinterpret_cast<EventQueue::Pair*>(
                                            reinterpret_cast<void*>(handle)));
}

inline
void EventScheduler::releaseEventRaw(RecurringEvent *handle)
{
    d_recurringQueue.releaseReferenceRaw(
                         reinterpret_cast<RecurringEventQueue::Pair*>(
                                            reinterpret_cast<void*>(handle)));
}

#ifdef BSLS_LIBRARYFEATURES_HAS_CPP11_BASELINE_LIBRARY
template <class CLOCK, class DURATION>
int EventScheduler::rescheduleEvent(
                 const Event                                     *handle,
                 const bsl::chrono::time_point<CLOCK, DURATION>&  newEpochTime)
{
    BSLS_ASSERT(handle);

    if (bslmt::ChronoUtil::isMatchingClock<CLOCK>(d_clockType)) {
        return rescheduleEvent(handle, newEpochTime.time_since_epoch());
                                                                      // RETURN
    }

    const EventQueue::Pair *h = reinterpret_cast<const EventQueue::Pair *>(
                                       reinterpret_cast<const void *>(handle));

    bool                           isNewTop;
    bslmt::LockGuard<bslmt::Mutex> lock(&d_mutex);
    bsls::TimeInterval             offsetFromNow(newEpochTime - CLOCK::now());

    if (h) {
        h->data().d_nowOffset =
                        bdlf::BindUtil::bind(timeUntilTrigger<CLOCK, DURATION>,
                                             newEpochTime);
    }

    int ret = d_eventQueue.updateR(h,
                                   (now() + offsetFromNow).totalMicroseconds(),
                                   &isNewTop);

    if (0 == ret && isNewTop) {
        d_queueCondition.signal();
    }
    return ret;
}

template <class CLOCK, class DURATION>
int EventScheduler::rescheduleEventAndWait(
                 const Event                                     *handle,
                 const bsl::chrono::time_point<CLOCK, DURATION>&  newEpochTime)
{
    BSLS_ASSERT(handle);

    if (bslmt::ChronoUtil::isMatchingClock<CLOCK>(d_clockType)) {
        return rescheduleEventAndWait(handle, newEpochTime.time_since_epoch());
                                                                      // RETURN
    }

    int                     ret;
    const EventQueue::Pair *h =
        reinterpret_cast<const EventQueue::Pair *>(
                                       reinterpret_cast<const void *>(handle));
    {
        bool                           isNewTop;
        bslmt::LockGuard<bslmt::Mutex> lock(&d_mutex);
        bsls::TimeInterval             offsetFromNow(
                                                  newEpochTime - CLOCK::now());

        if (h) {
            h->data().d_nowOffset = bdlf::BindUtil::bind(
                                             timeUntilTrigger<CLOCK, DURATION>,
                                             newEpochTime);
        }

        ret = d_eventQueue.updateR(h,
                                   (now() + offsetFromNow).totalMicroseconds(),
                                   &isNewTop);

        if (0 == ret) {
            if (isNewTop) {
                d_queueCondition.signal();
            }
            if (d_currentEvent != h) {
                return 0;                                             // RETURN
            }
        }
    }

    // Wait until event is rescheduled or dispatched.
    bslmt::LockGuard<bslmt::Mutex> lock(&d_mutex);
    while (1) {
        if (d_currentEvent != h) {
            break;
        }
        else {
            d_dispatcherAwaited = true;
            d_iterationCondition.wait(&d_mutex);
        }
    }

    return ret;
}
#endif

inline
void EventScheduler::scheduleEvent(const bsls::TimeInterval&    epochTime,
                                   const bsl::function<void()>& callback)
{
    scheduleEvent(epochTime,
                  EventData(callback, EventScheduler::returnZero));
}

inline
void EventScheduler::scheduleEvent(EventHandle                  *event,
                                   const bsls::TimeInterval&     epochTime,
                                   const bsl::function<void()>&  callback)
{
    scheduleEvent(event, epochTime, EventData(callback, returnZero));
}

#ifdef BSLS_LIBRARYFEATURES_HAS_CPP11_BASELINE_LIBRARY
template <class CLOCK, class DURATION>
inline
void EventScheduler::scheduleEvent(
                     const bsl::chrono::time_point<CLOCK, DURATION>& epochTime,
                     const bsl::function<void()>&                    callback)
{
    if (bslmt::ChronoUtil::isMatchingClock<CLOCK>(d_clockType)) {
        scheduleEvent(epochTime.time_since_epoch(), callback);
    }
    else {
        bsls::TimeInterval offsetFromNow(epochTime - CLOCK::now());
        scheduleEvent(
            now() + offsetFromNow,
            EventData(
                callback,
                bdlf::BindUtil::bind(
                    timeUntilTrigger<CLOCK, DURATION>,
                    epochTime)
                ));
    }
}

template <class CLOCK, class DURATION>
void EventScheduler::scheduleEvent(
                    EventHandle                                     *event,
                    const bsl::chrono::time_point<CLOCK, DURATION>&  epochTime,
                    const bsl::function<void()>&                     callback)
{
    BSLS_ASSERT(event);

    if (bslmt::ChronoUtil::isMatchingClock<CLOCK>(d_clockType)) {
        scheduleEvent(event, epochTime.time_since_epoch(), callback);
    }
    else {
        bsls::TimeInterval offsetFromNow(epochTime - CLOCK::now());

        scheduleEvent(
            event,
            now() + offsetFromNow,
            EventData(
             callback,
             bdlf::BindUtil::bind(timeUntilTrigger<CLOCK, DURATION>, epochTime)
            ));
    }
}

template <class CLOCK, class DURATION>
void EventScheduler::scheduleEventRaw(
                   Event                                           **event,
                   const bsl::chrono::time_point<CLOCK, DURATION>&   epochTime,
                   const bsl::function<void()>&                      callback)
{
    BSLS_ASSERT(event);

    if (bslmt::ChronoUtil::isMatchingClock<CLOCK>(d_clockType)) {
        scheduleEventRaw(event, epochTime.time_since_epoch(), callback);
    }
    else {
        using namespace bsl::chrono;

        microseconds stime =
                     duration_cast<microseconds>(epochTime.time_since_epoch());

        bool newTop;
        d_eventQueue.addRawR((EventQueue::Pair **)event,
                             (bsls::Types::Int64) stime.count(),
                             EventData(
                                 callback,
                                 bdlf::BindUtil::bind(
                                    timeUntilTrigger<CLOCK, DURATION>,
                                    epochTime)),
                             &newTop);

        if (newTop) {
            bslmt::LockGuard<bslmt::Mutex> lock(&d_mutex);
            d_queueCondition.signal();
        }
    }
}
#endif

inline
void EventScheduler::scheduleRecurringEvent(
                                   const bsls::TimeInterval&    interval,
                                   const bsl::function<void()>& callback,
                                   const bsls::TimeInterval&    startEpochTime)
{
    // Note that when this review is converted to an assert, the following
    // assert is redundant and can be removed.
    BSLS_REVIEW(1 <= interval.totalMicroseconds());
    BSLS_ASSERT(0 != interval);

    scheduleRecurringEventRaw(0, interval, callback, startEpochTime);
}

inline
void EventScheduler::scheduleRecurringEvent(
                                  RecurringEventHandle         *event,
                                  const bsls::TimeInterval&     interval,
                                  const bsl::function<void()>&  callback,
                                  const bsls::TimeInterval&     startEpochTime)
{
    // Note that when this review is converted to an assert, the following
    // assert is redundant and can be removed.
    BSLS_REVIEW(1 <= interval.totalMicroseconds());
    BSLS_ASSERT(0 != interval);
    BSLS_ASSERT(event);

    scheduleRecurringEvent(
                      event,
                      RecurringEventData(interval, callback, returnZeroInt),
                      startEpochTime);
}

#ifdef BSLS_LIBRARYFEATURES_HAS_CPP11_BASELINE_LIBRARY
template <class CLOCK, class REP_TYPE, class PERIOD_TYPE, class DURATION>
void
EventScheduler::scheduleRecurringEvent(
            const bsl::chrono::duration<REP_TYPE, PERIOD_TYPE>& interval,
            const bsl::function<void()>&                        callback,
            const bsl::chrono::time_point<CLOCK, DURATION>&     startEpochTime)
{
    BSLS_ASSERT(bsl::chrono::microseconds(1) <= interval);

    if (bslmt::ChronoUtil::isMatchingClock<CLOCK>(d_clockType)) {
        scheduleRecurringEvent(interval,
                               callback,
                               startEpochTime.time_since_epoch());
    }
    else {
        using namespace bsl::chrono;

        bsls::TimeInterval offsetFromNow(startEpochTime - CLOCK::now());

        scheduleRecurringEventRaw(
            0,
            RecurringEventData(
                interval,
                callback,
                bdlf::BindUtil::bind(
                    timeUntilTriggerRecurring
                                      <CLOCK, DURATION, REP_TYPE, PERIOD_TYPE>,
                    startEpochTime,
                    interval,
                    bdlf::PlaceHolders::_1)),
            now() + offsetFromNow);
    }
}

template <class CLOCK, class REP_TYPE, class PERIOD_TYPE, class DURATION>
void
EventScheduler::scheduleRecurringEvent(
           RecurringEventHandle                                *event,
           const bsl::chrono::duration<REP_TYPE, PERIOD_TYPE>&  interval,
           const bsl::function<void()>&                         callback,
           const bsl::chrono::time_point<CLOCK, DURATION>&      startEpochTime)
{
    BSLS_ASSERT(event);
    BSLS_ASSERT(bsl::chrono::microseconds(1) <= interval);

    if (bslmt::ChronoUtil::isMatchingClock<CLOCK>(d_clockType)) {
        scheduleRecurringEvent(event,
                               interval,
                               callback,
                               startEpochTime.time_since_epoch());
    }
    else {
        using namespace bsl::chrono;

        bsls::TimeInterval offsetFromNow(startEpochTime - CLOCK::now());

        scheduleRecurringEvent(
            event,
            RecurringEventData(
                interval,
                callback,
                bdlf::BindUtil::bind(
                  timeUntilTriggerRecurring
                                      <CLOCK, DURATION, REP_TYPE, PERIOD_TYPE>,
                  startEpochTime,
                  interval,
                  bdlf::PlaceHolders::_1)),
            now() + offsetFromNow);
    }
}

template <class CLOCK, class REP_TYPE, class PERIOD_TYPE, class DURATION>
void
EventScheduler::scheduleRecurringEventRaw(
          RecurringEvent                                      **event,
          const bsl::chrono::duration<REP_TYPE, PERIOD_TYPE>&   interval,
          const bsl::function<void()>&                          callback,
          const bsl::chrono::time_point<CLOCK, DURATION>&       startEpochTime)
{
    BSLS_ASSERT(event);
    BSLS_ASSERT(bsl::chrono::microseconds(1) <= interval);

    if (bslmt::ChronoUtil::isMatchingClock<CLOCK>(d_clockType)) {
        scheduleRecurringEventRaw(event,
                                  interval,
                                  callback,
                                  startEpochTime.time_since_epoch());
    }
    else {
        using namespace bsl::chrono;

        bsls::TimeInterval offsetFromNow(startEpochTime - CLOCK::now());

        scheduleRecurringEventRaw(
            event,
            RecurringEventData(
                interval,
                callback,
                bdlf::BindUtil::bind(
                    timeUntilTriggerRecurring
                                      <CLOCK, DURATION, REP_TYPE, PERIOD_TYPE>,
                    startEpochTime,
                    interval,
                    bdlf::PlaceHolders::_1)),
            now() + offsetFromNow);
    }
}
#endif

// ACCESSORS
inline
EventScheduler::Event*
EventScheduler::addEventRefRaw(Event *handle) const
{
    EventQueue::Pair *h = reinterpret_cast<EventQueue::Pair*>(
                                              reinterpret_cast<void*>(handle));
    return reinterpret_cast<Event*>(d_eventQueue.addPairReferenceRaw(h));
}

inline
EventScheduler::RecurringEvent*
EventScheduler::addRecurringEventRefRaw(RecurringEvent *handle) const
{
    RecurringEventQueue::Pair *h =
                               reinterpret_cast<RecurringEventQueue::Pair*>(
                                              reinterpret_cast<void*>(handle));
    return reinterpret_cast<RecurringEvent*>(
                                     d_recurringQueue.addPairReferenceRaw(h));
}

inline
bsls::SystemClockType::Enum EventScheduler::clockType() const
{
    return d_clockType;
}

inline
bsls::TimeInterval EventScheduler::now() const
{
    return d_currentTimeFunctor();
}

inline
int EventScheduler::numEvents() const
{
    return d_eventQueue.length();
}

inline
int EventScheduler::numRecurringEvents() const
{
    return d_recurringQueue.length();
}

inline
bool EventScheduler::isInDispatcherThread() const
{
    return d_dispatcherThreadId.loadAcquire() ==
                                           bslmt::ThreadUtil::selfIdAsUint64();
}

                                  // Aspects

inline
bslma::Allocator *EventScheduler::allocator() const
{
    return d_eventQueue.allocator();
}

}  // close package namespace
}  // close enterprise namespace

#endif

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