Timer

Detailed Description

Defines the methods for the timer interface.

Typedefs
typedef struct dwTimerObject const *	dwConstTimerHandle_t
	Handle represents a const Timer object. More...
typedef struct dwTimeSourceObject const *	dwConstTimeSourceHandle_t
	Handle represents a const TimeSource object. More...
typedef struct dwTimerObject *	dwTimerHandle_t
	Handle represents a Timer object. More...
typedef void(*	dwTimerWork) (void *ptr)
	dwTimerWork is a timer schedule task callback function, input void* ptr passes the extra data to the task More...
typedef struct dwTimeSourceObject *	dwTimeSourceHandle_t
	Handle represents a TimeSource object. More...

Functions
DW_API_PUBLIC dwStatus	dwTimer_cancelAsync (dwTimerHandle_t const timer)
	Asynchronously cancels all scheduled work associated with this timer. More...
DW_API_PUBLIC dwStatus	dwTimer_cancelSync (dwTimerHandle_t const timer)
	Synchronously cancels all scheduled work associated with this timer. More...
DW_API_PUBLIC dwStatus	dwTimer_initializeFromSource (dwTimerHandle_t *const timer, char8_t const *const timerName, dwTimeSourceHandle_t const source)
	Creates a new DW timer. More...
DW_API_PUBLIC dwStatus	dwTimer_release (dwTimerHandle_t const timer)
	Release the timer instance. More...
DW_API_PUBLIC dwStatus	dwTimer_scheduleTaskOneShot (dwTimerWork const task, void *const clientData, dwTime_t const startTime, dwTimerHandle_t const timer)
	Scheduled a task to be run at a future time (non-recurring) More...
DW_API_PUBLIC dwStatus	dwTimer_scheduleTaskRecurring (dwTimerWork const task, void *const clientData, dwTime_t const startTime, dwTime_t const period, dwTimerHandle_t const timer)
	Scheduled a task to be run at a future time (recurring) More...

Typedef Documentation

dwConstTimerHandle_t

typedef struct dwTimerObject const* dwConstTimerHandle_t

Handle represents a const Timer object.

Definition at line 65 of file Timer.h.

dwConstTimeSourceHandle_t

typedef struct dwTimeSourceObject const* dwConstTimeSourceHandle_t

Handle represents a const TimeSource object.

Definition at line 60 of file Timer.h.

dwTimerHandle_t

typedef struct dwTimerObject* dwTimerHandle_t

Handle represents a Timer object.

Definition at line 63 of file Timer.h.

dwTimerWork

typedef void(* dwTimerWork) (void *ptr)

dwTimerWork is a timer schedule task callback function, input void* ptr passes the extra data to the task

Definition at line 67 of file Timer.h.

dwTimeSourceHandle_t

typedef struct dwTimeSourceObject* dwTimeSourceHandle_t

Handle represents a TimeSource object.

Definition at line 58 of file Timer.h.

Function Documentation

dwTimer_cancelAsync()

DW_API_PUBLIC dwStatus dwTimer_cancelAsync

(

dwTimerHandle_t const

timer

)

Asynchronously cancels all scheduled work associated with this timer.

Asynchronously means this call will not wait the cancel operation finished. This call will allow pending work to complete before cancelling the job. This call will clear the all the time value assigned to timer. And then stop the timer.

Parameters

[in]

timer

A handle to the timer

Returns

DW_INVALID_HANDLE if provided context handle is invalid, i.e. null or of wrong type.
DW_SUCCESS if timer cancelled without any error.

API Group

• Init: Yes
• Runtime: Yes
• De-Init: Yes

dwTimer_cancelSync()

DW_API_PUBLIC dwStatus dwTimer_cancelSync

(

dwTimerHandle_t const

timer

)

Synchronously cancels all scheduled work associated with this timer.

Synchronously means this call will wait until the task is canceled. This call will allow pending work to complete before cancelling the job. This call will clear the all the time value assigned to timer. And then stop the timer.

Parameters

[in]

timer

A handle to the timer

Returns

DW_INVALID_HANDLE if provided context handle is invalid, i.e. null or of wrong type.
DW_SUCCESS if timer cancelled without any error.
DW_FAILURE if clear time value assigned to timer fails.

API Group

• Init: Yes
• Runtime: Yes
• De-Init: Yes

dwTimer_initializeFromSource()

DW_API_PUBLIC dwStatus dwTimer_initializeFromSource	(	dwTimerHandle_t *const	timer,
		char8_t const *const	timerName,
		dwTimeSourceHandle_t const	source
	)

Creates a new DW timer.

The new timer is initially disarmed. This call registers the timer with the primary time source of the context.

Parameters

[out]	timer	A pointer to the timer handle
[in]	timerName	Name of the timer, Note maximal length is 16 (incl. null character). Names longer than 16 characters will be truncated.
[in]	source	Specifies the handle to the time source which is used as time provider.

Note

source is gotten from dwContext_getTimeSource, which depends on the platform users use.

Returns

DW_INVALID_ARGUMENT if pointer to the timer handle is NULL.
DW_INVALID_HANDLE if provided source is NULL or invalid.
DW_SUCCESS if initialization is done without any error.
DW_FAILURE failed to create a timer from system.
DW_BUFFER_FULL number of timer created has exceeded the max number of timer(Now is 512).

API Group

• Init: Yes
• Runtime: No
• De-Init: No

dwTimer_release()

DW_API_PUBLIC dwStatus dwTimer_release

(

dwTimerHandle_t const

timer

)

Release the timer instance.

The timer will be stopped if it's started.

Parameters

[in]

timer

The timer handle

Returns

DW_INVALID_ARGUMENT if pointer to the timer handle is NULL.
DW_SUCCESS if timer released without any error.

API Group

• Init: Yes
• Runtime: No
• De-Init: Yes

dwTimer_scheduleTaskOneShot()

DW_API_PUBLIC dwStatus dwTimer_scheduleTaskOneShot	(	dwTimerWork const	task,
		void *const	clientData,
		dwTime_t const	startTime,
		dwTimerHandle_t const	timer
	)

Scheduled a task to be run at a future time (non-recurring)

Parameters

[in]	task	Function pointer for the task to be executed
[in]	clientData	Pointer to data to be passed back to task
[in]	startTime	Time when the task should be activated
[in]	timer	Handle to the timer object

Note

startTime should be at least 1 microsecond into the future. If users set 0, this call will set this value to 1 microsecond into the future.

Returns

DW_INVALID_HANDLE if provided timer handle is invalid, i.e. null or of wrong type. DW_CALL_NOT_ALLOWED if the task has been already scheduled.
DW_NOT_SUPPORTED if the timer does not support this feature.
DW_FAILURE if the task scheduling failed.
DW_SUCCESS if timer scheduled without any error.

API Group

• Init: Yes
• Runtime: Yes
• De-Init: Yes

dwTimer_scheduleTaskRecurring()

DW_API_PUBLIC dwStatus dwTimer_scheduleTaskRecurring	(	dwTimerWork const	task,
		void *const	clientData,
		dwTime_t const	startTime,
		dwTime_t const	period,
		dwTimerHandle_t const	timer
	)

Scheduled a task to be run at a future time (recurring)

Parameters

[in]	task	Function pointer for the task to be executed
[in]	clientData	Pointer to data to be passed back to task
[in]	startTime	Time when the task should be activated, in Us.
[in]	period	Period at which to fire the task, in Us.
[in]	timer	Handle to the timer object

Note

period should be greater than 0 if users want to schedule recurring task. If set as 0, it will schedule one-shot task as dwTimer_scheduleTaskOneShot().

startTime If the start time is less or equal to current time, timer will start at current time.

Returns

DW_INVALID_HANDLE if provided timer handle is invalid, i.e. null or of wrong type. DW_CALL_NOT_ALLOWED if the task has been already scheduled.
DW_NOT_SUPPORTED if the timer does not support this feature.
DW_FAILURE if the task scheduling failed.
DW_SUCCESS if timer scheduled without any error.

API Group

• Init: Yes
• Runtime: Yes
• De-Init: Yes