TimerInterface Class Reference

#include <timer.h>

Detailed Description

The timer interface consists of several methods for periodic events.

Public Member Functions
MAXON_FUNCTION Result< void >	Start (TimeValue interval, TimeValue delay, TimeValue tolerance, JobInterface *job, JobQueueInterface *queue)
template<typename FN >
MAXON_FUNCTION	DISABLE_IF_JOBREF (FN, Result< void >) Start(TimeValue interval
	iferr (TimerJob *job=NewObj(TimerJob, std::forward< FN >(src))) return err
return	Start (interval.GetSeconds(), delay.GetSeconds(), tolerance.GetSeconds(), *job, queue)
MAXON_METHOD void	CancelAndWait ()
MAXON_METHOD void	Cancel ()
	MAXON_OBSERVABLE (void, ObservableTimerStarted,(), ObservableCombinerRunAllComponent)
	MAXON_OBSERVABLE (void, ObservableTimerFinished,(), ObservableCombinerRunAllComponent)
	MAXON_OBSERVABLE (void, ObservableTimerOverload,(const TimeValue &duration, const TimeValue &maxDuration), ObservableCombinerRunAllComponent)
template<typename FN >
Result< TimerRef >	AddPeriodicTimer (TimeValue interval, FN &&job, JobQueueInterface *queue)
template<typename FN >
Result< TimerRef >	AddOneShotTimer (TimeValue delay, FN &&job, JobQueueInterface *queue)

Static Public Member Functions
static MAXON_METHOD TimerInterface *	Alloc (MAXON_SOURCE_LOCATION_DECLARATION)
template<typename FN >
static MAXON_FUNCTION Result< TimerRef >	AddPeriodicTimer (TimeValue interval, FN &&job, JobQueueInterface *queue)
template<typename FN >
static MAXON_FUNCTION Result< TimerRef >	AddOneShotTimer (TimeValue delay, FN &&job, JobQueueInterface *queue)

Public Attributes
MAXON_FUNCTION TimeValue	delay
MAXON_FUNCTION TimeValue TimeValue	tolerance
MAXON_FUNCTION TimeValue TimeValue FN &&	src
MAXON_FUNCTION TimeValue TimeValue FN JobQueueInterface *	queue

Private Member Functions
	MAXON_INTERFACE_NONVIRTUAL (TimerInterface, MAXON_REFERENCE_NORMAL, "net.maxon.interface.timer", MAXON_IMPLEMENTATION_MODULE("net.maxon.kernel"))

Member Function Documentation

MAXON_INTERFACE_NONVIRTUAL()

MAXON_INTERFACE_NONVIRTUAL ( TimerInterface  , MAXON_REFERENCE_NORMAL  , "net.maxon.interface.timer"  , MAXON_IMPLEMENTATION_MODULE("net.maxon.kernel")    )

private

Alloc()

static MAXON_METHOD TimerInterface* Alloc ( MAXON_SOURCE_LOCATION_DECLARATION  )

static

Allocators for common use.

Parameters

[in]

allocLocation

Source location.

Start() [1/2]

MAXON_FUNCTION Result<void> Start	(	TimeValue	interval,
		TimeValue	delay,
		TimeValue	tolerance,
		JobInterface *	job,
		JobQueueInterface *	queue
	)

Schedules a job to be called periodically at the specified interval. If the interval is 0.0 the timer is fired once after the specified delay. After a job has been started you must call CancelAndWait() and restart it to change the interval or other parameters. If you specify JOBQUEUE_NONE your job must execute very fast: It MUST NOT LOCK, MUST NOT take longer than a millisecond, preferably it should be faster than a microsecond. Specifying the main thread queue as destination is equivalent to creating a RunLoop/UI timer, but you can do this from any thread.

Parameters

[in]	interval	Timer interval.
[in]	delay	Delay until the timer fires the first time.
[in]	tolerance	Maximum tolerance of execution (used for timer coalescing).
[in]	job	The job to be executed (periodically).
[in]	queue	The queue, use JOBQUEUE_CURRENT for the current queue or JOBQUEUE_NONE if the job should be executed immediately.

Returns

OK on success.

DISABLE_IF_JOBREF()

MAXON_FUNCTION DISABLE_IF_JOBREF	(	FN	,
		Result< void >
	)

Schedules a job to be called periodically at the specified interval. If the interval is 0.0 the timer is fired once after the specified delay. After a job has been started you must call CancelAndWait() and restart it to change the interval or other parameters. If you specify JOBQUEUE_NONE your job must execute very fast: It MUST NOT LOCK, MUST NOT take longer than a millisecond, preferably it should be faster than a microsecond. Specifying the main thread queue as destination is equivalent to creating a RunLoop/UI timer, but you can do this from any thread.

Parameters

[in]	interval	Timer interval.
[in]	delay	Delay until the timer fires the first time.
[in]	tolerance	Maximum tolerance of execution (used for timer coalescing).
[in]	src	A lambda to be executed (periodically).
[in]	queue	The queue, use JOBQUEUE_CURRENT for the current queue or JOBQUEUE_NONE if the job should be executed immediately.

Returns

OK on success.

iferr()

iferr

(

TimerJob *

job = NewObj(TimerJob, std::forward< FN >(src))

)

Start() [2/2]

return Start	(	interval.	GetSeconds(),
		delay.	GetSeconds(),
		tolerance.	GetSeconds(),
		*	job,
		queue
	)

AddPeriodicTimer() [1/2]

static MAXON_FUNCTION Result<TimerRef> AddPeriodicTimer ( TimeValue  interval, FN &&  job, JobQueueInterface *  queue  )

static

Adds a job to be called periodically at the specified interval. The timer will be removed when CancelAndWait() is called. The timer will fire for the first time after the specified interval and with a default tolerance. For more options you might have to create a TimerRef directly. Please note that on Windows - and only there - you usually won't get a smaller interval and granularity than 15 milliseconds. For all other operating systems one millisecond or below is no problem, but of course this will take a lot of CPU cycles. If you have specified a queue other than JOBQUEUE_NONE and for one reason or another your job has not finished in the specified interval (e.g. because there were so many other jobs in the queue) the next call will be dropped - you won't get a sudden accumulation of calls. If you specify JOBQUEUE_NONE your job must execute very fast: It MUST NOT LOCK, MUST NOT take longer than a millisecond, preferrably it should be faster than a microsecond. Specifying the main thread queue as destination is equivalent to creating a RunLoop/UI timer, but you can do this from any thread.

Parameters

[in]	interval	Timer interval.
[in]	job	A JobInterface or lambda to be executed periodically.
[in]	queue	The queue, use JOBQUEUE_CURRENT for the current queue or JOBQUEUE_NONE if the job should be executed immediately.

Template Parameters

FN	Type of object/lambda, deduced by the compiler.

Returns

Timer reference.

AddOneShotTimer() [1/2]

static MAXON_FUNCTION Result<TimerRef> AddOneShotTimer ( TimeValue  delay, FN &&  job, JobQueueInterface *  queue  )

static

Adds a job to be called once after the specified delay. The timer will be removed after it has fired once or when CancelAndWait() is called. Please note that on Windows - and only there - you usually will have a granularity of about 15 milliseconds. For all other operating systems the granularity is usually one millisecond or lower (high CPU load might lead to deferred timers nonetheless). If you have specified a queue other than JOBQUEUE_NONE and for one reason or another your job has not finished in the specified interval (e.g. because there were so many other jobs in the queue) the next call will be dropped - you won't get a sudden accumulation of calls. If you specify JOBQUEUE_NONE your job must execute very fast: It MUST NOT LOCK, MUST NOT take longer than a millisecond, preferrably it should be faster than a microsecond. Specifying the main thread queue as destination is equivalent to creating a RunLoop/UI timer, but you can do this from any thread.

Parameters

[in]	delay	Delay until job will be enqueued.
[in]	job	A JobInterface or lambda to be executed once after the specified delay.
[in]	queue	The queue, use JOBQUEUE_CURRENT for the current queue or JOBQUEUE_NONE if the job should be executed immediately.

Template Parameters

FN	Type of object/lambda, deduced by the compiler.

Returns

Timer reference.

CancelAndWait()

MAXON_METHOD void CancelAndWait

(

)

Cancels a timer and if necessary waits until a currently pending timer job has finished. Does nothing if no timer was started. Don't call CancelAndWait() from inside a timer job because it cant't wait - use Cancel().

Cancel()

MAXON_METHOD void Cancel

(

)

Cancels a timer. Might have to wait for a currently pending timer job. Can be called from within the timer job.

MAXON_OBSERVABLE() [1/3]

MAXON_OBSERVABLE	(	void	,
		ObservableTimerStarted	,
		()	,
		ObservableCombinerRunAllComponent
	)

Notifies the observers that the timer has started.

MAXON_OBSERVABLE() [2/3]

MAXON_OBSERVABLE	(	void	,
		ObservableTimerFinished	,
		()	,
		ObservableCombinerRunAllComponent
	)

Notifies the observers that the timer has finished.

MAXON_OBSERVABLE() [3/3]

MAXON_OBSERVABLE	(	void	,
		ObservableTimerOverload	,
		(const TimeValue &duration, const TimeValue &maxDuration)	,
		ObservableCombinerRunAllComponent
	)

Notifies the observers that the timer job took longer than the specified interval. param[in] duration The duration spend in the observable. param[in] maxDuration Maximum time that was suggested.

AddPeriodicTimer() [2/2]

Result<TimerRef> AddPeriodicTimer	(	TimeValue	interval,
		FN &&	job,
		JobQueueInterface *	queue
	)

AddOneShotTimer() [2/2]

Result<TimerRef> AddOneShotTimer	(	TimeValue	delay,
		FN &&	job,
		JobQueueInterface *	queue
	)

Member Data Documentation

delay

MAXON_FUNCTION TimeValue delay

tolerance

MAXON_FUNCTION TimeValue TimeValue tolerance

src

MAXON_FUNCTION TimeValue TimeValue FN&& src

queue

MAXON_FUNCTION TimeValue TimeValue FN JobQueueInterface* queue