dcced319775503626c1c43b8d60140a4d670cc18
[charm.git] / doc / charm++ / python.tex
1 The Python scripting language in \charmpp{} allows the user to dynamically
2 execute pieces of code inside a running application, without the need to
3 recompile. This is performed through the CCS (Converse Client Server) framework
4 (see \htmladdnormallink{Converse Manual}
5 {http://charm.cs.illinois.edu/manuals/html/converse/5.html} for more information about this). 
6 The user specifies which elements of the system will be accessible through the interface,
7 as we will see later, and then run a client which connects to the server.
8
9 In order to exploit this functionality, Python interpreter needs to be installed
10 into the system, and \charmpp{} LIBS need to be built with:\\
11 \texttt{./build LIBS $<$arch$>$ $<$options$>$}
12
13 The interface provides three different types of requests:
14
15 \begin{description}
16 \item[Execute] requests to execute a code, it will contain the code to be executed on the server, together with the instructions on how to handle the environment;
17 \item[Print] asks the server to send back all the strings which have been printed by the script until now;
18 \item[Finished] asks the server if the current script has finished or it is still running.
19 \end{description}
20
21 There are three modes to run code on the server, ordered here by increase of
22 functionality, and decrease of dynamic flexibility:
23 \begin{itemize}
24 \item \textbf{simple read/write} By implementing the \kw{read} and \kw{write} methods
25 of the object exposed to python, in this way single variables may be exposed,
26 and the code will have the possibility to modify them individually as desired.
27 (see section~\ref{pythonServerRW})
28 \item \textbf{iteration} By implementing the iterator functions in the server (see
29 \ref{pythonServerIterator}), the user can upload the code of a Python function
30 and a user-defined iterator structure, and the system will apply the specified
31 function to all the objects reflected by the iterator structure.
32 \item \textbf{high level} By implementing \kw{python} entry methods, the Python code uploaded can access them and activate complex, parallel operations that will be performed by the \charmpp{} application. (see section~\ref{pythonHighLevel})
33 \end{itemize}
34
35 This documentation will describe the client API first, and then the server API. 
36
37
38 \section{Client API}
39
40 \label{pythonClient}
41
42 In order to facilitate the interface between the client and the server, some
43 classes are available to the user to include into the client. Currently \CC{} and
44 java interfaces are provided.
45
46 \CC{} programs need to include \texttt{PythonCCS-client.h} into their
47 code. This file is among the \charmpp{} include files. For java, the package
48 \texttt{charm.ccs} needs to be imported. This is located under the java
49 directory on the \charmpp{} distribution, and it provides both the Python and
50 CCS interface classes.
51
52 There are three main classes provided: \texttt{PythonExecute},
53 \texttt{PythonPrint}, and \texttt{PythonFinished} which are used for the three
54 different types of request.
55
56 All of them have two common methods to enable communication across different platforms:
57
58 \begin{description}
59
60 \item[int size();]
61 Returns the size of the class, as number of bytes that will be
62 transmitted through the network (this includes the code and other dynamic
63 variables in the case of \texttt{PythonExecute}).
64
65 \item[char *pack();]
66 Returns a new memory location containing the data to be sent to the server, this
67 is the data which has to be passed to the \texttt{CcsSendRequest} function. The
68 original class will be unmodified and can be reused in subsequent calls.
69
70 \end{description}
71
72 A typical invocation to send a request from the client to the server has the
73 following format:
74
75 \begin{alltt}
76 CcsSendRequest (&server, "pyCode", 0, request.size(), request.pack());
77 \end{alltt}
78
79 \section{PythonExecute}
80 \label{pythonExecute}
81
82 To execute a Python script on a running server, the client has to create an
83 instance of \texttt{PythonExecute}, the two constructors have the following
84 signature (java has a corresponding functionality):
85
86 \begin{alltt}
87 PythonExecute(char *code, bool persistent=false, bool highlevel=false, CmiUInt4 interpreter=0);
88 PythonExecute(char *code, char *method, PythonIterator *info, bool persistent=false,
89               bool highlevel=false, CmiUInt4 interpreter=0);
90 \end{alltt}
91
92 The second one is used for iterative requests (see~\ref{pythonIterator}). The
93 only required argument is the code, a null terminated string, which will not be
94 modified by the system. All the other parameters are optional. They refer to the
95 possible variants for an execution request. In particular, this is a
96 list of all the options:
97
98 \begin{description}
99
100 \item[iterative]
101 If the request is a single code (false) or if it represents a function over
102 which to iterate (true) (see~\ref{pythonIterator} for more details).
103
104 \item[persistent]
105 It is possible to store information on the server which will be
106 retained across different client calls (from simple data all the way
107 up to complete libraries). True means that the information will be
108 retained on the server, false means that the information will be
109 deleted when the script terminates. In order to properly release the
110 memory, when the last call is made (and the data is no longer
111 required), this flag should be set to false. To reuse persistent data,
112 the interpreter field of the request should be set to handle returned by a previous persistent call (see later in this subsection).
113
114 \item[high level]
115 In order to have the ability to call high level \charmpp{} functions (available
116 through the keyword \kw{python}) this flag must be set to true. If it is false,
117 the entire module ``charm'' will not be present, but the startup of the script
118 will be faster.
119
120 \item[print retain]
121 When the requested action triggers printed output for the client, this data can be
122 retrieved with a PythonPrint request. If the output is not desired, this flag
123 can be set to false, and the output will be discarded. If it is set to true the
124 output will be buffered pending retrieval by the client. The data will
125 survive also after the termination of the Python script, and if not retrieved
126 will bloat memory usage on the server.
127
128 \item[busy waiting]
129 Instead of returning a handle immediately to the client, that can be used to
130 retrieve prints and check if the script has finished, the server will answer to
131 the client only when the script has terminated to run (and it will effectively
132 work as a PythonFinished request).
133
134 \end{description}
135
136 These flags can be set and checked with the following routines (CmiUInt4 represent a 4
137 byte unsigned integer):
138
139 \begin{alltt}
140 void setCode(char *set);
141 void setPersistent(bool set);
142 void setIterate(bool set);
143 void setHighLevel(bool set);
144 void setKeepPrint(bool set);
145 void setWait(bool set);
146 void setInterpreter(CmiUInt4 i);
147
148 bool isPersistent();
149 bool isIterate();
150 bool isHighLevel();
151 bool isKeepPrint();
152 bool isWait();
153 CmiUInt4 getInterpreter();
154 \end{alltt}
155
156 From a PythonExecute request, the server will answer with a 4 byte integer
157 value, which is a handle for the interpreter that is running. It can be used to
158 request for prints, check if the script has finished, and for reusing the same
159 interpreter (if it was persistent).
160
161 A value of 0 means that there was an error and the script didn't run. This is
162 typically due to a request to reuse an existing interpreter which is not
163 available, either because it was not persistent or because another script is
164 still running on that interpreter.
165
166
167 \section{Auto-imported modules}
168 \label{pythonModules}
169
170 When a Python script is run inside a \charmpp{} application, two Python modules
171 are made available by the system. One is \textbf{ck}, the other is
172 \textbf{charm}. The first one is always present and it represent basic
173 functions, the second is related to high level scripting and it is present only
174 when this is enabled (see \ref{pythonExecute} for how to enable it, and
175 \ref{pythonHighLevel} for a description on how to implement charm functions).
176
177 The methods present in the \texttt{ck} module are the following:
178
179 \begin{description}
180
181 \item[printstr]
182 It accepts a string as parameter. It will write into the server stdout that string
183 using the \texttt{CkPrintf} function call.
184
185 \item[printclient]
186 It accepts a string as parameter. It will forward the string back to the client when it
187 issues a PythonPrint request. It will buffer the strings until requested by PythonPrint if the \texttt{KeepPrint}
188 option is true, otherwise it will discard them.
189
190 \item[mype]
191 Requires no parameters, and will return an integer representing the
192 current processor where the code is executing. It is equivalent to the \charmpp{}
193 function \texttt{CkMyPe()}.
194
195 \item[numpes]
196 Requires no parameters, and will return an integer representing the
197 total number of processors that the application is using. It is equivalent to
198 the \charmpp{} function \texttt{CkNumPes()}.
199
200 \item[myindex]
201 Requires no parameters, and will return the index of the current element
202 inside the array, if the object under which Python is running is an array, or
203 None if it is running under a Chare, a Group or a Nodegroup. The index will be a
204 tuple containing as many numbers as the dimension of the array.
205
206 \item[read]
207 It accepts one object parameter, and it will perform a read request to the
208 \charmpp{} object connected to the Python script, and return an object
209 containing the data read (see \ref{pythonServerRW} for a description of this
210 functionality). An example of a call can be:
211 \function{value = ck.read((number, param, var2, var3))}
212 where the double parenthesis are needed to create a single tuple object
213 containing four values passed as a single paramter, instead of four different
214 parameters.
215
216 \item[write]
217 It accepts two object parameters, and it will perform a write request to the
218 \charmpp{} object connected to the Python script. For a description of this
219 method, see \ref{pythonServerRW}. Again, only two objects need to be passed, so
220 extra parenthesis may be needed to create tuples from individual values.
221
222 \end{description}
223
224 \section{Iterate mode}
225 \label{pythonIterator}
226
227 Sometimes some operations need to be iterated over all the elements in the
228 system. This ``iterative'' functionality provides a shortcut for the client user
229 to do this. As an example, suppose we have a system which contains particles,
230 with their position, velocity and mass. If we implement \texttt{read} and
231 \texttt{write} routines which allow us to access single particle attributes, we may
232 upload a script which doubles the mass of the particles with velocity greater
233 than 1:
234
235 \begin{alltt}
236 size = ck.read((``numparticles'', 0));
237 for i in range(0, size):
238     vel = ck.read((``velocity'', i));
239     mass = ck.read((``mass'', i));
240     mass = mass * 2;
241     if (vel > 1): ck.write((``mass'', i), mass);
242 \end{alltt}
243
244 Instead of all these read and writes, it will be better to be able to write:
245
246 \begin{alltt}
247 def increase(p):
248     if (p.velocity > 1): p.mass = p.mass * 2;
249 \end{alltt}
250
251 This is what the ``iterative'' functionality provides. In order for this to
252 work, the server has to implement two additional functions
253 (see~\ref{pythonServerIterator}), and the client has to pass some more
254 information together with the code. This information is the name of the function
255 that has to be called (which can be defined in the ``code'' or was previously
256 uploaded to a persistent interpreter), and a user defined structure which
257 specifies over what data the function should be invoked. These values can be
258 specified either while constructing the PythonExecute variable (see the second
259 constructor in section~\ref{pythonExecute}), or with the following methods:
260
261 \begin{alltt}
262 void setMethodName(char *name);
263 void setIterator(PythonIterator *iter);
264 \end{alltt}
265
266 The \texttt{PythonIterator} object must be defined by the user, and
267 the user must insure that the same definition is present inside both the
268 client and the server. The \charmpp{} system will simply pass this structure as
269 a void pointer. This structure must inherit from \texttt{PythonIterator}.  In the simple case (highly recommended), wherein no pointers or dynamic allocation are used inside this class,  nothing else needs to be done because it is trivial to serialize such objects.
270
271 If instead pointers or dynamic memory allocation are used, the following methods
272 have to be reimplemented to support correct serialization:
273
274 \begin{alltt}
275 int size();
276 char * pack();
277 void unpack();
278 \end{alltt}
279
280 The first returns the size of the class/structure after being packed. The second
281 returns a pointer to a newly allocated memory containing all the packed data,
282 the returned memory must be compatible with the class itself, since later on
283 this same memory a call to unpack will be performed. Finally, the third will do
284 the work opposite to pack and fix all the pointers. This method will not return
285 anything and is supposed to fix the pointers ``inline''.
286
287 \section{PythonPrint}
288 \label{pythonPrint}
289
290 In order to receive the output printed by the Python script, the client needs to
291 send a PythonPrint request to the server. The constructor is:
292
293 \function{PythonPrint(CmiUInt4 interpreter, bool Wait=true, bool Kill=false);}
294
295 The interpreter for which the request is made is mandatory. The other parameters
296 are optional. The wait parameter represents whether a reply will be sent back
297 immediately to the client even if there is no output (false), or if the answer
298 will be delayed until there is an output (true). The \kw{kill} option set to
299 true means that this is not a normal request, but a signal to unblock the latest
300 print request which was blocking.
301
302 The returned data will be a non null-terminated string if some data is present
303 (or if the request is blocking), or a 4 byte zero data if nothing is present.
304 This zero reply can happen in different situations:
305
306 \begin{itemize}
307 \item If the request is non blocking and no data is available on the server;
308 \item If a kill request is sent, the previous blocking request is squashed;
309 \item If the Python code ends without any output and it is not persistent;
310 \item If another print request arrives, the previous one is squashed and the second one is kept.
311 \end{itemize}
312
313 As for a print kill request, no data is expected to come back, so it is safe to
314 call \texttt{CcsNoResponse(server)}.
315
316 The two options can also be dynamically set with the following methods:
317
318 \begin{alltt}
319 void setWait(bool set);
320 bool isWait();
321
322 void setKill(bool set);
323 bool isKill();
324 \end{alltt}
325
326 \section{PythonFinished}
327 \label{pythonFinished}
328
329 In order to know when a Python code has finished executing, especially when
330 using persistent interpreters, and a serialization of the scripts is needed, a
331 PythonFinished request is available. The constructor is the following:
332
333 \function{PythonFinished(CmiUInt4 interpreter, bool Wait=true);}
334
335 The interpreter corresponds to the handle for which the request was sent, while
336 the wait option refers to a blocking call (true), or immediate return (false).
337
338 The wait option can be dynamically modified with the two methods:
339
340 \begin{alltt}
341 void setWait(bool set);
342 bool isWait();
343 \end{alltt}
344
345 This request will return a 4 byte integer containing the same interpreter value
346 if the Python script has already finished, or zero if the script is still
347 running.
348
349 \section{Server API}
350 \label{pythonServer}
351
352 In order for a \charmpp{} object (chare, array, node, or nodegroup) to receive
353 python requests, it is necessary to define it as python-compliant. This is done
354 through the keyword \kw{python} placed in square brackets before the object name
355 in the .ci file. Some examples follow:
356
357 \begin{alltt}
358 mainchare [python] main \{\ldots\}
359 array [1D] [python] myArray \{\ldots\}
360 group [python] myGroup \{\ldots\}
361 \end{alltt}
362
363 In order to register a newly created object to receive Python scripts, the
364 method \texttt{registerPython} of the proxy should be called. As an example,
365 the following code creates a 10 element array myArray, and then registers it to
366 receive scripts directed to ``pycode''. The argument of \texttt{registerPython}
367 is the string that CCS will use to address the Python scripting capability of
368 the object.
369
370 \begin{alltt}
371 Cproxy_myArray localVar = CProxy_myArray::ckNew(10);
372 localVar.registerPython(``pycode'');
373 \end{alltt}
374
375
376 \section{Server \kw{read} and \kw{write} functions}
377 \label{pythonServerRW}
378
379 As explained previously in subsection~\ref{pythonModules}, some functions are
380 automatically made available to the scripting code through the {\em ck} module.
381 Two of these, \textbf{read} and \textbf{write} are only available if redefined
382 by the object. The signatures of the two methods to redefine are:
383
384 \begin{alltt}
385 PyObject* read(PyObject* where);
386 void write(PyObject* where, PyObject* what);
387 \end{alltt}
388
389 The read function receives as a parameter an object specifying from where the data
390 will be read, and returns an object with the information required. The write
391 function will receive two parameters: where the data will be written and what
392 data, and will perform the update. All these \texttt{PyObject}s are generic, and
393 need to be coherent with the protocol specified by the application. In order to
394 parse the parameters, and create the value of the read, please refer to the
395 manual \htmladdnormallink{``Extending and Embedding the Python Interpreter''}{http://docs.python.org/}, and in particular to the functions
396 \texttt{PyArg\_ParseTuple} and \texttt{Py\_BuildValue}.
397
398 \section{Server iterator functions}
399 \label{pythonServerIterator}
400
401 In order to use the iterative mode as explained in
402 subsection~\ref{pythonIterator}, it is necessary to implement two functions
403 which will be called by the system. These two functions have the following
404 signatures:
405
406 \begin{alltt}
407 int buildIterator(PyObject*, void*);
408 int nextIteratorUpdate(PyObject*, PyObject*, void*);
409 \end{alltt}
410
411 The first one is called once before the first execution of the Python code, and
412 receives two parameters. The first is a pointer to an empty PyObject to be filled with
413 the data needed by the Python code. In order to manage this object, some utility
414 functions are provided. They are explained in subsection~\ref{pythonUtilityFuncs}.
415
416 The second is a void pointer containing information of what the iteration should
417 run over. This parameter may contain any data structure, and an agreement between the
418 client and the user object is necessary. The system treats it as a void pointer
419 since it has no information about what user defined data it contains.
420
421 The second function (\texttt{nextIteratorUpdate}) has three
422 parameters. The first parameter contains the object to be filled
423 (similar to \texttt{buildIterator}), but the second object contains
424 the PyObject which was provided for the last iteration, potentially
425 modified by the Python function. Its content can be read with the
426 provided routines, used to retrieve the next logical element in the
427 iterator (with which to update the parameter itself), and possibly
428 update the content of the data inside the \charmpp{} object. The
429 second parameter is the object returned by the last call to the Python
430 function, and the third parameter is the same data structure passed
431 to \texttt{buildIterator}.
432
433 Both functions return an integer which will be interpreted by the system as follows:
434 \begin{description}
435 \item[1] - a new iterator in the first parameter has been provided, and the Python function should be called with it;
436 \item[0] - there are no more elements to iterate.
437 \end{description}
438
439 \section{Server utility functions}
440 \label{pythonUtilityFuncs}
441
442 These are inherited when declaring an object as Python-compliant, and therefore
443 they are available inside the object code. All of them accept a PyObject pointer
444 where to read/write the data, a string with the name of a field, and one or two
445 values containing the data to be read/written (note that to read the data from
446 the PyObject, a pointer needs to be passed). The strings used to identify the
447 fields will be the same strings that the Python script will use to access the
448 data inside the object.
449
450 The name of the function identifies the type of Python object stored inside the
451 PyObject container (i.e String, Int, Long, Float, Complex), while the parameter
452 of the functions identifies the \CC object type.
453
454 \begin{alltt}
455 void pythonSetString(PyObject*, char*, char*);
456 void pythonSetString(PyObject*, char*, char*, int);
457 void pythonSetInt(PyObject*, char*, long);
458 void pythonSetLong(PyObject*, char*, long);
459 void pythonSetLong(PyObject*, char*, unsigned long);
460 void pythonSetLong(PyObject*, char*, double);
461 void pythonSetFloat(PyObject*, char*, double);
462 void pythonSetComplex(PyObject*, char*, double, double);
463
464 void pythonGetString(PyObject*, char*, char**);
465 void pythonGetInt(PyObject*, char*, long*);
466 void pythonGetLong(PyObject*, char*, long*);
467 void pythonGetLong(PyObject*, char*, unsigned long*);
468 void pythonGetLong(PyObject*, char*, double*);
469 void pythonGetFloat(PyObject*, char*, double*);
470 void pythonGetComplex(PyObject*, char*, double*, double*);
471 \end{alltt}
472
473 To handle more complicated structures like Dictionaries, Lists or Tuples, please refer to \htmladdnormallink{``Python/C API Reference Manual''}{http://docs.python.org/}.
474
475 \section{High level scripting}
476 \label{pythonHighLevel}
477
478 When in addition to the definition of the \charmpp{} object as \kw{python}, an
479 entry method is also defined as \kw{python}, this entry method can be accessed
480 directly by a Python script through the {\em charm} module. For example, the
481 following definition will be accessible with the python call:
482 \function{result = charm.highMethod(var1, var2, var3)}
483 It can accept any number of parameters (even complex like tuples or
484 dictionaries), and it can return an object as complex as needed.
485
486 The method must have the following signature:
487
488 \begin{alltt}
489 entry [python] void highMethod(int handle);
490 \end{alltt}
491
492 The parameter is a handle that is passed by the system, and can be used in
493 subsequent calls to return values to the Python code. %Thus, if the method
494 %does not return immediately but it sends out messages to other \charmpp{}
495 %objects, the handle must be saved somewhere. \textbf{Note:} if another Python
496 %script is sent to the server, this second one could also call the same function.
497 %If this is possible, the handle should be saved in a non-scalar variable.
498
499 The arguments passed by the Python caller can be retrieved using the function:
500
501 \function{PyObject *pythonGetArg(int handle);}
502
503 which returns a PyObject. This object is a Tuple containing a vector of all
504 parameters. It can be parsed using \texttt{PyArg\_ParseTuple} to extract the
505 single parameters.
506
507 When the \charmpp's entry method terminates (by means of \texttt{return} or
508 termination of the function), control is returned to the waiting Python script.
509 Since the \kw{python} entry methods execute within an user-level thread, it is
510 possible to suspend the entry method while some computation is carried on in
511 \charmpp. To start parallel computation, the entry method can send regular messages,
512 as every other threaded entry method (see~\ref{libraryInterface} for more
513 information on how this can be done using CkCallbackResumeThread callbacks). The
514 only difference with other threaded entry methods is that here the callback
515 \texttt{CkCallbackPython} must be used instead of CkCallbackResumeThread. The
516 more specialized CkCallbackPython callback works exactly like the other one,
517 except that it correctly handles Python internal locks.
518
519 At the end of the computation, the following special function will return a value to the Python script:
520
521 \function{void pythonReturn(int handle, PyObject* result);}
522
523 where the second parameter is the Python object representing the returned value.
524 The function \texttt{Py\_BuildValue} can be used to create this value. This
525 function in itself does not terminate the entry method, but only sets the
526 returning value for Python to read when the entry method terminates.
527
528 A characteristic of Python is that in a multithreaded environment (like the one
529 provided in \charmpp{}), the running thread needs to keep a lock to prevent
530 other threads to access any variable. When using high level scripting, and the
531 Python script is suspended for long periods of time while waiting for the
532 \charmpp{} application to perform the required task, the Python internal locks
533 are automatically released and re-acquired by the \texttt{CkCallbackPython}
534 class when it suspends.
535
536 \zap{
537 This can be done using the two functions:
538
539 \begin{alltt}
540 void pythonAwake(int handle);   // to acquire the lock
541 void pythonSleep(int handle);   // to release the lock
542 \end{alltt}
543
544 Important to remember is that before any Python value is accessed, the Python
545 interpreter must be awake. This include the functions \texttt{Py\_BuildValue} and
546 \texttt{PyArg\_ParseTuple}. \textbf{Note:} it is an error to call these functions
547 more than once before the other one is called.
548 } % end zap