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.