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