msgQ: Use the datatype for msg prios as specified by user (CMK_MSG_PRIO_TYPE)
[charm.git] / doc / debugger / implementation.tex
1 %% Section: Implementation details
2
3 The following classes in the PUP framework were used in
4 implementing debugging support in charm.
5
6
7 \begin{itemize}
8
9 \item
10
11 \texttt{class PUP::er} - This class is the abstract superclass of
12 all the other classes in the framework. The \texttt{pup} method of
13 a particular class takes a reference to a \texttt{PUP::er} as
14 parameter. This class has methods for dealing with all the basic
15 C++ data types. All these methods are expressed in terms of a
16 generic pure virtual method. Subclasses only need to provide the
17 generic method.
18
19 \item
20
21 \texttt{class PUP::toText} - This is a subclass of the
22 \texttt{PUP::toTextUtil} class which is a subclass of the
23 \texttt{PUP::er} class. It copies the data of an object to a C
24 string, including the terminating NULL.
25
26 \item
27
28 \texttt{class PUP::sizerText} - This is a subclass of the
29 \texttt{PUP::toTextUtil} class which is a subclass of the
30 \texttt{PUP::er} class. It returns the number of characters
31 including the terminating NULL and is used by the
32 \texttt{PUP::toText} object to allocate space for building the C
33 string.
34
35 \end{itemize}
36
37
38 The code below shows a simple class declaration
39 that includes a \texttt{pup} method.
40
41
42 \begin{verbatim}
43   class foo {
44    private:
45     bool isBar;
46     int x;
47     char y;
48     unsigned long z;
49     float q[3];
50    public:
51     void pup(PUP::er &p) {
52       p(isBar);
53       p(x);p(y);p(z);
54       p(q,3);
55     }
56   };
57 \end{verbatim}
58
59
60 \subsection{Converse Client-Server Interface}
61
62 The Converse Client-Server (CCS) module enables Converse
63 \cite{InterOpIPPS96} programs to act as parallel servers,
64 responding to requests from non-Converse programs. The CCS module
65 is split into two parts - client and server. The server side is
66 used by a Converse program while the client side is used by
67 arbitrary non-Converse programs. A CCS client accesses a running
68 Converse program by talking to a \texttt{server-host} which
69 receives the CCS requests and relays them to the appropriate
70 processor. The \texttt{server-host} is \texttt{charmrun}
71 \cite{charmman} for net-versions and is the first processor for
72 all other versions.
73
74 In the case of the net-version of \charmpp{}, a Converse program
75 is started as a server by running the \charmpp{} program using the
76 additional runtime option ``\textit{++server}''. This opens the CCS
77 server on any TCP port number. The TCP port number can be
78 specified using the command-line option ``\textit{server-port}''. A
79 CCS client connects to a CCS server, asks a server PE to execute a
80 pre-registered handler and receives the response data. The
81 function \texttt{CcsConnect} takes a pointer to a
82 \texttt{CcsServer} as an argument and connects to the given CCS
83 server. The functions \texttt{CcsNumNodes}, \texttt{CcsNumPes},
84 \texttt{CcsNodeSize} implemented as part of the client interface
85 in \charmpp{} returns information about the parallel machine. The
86 function \texttt{CcsSendRequest} takes a handler ID and the
87 destination processor number as arguments and asks the server to
88 execute the particular handler on the specified processor.
89 \texttt{CcsRecvResponse} receives a response to the previous
90 request in-place. A timeout is also specified which gives the
91 number of seconds to wait till the function returns a 0, otherwise
92 the number of bytes received is returned.
93
94 Once a request arrives on a CCS server socket, the CCS server
95 runtime looks up the appropriate registered handler and calls it.
96 If no handler is found the runtime prints a diagnostic and ignores
97 the message. If the CCS module is disabled in the core, all CCS
98 routines become macros returning 0. The function
99 \texttt{CcsRegisterHandler} is used to register handlers in the
100 CCS server. A handler ID string and a function pointer are passed
101 as parameters. A table of strings corresponding to appropriate
102 function pointers is created. Various built-in functions are
103 provided which can be called from within a CCS handler. The
104 debugger behaves as a CCS client invoking appropriate handlers
105 which makes use of some of these functions. Some of the built-in
106 functions are as follows.
107
108 \begin{itemize}
109
110 \item
111
112 \texttt{CcsSendReply} - This function sends the data provided as
113 an argument back to the client as a reply. This function can only
114 be called from a CCS handler invoked remotely.
115
116 \item
117
118 \texttt{CcsDelayReply} - This call is made to allow a CCS reply to
119 be delayed until after the handler has completed.
120
121
122 \end{itemize}
123
124 The CCS runtime system provides several built-in CCS handlers,
125 which are available to any Converse program. All \charmpp{}
126 programs are essentially Converse programs. \texttt{ccs\_getinfo}
127 takes an empty message and responds with information about the
128 parallel job. Similarly the handler \texttt{ccs\_killport} allows
129 a client to be notified when a parallel run exits.