inserting new section about Python scripting.
authorFilippo Gioachin <gioachin@illinois.edu>
Tue, 8 Mar 2005 00:56:46 +0000 (00:56 +0000)
committerFilippo Gioachin <gioachin@illinois.edu>
Tue, 8 Mar 2005 00:56:46 +0000 (00:56 +0000)
doc/charm++/Makefile
doc/charm++/entry.tex
doc/charm++/manual.tex
doc/charm++/python.tex [new file with mode: 0644]

index 79974ec18c225ea290491ceaa6c1e086533d513c..15672e73b1e7e97a9ba163d7760500a7be9575e6 100644 (file)
@@ -4,7 +4,8 @@ TEX=$(FILE).tex arrays.tex callbacks.tex chares.tex commlib.tex delegation.tex \
        entry.tex further.tex groups.tex inhertmplt.tex index.tex intro.tex \
        io.tex loadb.tex advancedlb.tex \
        marshalling.tex messages.tex modules.tex nodegroups.tex othercalls.tex \
-       overview.tex pup.tex quiesce.tex readonly.tex reductions.tex sdag.tex
+       overview.tex pup.tex quiesce.tex readonly.tex reductions.tex sdag.tex \
+       python.tex
 DEST=charm++
 LATEX2HTML=$(L2H) -split 5
 
index 48950fe8a924d53563aee7944571eaf24f6c210c..e4e4d487c0b3eceb0b1c0947d4049efc05b07d7c 100644 (file)
@@ -41,19 +41,20 @@ entry [\uw{attribute1}, ..., \uw{attributeN}] void \uw{EntryMethod}(\uw{paramete
 entry method:
 \kw{threaded}, \kw{sync}, \kw{exclusive}, \kw{nokeep}, \kw{notrace}, \kw{immediate}, \kw{expedited}.
 
-\index{threaded}Threaded \index{entry method}entry methods are simply entry
+\begin{description}
+\index{threaded}\item[Threaded] \index{entry method}entry methods are simply entry
 methods which are run in their own nonpremptible threads.  To make an
 \index{entry method}entry method threaded, one simply adds the keyword
 \kw{threaded} to the attribute list of that entry method.
 
-\index{sync}Sync \index{entry method}entry methods are special in that calls to
+\index{sync}\item[Sync] \index{entry method}entry methods are special in that calls to
 sync entry methods are blocking - they do not return control to the caller
 until the method is finished executing completely.  Sync methods may have
 return values; however, they may only return messages.  To make an \index{entry
 method}entry method a sync entry method, add the keyword \kw{sync} to the
 attribute list of that entry method.
 
-\index{exclusive}Exclusive entry methods, which exist only on node groups, are
+\index{exclusive}\item[Exclusive] entry methods, which exist only on node groups, are
 \index{entry method}entry methods that do not execute while other exclusive
 \index{entry method}entry methods of its node group are executing in the same
 node.  If one exclusive method of a node group is executing on node 0, and
@@ -62,35 +63,38 @@ will wait for the first to finish before it executes.  To make an \index{entry
 method}entry method exclusive, add the keyword \kw{exclusive} to that
 entry method's attribute list.
 
-\index{nokeep}{\bf Nokeep} entry methods tells Charm++ that messages passed to
+\index{nokeep}\item[Nokeep] entry methods tells Charm++ that messages passed to
 these user entry methods will not be kept by the calls. Charm++ runtime
 may be able to adopt optimization for reusing the message memory.
 
-\index{notrace}{\bf Notrace} entry methods simply tells Charm++ that calls to 
+\index{notrace}\item[Notrace] entry methods simply tells Charm++ that calls to 
 these entry methods should be not traced in trace projections or summary mode.
 
-\index{immediate}{\bf Immediate} entry methods are entry functions in which 
-short messages can be executed in an ``immediate'' fashion when they are 
-received either by an interrupt (Network version) or by a communication 
-thread (in SMP version). Such messages can be useful for 
-implementing multicasts/reductions as well as data lookup, in which case 
-processing of critical messages won't be delayed (in the scheduler queue) 
-by entry functions that could take long time to finish. 
-Immediate messages are only available for nodegroup entry methods.
-Immediate messages are implicitly ``exclusive'' on each node, that is 
-one execution of immediate message will not be interrupted by another.
-Function \kw{CmiProbeImmediateMsg()} can be called in users code to 
+\index{immediate}\item[Immediate] entry methods are entry functions in which 
+short messages can be executed in an ``immediate'' fashion when they are
+received either by an interrupt (Network version) or by a communication thread
+(in SMP version). Such messages can be useful for implementing
+multicasts/reductions as well as data lookup, in which case processing of
+critical messages won't be delayed (in the scheduler queue) by entry functions
+that could take long time to finish. Immediate messages are only available for
+nodegroup entry methods. Immediate messages are implicitly ``exclusive'' on each
+node, that is one execution of immediate message will not be interrupted by
+another. Function \kw{CmiProbeImmediateMsg()} can be called in users code to
 probe and process immediate messages periodically.
 
-\index{expedited}{\bf Expedited} entry methods are entry functions 
-that skip Charm++'s priority-based message queue. It is useful for messages 
-that require prompt processing however in the situation when immediate message 
-does not apply. Compared with immediate message, it provides a more general
-solution that works for all Charm++ objects, i.e. Chare, Group, NodeGroup 
-and Chare Array. However, skipscheduler message still needs to be 
-scheduled in low level Converse message queue and be processed in the order 
-of arrival. It may still suffer from long running entry methods.
-
+\index{expedited}\item[Expedited] entry methods are entry functions 
+that skip Charm++'s priority-based message queue. It is useful for messages that
+require prompt processing however in the situation when immediate message does
+not apply. Compared with immediate message, it provides a more general solution
+that works for all Charm++ objects, i.e. Chare, Group, NodeGroup and Chare
+Array. However, skipscheduler message still needs to be scheduled in low level
+Converse message queue and be processed in the order of arrival. It may still
+suffer from long running entry methods.
 
 
+\index{python}\item[Python] entry methods are methods which are enabled to be
+called from python scripts running as explained in section~\ref{python}. In
+order to work, the object owning the method must also be declared with the
+keywork \kw{python}.
 
+\end{description}
index 5daa26034e0b8de340b747ee5653a9b0406ae396..e1a06ba2c555ba5383388123a693b1a1bd9e57d5 100644 (file)
@@ -79,6 +79,7 @@ for the changes to the system since the last release.
   \input{othercalls}    
   \input{delegation}    
   \input{commlib}
+  \input{python}
 \input{inhertmplt}
 
 \input{checkpoint}
diff --git a/doc/charm++/python.tex b/doc/charm++/python.tex
new file mode 100644 (file)
index 0000000..88d836e
--- /dev/null
@@ -0,0 +1,535 @@
+\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.
+
+In order to exploit this functionality, Python interpreter needs to be installed
+into the system, and \charmpp{} LIBS need to be built with:\\
+\texttt{./build LIBS $<$arch$>$ $<$options$>$}
+
+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[Finished] asks the server if the current script has finished or it is still running.
+\end{description}
+
+There are three modes to run code on the server, ordered here by increase of
+functionality, and decrease of dynamic flexibility:
+\begin{itemize}
+\item \textbf{simple read/write} By implementing the \kw{read} and \kw{write} methods
+of the object exposed to python, in this way single variables may be exposed,
+and the code will have the possibility to modify them individually as desired.
+(see section~\ref{pythonServerRW})
+\item \textbf{iteration} By implementing the iterator functions in the server (see
+\ref{pythonServerIterator}), the user can upload the code of a Python function
+and a user-defined iterator structure, and the system will apply the specified
+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.
+
+
+\subsubsection{The client side}
+\label{pythonClient}
+
+In order to facilitate the interface between the client and the server, some
+classes are available to the user to include into the client. Currently \CC{} and
+java interfaces are provided.
+
+\CC{} programs need to include \texttt{PythonCCS-client.h} into their
+code. This file is among the \charmpp{} include files. For java, the package
+\texttt{charm.ccs} needs to be imported. This is located under the java
+directory on the \charmpp{} distribution, and it provides both the Python and
+CCS interface classes.
+
+There are three main classes provided: \texttt{PythonExecute},
+\texttt{PythonPrint}, and \texttt{PythonFinished} which are used for the three
+different types of request.
+
+All of them have two common methods to enable communication across different platforms:
+
+\begin{description}
+
+\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
+variables in the case of \texttt{PythonExecute}).
+
+\item[char *pack();]
+Returns a new memory location containing the data to be sent to the server, this
+is the data which has to be passed to the \texttt{CcsSendRequest} function. The
+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
+following format:
+
+\begin{alltt}
+CcsSendRequest (&server, "pyCode", 0, request.size(), request.pack());
+\end{alltt}
+
+\subsubsection{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):
+
+\begin{alltt}
+PythonExecute(char *code, bool persistent=false, bool highlevel=false, CmiUInt4 interpreter=0);
+PythonExecute(char *code, char *method, PythonIterator *info, bool persistent=false,
+              bool highlevel=false, CmiUInt4 interpreter=0);
+\end{alltt}
+
+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:
+
+\begin{description}
+
+\item[iterative]
+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).
+
+\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,
+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
+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
+survive also after the termination of the Python script, and if not retrieved
+will waste memory on the server.
+
+\item[busy waiting]
+Instead of returning immediately to the client a handle 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).
+
+\end{description}
+
+These flags can be set and checked with the following routines (CmiUInt4 represent a 4
+byte unsigned integer):
+
+\begin{alltt}
+void setCode(char *set);
+void setPersistent(bool set);
+void setIterate(bool set);
+void setHighLevel(bool set);
+void setKeepPrint(bool set);
+void setWait(bool set);
+void setInterpreter(CmiUInt4 i);
+
+bool isPersistent();
+bool isIterate();
+bool isHighLevel();
+bool isKeepPrint();
+bool isWait();
+CmiUInt4 getInterpreter();
+\end{alltt}
+
+From a PythonExecute request, the server will answer with a 4 byte integer
+value, which is a handle for the interpreter that is running. It can be used to
+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
+available, either because it was not persistent or because another script is
+still running on that interpreter.
+
+
+\subsubsection{Auto-imported modules}
+\label{pythonModules}
+
+When a Python script is run inside a \charmpp{} application, two Python modules
+are made available by the system. One is \textbf{ck}, the other is
+\textbf{charm}. The first one is always present and it represent basic
+functions, the second is related to high level scripting and it is present only
+when this is enabled (see \ref{pythonExecute} for how to enable it, and
+\ref{pythonHighLevel} for a description on how to implement charm functions).
+
+The methods present in the \texttt{ck} module are the following:
+
+\begin{description}
+
+\item[printstr]
+It accepts a string as parameter. It will write into the server stdout that string
+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}
+option is true, otherwise it will discard them.
+
+\item[mype]
+It requires no parameters, and it 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
+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
+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.
+
+\item[read]
+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:
+\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
+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
+extra parenthesis may be needed to create tuples from individual values.
+
+\end{description}
+
+\subsubsection{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 a \texttt{read} and
+\texttt{write} routines which allow to access single particle attributes, we may
+upload a script which doubles the mass of the particles with velocity greater
+than 1:
+
+\begin{alltt}
+size = ck.read((``numparticles'', 0));
+for i in range(0, size):
+    vel = ck.read((``velocity'', i));
+    mass = ck.read((``mass'', i));
+    mass = mass * 2;
+    if (vel > 1): ck.write((``mass'', i), mass);
+\end{alltt}
+
+Instead of all these read and writes, it will be better to be able to write:
+
+\begin{alltt}
+def increase(p):
+    if (p.velocity > 1): p.mass = p.mass * 2;
+\end{alltt}
+
+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
+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
+constructor in section~\ref{pythonExecute}), or with the following methods:
+
+\begin{alltt}
+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
+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.
+
+If instead pointers and dynamic memory allocation is used, the following methods
+have to be reimplemented:
+
+\begin{alltt}
+int size();
+char * pack();
+void unpack();
+\end{alltt}
+
+The first returns the size of the class/structure after being packed. The second
+returns a pointer to a newly allocated memory containing all the packed data,
+the returned memory must be compatible with the class itself, since later on
+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}
+\label{pythonPrint}
+
+In order to receive the output printed by the Python script, the client needs to
+send a PythonPrint request to the server. The constructor is:
+
+\function{PythonPrint(CmiUInt4 interpreter, bool Wait=true, bool Kill=false);}
+
+The interpreter for which the request is made is mandatory. The other parameters
+are optional. The wait parameter represents whether a reply will be sent back
+immediately to the client even if there is no output (false), or if the answer
+will be delayed until there is an output (true). The \kw{kill} option set to
+true means that this is not a normal request, but a signal to unblock the latest
+print request which was blocking.
+
+The returned data will be a non null-terminated string if some data is present
+(or if the request is blocking), or a 4 byte zero data if nothing is present.
+This zero reply can happen in different situations:
+
+\begin{itemize}
+\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.
+\end{itemize}
+
+As for a print kill request, no data is expected to come back, so it is safe to
+call \texttt{CcsNoResponse(server)}.
+
+The two options can also be dynamically set with the following methods:
+
+\begin{alltt}
+void setWait(bool set);
+bool isWait();
+
+void setKill(bool set);
+bool isKill();
+\end{alltt}
+
+\subsubsection{PythonFinished}
+\label{pythonFinished}
+
+In order to know when a Python code has finished to execute, 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 wait option refers to a blocking call (true), or immediate return (false).
+
+The wait option can be dynamically modified with the two methods:
+
+\begin{alltt}
+void setWait(bool set);
+bool isWait();
+\end{alltt}
+
+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}
+\label{pythonServer}
+
+In order for a \charmpp{} object (chare, array, node, or nodegroup) to receive
+python requests, it is necessary to define it as python-compliant. This is done
+through the keyword \kw{python} placed in square brackets before the object name
+in the .ci file. Some examples follow:
+
+\begin{alltt}
+mainchare [python] main \{\ldots\}
+array [1D] [python] myArray \{\ldots\}
+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
+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.
+
+\begin{alltt}
+Cproxy_myArray localVar = CProxy_myArray::ckNew(10);
+localVar.registerPython(``pycode'');
+\end{alltt}
+
+
+\subsubsection{Server \kw{read} and \kw{write} functions}
+\label{pythonServerRW}
+
+As explained previously in subsection~\ref{pythonModules}, some functions are
+automatically made available to the scripting code through the {\em ck} module.
+Two of these, \textbf{read} and \textbf{write} are only available if redefined
+by the object. The signatures of the two methods to redefine are:
+
+\begin{alltt}
+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
+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
+\texttt{PyArg\_ParseTuple} and \texttt{Py\_BuildValue}.
+
+\subsubsection{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:
+
+\begin{alltt}
+int buildIterator(PyObject*, void*);
+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
+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}.
+
+Both functions return an integer which will be interpreted by the system as follows:
+\begin{description}
+\item[1] - a new iterator in the first parameter has been provided, and the Python function should be called with it;
+\item[0] - there are no more elements to iterate.
+\end{description}
+
+\subsubsection{Server utility functions}
+\label{pythonUtilityFuncs}
+
+They 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
+the PyObject, a pointer needs to be passed). The strings used to identify the
+fields will be the same strings that the Python script will use to access the
+data inside the object.
+
+The name of the function identifies the type of Python object stored inside the
+PyObject container (i.e String, Int, Long, Float, Complex), while the parameter
+of the functions identifies the \CC object type.
+
+\begin{alltt}
+void pythonSetString(PyObject*, char*, char*);
+void pythonSetString(PyObject*, char*, char*, int);
+void pythonSetInt(PyObject*, char*, long);
+void pythonSetLong(PyObject*, char*, long);
+void pythonSetLong(PyObject*, char*, unsigned long);
+void pythonSetLong(PyObject*, char*, double);
+void pythonSetFloat(PyObject*, char*, double);
+void pythonSetComplex(PyObject*, char*, double, double);
+
+void pythonGetString(PyObject*, char*, char**);
+void pythonGetInt(PyObject*, char*, long*);
+void pythonGetLong(PyObject*, char*, long*);
+void pythonGetLong(PyObject*, char*, unsigned long*);
+void pythonGetLong(PyObject*, char*, double*);
+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/).
+
+\subsubsection{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:
+\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.
+
+The method must have the following signature:
+
+\begin{alltt}
+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 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
+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:
+
+\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.
+
+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
+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:
+
+\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
+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.