Timer

Detailed Description

Defines the methods for the timer interface.

Typedefs
typedef struct dwTimerObject const *	dwConstTimerHandle_t
typedef struct dwTimeSourceObject const *	dwConstTimeSourceHandle_t
typedef struct dwTimerObject *	dwTimerHandle_t
typedef void(*	dwTimerWork) (void *ptr)
typedef struct dwTimeSourceObject *	dwTimeSourceHandle_t

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 and initializes a 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

Definition at line 61 of file Timer.h.

dwConstTimeSourceHandle_t

typedef struct dwTimeSourceObject const* dwConstTimeSourceHandle_t

Definition at line 58 of file Timer.h.

dwTimerHandle_t

typedef struct dwTimerObject* dwTimerHandle_t

Definition at line 60 of file Timer.h.

dwTimerWork

typedef void(* dwTimerWork) (void *ptr)

Definition at line 62 of file Timer.h.

dwTimeSourceHandle_t

typedef struct dwTimeSourceObject* dwTimeSourceHandle_t

Definition at line 57 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.

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. Provide a valid timer pointer.
DW_NOT_SUPPORTED if the timer does not support this feature.
DW_SUCCESS if timer cancelled without any error.

dwTimer_cancelSync()

DW_API_PUBLIC dwStatus dwTimer_cancelSync

(

dwTimerHandle_t const

timer

)

Synchronously cancels all scheduled work associated with this timer.

This call will allow pending work to complete for cancelling the job.

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. Provide a valid timer pointer.
DW_NOT_SUPPORTED if the timer does not support this feature.
DW_SUCCESS if timer cancelled without any error.

dwTimer_initializeFromSource()

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

Creates and initializes a DW Timer.

This method creates a timer instance and registers it with the primary time source for the context.

Parameters

[out]	timer	A pointer to the timer handle
[in]	timerName	Name of the timer, which will be associated with the created thread. Note maximal length is 16 (incl. null character). Any length above will be cut.
[in]	source	Specifies the handle to the time source which is used as time provider.

Returns

DW_INVALID_ARGUMENT if pointer to the timer handle is NULL. Provide a valid timer pointer.
DW_INVALID_HANDLE if provided source is NULL or invalid. Provide a valid source pointer.
DW_SUCCESS if initialization is done without any error.

dwTimer_release()

DW_API_PUBLIC dwStatus dwTimer_release

(

dwTimerHandle_t const

timer

)

Release the timer instance.

Parameters

[in]

timer

The timer handle

Returns

DW_INVALID_ARGUMENT if pointer to the timer handle is NULL. Provide a valid timer pointer.
DW_INVALID_HANDLE if provided timer handle is invalid. Provide a valid timer handle.
DW_SUCCESS if timer released without any error.

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

Returns

DW_INVALID_HANDLE if provided timer handle is invalid, i.e. null or of wrong type. Provide a valid timer pointer.
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.

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]	period	Period at which to fire the task
[in]	timer	Handle to the timer object

Returns

DW_INVALID_HANDLE if provided timer handle is invalid, i.e. null or of wrong type. Provide a valid timer pointer.
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.