Updated and expanded description of condition handling, including
[charm.git] / doc / converse / conditions.tex
1 \chapter{Timers, Periodic Checks, and Conditions}
2
3 This module provides functions that allow users to insert hooks,
4 i.e. user-supplied functions, that are called by the system at
5 as specific conditions arise.  These conditions differ from UNIX
6 signals in that they are raised synchronously, via a regular
7 function call; and that a single condition can call several 
8 different functions.  
9
10 The system-defined conditions are:
11 \begin{description}
12 \item[CcdPROCESSOR\_BEGIN\_IDLE] Raised when the scheduler first
13 finds it has no messages to execute.  That is, this condition is
14 raised at the trailing edge of the processor utilization graph.
15 \item[CcdPROCESSOR\_STILL\_IDLE] Raised when the scheduler subsequently
16 finds it still has no messages to execute.  That is, this condition is
17 raised while the processor utilization graph is flat.
18 \item[CcdPROCESSOR\_BEGIN\_BUSY] Raised when a message first arrives
19 on an idle processor.  That is, raised on the rising edge of the
20 processor utilization graph.
21 \item[CcdPERIODIC] The scheduler attempts to raise this condition every
22 few milliseconds.  The scheduling for this and the other periodic conditions
23 is nonpreemptive, and hence may be delayed until the current entry point is 
24 finished.
25 \item[CcdPERIODIC\_10ms] Raised every 10ms (at 100Hz).
26 \item[CcdPERIODIC\_100ms] Raised every 100ms (at 10Hz).
27 \item[CcdPERIODIC\_1second] Raised once per second.
28 \item[CcdPERIODIC\_10second] Raised once every 10 seconds.
29 \item[CcdPERIODIC\_1minute] Raised once per minute.
30 \item[CcdPERIODIC\_10minute] Raised once every 10 minutes.
31 \item[CcdPERIODIC\_1hour] Raised once every hour.
32 \item[CcdPERIODIC\_12hour] Raised once every twelve hours.
33 \item[CcdPERIODIC\_1day] Raised once every day.
34
35 \item[CcdQUIESCENCE] Raised when the quiescence detection system
36 has determined that the system is quiescent.
37 \item[CcdSIGUSR1] Raised when the system receives the UNIX signal SIGUSR1.
38 Be aware that this condition is thus raised asynchronously, from
39 within a signal handler, and all the usual signal handler restrictions apply.
40 \item[CcdSIGUSR2] Raised when the system receives the UNIX signal SIGUSR2.
41 \item[CcdUSER] The system never raises this or any larger conditions.
42 They can be used by the user for application-specific use.  All conditions
43 from CcdUSER to CcdUSER+256 are so available.
44 \end{description}
45
46 \function{int CcdCallOnCondition(condnum,fnp,arg)}
47 \args{int condnum;}
48 \args{CcdVoidFn fnp;}
49 \args{void *arg;}
50
51 This call instructs the system to call the function indicated by the
52 function pointer {\tt fnp}, with the specified argument {\tt arg}, when the
53 condition indicated by {\tt condnum} is raised next. Multiple functions may
54 be registered for the same condition number.
55
56 \function{int CcdCallOnConditionKeep(condnum,fnp,arg)}
57 As above, but the association is permanent-- the given function will
58 be called again whenever this condition is raised.
59
60 Returns an index that may be used to cancel the association later.
61
62 \function{void CcdCancelCallOnCondition(int condnum, int idx)}
63 \function{void CcdCancelCallOnConditionKeep(int condnum, int idx)}
64 Delete the given index from the list of callbacks for
65 the given condition. The corresponding function will no longer be 
66 called when the condition is raised.
67
68 \function{void CcdRaiseCondition(condNum)}
69 \args{int condNum;}
70
71 When this function is called, it invokes all the functions whose
72 pointers were registered for the \verb#condNum# via a {\em prior} call
73 to {\tt CcdCallOnCondition} or {\tt CcdCallOnConditionKeep}.  
74
75 \function{void CcdCallFnAfter(fnp, arg, msLater)}
76 \args{CcdVoidFn fnp;}
77 \args{void *arg;}
78 \args{unsigned int msLater;}
79
80 This call registers a function via a pointer to it, {\tt fnp},  that will be
81 called at least {\tt msLater} milliseconds later. 
82 The registered function {\tt fnp} is actually called the first time the
83 scheduler gets control after {\tt deltaT} milliseconds have elapsed. 
84