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