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

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.

== Synopsis

Declared in `<bdlmt_eventscheduler.h>`

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

== Types

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bdlmt/EventScheduler/Event.adoc[`Event`] 
| Opaque structure identifying a non‐recurring event; pointers are populated by the "Raw" API of `EventScheduler`.
| xref:BloombergLP/bdlmt/EventScheduler/RecurringEvent.adoc[`RecurringEvent`] 
| Opaque structure identifying a recurring event; pointers are populated by the "Raw" API of `EventScheduler`.
|===


== Type Aliases

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bdlmt/EventScheduler/Dispatcher.adoc[`Dispatcher`] 
| Defines a type alias for the dispatcher functor type.
| xref:BloombergLP/bdlmt/EventScheduler/EventHandle.adoc[`EventHandle`] 
| Defines a type alias for a handle managing a non‐recurring event.
| xref:BloombergLP/bdlmt/EventScheduler/RecurringEventHandle.adoc[`RecurringEventHandle`] 
| Defines a type alias for a handle managing a recurring event.
|===


== Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bdlmt/EventScheduler/2constructor-05e.adoc[`EventScheduler`]         [.small]#[constructor]#
| Constructors
| xref:BloombergLP/bdlmt/EventScheduler/2destructor.adoc[`~EventScheduler`] [.small]#[destructor]#
| Discard all unprocessed events and destroy this object. The behavior is undefined unless the scheduler is stopped.
| xref:BloombergLP/bdlmt/EventScheduler/addEventRefRaw.adoc[`addEventRefRaw`] 
| 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.
| xref:BloombergLP/bdlmt/EventScheduler/addRecurringEventRefRaw.adoc[`addRecurringEventRefRaw`] 
| 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.
| xref:BloombergLP/bdlmt/EventScheduler/allocator.adoc[`allocator`] 
| Return the allocator used by this object to supply memory.
| xref:BloombergLP/bdlmt/EventScheduler/cancelAllEvents.adoc[`cancelAllEvents`] 
| Cancel all recurring and one‐time events scheduled in this EventScheduler.
| xref:BloombergLP/bdlmt/EventScheduler/cancelAllEventsAndWait.adoc[`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.
| xref:BloombergLP/bdlmt/EventScheduler/cancelEvent-01.adoc[`cancelEvent`] 
| `cancelEvent` overloads
| xref:BloombergLP/bdlmt/EventScheduler/cancelEventAndWait-05.adoc[`cancelEventAndWait`] 
| `cancelEventAndWait` overloads
| xref:BloombergLP/bdlmt/EventScheduler/clockType.adoc[`clockType`] 
| Return the value of the clock type that this object was created with.
| xref:BloombergLP/bdlmt/EventScheduler/isInDispatcherThread.adoc[`isInDispatcherThread`] 
| Return `true` if the calling thread is the dispatcher thread of this scheduler, and `false` otherwise.
| xref:BloombergLP/bdlmt/EventScheduler/isStarted.adoc[`isStarted`] 
| Return `true` if a call to `start` has finished successfully more recently than any call to `stop`, and `false` otherwise.
| xref:BloombergLP/bdlmt/EventScheduler/nextPendingEventTime.adoc[`nextPendingEventTime`] 
| Return the earliest scheduled starting time of the pending events and recurring events registered with this scheduler. If there are no pending events or recurring events, return `INT64_MAX` microseconds.
| xref:BloombergLP/bdlmt/EventScheduler/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 {Supported Clock Types} in the component documentation).
| xref:BloombergLP/bdlmt/EventScheduler/numEvents.adoc[`numEvents`] 
| Return the number of pending one‐time events in this scheduler.
| xref:BloombergLP/bdlmt/EventScheduler/numRecurringEvents.adoc[`numRecurringEvents`] 
| Return the number of recurring events registered with this scheduler.
| xref:BloombergLP/bdlmt/EventScheduler/releaseEventRaw-0e.adoc[`releaseEventRaw`] 
| `releaseEventRaw` overloads
| xref:BloombergLP/bdlmt/EventScheduler/rescheduleEvent-00.adoc[`rescheduleEvent`] 
| `rescheduleEvent` overloads
| xref:BloombergLP/bdlmt/EventScheduler/rescheduleEventAndWait-0f.adoc[`rescheduleEventAndWait`] 
| `rescheduleEventAndWait` overloads
| xref:BloombergLP/bdlmt/EventScheduler/scheduleEvent-052.adoc[`scheduleEvent`] 
| `scheduleEvent` overloads
| xref:BloombergLP/bdlmt/EventScheduler/scheduleEventRaw-04.adoc[`scheduleEventRaw`] 
| `scheduleEventRaw` overloads
| xref:BloombergLP/bdlmt/EventScheduler/scheduleRecurringEvent-09.adoc[`scheduleRecurringEvent`] 
| `scheduleRecurringEvent` overloads
| xref:BloombergLP/bdlmt/EventScheduler/scheduleRecurringEventRaw-06.adoc[`scheduleRecurringEventRaw`] 
| `scheduleRecurringEventRaw` overloads
| xref:BloombergLP/bdlmt/EventScheduler/scheduledEventTime-00.adoc[`scheduledEventTime`] 
| Return the scheduled starting time of the event having the specified `handle`. If the `handle` is invalid, _or_ the event has already been canceled, return an optional without a value.
| xref:BloombergLP/bdlmt/EventScheduler/start-07.adoc[`start`] 
| `start` overloads
| xref:BloombergLP/bdlmt/EventScheduler/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/EventScheduler/2conversion.adoc[`operator BloombergLP::bslmf::NestedTraitDeclaration<EventScheduler, UsesBslmaAllocator>`] 
| Declare that this type uses a `bslma` allocator.
|===


== Friends

[cols="1,4"]
|===
| Name| Description
| `xref:BloombergLP/bdlmt/EventSchedulerTestTimeSource.adoc[BloombergLP::bdlmt::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`.
| `xref:BloombergLP/bdlmt/EventSchedulerRecurringEventHandle.adoc[BloombergLP::bdlmt::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.
| `xref:BloombergLP/bdlmt/EventSchedulerEventHandle.adoc[BloombergLP::bdlmt::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.
|===


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