#include <bdlmt_timereventscheduler.h>

Classes
struct	ClockData
Public Types
enum	{ e_INVALID_HANDLE = -1, BCEP_INVALID_HANDLE = e_INVALID_HANDLE, INVALID_HANDLE = e_INVALID_HANDLE }
typedef int	Handle
typedef bsl::function< void(const bsl::function< void()> &)>	Dispatcher
typedef bdlcc::TimeQueue < bsl::function< void()> >::Key	EventKey
Public Member Functions
	BSLMF_NESTED_TRAIT_DECLARATION (TimerEventScheduler, bslma::UsesBslmaAllocator)
	TimerEventScheduler (bslma::Allocator *basicAllocator=0)
	TimerEventScheduler (bsls::SystemClockType::Enum clockType, bslma::Allocator *basicAllocator=0)
	TimerEventScheduler (const Dispatcher &dispatcherFunctor, bslma::Allocator *basicAllocator=0)
	TimerEventScheduler (const Dispatcher &dispatcherFunctor, bsls::SystemClockType::Enum clockType, bslma::Allocator *basicAllocator=0)
	TimerEventScheduler (int numEvents, int numClocks, bslma::Allocator *basicAllocator=0)
	TimerEventScheduler (int numEvents, int numClocks, bsls::SystemClockType::Enum clockType, bslma::Allocator *basicAllocator=0)
	TimerEventScheduler (int numEvents, int numClocks, const Dispatcher &dispatcherFunctor, bslma::Allocator *basicAllocator=0)
	TimerEventScheduler (int numEvents, int numClocks, const Dispatcher &dispatcherFunctor, bsls::SystemClockType::Enum clockType, bslma::Allocator *basicAllocator=0)
	~TimerEventScheduler ()
int	start ()
int	start (const bslmt::ThreadAttributes &threadAttributes)
void	stop ()
Handle	scheduleEvent (const bsls::TimeInterval &time, const bsl::function< void()> &callback, const EventKey &key=EventKey(0))
int	rescheduleEvent (Handle handle, const bsls::TimeInterval &newTime, bool wait=false)
int	rescheduleEvent (Handle handle, const EventKey &key, const bsls::TimeInterval &newTime, bool wait=false)
int	cancelEvent (Handle handle, bool wait=false)
int	cancelEvent (Handle handle, const EventKey &key, bool wait=false)
void	cancelAllEvents (bool wait=false)
Handle	startClock (const bsls::TimeInterval &interval, const bsl::function< void()> &callback, const bsls::TimeInterval &startTime=bsls::TimeInterval(0))
int	cancelClock (Handle handle, bool wait=false)
void	cancelAllClocks (bool wait=false)
bsls::SystemClockType::Enum	clockType () const
bsls::TimeInterval	now () const
int	numClocks () const
int	numEvents () const
Friends
struct	TimerEventSchedulerDispatcher
class	TimerEventSchedulerTestTimeSource

Detailed Description

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.

See Component bdlmt_timereventscheduler

Member Typedef Documentation

typedef int bdlmt::TimerEventScheduler::Handle

typedef bsl::function<void(const bsl::function<void()>&)> bdlmt::TimerEventScheduler::Dispatcher

Defines a type alias for the dispatcher functor type.

typedef bdlcc::TimeQueue<bsl::function<void()> >::Key bdlmt::TimerEventScheduler::EventKey

Defines a type alias for a user-supplied key for identifying events.

Member Enumeration Documentation

anonymous enum

Enumerator:

e_INVALID_HANDLE	value of an invalid event or clock handle
BCEP_INVALID_HANDLE
INVALID_HANDLE

Constructor & Destructor Documentation

bdlmt::TimerEventScheduler::TimerEventScheduler ( bslma::Allocator * basicAllocator = 0 ) [explicit]

Construct an event scheduler using the default dispatcher functor (see the "The dispatcher thread and the dispatcher functor" section in component-level doc) and use the realtime clock epoch 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. Note that the maximal number of scheduled non-recurring events and recurring events defaults to an implementation defined constant.

bdlmt::TimerEventScheduler::TimerEventScheduler	(	bsls::SystemClockType::Enum	clockType,
		bslma::Allocator *	basicAllocator = `0`
	)			`[explicit]`

Construct an event scheduler using the default dispatcher functor (see the "The dispatcher thread and the dispatcher functor" section in component-level doc) and use 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. Note that the maximal number of scheduled non-recurring events and recurring events defaults to an implementation defined constant.

bdlmt::TimerEventScheduler::TimerEventScheduler	(	const Dispatcher &	dispatcherFunctor,
		bslma::Allocator *	basicAllocator = `0`
	)			`[explicit]`

Construct an event scheduler using the specified dispatcherFunctor (see "The dispatcher thread and the dispatcher functor" section in component-level doc) and use the realtime clock epoch 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. Note that the maximal number of scheduled non-recurring events and recurring events defaults to an implementation defined constant.

bdlmt::TimerEventScheduler::TimerEventScheduler	(	const Dispatcher &	dispatcherFunctor,
		bsls::SystemClockType::Enum	clockType,
		bslma::Allocator *	basicAllocator = `0`
	)			`[explicit]`

Construct an event scheduler using the specified dispatcherFunctor (see "The dispatcher thread and the dispatcher functor" section in component-level doc) and use 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. Note that the maximal number of scheduled non-recurring events and recurring events defaults to an implementation defined constant.

bdlmt::TimerEventScheduler::TimerEventScheduler	(	int	numEvents,
		int	numClocks,
		bslma::Allocator *	basicAllocator = `0`
	)

Construct a timer event scheduler using the default dispatcher functor (see the "The dispatcher thread and the dispatcher functor" section in component level doc) that has the capability to concurrently schedule at least the specified numEvents and numClocks and use the realtime clock epoch 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. The behavior is undefined unless 0 <= numEvents < 2**24 and 0 <= numClocks < 2**24.

bdlmt::TimerEventScheduler::TimerEventScheduler	(	int	numEvents,
		int	numClocks,
		bsls::SystemClockType::Enum	clockType,
		bslma::Allocator *	basicAllocator = `0`
	)

Construct a timer event scheduler using the default dispatcher functor (see the "The dispatcher thread and the dispatcher functor" section in component level doc) that has the capability to concurrently schedule at least the specified numEvents and numClocks and use 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. The behavior is undefined unless 0 <= numEvents < 2**24 and 0 <= numClocks < 2**24.

bdlmt::TimerEventScheduler::TimerEventScheduler	(	int	numEvents,
		int	numClocks,
		const Dispatcher &	dispatcherFunctor,
		bslma::Allocator *	basicAllocator = `0`
	)

Construct a timer event scheduler using the specified dispatcherFunctor (see "The dispatcher thread and the dispatcher functor" section in component level doc) that has the capability to concurrently schedule at least the specified numEvents and numClocks and use the realtime clock epoch 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. The behavior is undefined unless 0 <= numEvents < 2**24 and 0 <= numClocks < 2**24.

bdlmt::TimerEventScheduler::TimerEventScheduler	(	int	numEvents,
		int	numClocks,
		const Dispatcher &	dispatcherFunctor,
		bsls::SystemClockType::Enum	clockType,
		bslma::Allocator *	basicAllocator = `0`
	)

Construct a timer event scheduler using the specified dispatcherFunctor (see "The dispatcher thread and the dispatcher functor" section in component level doc) that has the capability to concurrently schedule at least the specified numEvents and numClocks and use 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. The behavior is undefined unless 0 <= numEvents < 2**24 and 0 <= numClocks < 2**24.

bdlmt::TimerEventScheduler::~TimerEventScheduler ( )

Stop this scheduler, discard all the unprocessed events and destroy this object.

Member Function Documentation

bdlmt::TimerEventScheduler::BSLMF_NESTED_TRAIT_DECLARATION	(	TimerEventScheduler	,
		bslma::UsesBslmaAllocator
	)

int bdlmt::TimerEventScheduler::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 bdlmt::TimerEventScheduler::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 bdlmt::TimerEventScheduler::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.

Handle bdlmt::TimerEventScheduler::scheduleEvent	(	const bsls::TimeInterval &	time,
		const bsl::function< void()> &	callback,
		const EventKey &	key = `EventKey(0)`
	)

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 Supported Clock-Types in the component documentation).

int bdlmt::TimerEventScheduler::rescheduleEvent	(	Handle	handle,
		const bsls::TimeInterval &	newTime,
		bool	wait = `false`
	)

int bdlmt::TimerEventScheduler::rescheduleEvent	(	Handle	handle,
		const EventKey &	key,
		const bsls::TimeInterval &	newTime,
		bool	wait = `false`
	)

Reschedule the event having the specified handle at the specified newTime. Optionally use the specified key to uniquely identify the event. If the optionally specified wait is true, then ensure that the event having the 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 the handle is invalid or if the event has already been dispatched or if the event has not yet been dispatched but will soon be dispatched. If this method is being invoked from the dispatcher thread then the wait is ignored to avoid deadlock. The newTime is an absolute time represented as an interval from some epoch, which is detemined by the clock indicated at construction (see Supported Clock-Types in the component documentation).

int bdlmt::TimerEventScheduler::cancelEvent	(	Handle	handle,
		bool	wait = `false`
	)

int bdlmt::TimerEventScheduler::cancelEvent	(	Handle	handle,
		const EventKey &	key,
		bool	wait = `false`
	)

Cancel the event having the specified handle. Optionally use the specified key to uniquely identify the event. If the optionally specified wait is true, then ensure that the dispatcher thread has resumed execution before returning. Return 0 on successful cancellation, and a non-zero value if the handle is invalid or if it is too late to cancel the event. If this method is being invoked from the dispatcher thread then the wait is ignored to avoid deadlock.

void bdlmt::TimerEventScheduler::cancelAllEvents ( bool wait = false )

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.

Handle bdlmt::TimerEventScheduler::startClock	(	const bsls::TimeInterval &	interval,
		const bsl::function< void()> &	callback,
		const bsls::TimeInterval &	startTime = `bsls::TimeInterval(0)`
	)

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 Supported Clock-Types in the component documentation).

int bdlmt::TimerEventScheduler::cancelClock	(	Handle	handle,
		bool	wait = `false`
	)

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.

void bdlmt::TimerEventScheduler::cancelAllClocks ( bool wait = false )

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.

bsls::SystemClockType::Enum bdlmt::TimerEventScheduler::clockType ( ) const

Return the value of the clock type that this object was created with.

bsls::TimeInterval bdlmt::TimerEventScheduler::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 bdlmt::TimerEventScheduler::numClocks ( ) const

Return a snapshot of the number of registered clocks with this scheduler.

int bdlmt::TimerEventScheduler::numEvents ( ) const

Return a snapshot of the number of pending events and events being dispatched in this scheduler.

Friends And Related Function Documentation

friend struct TimerEventSchedulerDispatcher [friend]

friend class TimerEventSchedulerTestTimeSource [friend]

The documentation for this class was generated from the following file:

bdlmt_timereventscheduler.h

bdlmt::TimerEventScheduler Class Reference

Classes

Public Types