doc/charm++: startup text revisions
[charm.git] / doc / converse / ccs.tex
1 \chapter{\converse{} Client-Server Interface}
2
3 This note describes the \converse{} client-server (CCS) 
4 module. This module enables \converse{} programs to act as
5 parallel servers, responding to requests from (non-\converse{}) programs
6 across the internet.
7
8 The CCS module is split into two parts-- client and server. 
9 The server side is the interface used by a \converse{} program;
10 the client side is used by arbitrary (non-\converse{}) programs.
11 The following sections describe both these parts. 
12
13 A CCS client accesses a running \converse{} program by talking to
14 a {\tt server-host}, which receives the CCS requests and relays them
15 to the appropriate processor.  The {\tt server-host} is \kw{charmrun}
16 for net- versions, and is the first processor for all other versions.
17
18
19 \section{CCS: Starting a Server}
20 A \converse{} program is started using
21 \begin{alltt}
22 charmrun pgmname +pN charmrun-opts pgm-opts
23 \end{alltt}
24 \kw{charmrun} also accepts the CCS options:
25
26 {\tt ++server}: open a CCS server on any TCP port number
27
28 {\tt ++server-port}=$port$: open the given TCP port as a CCS server   
29
30 {\tt ++server-auth}=$authfile$: accept authenticated queries
31
32 As the parallel job starts, it will print a line giving the 
33 IP address and TCP port number of the new CCS server.
34 The format is: ``ccs: Server IP = $ip$, Server port = $port$ \$'',
35 where $ip$ is a dotted decimal version of the 
36 server IP address, and $port$ is the decimal port number.
37
38 \section{CCS: Client-Side}
39
40 A CCS client connects to a CCS server, asks a server PE to 
41 execute a pre-registered handler, and receives the response data.
42 The CCS client may be written in any language (see CCS network protocol,
43 below), but a C interface (files ``ccs-client.c'' and ``ccs-client.h'') 
44 and Java interface (file ``CcsServer.java'') are available in 
45 the charm include directory.
46
47 The C routines use the skt\_abort error-reporting strategy;
48 see ``sockRoutines.h'' for details.  The C client API is:
49
50 \function{void CcsConnect(CcsServer *svr, char *host, int port);}
51 Connect to the given CCS server.  svr points to a pre-allocated
52 CcsServer structure.
53
54 \function{void CcsConnectIp(CcsServer *svr, int ip, int port);}
55 As above, but a numeric IP is specified.
56
57 \function{int CcsNumNodes(CcsServer *svr);}
58 \function{int CcsNumPes(CcsServer *svr);}
59 \function{int CcsNodeFirst(CcsServer *svr, int node);}
60 \function{int CcsNodeSize(CcsServer *svr,int node);}
61 These functions return information about the parallel machine;
62 they are equivalent to the \converse{} calls CmiNumNodes,
63 CmiNumPes, CmiNodeFirst, and CmiNodeSize.
64
65 \function{void CcsSendRequest(CcsServer *svr, char *hdlrID, int pe, 
66                     unsigned int size, const char *msg);}
67 Ask the server to execute the handler hdlrID on the given processor.
68 The handler is passed the given data as a message.  The data may
69 be in any desired format (including binary). 
70
71 \function{int CcsSendBroadcastRequest(CcsServer *svr, const char *hdlrID,
72             int size, const void *msg);}
73 As CcsSendRequest, only that the handler hdlrID is invoked on all processors.
74
75 \function{int CcsSendMulticastRequest(CcsServer *svr, const char *hdlrID, int npes, 
76             int *pes, int size, const void *msg);}
77 As CcsSendRequest, only that the handler hdlrID is invoked on the processors
78 specified in the array \uw{pes} (of size \uw{npes}).
79
80 \function{int CcsRecvResponse(CcsServer *svr, 
81                     unsigned int maxsize, char *recvBuffer, int timeout);}
82 Receive a response to the previous request in-place.
83 Timeout gives the number of seconds to wait before returning 0;
84 otherwise the number of bytes received is returned. 
85
86 \function{int CcsRecvResponseMsg(CcsServer *svr, 
87                     unsigned int *retSize,char **newBuf, int timeout);}
88 As above, but receive a variable-length response.  The
89 returned buffer must be free()'d after use.
90
91 \function{int CcsProbe(CcsServer *svr);}
92 Return 1 if a response is available; otherwise 0.
93
94 \function{void CcsFinalize(CcsServer *svr);}
95 Closes connection and releases server.
96
97
98 The Java routines throw an IOException on network errors.
99 Use javadoc on CcsServer.java for the interface, which mirrors
100 the C version above.
101
102
103 \section{CCS: Server-Side}
104
105 Once a request arrives on a CCS server socket, the CCS server 
106 runtime looks up the appropriate handler and calls it.
107 If no handler is found, the runtime prints a diagnostic
108 and ignores the message.
109
110 CCS calls its handlers in the usual \converse{} fashion--
111 the request data is passed as a newly-allocated message,
112 and the actual user data begins CmiMsgHeaderSizeBytes
113 into the message.  The handler is responsible for CmiFree'ing
114 the passed-in message.
115
116 The interface for the server side of CCS is included in 
117 ``converse.h''; if CCS is disabled (in conv-mach.h), all
118 CCS routines become macros returning 0.
119
120 The handler registration interface is:
121
122 \function{void CcsUseHandler(char *id, int hdlr);}
123 \function{int CcsRegisterHandler(char *id, CmiHandler fn);}
124 Associate this handler ID string with this function.  
125 hdlr is a \converse{} handler index; fn is a function pointer.
126 The ID string cannot be more than 32 characters, including the
127 terminating NULL.
128
129 After a handler has been registered to CCS, the user can also setup a merging
130 function. This function will be passed in to CmiReduce to combine replies to
131 multicast and broadcast requests.
132
133 \function{void CcsSetMergeFn(const char *name, CmiReduceMergeFn newMerge);}
134 \desc{Associate the given merge function to the CCS identified by id. This will
135 be used for CCS request received as broadcast or multicast.}
136
137 These calls can be used from within a CCS handler:
138
139 \function{int CcsEnabled(void);}
140 Return 1 if CCS routines are available (from conv-mach.h).
141 This routine does not determine if a CCS server port is 
142 actually open.
143
144 \function{int CcsIsRemoteRequest(void);}
145 Return 1 if this handler was called via CCS; 0 if it was
146 called as the result of a normal \converse{} message.
147
148 \function{void CcsCallerId(skt\_ip\_t *pip, unsigned int *pport);}
149 Return the IP address and TCP port number
150 of the CCS client that invoked this method.
151 Can only be called from a CCS handler invoked remotely.
152
153 \function{void CcsSendReply(int size, const void *reply);}
154 Send the given data back to the client as a reply.
155 Can only be called from a CCS handler invoked remotely.
156 In case of broadcast or multicast CCS requests, the handlers in
157 all processors involved must call this function.
158
159 \function{CcsDelayedReply CcsDelayReply(void);}
160 Allows a CCS reply to be delayed until after the handler
161 has completed.  Returns a token used below.
162
163 \function{void CcsSendDelayedReply(CcsDelayedReply d,int size, const void *reply);}
164 Send a CCS reply for the given request.  Unlike
165 CcsSendReply, can be invoked from any handler on any processor.
166
167
168 \section{CCS: system handlers}
169 The CCS runtime system provides several built-in CCS handlers,
170 which are available in any \converse{} job:
171
172 \kw{ccs\_getinfo}
173 Takes an empty message, responds with information about the parallel
174 job.  The response is in the form of network byte order (big-endian) 4-byte 
175 integers: first the number of parallel nodes, then the number of processors
176 on each node.  This handler is invoked by the client routine CcsConnect.
177
178 \kw{ccs\_killport}
179 Allows a client to be notified when a parallel run exits (for any reason).
180 Takes one network byte order (big-endian) 4-byte integer: a TCP port
181 number. The runtime writes ``die\\n'' to this port before exiting.
182 There is no response data.
183
184 \kw{perf\_monitor}
185 Takes an empty message, responds (after a delay) with performance data.
186 When CMK\_WEB\_MODE is enabled in conv-mach.h, the runtime system collects
187 performance data.  Every 2 seconds, this data is collected on processor
188 0 and sent to any clients that have invoked perf\_monitor on processor 0.
189 The data is returned in ASCII format with the leading string "perf", 
190 and for each processor the current load (in percent) and scheduler message
191 queue length (in messages).  Thus a heavily loaded, two-processor system
192 might reply with the string ``perf 98 148230 100 385401''.
193
194
195 \section{CCS: network protocol}
196 This information is provided for completeness and clients written
197 in non-C, non-Java languages.  The client and server APIs above are
198 the preferred way to use CCS.
199
200 A CCS request arrives as a new TCP connection to the CCS server port.
201 The client speaks first, sending a request header and then the request
202 data.  The server then sends the response header and response data,
203 and closes the connection.  Numbers are sent as network byte order
204 (big-endian) 4-byte integers-- network binary integers.
205
206 The request header has three fields: the number of bytes of request data,
207 the (0-based) destination processor number, and the CCS handler identifier
208 string.  The byte count and processor are network binary integers (4 bytes
209 each), the CCS handler ID is zero-terminated ASCII text (32 bytes); for
210 a total request header length of 40 bytes.  The remaining request data
211 is passed directly to the CCS handler.
212
213 The response header consists of a single network binary integer-- the 
214 length in bytes of the response data to follow.  The header is thus 4 
215 bytes long.  If there is no response data, this field has value 0.
216
217
218 \section{CCS: Authentication}
219 By default, CCS provides no authentication-- this means any
220 client anywhere on the internet can interact with the server.
221 $authfile$, passed to '++server-auth', is a configuration file
222 that enables authentication and describes the authentication to 
223 perform.
224
225 The configuration file is line-oriented ASCII text,
226 consisting of security level / key pairs.  The security
227 level is an integer from 0 (the default) to 255.
228 Any security levels not listed in the file are disallowed.
229
230 The key is the 128-bit secret key used to authenticate CCS
231 clients for that security level.  It is either up 
232 to 32 hexadecimal digits of key data or the string "OTP".
233 "OTP" stands for One Time Pad, which will generate a random
234 key when the server is started.  This key is printed out
235 at job startup with the format "CCS\_OTP\_KEY$>$ Level $i$ key: $hexdigits$"
236 where $i$ is the security level in decimal and $hexdigits$ is
237 32 hexadecimal digits of key data.
238
239 For example, a valid CCS authentication file might consist of
240 the single line "0 OTP", indicating that the default security
241 level 0 requires a randomly generated key.  All other security
242 levels are disallowed.
243
244