[#BloombergLP-bdlmt-TimerEventScheduler]
= xref:BloombergLP.adoc[BloombergLP]::xref:BloombergLP/bdlmt.adoc[bdlmt]::TimerEventScheduler
:relfileprefix: ../../
:mrdocs:

This class provides a thread‐safe event scheduler. `scheduleEvent` schedules a non‐recurring event, returning a handle of type `TimerEventScheduler::Handle`, which can be used to cancel the scheduled event by invoking `cancelEvent`. Similarly, `startClock` schedules a recurring event, returning a handle of type `TimerEventScheduler::Handle`, which can be used to cancel the clock by invoking `cancelClock`. `cancelAllEvents` cancels all the registered events and `cancelAllClocks` cancels all the registered clocks. The callbacks are processed by a separate thread (called dispatcher thread). By default the callbacks are executed in the dispatcher thread, but this behavior can be altered by providing a dispatcher functor at the creation time (see the section "The dispatcher thread and the dispatcher functor"). `start` must be invoked to start dispatching the callbacks. `stop` stops the dispatching of the callbacks without removing the pending events.

== Synopsis

Declared in `<bdlmt_timereventscheduler.h>`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
class TimerEventScheduler;
----

== Type Aliases

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bdlmt/TimerEventScheduler/Dispatcher.adoc[`Dispatcher`] 
| Defines a type alias for the dispatcher functor type.
| xref:BloombergLP/bdlmt/TimerEventScheduler/EventKey.adoc[`EventKey`] 
| Defines a type alias for a user‐supplied key for identifying events.
| xref:BloombergLP/bdlmt/TimerEventScheduler/Handle.adoc[`Handle`] 
| Defines a type alias for a handle that identifies a scheduled clock or event.
|===


== Enums

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bdlmt/TimerEventScheduler/_04enum.adoc[`Unnamed enum`] 
| Invalid handle constants.
|===


== Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bdlmt/TimerEventScheduler/2constructor-0e02.adoc[`TimerEventScheduler`]         [.small]#[constructor]#
| Constructors
| xref:BloombergLP/bdlmt/TimerEventScheduler/2destructor.adoc[`~TimerEventScheduler`] [.small]#[destructor]#
| Stop this scheduler, discard all the unprocessed events and destroy this object.
| xref:BloombergLP/bdlmt/TimerEventScheduler/cancelAllClocks.adoc[`cancelAllClocks`] 
| Cancel all clocks. If the optionally specified `wait` is true, then ensure that any clock event still in this scheduler is either cancelled or has been dispatched before this call returns. If this method is being invoked from the dispatcher thread, then the `wait` is ignored to avoid deadlock.
| xref:BloombergLP/bdlmt/TimerEventScheduler/cancelAllEvents.adoc[`cancelAllEvents`] 
| Cancel all the events. If the optionally specified `wait` is true, then ensure any event still in this scheduler is either cancelled or has been dispatched before this call returns. If this method is being invoked from the dispatcher thread then the `wait` is ignored to avoid deadlock.
| xref:BloombergLP/bdlmt/TimerEventScheduler/cancelClock.adoc[`cancelClock`] 
| Cancel the clock having the specified `handle`. If the optionally specified `wait` is true, then ensure that any scheduled event for the clock having `handle` is either cancelled or has been dispatched before this call returns. Return 0 on success, and a non‐zero value if the `handle` is invalid. If this method is being invoked from the dispatcher thread, then the `wait` is ignored to avoid deadlock.
| xref:BloombergLP/bdlmt/TimerEventScheduler/cancelEvent-0b.adoc[`cancelEvent`] 
| `cancelEvent` overloads
| xref:BloombergLP/bdlmt/TimerEventScheduler/clockType.adoc[`clockType`] 
| Return the value of the clock type that this object was created with.
| xref:BloombergLP/bdlmt/TimerEventScheduler/nextPendingEventTime.adoc[`nextPendingEventTime`] 
| Return the earliest scheduled starting time of the pending events and clocks registered with this scheduler. If there are no pending events or clocks, return `INT64_MAX` microseconds.
| xref:BloombergLP/bdlmt/TimerEventScheduler/now.adoc[`now`] 
| 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 []Clock‐Types)).
| xref:BloombergLP/bdlmt/TimerEventScheduler/numClocks.adoc[`numClocks`] 
| Return a _snapshot_ of the number of registered clocks with this scheduler.
| xref:BloombergLP/bdlmt/TimerEventScheduler/numEvents.adoc[`numEvents`] 
| Return a _snapshot_ of the number of pending events and events being dispatched in this scheduler.
| xref:BloombergLP/bdlmt/TimerEventScheduler/rescheduleEvent-06.adoc[`rescheduleEvent`] 
| `rescheduleEvent` overloads
| xref:BloombergLP/bdlmt/TimerEventScheduler/scheduleEvent.adoc[`scheduleEvent`] 
| Schedule the specified `callback` to be dispatched at the specified `time`. On success, return a handle that can be used to cancel the `callback` (by invoking `cancelEvent`), or return `e_INVALID_HANDLE` if scheduling this event would exceed the maximum number of scheduled events for this object (see constructor). Optionally specify `key` to uniquely identify the event. The `time` is an absolute time represented as an interval from some epoch, which is detemined by the clock indicated at construction (see []Clock‐Types)).
| xref:BloombergLP/bdlmt/TimerEventScheduler/start-0d.adoc[`start`] 
| `start` overloads
| xref:BloombergLP/bdlmt/TimerEventScheduler/startClock.adoc[`startClock`] 
| Schedule a recurring event that invokes the specified `callback` at every specified `interval`, starting at the optionally specified `startTime`. On success, return a handle that can be use to cancel the clock (by invoking `cancelClock`), or return `e_INVALID_HANDLE` if scheduling this event would exceed the maximum number of scheduled events for this object (see constructor). If no start time is specified, it is assumed to be the `interval` time from now. The `startTime` is an absolute time represented as an interval from some epoch, which is detemined by the clock indicated at construction (see []Clock‐Types)).
| xref:BloombergLP/bdlmt/TimerEventScheduler/stop.adoc[`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.
| xref:BloombergLP/bdlmt/TimerEventScheduler/2conversion.adoc[`operator BloombergLP::bslmf::NestedTraitDeclaration<TimerEventScheduler, UsesBslmaAllocator>`] 
| Declare that this type uses a `bslma` allocator.
|===


== Friends

[cols="1,4"]
|===
| Name| Description
| `xref:BloombergLP/bdlmt/TimerEventSchedulerTestTimeSource.adoc[BloombergLP::bdlmt::TimerEventSchedulerTestTimeSource]`
| 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 `TimerEventSchedulerTestTimeSource` 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`.
| `xref:BloombergLP/bdlmt/TimerEventSchedulerDispatcher.adoc[BloombergLP::bdlmt::TimerEventSchedulerDispatcher]`
| Dispatcher functor type for `TimerEventScheduler`.
|===


[.small]#Created with https://www.mrdocs.com[MrDocs]#