Coda File System

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