Docs: refer to illinois.edu, not uiuc.edu
[charm.git] / doc / charm++ / quiesce.tex
1 \section{Completion Detection}
2
3 Completion detection is a method for automatically detecting
4 completion of a distributed process within an application. It is a
5 module, and therefore is only included when ``-module completion'' is
6 specified when linking your application.
7
8 Completion is reached within a distributed process when the
9 participating objects have produced and consumed an equal number of
10 events globally. The number of global events that will be produced and
11 consumed does not need to be known, just the number of producers is
12 required.
13
14 First, the detector should be constructed. This call would typically
15 belong in application startup code (it initializes the group that
16 keeps track of completion):
17
18 \begin{alltt}
19 CProxy_CompletionDetector detector = CProxy_CompletionDetector::ckNew();
20 \end{alltt}
21
22 When it is time to start completion detection, make the following call to the
23 library:
24
25 \begin{alltt}
26 void start_detection(int num_producers, CkCallback start, CkCallback finish,
27 int prio_)
28 \end{alltt}
29
30 \begin{alltt}
31 detector.start_detection(10, CkCallback(CkIndex_chare1::start_test(0),
32                                        thisProxy),
33                              CkCallback(CkIndex_chare2::finish_test(0),
34                                        thisProxy), 0);
35 \end{alltt}
36
37 The \verb|num_producers| parameter is the number of objects (chares)
38 that will produce elements. So if every array element will produce one
39 event, then it would be the size of the array.
40
41 The \verb|start| callback notifies your program that it is safe to
42 begin producing and consuming (this state is reached when the module
43 has finished its internal initialization).
44
45 The \verb|finish| callback is instigated when completion has been
46 detected (all objects participating have produced and consumed an
47 equal number of elements globally).
48
49 The \verb|prio| parameter is the priority that the detector will run
50 at. This is still under development, but it should be set below the
51 application's priority if possible.
52
53 Once initialization is complete (the ``start'' callback is triggered),
54 make the following call to the library:
55
56 \begin{alltt}
57 void CompletionDetector::produce(int events_produced)
58 void CompletionDetector::produce() // 1 by default
59 \end{alltt}
60
61 \begin{alltt}
62 detector.ckLocalBranch()->produce(4);
63 \end{alltt}
64
65 Once all the ``events'' that this chare is going to produce have been sent out,
66 make the following call:
67
68 \begin{alltt}
69 void CompletionDetector::done(int producers_done)
70 void CompletionDetector::done() // 1 by default
71 \end{alltt}
72
73 \begin{alltt}
74 detector.ckLocalBranch()->done();
75 \end{alltt}
76
77 The application can now start consuming elements, using the following calls:
78
79 \begin{alltt}
80 void CompletionDetector::consume(int events_consumed)
81 void CompletionDetector::consume() // 1 by default
82 \end{alltt}
83
84 \begin{alltt}
85 detector.ckLocalBranch()->consume();
86 \end{alltt}
87
88 At some point, when everyone is consuming elements, completion will be
89 reached. The system will detect that state and will trigger the \verb|finish|
90 callback. At that point, \verb|start_detection| can be called again to restart
91 the process.
92
93 \section{Quiescence Detection}
94 \label{sec:qd}
95
96 In \charmpp, \index{quiescence}quiescence is defined as the state in which no
97 processor is executing an entry point, and no messages are awaiting processing.
98
99 \charmpp\ provides two facilities for detecting quiescence: \kw{CkStartQD} and
100 \kw{CkWaitQD}.
101
102 \kw{CkStartQD} registers with the system a callback that should be made the
103 next time \index{quiescence}quiescence is detected.  \kw{CkStartQD} has two
104 variants which expect the following arguments: 
105 \begin{enumerate}
106 \item An index corresponding to the entry function that is to be called,
107 and a handle to the chare on which that entry function should be called.  The
108 syntax of this call looks like this:
109
110 \begin{alltt}
111  CkStartQD(int Index,const CkChareID* chareID);
112 \end{alltt}
113
114 To retrieve the corresponding index of a particular \index{entry method}entry
115 method, you must use a static method contained within the \uw{CkIndex} object
116 corresponding to the \index{chare}chare containing that entry method.  The
117 syntax of this call is as follows:
118
119 \begin{alltt}
120 \kw{myIdx}=CkIndex_\uw{ChareClass}::\uw{EntryMethod}(\uw{parameters});
121 \end{alltt}
122
123 where \uw{ChareClass} is the C++ class of the chare containing
124 the desired entry method, \uw{EntryMethod} is the name of that entry method,
125 and \uw{parameters} are the parameters taken by the method.
126 These parameters are only used to resolve the proper \uw{EntryMethod};
127 they are otherwise ignored.
128
129 \item 
130 A \uw{CkCallback} object. The syntax of this call looks like:
131 \begin{alltt}
132   CkStartQD(const CkCallback& cb);
133 \end{alltt}
134
135 Upon quiescence detection, specified callback is called with no parameters.
136
137 \end{enumerate}
138
139
140 \kw{CkWaitQD}, by contrast, does not register a callback.  Rather,
141 \kw{CkWaitQD} blocks and does not return until \index{quiescence}quiescence is
142 detected.  It takes no parameters and returns no value.  A call to
143 \kw{CkWaitQD} simply looks like this: 
144
145 \begin{alltt}
146   CkWaitQD();
147 \end{alltt}
148
149 Keep in mind that \kw{CkWaitQD} should only be called from threaded
150 \index{entry method}entry methods because a call to \kw{CkWaitQD} suspends the
151 current thread of execution, and if it were called outside of a threaded entry
152 method it would suspend the main thread of execution of the processor from
153 which \kw{CkWaitQD} was called and the entire program would come to a grinding
154 halt on that processor.
155
156 \function{void CkExitAfterQuiescence()} \index{CkExitAfterQuiescence}
157 \desc{This call informs the Charm RTS that computation on all processors
158 should terminate as soon as the machine becomes completely idle--that is,
159 after all messages and entry methods are finished.  This is the state of 
160 quiescence, as described further in Section~\ref{sec:qd}.
161 This routine returns immediately.}
162