adding the ccs link to dynamic code injection section
[charm.git] / doc / charm++ / python.tex
index 88d836ec1cca4508e83120d6a18ea8dfebae82f8..dcced319775503626c1c43b8d60140a4d670cc18 100644 (file)
@@ -1,12 +1,10 @@
-\subsection{Python scripting language}
-\label{python}
-
 The Python scripting language in \charmpp{} allows the user to dynamically
 execute pieces of code inside a running application, without the need to
 recompile. This is performed through the CCS (Converse Client Server) framework
-(see ``Converse Manual'' for more information about this). The user specifies
-which elements of the system will be accessible through the interface, as we
-will see later, and then run a client which connects to the server.
+(see \htmladdnormallink{Converse Manual}
+{http://charm.cs.illinois.edu/manuals/html/converse/5.html} for more information about this). 
+The user specifies which elements of the system will be accessible through the interface,
+as we will see later, and then run a client which connects to the server.
 
 In order to exploit this functionality, Python interpreter needs to be installed
 into the system, and \charmpp{} LIBS need to be built with:\\
@@ -16,7 +14,7 @@ The interface provides three different types of requests:
 
 \begin{description}
 \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;
-\item[Print] asks the server to send back all the strings which has been printed by the script until now;
+\item[Print] asks the server to send back all the strings which have been printed by the script until now;
 \item[Finished] asks the server if the current script has finished or it is still running.
 \end{description}
 
@@ -34,11 +32,11 @@ function to all the objects reflected by the iterator structure.
 \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})
 \end{itemize}
 
-The description will follow the client implementation first, and continuing then
-on the server implementation.
+This documentation will describe the client API first, and then the server API. 
+
 
+\section{Client API}
 
-\subsubsection{The client side}
 \label{pythonClient}
 
 In order to facilitate the interface between the client and the server, some
@@ -61,7 +59,7 @@ All of them have two common methods to enable communication across different pla
 
 \item[int size();]
 Returns the size of the class, as number of bytes that will be
-transmitted through the network (this include the code and other dynamic
+transmitted through the network (this includes the code and other dynamic
 variables in the case of \texttt{PythonExecute}).
 
 \item[char *pack();]
@@ -71,19 +69,19 @@ original class will be unmodified and can be reused in subsequent calls.
 
 \end{description}
 
-A tipical invocation to send a request from the client to the server have the
+A typical invocation to send a request from the client to the server has the
 following format:
 
 \begin{alltt}
 CcsSendRequest (&server, "pyCode", 0, request.size(), request.pack());
 \end{alltt}
 
-\subsubsection{PythonExecute}
+\section{PythonExecute}
 \label{pythonExecute}
 
 To execute a Python script on a running server, the client has to create an
 instance of \texttt{PythonExecute}, the two constructors have the following
-signature (java has a correspondent functionality):
+signature (java has a corresponding functionality):
 
 \begin{alltt}
 PythonExecute(char *code, bool persistent=false, bool highlevel=false, CmiUInt4 interpreter=0);
@@ -94,8 +92,8 @@ PythonExecute(char *code, char *method, PythonIterator *info, bool persistent=fa
 The second one is used for iterative requests (see~\ref{pythonIterator}). The
 only required argument is the code, a null terminated string, which will not be
 modified by the system. All the other parameters are optional. They refer to the
-possible variants that an execution request can be. In particular, this is a
-list of all the options present:
+possible variants for an execution request. In particular, this is a
+list of all the options:
 
 \begin{description}
 
@@ -104,32 +102,31 @@ If the request is a single code (false) or if it represents a function over
 which to iterate (true) (see~\ref{pythonIterator} for more details).
 
 \item[persistent]
-It is possible to store information on the server which will be retained across
-different client calls (such as simple data or complete libraries). True means
-that the information will be retained on the server, false means that the
-information will be deleted when the script terminates to run. In order to
-properly dispose the memory, when the last call is made (and the data is not
-anymore needed), this flag should be set to false. When information has been
-stored on the server, in order to reuse it, the interpreter field of the request
-should be set to the correct value (which was returned by the previous call, see
-later in this subsection).
+It is possible to store information on the server which will be
+retained across different client calls (from simple data all the way
+up to complete libraries). True means that the information will be
+retained on the server, false means that the information will be
+deleted when the script terminates. In order to properly release the
+memory, when the last call is made (and the data is no longer
+required), this flag should be set to false. To reuse persistent data,
+the interpreter field of the request should be set to handle returned by a previous persistent call (see later in this subsection).
 
 \item[high level]
 In order to have the ability to call high level \charmpp{} functions (available
-through the keywork \kw{python}) this flag must be set to true. If it is false,
+through the keyword \kw{python}) this flag must be set to true. If it is false,
 the entire module ``charm'' will not be present, but the startup of the script
 will be faster.
 
 \item[print retain]
-When the client decides to print some output back to the client, this data can be
+When the requested action triggers printed output for the client, this data can be
 retrieved with a PythonPrint request. If the output is not desired, this flag
 can be set to false, and the output will be discarded. If it is set to true the
-output will be saved waiting to be retrieved by the client. The data will
+output will be buffered pending retrieval by the client. The data will
 survive also after the termination of the Python script, and if not retrieved
-will waste memory on the server.
+will bloat memory usage on the server.
 
 \item[busy waiting]
-Instead of returning immediately to the client a handle that can be used to
+Instead of returning a handle immediately to the client, that can be used to
 retrieve prints and check if the script has finished, the server will answer to
 the client only when the script has terminated to run (and it will effectively
 work as a PythonFinished request).
@@ -162,12 +159,12 @@ request for prints, check if the script has finished, and for reusing the same
 interpreter (if it was persistent).
 
 A value of 0 means that there was an error and the script didn't run. This is
-typically due to a request to reuse of an existing interpreter which is not
+typically due to a request to reuse an existing interpreter which is not
 available, either because it was not persistent or because another script is
 still running on that interpreter.
 
 
-\subsubsection{Auto-imported modules}
+\section{Auto-imported modules}
 \label{pythonModules}
 
 When a Python script is run inside a \charmpp{} application, two Python modules
@@ -187,21 +184,21 @@ using the \texttt{CkPrintf} function call.
 
 \item[printclient]
 It accepts a string as parameter. It will forward the string back to the client when it
-issue a PythonPrint request. It will buffer the strings if the \texttt{KeepPrint}
+issues a PythonPrint request. It will buffer the strings until requested by PythonPrint if the \texttt{KeepPrint}
 option is true, otherwise it will discard them.
 
 \item[mype]
-It requires no parameters, and it will return an integer representing the
+Requires no parameters, and will return an integer representing the
 current processor where the code is executing. It is equivalent to the \charmpp{}
 function \texttt{CkMyPe()}.
 
 \item[numpes]
-It requires no parameters, and it will return an integer representing the
+Requires no parameters, and will return an integer representing the
 total number of processors that the application is using. It is equivalent to
 the \charmpp{} function \texttt{CkNumPes()}.
 
 \item[myindex]
-It requires no parameters, and it will return the index of the current element
+Requires no parameters, and will return the index of the current element
 inside the array, if the object under which Python is running is an array, or
 None if it is running under a Chare, a Group or a Nodegroup. The index will be a
 tuple containing as many numbers as the dimension of the array.
@@ -210,7 +207,7 @@ tuple containing as many numbers as the dimension of the array.
 It accepts one object parameter, and it will perform a read request to the
 \charmpp{} object connected to the Python script, and return an object
 containing the data read (see \ref{pythonServerRW} for a description of this
-functionality). An example of call can be:
+functionality). An example of call can be:
 \function{value = ck.read((number, param, var2, var3))}
 where the double parenthesis are needed to create a single tuple object
 containing four values passed as a single paramter, instead of four different
@@ -219,19 +216,19 @@ parameters.
 \item[write]
 It accepts two object parameters, and it will perform a write request to the
 \charmpp{} object connected to the Python script. For a description of this
-method, see \ref{pythonServerRW}. Again, only two object need to be passed, so
+method, see \ref{pythonServerRW}. Again, only two objects need to be passed, so
 extra parenthesis may be needed to create tuples from individual values.
 
 \end{description}
 
-\subsubsection{Iterate mode}
+\section{Iterate mode}
 \label{pythonIterator}
 
 Sometimes some operations need to be iterated over all the elements in the
-system. This ``iterative'' functinality provides a shortcup for the client user
-to do this. With an example, suppose we have a system which contains particles,
-with their position, velocity and mass. If we implement \texttt{read} and
-\texttt{write} routines which allow to access single particle attributes, we may
+system. This ``iterative'' functionality provides a shortcut for the client user
+to do this. As an example, suppose we have a system which contains particles,
+with their position, velocity and mass. If we implement \texttt{read} and
+\texttt{write} routines which allow us to access single particle attributes, we may
 upload a script which doubles the mass of the particles with velocity greater
 than 1:
 
@@ -255,7 +252,7 @@ This is what the ``iterative'' functionality provides. In order for this to
 work, the server has to implement two additional functions
 (see~\ref{pythonServerIterator}), and the client has to pass some more
 information together with the code. This information is the name of the function
-that has to be called (which can be defined in the ``code'' or have already been
+that has to be called (which can be defined in the ``code'' or was previously
 uploaded to a persistent interpreter), and a user defined structure which
 specifies over what data the function should be invoked. These values can be
 specified either while constructing the PythonExecute variable (see the second
@@ -266,15 +263,13 @@ void setMethodName(char *name);
 void setIterator(PythonIterator *iter);
 \end{alltt}
 
-As for the PythonIterator object, it has to be a class defined by the user, and
-the user has to insure that the same definition is present inside both the
+The \texttt{PythonIterator} object must be defined by the user, and
+the user must insure that the same definition is present inside both the
 client and the server. The \charmpp{} system will simply pass this structure as
-a void pointer. This structure needs to inherit from \texttt{PythonIterator}. It
-is recommended that no pointers are used inside this class, and no dynamic
-memory allocation. If this is the case, nothing else needs to be done.
+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.
 
-If instead pointers and dynamic memory allocation is used, the following methods
-have to be reimplemented:
+If instead pointers or dynamic memory allocation are used, the following methods
+have to be reimplemented to support correct serialization:
 
 \begin{alltt}
 int size();
@@ -289,7 +284,7 @@ this same memory a call to unpack will be performed. Finally, the third will do
 the work opposite to pack and fix all the pointers. This method will not return
 anything and is supposed to fix the pointers ``inline''.
 
-\subsubsection{PythonPrint}
+\section{PythonPrint}
 \label{pythonPrint}
 
 In order to receive the output printed by the Python script, the client needs to
@@ -312,7 +307,7 @@ This zero reply can happen in different situations:
 \item If the request is non blocking and no data is available on the server;
 \item If a kill request is sent, the previous blocking request is squashed;
 \item If the Python code ends without any output and it is not persistent;
-\item If another print requests arrive, the previous one is squashed and the second one is kept.
+\item If another print request arrives, the previous one is squashed and the second one is kept.
 \end{itemize}
 
 As for a print kill request, no data is expected to come back, so it is safe to
@@ -328,16 +323,16 @@ void setKill(bool set);
 bool isKill();
 \end{alltt}
 
-\subsubsection{PythonFinished}
+\section{PythonFinished}
 \label{pythonFinished}
 
-In order to know when a Python code has finished to execute, especially when
+In order to know when a Python code has finished executing, especially when
 using persistent interpreters, and a serialization of the scripts is needed, a
 PythonFinished request is available. The constructor is the following:
 
 \function{PythonFinished(CmiUInt4 interpreter, bool Wait=true);}
 
-The interpreter correspond to the handle for which the request was sent, while
+The interpreter corresponds to the handle for which the request was sent, while
 the wait option refers to a blocking call (true), or immediate return (false).
 
 The wait option can be dynamically modified with the two methods:
@@ -351,7 +346,7 @@ This request will return a 4 byte integer containing the same interpreter value
 if the Python script has already finished, or zero if the script is still
 running.
 
-\subsubsection{The server side}
+\section{Server API}
 \label{pythonServer}
 
 In order for a \charmpp{} object (chare, array, node, or nodegroup) to receive
@@ -366,8 +361,8 @@ group [python] myGroup \{\ldots\}
 \end{alltt}
 
 In order to register a newly created object to receive Python scripts, the
-method \texttt{registerPython} of the proxy should be called. With an example,
-the following code creates a 10 elements array myArray, and then registers it to
+method \texttt{registerPython} of the proxy should be called. As an example,
+the following code creates a 10 element array myArray, and then registers it to
 receive scripts directed to ``pycode''. The argument of \texttt{registerPython}
 is the string that CCS will use to address the Python scripting capability of
 the object.
@@ -378,7 +373,7 @@ localVar.registerPython(``pycode'');
 \end{alltt}
 
 
-\subsubsection{Server \kw{read} and \kw{write} functions}
+\section{Server \kw{read} and \kw{write} functions}
 \label{pythonServerRW}
 
 As explained previously in subsection~\ref{pythonModules}, some functions are
@@ -391,23 +386,22 @@ PyObject* read(PyObject* where);
 void write(PyObject* where, PyObject* what);
 \end{alltt}
 
-The read function receives as parameter an object specifying from where the data
+The read function receives as parameter an object specifying from where the data
 will be read, and returns an object with the information required. The write
 function will receive two parameters: where the data will be written and what
 data, and will perform the update. All these \texttt{PyObject}s are generic, and
 need to be coherent with the protocol specified by the application. In order to
 parse the parameters, and create the value of the read, please refer to the
-manual ``Extending and Embedding the Python Interpreter''
-(http://docs.python.org/), and in particular to the functions
+manual \htmladdnormallink{``Extending and Embedding the Python Interpreter''}{http://docs.python.org/}, and in particular to the functions
 \texttt{PyArg\_ParseTuple} and \texttt{Py\_BuildValue}.
 
-\subsubsection{Server iterator functions}
+\section{Server iterator functions}
 \label{pythonServerIterator}
 
 In order to use the iterative mode as explained in
 subsection~\ref{pythonIterator}, it is necessary to implement two functions
-which will be called by the system. This two functions have the following
-signature:
+which will be called by the system. These two functions have the following
+signatures:
 
 \begin{alltt}
 int buildIterator(PyObject*, void*);
@@ -415,24 +409,26 @@ int nextIteratorUpdate(PyObject*, PyObject*, void*);
 \end{alltt}
 
 The first one is called once before the first execution of the Python code, and
-receives to parameters. The first is a pointer to an empty PyObject to be filled with
+receives two parameters. The first is a pointer to an empty PyObject to be filled with
 the data needed by the Python code. In order to manage this object, some utility
 functions are provided. They are explained in subsection~\ref{pythonUtilityFuncs}.
 
 The second is a void pointer containing information of what the iteration should
 run over. This parameter may contain any data structure, and an agreement between the
 client and the user object is necessary. The system treats it as a void pointer
-since it has no information of what user defined data it contains.
-
-The second function (\texttt{nextIteratorUpdate}) has three parameters. The
-first contains the object to be filled like in \texttt{buildIterator}, but this
-time the object contains the PyObject which was provided for the last iteration,
-potentially modified by the Python function. Its content can be read with the
-provided routines, used to retrieve the next logical element in the iterator
-(with which to update the parameter itself), and possibly update the content of
-the data inside the \charmpp{} object. The second parameter is the object
-returned by the last call to the Python function, and the third parameter is the
-same data structure passed to \texttt{buildIterator}.
+since it has no information about what user defined data it contains.
+
+The second function (\texttt{nextIteratorUpdate}) has three
+parameters. The first parameter contains the object to be filled
+(similar to \texttt{buildIterator}), but the second object contains
+the PyObject which was provided for the last iteration, potentially
+modified by the Python function. Its content can be read with the
+provided routines, used to retrieve the next logical element in the
+iterator (with which to update the parameter itself), and possibly
+update the content of the data inside the \charmpp{} object. The
+second parameter is the object returned by the last call to the Python
+function, and the third parameter is the same data structure passed
+to \texttt{buildIterator}.
 
 Both functions return an integer which will be interpreted by the system as follows:
 \begin{description}
@@ -440,10 +436,10 @@ Both functions return an integer which will be interpreted by the system as foll
 \item[0] - there are no more elements to iterate.
 \end{description}
 
-\subsubsection{Server utility functions}
+\section{Server utility functions}
 \label{pythonUtilityFuncs}
 
-They are inherited when declaring an object as Python-compliant, and therefore
+These are inherited when declaring an object as Python-compliant, and therefore
 they are available inside the object code. All of them accept a PyObject pointer
 where to read/write the data, a string with the name of a field, and one or two
 values containing the data to be read/written (note that to read the data from
@@ -474,15 +470,15 @@ void pythonGetFloat(PyObject*, char*, double*);
 void pythonGetComplex(PyObject*, char*, double*, double*);
 \end{alltt}
 
-To handle more complicated structures like Dictionaries, Lists or Tuples, please refer to ``Python/C API Reference Manual'' (http://docs.python.org/).
+To handle more complicated structures like Dictionaries, Lists or Tuples, please refer to \htmladdnormallink{``Python/C API Reference Manual''}{http://docs.python.org/}.
 
-\subsubsection{High level scripting}
+\section{High level scripting}
 \label{pythonHighLevel}
 
-When other than defining the \charmpp{} object as \kw{python}, an entry method
-is also defined python, it can be accessed directly by a Python script through the
-{\em charm} module. For example, the following definition will be accessible
-with the python call:
+When in addition to the definition of the \charmpp{} object as \kw{python}, an
+entry method is also defined as \kw{python}, this entry method can be accessed
+directly by a Python script through the {\em charm} module. For example, the
+following definition will be accessible with the python call:
 \function{result = charm.highMethod(var1, var2, var3)}
 It can accept any number of parameters (even complex like tuples or
 dictionaries), and it can return an object as complex as needed.
@@ -493,43 +489,60 @@ The method must have the following signature:
 entry [python] void highMethod(int handle);
 \end{alltt}
 
-The parameter is a handle that is passed by the system and has to be used in
-subsequest calls to return the control to the Python code. Thus, if the method
-does not return immediately but it sends out messages to other \charmpp{}
-objects, the handle must be saved somewhere. \textbf{Note:} if another Python
-script is sent to the server, this second one could also call the same function.
-If this is possible, the handle should be saved in a non-scalar variable.
+The parameter is a handle that is passed by the system, and can be used in
+subsequent calls to return values to the Python code. %Thus, if the method
+%does not return immediately but it sends out messages to other \charmpp{}
+%objects, the handle must be saved somewhere. \textbf{Note:} if another Python
+%script is sent to the server, this second one could also call the same function.
+%If this is possible, the handle should be saved in a non-scalar variable.
 
 The arguments passed by the Python caller can be retrieved using the function:
 
 \function{PyObject *pythonGetArg(int handle);}
 
-which will return a PyObject. This object is a Tuple containing a vector of all
+which returns a PyObject. This object is a Tuple containing a vector of all
 parameters. It can be parsed using \texttt{PyArg\_ParseTuple} to extract the
 single parameters.
 
-At the end of the computation, when the control flow must be retuned to the
-Python script, a special returning function needs to be called:
+When the \charmpp's entry method terminates (by means of \texttt{return} or
+termination of the function), control is returned to the waiting Python script.
+Since the \kw{python} entry methods execute within an user-level thread, it is
+possible to suspend the entry method while some computation is carried on in
+\charmpp. To start parallel computation, the entry method can send regular messages,
+as every other threaded entry method (see~\ref{libraryInterface} for more
+information on how this can be done using CkCallbackResumeThread callbacks). The
+only difference with other threaded entry methods is that here the callback
+\texttt{CkCallbackPython} must be used instead of CkCallbackResumeThread. The
+more specialized CkCallbackPython callback works exactly like the other one,
+except that it correctly handles Python internal locks.
+
+At the end of the computation, the following special function will return a value to the Python script:
 
 \function{void pythonReturn(int handle, PyObject* result);}
 
-where the second parameter is optional, and needs to be present only if a result
-is returned to Python. The function \texttt{Py\_BuildValue} can be used to create
-this value.
+where the second parameter is the Python object representing the returned value.
+The function \texttt{Py\_BuildValue} can be used to create this value. This
+function in itself does not terminate the entry method, but only sets the
+returning value for Python to read when the entry method terminates.
 
 A characteristic of Python is that in a multithreaded environment (like the one
-provided in \charmpp{}), the runinng thread needs to keep a lock to prevent
+provided in \charmpp{}), the running thread needs to keep a lock to prevent
 other threads to access any variable. When using high level scripting, and the
-Python script is suspended for long times waiting for the \charmpp{} application
-to perform the required task, it may be useful to release the lock to allow
-other threads to run. This can be done using the two functions:
+Python script is suspended for long periods of time while waiting for the
+\charmpp{} application to perform the required task, the Python internal locks
+are automatically released and re-acquired by the \texttt{CkCallbackPython}
+class when it suspends.
+
+\zap{
+This can be done using the two functions:
 
 \begin{alltt}
 void pythonAwake(int handle);   // to acquire the lock
 void pythonSleep(int handle);   // to release the lock
 \end{alltt}
 
-Important to remember is that before any Python value is access, the Python
+Important to remember is that before any Python value is accessed, the Python
 interpreter must be awake. This include the functions \texttt{Py\_BuildValue} and
 \texttt{PyArg\_ParseTuple}. \textbf{Note:} it is an error to call these functions
 more than once before the other one is called.
+} % end zap