README file for the TCE Python bindings

This directory contains the Python bindings for TCE libraries.

Background

The bindings use the Boost.Python library for exposing C++ classes to Python. The library makes it possible to manipulate objects created by C++ libraries as if they were Python objects.

Loadable Python modules

Boost.Python produces shared objects that the Python interpreter can load as if they were regular Python modules. Once loaded with import, the C++ classes and functions in a module are visible as Python classes and functions. For example:

    $ python2.4
    Python 2.4.4c1 (#2, Oct 11 2006, 21:51:02) 
    [GCC 4.1.2 20060928 (prerelease) (Ubuntu 4.1.1-13ubuntu5)] on linux2
    Type "help", "copyright", "credits" or "license" for more information.
    >>> import TTAMachine
    >>> b = TTAMachine.Bus("b1", 32, 16, TTAMachine.Machine.Extension.ZERO)
    >>> b
    <TTAMachine.Bus object at 0xb7da2a54>
    >>> m = TTAMachine.Machine()
    >>> m
    <TTAMachine.Machine object at 0xb7da2a7c>
    >>> m.addBus(b)

You need to set PYTHONPATH to include the directory where the loadable modules are, and you also need to set LD_LIBRARY_PATH appropriately so that the TCE libraries referenced by the bindings can be found. The Python modules only provide the glue between C++ and Python.

Scheduler Passes in Python

See a separate document for information on how to write scheduler passes in Python.

Adding new bindings

Adding new classes is relatively easy, and adding new methods in existing classes is even easier. The Boost.Python tutorial gives a pretty clear idea what to do, and it is relatively safe just to copy and paste from the existing ones. The cases to be aware of are:

function that returns a raw pointer, and
function that takes a raw pointer and retains ownership of the pointer.

Both of these have to do with how C++ and Python manage objects.

When a C++ function returns a pointer, Boost.Python needs to know whether it should take care of the pointer or not. This is something that cannot be inferred from a function signature, so it needs to be explicitly stated by the programmer using a call policy, as explained in the tutorial. The two more common policies are return_internal_reference and return_value_policy<manage_new_object>.

If a C++ function (e.g. a member function) is passed a raw pointer, and the function takes ownership of the pointer, Python needs to be informed about the ownership transfer. This can be done using an auto_ptr, see the Boost.Python FAQ for details.

Useful reading

Article Building Hybrid Systems with Boost.Python, also available as PDF
Boost.Python tutorial

Pertti Kellomäki, firstname.lastname@tut.fi