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 TimerInterfaceAlloc (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 JobQueueInterfacequeue
 

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()

Allocators for common use.

Parameters
[in]allocLocationSource 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]intervalTimer interval.
[in]delayDelay until the timer fires the first time.
[in]toleranceMaximum tolerance of execution (used for timer coalescing).
[in]jobThe job to be executed (periodically).
[in]queueThe 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]intervalTimer interval.
[in]delayDelay until the timer fires the first time.
[in]toleranceMaximum tolerance of execution (used for timer coalescing).
[in]srcA lambda to be executed (periodically).
[in]queueThe 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]intervalTimer interval.
[in]jobA JobInterface or lambda to be executed periodically.
[in]queueThe queue, use JOBQUEUE_CURRENT for the current queue or JOBQUEUE_NONE if the job should be executed immediately.
Template Parameters
FNType 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]delayDelay until job will be enqueued.
[in]jobA JobInterface or lambda to be executed once after the specified delay.
[in]queueThe queue, use JOBQUEUE_CURRENT for the current queue or JOBQUEUE_NONE if the job should be executed immediately.
Template Parameters
FNType 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

◆ tolerance

◆ src

◆ queue