Next Previous Contents

## 11. The Timer Package

The timer package contains a number of routines that assist in manipulating lists of objects of type `struct TM_Elem`. TM_Elems (timers) are assigned a timeout value by the user and inserted in a package-maintained list. The time remaining to timeout for each timer is kept up to date by the package under user control. There are routines to remove a timer from its list, to return an expired timer from a list and to return the next timer to expire. This specialized package is currently used by the IOMGR package and by the implementation of RPC2. A timer is used commonly by inserting a field of type `struct TM_Elem` into a structure. After inserting the desired timeout value the structure is inserted into a list, by means of its timer field.

## 11.1 A Simple Example

> `

>     static struct TM_Elem *requests;

>     . . .

>         TM_Init (&requests);        /* Initialize timer list */
>         . . .
>         for (;;) {
>             TM_Rescan (requests);   /* Update the timers */
>             expired = TM_GetExpired (requests);
>             if (expired == 0) break;
>             . . . process expired element . . .
>         }

> `

### Timer Primitives

### TM_Init -- Initialize a timer list

### Call:

void TM_Init( @w<out struct TM_Elem **list>, )

### Parameters:

list

  The list to be initialized

### Completion Codes:

0

  ok,

-1

  not enough free storage

### Description:

The specified list will be initialized so that it is an empty timer list. This routine must be called before any other operations are applied to the list. )

### TM_Final -- Finalize a timer list

### Call:

void TM_Final( @w<out struct TM_Elem **list>, )

### Parameters:

list

  The list to be finalized

### Completion Codes:

0

  ok,

-1

  *list was 0 or list was never initialized

### Description:

Call this routine when you are finished with a timer list and the list is empty. This routine releases any auxiliary storage associated with the list. )

### TM_Insert -- Release a read lock,

### Call:

void TM_Insert( in struct TM_Elem *list>, @w<in out struct TM_Elem *elem )

### Parameters:

list

  The list into which the element is to be inserted

elem

  The element to be initialized and inserted

### Completion Codes:

The element elem is initialized so that the TimeLeft field is equal to the TotalTime field. (The TimeLeft field may be kept current by use of TM_Rescan.) The element is then inserted into the list.

### Description:

The element elem is initialized so that the TimeLeft field is equal to the TotalTime field. (The TimeLeft field may be kept current by use of TM_Rescan.) The element is then inserted into the list. )

### TM_Rescan -- Update TimeLeft fields of entries on a timer list and look for expired elements

### Call:

void TM_Rescan( @w<out struct TM_Elem **list>, )

### Parameters:

list

  The list to be updated

### Completion Codes:

### Description:

This routine will update the TimeLeft fields of all timers on list. (This is done by checking the time of day clock in Unix.) This routine returns a count of the number of expired timers on the list. This is the only routine (besides TM_Init that updates the TimeLeft field. )

@Pascall(Tag=<TMGetExpired>, Callname=`TM_GetExpired, Abstract=`Return an expired timer from a list, Parmlist=`@w<in struct TM_Elem *list>, Type=`struct TM_Elem *,

list

  The list to be searched, Text=`The specified list will be searched and a pointer to an expired timer will be returned. 0 is returned if there are no expired timers. An expired timer is one whose TimeLeft field is less than or equal to 0. )

### TM_GetEarliest -- Return the earliest timer on a list

### Call:

void TM_GetEarliest( @w<out struct TM_Elem **list>, )

### Parameters:

list

  The list to be searched

### Completion Codes:

### Description:

This routine returns a pointer to the timer that will be next to expire -- that with a smallest TimeLeft field. If there are no timers on the list, 0 is returned. )

### TM_eql -- See if 2 timevals are equal

### Call:

void TM_eql(in struct timeval *t1, in struct timeval *t2 )

### Parameters:

t1

  a timeval

t2

  Another timeval

### Completion Codes:

### Description:

This routine returns 0 if and only if t1 and t2 are not equal.

Next Previous Contents