Xenomai  3.1
Alarm services

General-purpose watchdog timers. More...

Collaboration diagram for Alarm services:

Data Structures

struct  RT_ALARM_INFO
 Alarm status descriptor. More...
 

Functions

int rt_alarm_start (RT_ALARM *alarm, RTIME value, RTIME interval)
 
Start an alarm. More...
 
int rt_alarm_stop (RT_ALARM *alarm)
 
Stop an alarm. More...
 
int rt_alarm_inquire (RT_ALARM *alarm, RT_ALARM_INFO *info)
 
Query alarm status. More...
 
int rt_alarm_create (RT_ALARM *alarm, const char *name, void(*handler)(void *arg), void *arg)
 
Create an alarm object. More...
 
int rt_alarm_delete (RT_ALARM *alarm)
 
Delete an alarm. More...
 

Detailed Description

General-purpose watchdog timers.

Alarms are general-purpose watchdog timers. Alchemy tasks may create any number of alarms and use them to run a user-defined handler, after a specified initial delay has elapsed. Alarms can be either one shot or periodic; in the latter case, the real-time system automatically reprograms the alarm for the next shot according to a user-defined interval value.

Function Documentation

◆ rt_alarm_create()

int rt_alarm_create ( RT_ALARM *  alarm,
const char *  name,
void(*)(void *arg)  handler,
void *  arg 
)


Create an alarm object.

This routine creates an object triggering an alarm routine at a specified time in the future. Alarms can be periodic or oneshot, depending on the reload interval value passed to rt_alarm_start().

Parameters
alarmThe address of an alarm descriptor which can be later used to identify uniquely the created object, upon success of this call.
nameAn ASCII string standing for the symbolic name of the alarm. When non-NULL and non-empty, a copy of this string is used for indexing the created alarm into the object registry.
handlerThe address of the routine to call when the alarm expires. This routine is passed the arg value.
argA user-defined opaque argument passed to the handler.
Returns
Zero is returned upon success. Otherwise:
  • -ENOMEM is returned if the system fails to get memory from the local pool in order to create the alarm.
  • -EEXIST is returned if the name is conflicting with an already registered alarm.
  • -EPERM is returned if this service was called from an asynchronous context.
Tags
mode-unrestricted, switch-secondary
Note
Alarms are process-private objects and thus cannot be shared by multiple processes, even if they belong to the same Xenomai session.

◆ rt_alarm_delete()

int rt_alarm_delete ( RT_ALARM *  alarm)


Delete an alarm.

This routine deletes an alarm object previously created by a call to rt_alarm_create().

Parameters
alarmThe alarm descriptor.
Returns
Zero is returned upon success. Otherwise:
  • -EINVAL is returned if alarm is not a valid alarm descriptor.
  • -EPERM is returned if this service was called from an asynchronous context.
Tags
mode-unrestricted, switch-secondary

◆ rt_alarm_inquire()

int rt_alarm_inquire ( RT_ALARM *  alarm,
RT_ALARM_INFO info 
)


Query alarm status.

This routine returns the status information about the specified alarm.

Parameters
alarmThe alarm descriptor.
infoA pointer to the return buffer" to copy the information to.
Returns
Zero is returned and status information is written to the structure pointed at by info upon success. Otherwise:
  • -EINVAL is returned if alarm is not a valid alarm descriptor.
Tags
unrestricted, switch-primary

◆ rt_alarm_start()

int rt_alarm_start ( RT_ALARM *  alarm,
RTIME  value,
RTIME  interval 
)


Start an alarm.

This routine programs the trigger date of an alarm object. An alarm can be either periodic or oneshot, depending on the interval value.

Alarm handlers are always called on behalf of Xenomai's internal timer event routine. Therefore, Xenomai routines which can be called from such handlers are restricted to the set of services available on behalf of an asynchronous context.

This service overrides any previous setup of the expiry date and reload interval for the alarm.

Parameters
alarmThe alarm descriptor.
valueThe relative date of the first expiry, expressed in clock ticks (see note).
intervalThe reload value of the alarm. It is a periodic interval value to be used for reprogramming the next alarm shot, expressed in clock ticks (see note). If interval is equal to TM_INFINITE, the alarm will not be reloaded after it has expired.
Returns
Zero is returned upon success. Otherwise:
  • -EINVAL is returned if alarm is not a valid alarm descriptor.
  • -EPERM is returned if this service was called from an invalid context.
Tags
xthread-only, switch-primary
Note
Each of the initial value and interval is interpreted as a multiple of the Alchemy clock resolution (see –alchemy-clock-resolution option, defaults to 1 nanosecond).

◆ rt_alarm_stop()

int rt_alarm_stop ( RT_ALARM *  alarm)


Stop an alarm.

This routine disables an alarm object, preventing any further expiry until it is re-enabled via rt_alarm_start().

Parameters
alarmThe alarm descriptor.
Returns
Zero is returned upon success. Otherwise:
  • -EINVAL is returned if alarm is not a valid alarm descriptor.
Tags
unrestricted, switch-primary