Tasklets

Tasklet framework for scheduling simple events for the future. More...

Collaboration diagram for Tasklets:

Classes
struct	ca_tasklet
	Internal tasklet state structure. More...

Typedefs
typedef ca_error(*	ca_tasklet_callback) (void *context)
	Function pointer typedef for tasklet callbacks. More...
typedef struct ca_tasklet	ca_tasklet
	Internal tasklet state structure. More...

Functions
ca_error	TASKLET_Init (ca_tasklet *aTasklet, ca_tasklet_callback aCallback)
	Initialise a tasklet to a stable state, and register its associated callback function. More...
ca_error	TASKLET_ScheduleDelta (ca_tasklet *aTasklet, uint32_t aTimeDelta, void *aContext)
	Schedule a tasklet to be called in the future, by aTimeDelta milliseconds. More...
ca_error	TASKLET_ScheduleAbs (ca_tasklet *aTasklet, uint32_t aTimeNow, uint32_t aTimeAbs, void *aContext)
	Schedule a tasklet to be called in the future, at aTimeAbs milliseconds. More...
ca_error	TASKLET_GetScheduledTime (ca_tasklet *aTasklet, uint32_t *aTimeAbs)
	Get the time that the tasklet is scheduled to be called. More...
ca_error	TASKLET_GetScheduledTimeDelta (ca_tasklet *aTasklet, uint32_t *aTimeDelta)
	Get the time delta until a tasklet is scheduled to be called. More...
ca_error	TASKLET_Cancel (ca_tasklet *aTasklet)
	Cancel a scheduled tasklet if it is scheduled. More...
bool	TASKLET_IsQueued (ca_tasklet *aTasklet)
	Query whether a tasklet is currently scheduled. More...
ca_error	TASKLET_GetTimeToNext (uint32_t *aTimeDelta)
	Get the time delta until the next tasklet is scheduled to occur. More...
ca_error	TASKLET_Process (void)
	Process the callbacks for any tasklets that are scheduled to happen now or in the past. More...

Detailed Description

Tasklet framework for scheduling simple events for the future.

Typedef Documentation

ca_tasklet

typedef struct ca_tasklet ca_tasklet

Internal tasklet state structure.

Must be allocated with a lifetime that exceeds the usage of the tasklet, ideally statically. Do not modify this struct directly, and instead use the TASKLET_ functions to control it.

ca_tasklet_callback

typedef ca_error(* ca_tasklet_callback) (void *context)

Function pointer typedef for tasklet callbacks.

Will be called when the tasklet is triggered.

Parameters

context

User-defined context to be passed to the callback when it is triggered.

Returns

ca_error status

Return values

CA_ERROR_SUCCESS

Callback successfully executed

Function Documentation

TASKLET_Cancel()

ca_error TASKLET_Cancel

(

ca_tasklet *

aTasklet

)

Cancel a scheduled tasklet if it is scheduled.

Parameters

aTasklet

A pointer to an initialised ca_tasklet struct to cancel

Returns

status

Return values

CA_ERROR_SUCCESS	Tasklet successfully cancelled
CA_ERROR_ALREADY	Tasklet is not currently scheduled

TASKLET_GetScheduledTime()

ca_error TASKLET_GetScheduledTime	(	ca_tasklet *	aTasklet,
		uint32_t *	aTimeAbs
	)

Get the time that the tasklet is scheduled to be called.

Parameters

[in]	aTasklet	A pointer to an initialised ca_tasklet struct to query
[out]	aTimeAbs	Output parameter which will be filled with the absolute time that the tasklet is scheduled for.

Returns

status

Return values

CA_ERROR_SUCCESS	Tasklet is scheduled to be called at *aTimeAbs ms
CA_ERROR_INVALID_STATE	Tasklet is not currently scheduled. aTimeAbs has not been modified.

TASKLET_GetScheduledTimeDelta()

ca_error TASKLET_GetScheduledTimeDelta	(	ca_tasklet *	aTasklet,
		uint32_t *	aTimeDelta
	)

Get the time delta until a tasklet is scheduled to be called.

aTimeDelta will be set to 0 if event is still queued, but is due to happen now or in past.

Parameters

[in]	aTasklet	A pointer to an initialised ca_tasklet struct to query
[out]	aTimeDelta	Output parameter which will be filled with the delta time in ms until tasklet is scheduled.

Returns

status

Return values

CA_ERROR_SUCCESS	Tasklet is scheduled to be called in *aTimeDelta ms
CA_ERROR_INVALID_STATE	Tasklet is not currently scheduled. aTimeDelta has not been modified.

TASKLET_GetTimeToNext()

ca_error TASKLET_GetTimeToNext

(

uint32_t *

aTimeDelta

)

Get the time delta until the next tasklet is scheduled to occur.

Parameters

[out]

aTimeDelta

Output parameter that will be filled with the time delta until the next tasklet to be scheduled.

Returns

status

Return values

CA_ERROR_SUCCESS	There is at least one tasklet scheduled and it is scheduled for *aTimeDelta milliseconds
CA_ERROR_NOT_FOUND	There are no tasklets currently scheduled. aTimeDelta has not been modified.

TASKLET_Init()

ca_error TASKLET_Init	(	ca_tasklet *	aTasklet,
		ca_tasklet_callback	aCallback
	)

Initialise a tasklet to a stable state, and register its associated callback function.

It is invalid to call this function on a currently scheduled target, and this produces undefined behaviour.

Parameters

aTasklet	A pointer to the uninitialised target
aCallback	The callback to be called when this tasklet passes its scheduled time.

Returns

status

Return values

CA_ERROR_SUCCESS

Successfully initialised tasklet

TASKLET_IsQueued()

bool TASKLET_IsQueued

(

ca_tasklet *

aTasklet

)

Query whether a tasklet is currently scheduled.

This function can only be called on ca_tasklet structs initialized with TASKLET_Init, or those which were zero-initialized previously (e.g. memset the entire struct to zero)

Parameters

aTasklet

A pointer to a ca_tasklet struct to query

Returns

True if the tasklet is scheduled, false if not

TASKLET_Process()

ca_error TASKLET_Process

(

void

)

Process the callbacks for any tasklets that are scheduled to happen now or in the past.

Returns

CA_ERROR_SUCCESS Pending tasklets have been processed.

CA_ERROR_NOT_FOUND No tasklets currently scheduled for now or the past.

TASKLET_ScheduleAbs()

ca_error TASKLET_ScheduleAbs	(	ca_tasklet *	aTasklet,
		uint32_t	aTimeNow,
		uint32_t	aTimeAbs,
		void *	aContext
	)

Schedule a tasklet to be called in the future, at aTimeAbs milliseconds.

Parameters

aTasklet	A pointer to an initialised ca_tasklet struct
aTimeNow	The current time used to schedule the event. Used to prevent race condition.
aTimeAbs	The absolute time to schedule this tasklet.
aContext	A user-defined context pointer which will be passed to the callback. Can be NULL.

Returns

status

Return values

CA_ERROR_SUCCESS	Successfully scheduled the tasklet
CA_ERROR_ALREADY	The given tasklet is already registered. Must first be excecuted or cancelled with TASKLET_Cancel.
CA_ERROR_INVALID_ARGS	Scheduled too far into the future (must be less than 0x7FFFFFFF ms into future)

TASKLET_ScheduleDelta()

ca_error TASKLET_ScheduleDelta	(	ca_tasklet *	aTasklet,
		uint32_t	aTimeDelta,
		void *	aContext
	)

Schedule a tasklet to be called in the future, by aTimeDelta milliseconds.

Parameters

aTasklet	A pointer to an initialised ca_tasklet struct
aTimeDelta	The number of milliseconds into the future that this tasklet should be called
aContext	A user-defined context pointer which will be passed to the callback. Can be NULL.

Returns

status

Return values

CA_ERROR_SUCCESS	Successfully scheduled the tasklet
CA_ERROR_ALREADY	The given tasklet is already registered. Must first be excecuted or cancelled with TASKLET_Cancel.
CA_ERROR_INVALID_ARGS	Scheduled too far into the future (must be less than 0x7FFFFFFF ms into future)