ecf6cb338841c507b89e0580818b38b6fdced0f2
[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, that
6 is user supplied functions that are called by the system at specified
7 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 called instructs the system to call the function indicated by the
18 function pointer fnp, with the specified argument arg, when the
19 condition indicated by condnum is raised next. Multiple functions may
20 be registered for the same condition number. A total of 511
21 conditions, numbered one through 511, are supported.  Currently, users
22 must make sure that various condition numbers used in a program are
23 disjoint.  (In 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 they 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 CcdCallOnCondition(..).  All calls to CcdCallOnCondition(..) {\em
42 during} this function's execution take effect only after this function
43 returns.  Once a user-registered function is called, it loses its
44 registration.  So, if users want the function to be called the next
45 time the same condition arises, they must register the function again.
46
47 \vspace*{0.2in}
48 {\bf  CcdPeriodicallyCall}
49 \begin{verbatim}
50 void CcdPeriodicallyCall(fnp, arg)
51     CcdVoidFn fnp;
52     void *arg;  
53 \end{verbatim}
54
55 To function registered through this call is called periodically by the
56 system's scheduler.  Typically, it would be called every time the
57 scheduler gets control, such as while switching context to a new
58 thread or before scheduling a message for an object, or before calling
59 a posted handler. These functions don't have to be re-registered after
60 every call, unlike the functions for the "conditions". 
61
62 \vspace*{0.2in}
63 {\bf  CcdCallFnAfter}
64 \begin{verbatim}
65 void CcdCallFnAfter(fnp, arg, deltaT)
66     CcdVoidFn fnp;
67     void *arg;
68     unsigned int deltaT; 
69 \end{verbatim}
70
71 This call registers a function via a pointer to it, fnp,  that will be
72 called at least deltaT milliseconds later. 
73 The registered function fnp is actually called the first time
74 scheduler gets control after deltaT milliseconds have elapsed. 
75