<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
<HEAD>
<META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.9">
<TITLE> RPC2 User Guide and Reference Manual: The Timer Package</TITLE>
<LINK HREF="rpc2_manual-12.html" REL=next>
<LINK HREF="rpc2_manual-10.html" REL=previous>
<LINK HREF="rpc2_manual.html#toc11" REL=contents>
</HEAD>
<BODY>
<A HREF="rpc2_manual-12.html">Next</A>
<A HREF="rpc2_manual-10.html">Previous</A>
<A HREF="rpc2_manual.html#toc11">Contents</A>
<HR>
<H2><A NAME="s11">11. The Timer Package</A></H2>
<P>
<A NAME="TMPackage"></A> <P>The timer package contains a number of routines that assist in manipulating
lists of objects of type <CODE>struct TM_Elem</CODE>.
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 <CODE>struct TM_Elem</CODE>
into a structure.
After inserting the desired timeout value the structure is inserted into a
list, by means of its timer field.
<P>
<H2><A NAME="ss11.1">11.1 A Simple Example</A>
</H2>
<P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
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 . . .
}
</PRE>
</CODE></BLOCKQUOTE>
<P>
<H3>Timer Primitives</H3>
<P>
<P>
<H3>TM_Init -- Initialize a timer list </H3>
<P>
<H3>Call:</H3>
<P><EM> void TM_Init(</EM> @w<<B>out</B> struct TM_Elem **list>, <EM>)</EM>
<H3>Parameters:</H3>
<P>
<DL>
<DT><B>list</B><DD><P>The list to be initialized
</DL>
<H3>Completion Codes:</H3>
<P>
<DL>
<DT><B>0</B><DD><P>ok,
<DT><B>-1</B><DD><P>not enough free storage
</DL>
<H3>Description:</H3>
<P>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.
)
<P>
<H3>TM_Final -- Finalize a timer list </H3>
<P>
<H3>Call:</H3>
<P><EM> void TM_Final(</EM> @w<<B>out</B> struct TM_Elem **list>, <EM>)</EM>
<H3>Parameters:</H3>
<P>
<DL>
<DT><B>list</B><DD><P>The list to be finalized
</DL>
<H3>Completion Codes:</H3>
<P>
<DL>
<DT><B>0</B><DD><P>ok,
<DT><B>-1</B><DD><P>*list was 0 or list was never initialized
</DL>
<H3>Description:</H3>
<P>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.
)
<P>
<H3>TM_Insert -- Release a read lock, </H3>
<P>
<H3>Call:</H3>
<P><EM> void TM_Insert(</EM> <B>in</B> struct TM_Elem *list>, @w<<B>in out</B> struct TM_Elem *elem <EM>)</EM>
<H3>Parameters:</H3>
<P>
<DL>
<DT><B>list</B><DD><P>The list into which the element is to be inserted
<DT><B>elem</B><DD><P>The element to be initialized and inserted
</DL>
<H3>Completion Codes:</H3>
<P>
<DL>
<P>The element <EM>elem</EM> is initialized so that the <EM>TimeLeft</EM>
field is equal to the <EM>TotalTime</EM> field. (The <EM>TimeLeft</EM>
field may be kept current by use of TM_Rescan.) The
element is then inserted into the list.
</DL>
<H3>Description:</H3>
<P>The element <EM>elem</EM> is initialized so that the <EM>TimeLeft</EM>
field is equal to the <EM>TotalTime</EM> field. (The <EM>TimeLeft</EM>
field may be kept current by use of TM_Rescan.) The
element is then inserted into the list.
)
<P>
<H3>TM_Rescan -- Update <EM>TimeLeft</EM> fields of entries on a timer list and look for expired elements</H3>
<P>
<H3>Call:</H3>
<P><EM> void TM_Rescan(</EM> @w<<B>out</B> struct TM_Elem **list>, <EM>)</EM>
<H3>Parameters:</H3>
<P>
<DL>
<DT><B>list</B><DD><P>The list to be updated
</DL>
<H3>Completion Codes:</H3>
<P>
<H3>Description:</H3>
<P>This routine will update the <EM>TimeLeft</EM> fields of all timers
on <EM>list</EM>. (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 <EM>TimeLeft</EM> field.
)
<P>@Pascall(Tag=<TMGetExpired>,
Callname=`TM_GetExpired,
Abstract=`Return an expired timer from a list,
Parmlist=`@w<<B>in</B> struct TM_Elem *list>,
Type=`struct TM_Elem *,
<DL>
<DT><B>list</B><DD><P>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 <EM>TimeLeft</EM>
field is less than or equal to 0.
)
</DL>
<P>
<H3>TM_GetEarliest -- Return the earliest timer on a list</H3>
<P>
<H3>Call:</H3>
<P><EM> void TM_GetEarliest(</EM> @w<<B>out</B> struct TM_Elem **list>, <EM>)</EM>
<H3>Parameters:</H3>
<P>
<DL>
<DT><B>list</B><DD><P>The list to be searched
</DL>
<H3>Completion Codes:</H3>
<P>
<DL>
<P>
</DL>
<H3>Description:</H3>
<P>This routine returns a pointer to the timer that will be next
to expire -- that with a smallest <EM>TimeLeft</EM> field. If there
are no timers on the list, 0 is returned.
)
<P>
<H3>TM_eql -- See if 2 timevals are equal </H3>
<P>
<H3>Call:</H3>
<P><EM> void TM_eql(</EM><B>in</B> struct timeval *t1, <B>in</B> struct timeval *t2 <EM>)</EM>
<H3>Parameters:</H3>
<P>
<DL>
<DT><B>t1</B><DD><P>a timeval
<DT><B>t2</B><DD><P>Another timeval
</DL>
<H3>Completion Codes:</H3>
<P>
<DL>
<P>
</DL>
<H3>Description:</H3>
<P>This routine returns 0 if and only if <EM>t1</EM> and <EM>t2</EM> are not equal.
<P>
<HR>
<A HREF="rpc2_manual-12.html">Next</A>
<A HREF="rpc2_manual-10.html">Previous</A>
<A HREF="rpc2_manual.html#toc11">Contents</A>
</BODY>
</HTML>
distrib
>
Mandriva
>
8.2
>
i586
>
media
>
contrib
>
by-pkgid
>
211238da6d926d1ca4390483bb29f586
>
files
>
48
