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