Main Page   Modules   Data Structures   File List   Data Fields   Globals   Related Pages  

gm_set_alarm.c File Reference

#include "gm_call_trace.h"
#include "gm_debug.h"
#include "gm_cmp64.h"
#include "gm_internal.h"
#include "gm_send_queue.h"
#include "gm_set_alarm.h"

Functions

GM_ENTRY_POINT void gm_cancel_alarm (gm_alarm_t *my_alarm)
GM_ENTRY_POINT void gm_initialize_alarm (gm_alarm_t *my_alarm)
GM_ENTRY_POINT void gm_set_alarm (gm_port_t *port, gm_alarm_t *my_alarm, gm_u64_t usecs, void(*callback)(void *), void *context)

Detailed Description

This file includes source for the user-level alarm API calls gm_initialize_alarm(), gm_set_alarm(), and gm_cancel_alarm().

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.

These source for all the functions is included here, because if the user needs one, the user needs them all.

This code is a bit tricky, since the LANai provides only one alarm per port. This alarm is used to time the first pending alarm, but if any new alarm is set, then the LANai alarm must be flushed to find out what time it is and potentially to allow the alarm to be rescheduled for an earlier time. Therefore, unless no other alarm is set, alarms are set by adding them to an "unset alarm" queue, flushing any pending alarm, and then adding the alarms to the sorted alarm queue only once the pending LANai alarm has been flushed or triggered.


Function Documentation

GM_ENTRY_POINT void gm_cancel_alarm gm_alarm_t *    my_alarm
 

gm_cancel_alarm() cancels a scheduled alarm, or does nothing if an alarm is not scheduled. Alarms are cancelled by simply removing them from the alarm list so that when the next GM_ALARM_EVENT arrives from the LANai _gm_handle_alarm() will not find the alarm.

Parameters:
my_alarm  (IN) Alarm to be cancelled.
See also:
gm_initialize_alarm gm_set_alarm gm_flush_alarm
Author:
Glenn Brown
Version:
GM_API_VERSION (as defined in gm.h)

GM_ENTRY_POINT void gm_initialize_alarm gm_alarm_t *    my_alarm
 

gm_initialize_alarm() initializes 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().

Parameters:
my_alarm  (IN) Alarm to be initialized.
See also:
gm_cancel_alarm gm_set_alarm gm_flush_alarm
Author:
Glenn Brown
Version:
GM_API_VERSION (as defined in gm.h)

GM_ENTRY_POINT void gm_set_alarm gm_port_t *    port,
gm_alarm_t *    my_alarm,
gm_u64_t    usecs,
void(*    callback)(void *),
void *    context
 

gm_set_alarm() sets an alarm, which may already be pending. If it is pending, it is rescheduled. The user supplies MY_ALARM, a pointer to storage for the alarm state, which has been initialized with gm_init_alarm_my_alarm(). When the alarm occurs, CALLBACK(CONTEXT) is called.

gm_set_alarm() schedules 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 the effect of alarm callbacks only here
 
       break;
   
Parameters:
port  (IN) A pointer to the GM Port.
my_alarm  (IN) Alarm to be initialized.
usecs 
callback 
context 
See also:
gm_cancel_alarm gm_initialize_alarm gm_flush_alarm
Author:
Glenn Brown
Version:
GM_API_VERSION (as defined in gm.h)


Generated on Mon Nov 3 15:39:26 2003 for GM by doxygen1.2.15