11. Alarms

GM provides the following simple alarm API. The alarm API allows the GM client to schedule a callback function to be called after a delay, specified in microseconds. An unbounded number of alarms may be set, although alarm overhead increases linearly in the number of set alarms, and the client must provide storage for each set alarm.

- void gm_initialize_alarm (gm_alarm_t *alarm)

Initialize a client-allocated gm_alarm_t structure for use with gm_set_alarm(). This function should be called after the structure is allocated but before a pointer to it is passed to gm_set_alarm() or gm_cancel_alarm().

- void gm_cancel_alarm (gm_alarm_t *alarm)

Cancel a scheduled alarm, or do nothing if the alarm is not scheduled.

- void gm_set_alarm (struct gm_port *port, gm_alarm_t *alarm, unsigned int usec, void (*callback)(void *), void *context)

Schedule callback(context) to be called after usec microseconds (or later), or reschedule the alarm if it has already been scheduled and has not yet triggered. callback must be non-NULL. context is treated as an opaque pointer by GM, and will be passed as the single parameter to the client-supplied callback function.

GM clients will also be able to take advantage of the fact that an application is guaranteed to receive a single GM_ALARM_EVENT for each call to a client-supplied callback, with the corresponding callback occurring during the call to gm_unknown() that processes that alarm. This means that a case statement like the following in the client's event loops can be used to significantly reduce the overhead of polling for any effect of a client supplied alarm callback:

case GM_ALARM_EVENT: gm_unknown (event); /* poll for effect of alarm callbacks only here */ break;