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

This class provides a thread&hyphen;safe event scheduler&period; `scheduleEvent` schedules a non&hyphen;recurring event, returning a handle of type `TimerEventScheduler&colon;&colon;Handle`, which can be used to cancel the scheduled event by invoking `cancelEvent`&period; Similarly, `startClock` schedules a recurring event, returning a handle of type `TimerEventScheduler&colon;&colon;Handle`, which can be used to cancel the clock by invoking `cancelClock`&period; `cancelAllEvents` cancels all the registered events and `cancelAllClocks` cancels all the registered clocks&period; The callbacks are processed by a separate thread (called dispatcher thread)&period; 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 &quot;The dispatcher thread and the dispatcher functor&quot;)&period; `start` must be invoked to start dispatching the callbacks&period; `stop` stops the dispatching of the callbacks without removing the pending events&period;

== Synopsis

Declared in `&lt;bdlmt&lowbar;timereventscheduler&period;h&gt;`

[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&period;
| xref:BloombergLP/bdlmt/TimerEventScheduler/EventKey.adoc[`EventKey`] 
| Defines a type alias for a user&hyphen;supplied key for identifying events&period;
| xref:BloombergLP/bdlmt/TimerEventScheduler/Handle.adoc[`Handle`] 
| Defines a type alias for a handle that identifies a scheduled clock or event&period;
|===


== Enums

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


== Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bdlmt/TimerEventScheduler/2constructor-0e02.adoc[`TimerEventScheduler`]         [.small]#[constructor]#
| Constructors
| xref:BloombergLP/bdlmt/TimerEventScheduler/2destructor.adoc[`&#126;TimerEventScheduler`] [.small]#[destructor]#
| Stop this scheduler, discard all the unprocessed events and destroy this object&period;
| xref:BloombergLP/bdlmt/TimerEventScheduler/cancelAllClocks.adoc[`cancelAllClocks`] 
| Cancel all clocks&period; 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&period; If this method is being invoked from the dispatcher thread, then the `wait` is ignored to avoid deadlock&period;
| xref:BloombergLP/bdlmt/TimerEventScheduler/cancelAllEvents.adoc[`cancelAllEvents`] 
| Cancel all the events&period; 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&period; If this method is being invoked from the dispatcher thread then the `wait` is ignored to avoid deadlock&period;
| xref:BloombergLP/bdlmt/TimerEventScheduler/cancelClock.adoc[`cancelClock`] 
| Cancel the clock having the specified `handle`&period; 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&period; Return 0 on success, and a non&hyphen;zero value if the `handle` is invalid&period; If this method is being invoked from the dispatcher thread, then the `wait` is ignored to avoid deadlock&period;
| 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&period;
| xref:BloombergLP/bdlmt/TimerEventScheduler/nextPendingEventTime.adoc[`nextPendingEventTime`] 
| Return the earliest scheduled starting time of the pending events and clocks registered with this scheduler&period; If there are no pending events or clocks, return `INT64&lowbar;MAX` microseconds&period;
| 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 &lsqb;&rsqb;Clock&hyphen;Types))&period;
| xref:BloombergLP/bdlmt/TimerEventScheduler/numClocks.adoc[`numClocks`] 
| Return a _snapshot_ of the number of registered clocks with this scheduler&period;
| xref:BloombergLP/bdlmt/TimerEventScheduler/numEvents.adoc[`numEvents`] 
| Return a _snapshot_ of the number of pending events and events being dispatched in this scheduler&period;
| 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`&period; On success, return a handle that can be used to cancel the `callback` (by invoking `cancelEvent`), or return `e&lowbar;INVALID&lowbar;HANDLE` if scheduling this event would exceed the maximum number of scheduled events for this object (see constructor)&period; Optionally specify `key` to uniquely identify the event&period; The `time` is an absolute time represented as an interval from some epoch, which is detemined by the clock indicated at construction (see &lsqb;&rsqb;Clock&hyphen;Types))&period;
| 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`&period; On success, return a handle that can be use to cancel the clock (by invoking `cancelClock`), or return `e&lowbar;INVALID&lowbar;HANDLE` if scheduling this event would exceed the maximum number of scheduled events for this object (see constructor)&period; If no start time is specified, it is assumed to be the `interval` time from now&period; The `startTime` is an absolute time represented as an interval from some epoch, which is detemined by the clock indicated at construction (see &lsqb;&rsqb;Clock&hyphen;Types))&period;
| 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&period; If the scheduler is already stopped then this method has no effect&period; This scheduler can be restarted by invoking `start`&period; The behavior is undefined if this method is invoked from the dispatcher thread&period;
| xref:BloombergLP/bdlmt/TimerEventScheduler/2conversion.adoc[`operator BloombergLP::bslmf::NestedTraitDeclaration&lt;TimerEventScheduler, UsesBslmaAllocator&gt;`] 
| Declare that this type uses a `bslma` allocator&period;
|===


== 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&hyphen;scheduler to determine when events should be triggered&period; Constructing a `TimerEventSchedulerTestTimeSource` alters the behavior of the supplied event&hyphen;scheduler&period; After a test time&hyphen;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&hyphen;source, and can be retrieved by calling `now` on that test time&hyphen;source&period; Note that the &quot;system&hyphen;time&quot; held by a test time&hyphen;source _does_ _not_ correspond to the current system time&period; Test writers must use caution when scheduling absolute&hyphen;time events so that they are scheduled relative to the test time&hyphen;source&apos;s value for `now`&period;
| `xref:BloombergLP/bdlmt/TimerEventSchedulerDispatcher.adoc[BloombergLP::bdlmt::TimerEventSchedulerDispatcher]`
| Dispatcher functor type for `TimerEventScheduler`&period;
|===


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