Provide a thread-safe recurring and one-time event scheduler.
More...
Namespaces |
namespace | bdlmt |
Detailed Description
- Outline
-
-
- Purpose:
- Provide a thread-safe recurring and one-time event scheduler.
-
- Classes:
-
- See also:
- Component 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: where time
is a time_point
, t_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 t_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. We allow the scheduler to run for a short time while changing this value and observe that the callback is executed: 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{
public:
int processData(void *data, int length);
};
class my_Server {
struct Connection {
bdlmt::EventSchedulerEventHandle d_timerId;
my_Session *d_session_p;
};
bsl::vector<Connection*> d_connections;
bdlmt::EventScheduler d_scheduler;
bsls::TimeInterval d_ioTimeout;
void newConnection(Connection *connection);
void closeConnection(Connection *connection);
void dataAvailable(Connection *connection, void *data, int length);
public:
my_Server(const bsls::TimeInterval& ioTimeout,
bslma::Allocator *allocator = 0);
~my_Server();
};
my_Server::my_Server(const bsls::TimeInterval& ioTimeout,
bslma::Allocator *alloc)
: d_connections(alloc)
, d_scheduler(bsls::SystemClockType::e_MONOTONIC, alloc)
, d_ioTimeout(ioTimeout)
{
d_scheduler.start();
}
my_Server::~my_Server()
{
d_scheduler.stop();
}
void my_Server::newConnection(my_Server::Connection *connection)
{
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)
{
}
void my_Server::dataAvailable(my_Server::Connection *connection,
void *data,
int length)
{
if (d_scheduler.cancelEvent(connection->d_timerId)) {
return;
}
connection->d_session_p->processData(data, length);
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:
-
- Note that this feature should be used only for testing purposes, never in production code.