Made some fixes to the conditions section.
[charm.git] / doc / converse / conditions.tex
1
2
3 \chapter{Timers, Periodic Checks, and Conditions}
4
5 This module provides functions that allow users to insert hooks,
6 i.e. user-supplied functions, that are called by the system at
7 specified times, or as specific conditions arise.
8
9 {\bf  CcdCallOnCondition}
10 \begin{verbatim}
11 void CcdCallOnCondition(condnum,fnp,arg)
12     int condnum;
13     CcdVoidFn fnp;
14     void *arg;      
15 \end{verbatim}
16
17 This call instructs the system to call the function indicated by the
18 function pointer {\tt fnp}, with the specified argument {\tt arg}, when the
19 condition indicated by {\tt condnum} is raised next. Multiple functions may
20 be registered for the same condition number. A total of 511
21 conditions, numbered 1 through 511, are supported.  Currently, users
22 must make sure that various condition numbers used in a program are
23 disjoint.  (In the future, we may provide a call to allocate the next
24 available condition number.)
25
26 The system supports a predefined condition, with condition number 1
27 (CcdPROCESSORIDLE, BUT I AM AM NOT SURE THAT IS EXPORTED TO THE USER
28 PROGRAM), which is raised by the system when there are no entities
29 (ready threads, messages for objects, posted handlers, etc.) in the
30 scheduler's queue.
31
32 \vspace*{0.2in}
33 {\bf  CcdRaiseCondition}
34 \begin{verbatim}
35 void CcdRaiseCondition(condNum)
36      int condNum;
37 \end{verbatim}
38
39 When this function is called, it invokes all the functions whose
40 pointers were registered for the \verb#condNum# via a {\em prior} call
41 to {\tt CcdCallOnCondition(..)}.  All calls to {\tt
42 CcdCallOnCondition(..)} {\em during} this function's execution takes
43 effect only after it returns.  Once a user-registered
44 function is called, it loses its registration.  So, if users want the
45 function to be called the next time the same condition arises, they
46 must register the function again.
47
48 \vspace*{0.2in}
49 {\bf  CcdPeriodicallyCall}
50 \begin{verbatim}
51 void CcdPeriodicallyCall(fnp, arg)
52     CcdVoidFn fnp;
53     void *arg;  
54 \end{verbatim}
55
56 A function registered through this call is called periodically by the
57 system's scheduler.  Typically, it would be called every time the
58 scheduler gets control, such as while switching context to a new
59 thread or before scheduling a message for an object, or before calling
60 a posted handler. These functions don't have to be re-registered after
61 every call, unlike the functions for the "conditions". 
62
63 \vspace*{0.2in}
64 {\bf  CcdCallFnAfter}
65 \begin{verbatim}
66 void CcdCallFnAfter(fnp, arg, deltaT)
67     CcdVoidFn fnp;
68     void *arg;
69     unsigned int deltaT; 
70 \end{verbatim}
71
72 This call registers a function via a pointer to it, {\tt fnp},  that will be
73 called at least {\tt deltaT} milliseconds later. 
74 The registered function {\tt fnp} is actually called the first time the
75 scheduler gets control after {\tt deltaT} milliseconds have elapsed. 
76