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