Alarms

The alarm family of functions are used for creating alarms which call a callback or wake up waiting threads after a period of time. More...

Collaboration diagram for Alarms:

Data Structures
struct	OSAlarmQueue
struct	OSAlarmLink
struct	OSAlarm

Macros
#define	OS_ALARM_QUEUE_TAG   0x614C6D51u
#define	OS_ALARM_TAG   0x614C724Du

Typedefs
typedef struct OSAlarm	OSAlarm
typedef struct OSAlarmLink	OSAlarmLink
typedef struct OSAlarmQueue	OSAlarmQueue
typedef void(*	OSAlarmCallback) (OSAlarm *, OSContext *)

Functions
BOOL	OSCancelAlarm (OSAlarm *alarm)
	Cancel an alarm. More...
void	OSCancelAlarms (uint32_t group)
	Cancel all alarms which have a matching tag set by OSSetAlarmTag. More...
void	OSCreateAlarm (OSAlarm *alarm)
	Initialise an alarm structure. More...
void	OSCreateAlarmEx (OSAlarm *alarm, const char *name)
	Initialise an alarm structure with a name. More...
void *	OSGetAlarmUserData (OSAlarm *alarm)
	Return user data set by OSSetAlarmUserData. More...
void	OSInitAlarmQueue (OSAlarmQueue *queue)
	Initialise an alarm queue structure. More...
void	OSInitAlarmQueueEx (OSAlarmQueue *queue, const char *name)
	Initialise an alarm queue structure with a name. More...
BOOL	OSSetAlarm (OSAlarm *alarm, OSTime time, OSAlarmCallback callback)
	Set a one shot alarm to perform a callback after a set amount of time. More...
BOOL	OSSetPeriodicAlarm (OSAlarm *alarm, OSTime start, OSTime interval, OSAlarmCallback callback)
	Set a repeated alarm to execute a callback every interval from start. More...
void	OSSetAlarmTag (OSAlarm *alarm, uint32_t group)
	Set an alarm tag which is used in OSCancelAlarms for bulk cancellation. More...
void	OSSetAlarmUserData (OSAlarm *alarm, void *data)
	Set alarm user data which is returned by OSGetAlarmUserData. More...
BOOL	OSWaitAlarm (OSAlarm *alarm)
	Sleep the current thread until the alarm has been triggered or cancelled. More...

Detailed Description

The alarm family of functions are used for creating alarms which call a callback or wake up waiting threads after a period of time.

Alarms can be one shot alarms which trigger once after a period of time, or periodic which trigger at regular intervals until they are cancelled.

---

Data Structure Documentation

OSAlarmQueue

struct OSAlarmQueue

Definition at line 32 of file alarm.h.

Data Fields
uint32_t	tag	Should always be set to the value OS_ALARM_QUEUE_TAG.
const char *	name	Name set by OSInitAlarmQueueEx.
OSThreadQueue	threadQueue
OSAlarm *	head
OSAlarm *	tail

OSAlarmLink

struct OSAlarmLink

Definition at line 52 of file alarm.h.

Data Fields
OSAlarm *	prev
OSAlarm *	next

OSAlarm

struct OSAlarm

Definition at line 62 of file alarm.h.

Data Fields
uint32_t	tag	Should always be set to the value OS_ALARM_TAG.
const char *	name	Name set from OSCreateAlarmEx.
OSAlarmCallback	callback	The callback to execute once the alarm is triggered.
uint32_t	group	Used with OSCancelAlarms for bulk cancellation of alarms.
OSTime	nextFire	The time when the alarm will next be triggered.
OSAlarmLink	link	Link used for when this OSAlarm object is inside an OSAlarmQueue.
OSTime	period	The period between alarm triggers, this is only set for periodic alarms.
OSTime	start	The time the alarm was started.
void *	userData	User data set with OSSetAlarmUserData and retrieved with OSGetAlarmUserData.
uint32_t	state	The current state of the alarm, internal values.
OSThreadQueue	threadQueue	Queue of threads currently waiting for the alarm to trigger with OSWaitAlarm.
OSAlarmQueue *	alarmQueue	The queue that this alarm is currently in.
OSContext *	context	The context the alarm was triggered on.

Macro Definition Documentation

OS_ALARM_QUEUE_TAG

#define OS_ALARM_QUEUE_TAG   0x614C6D51u

Definition at line 30 of file alarm.h.

OS_ALARM_TAG

#define OS_ALARM_TAG   0x614C724Du

Definition at line 61 of file alarm.h.

Typedef Documentation

OSAlarm

typedef struct OSAlarm OSAlarm

Definition at line 1 of file alarm.h.

OSAlarmLink

typedef struct OSAlarmLink OSAlarmLink

Definition at line 1 of file alarm.h.

OSAlarmQueue

typedef struct OSAlarmQueue OSAlarmQueue

Definition at line 1 of file alarm.h.

OSAlarmCallback

typedef void(* OSAlarmCallback) (OSAlarm *, OSContext *)

Definition at line 28 of file alarm.h.

Function Documentation

OSCancelAlarm()

BOOL OSCancelAlarm

(

OSAlarm *

alarm

)

Cancel an alarm.

OSCancelAlarms()

void OSCancelAlarms

(

uint32_t

group

)

Cancel all alarms which have a matching tag set by OSSetAlarmTag.

Parameters

group

The alarm tag to cancel.

OSCreateAlarm()

void OSCreateAlarm

(

OSAlarm *

alarm

)

Initialise an alarm structure.

OSCreateAlarmEx()

void OSCreateAlarmEx	(	OSAlarm *	alarm,
		const char *	name
	)

Initialise an alarm structure with a name.

OSGetAlarmUserData()

void* OSGetAlarmUserData

(

OSAlarm *

alarm

)

Return user data set by OSSetAlarmUserData.

OSInitAlarmQueue()

void OSInitAlarmQueue

(

OSAlarmQueue *

queue

)

Initialise an alarm queue structure.

OSInitAlarmQueueEx()

void OSInitAlarmQueueEx	(	OSAlarmQueue *	queue,
		const char *	name
	)

Initialise an alarm queue structure with a name.

OSSetAlarm()

BOOL OSSetAlarm	(	OSAlarm *	alarm,
		OSTime	time,
		OSAlarmCallback	callback
	)

Set a one shot alarm to perform a callback after a set amount of time.

Parameters

alarm	The alarm to set.
time	The duration until the alarm should be triggered.
callback	The alarm callback to call when the alarm is triggered.

OSSetPeriodicAlarm()

BOOL OSSetPeriodicAlarm	(	OSAlarm *	alarm,
		OSTime	start,
		OSTime	interval,
		OSAlarmCallback	callback
	)

Set a repeated alarm to execute a callback every interval from start.

Parameters

alarm	The alarm to set.
start	The duration until the alarm should first be triggered.
interval	The interval between triggers after the first trigger.
callback	The alarm callback to call when the alarm is triggered.

OSSetAlarmTag()

void OSSetAlarmTag	(	OSAlarm *	alarm,
		uint32_t	group
	)

Set an alarm tag which is used in OSCancelAlarms for bulk cancellation.

OSSetAlarmUserData()

void OSSetAlarmUserData	(	OSAlarm *	alarm,
		void *	data
	)

Set alarm user data which is returned by OSGetAlarmUserData.

OSWaitAlarm()

BOOL OSWaitAlarm

(

OSAlarm *

alarm

)

Sleep the current thread until the alarm has been triggered or cancelled.