coriolis/documentation/PythonCpp/Introduction.rst

.. -*- Mode: rst -*-

.. include:: ../etc/definitions.rst


1. Introduction
=================

* This document is written for people already familiar with the
  `Python/C API Reference Manual`_.

* The macros provided by the Hurricane Python/C API are written using
  the standard Python C/API. That is, you may not use them and write
  directly your functions with the original API or any mix between.
  You only have to respect some naming convention.

* Coriolis is build against Python 2.7.


1.1 First, A Disclaimer
~~~~~~~~~~~~~~~~~~~~~~~~~

The Hurricane Python/C++ API has been written about ten years ago, at a time
my mastering of template programming was less than complete. This is why this
interface is build with old fashioned C macro instead of C++ template.

It is my hope that at some point in the future I will have time to completly
rewrite it, borrowing the interface from ``boost::python``.


1.2 About Technical Choices
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Some would say, why not use *off the shelf* wrappers like  ``swig``
or ``boost::python``, here are some clues.

#. **Partial exposure of the C++ class tree.** We expose at Python level
   C++ base classes, only if they provides common methods that we want
   to see. Otherwise, we just show them as base classes under Python.
   For instance ``Library`` is derived from ``DBo``, but we won't see
   it under Python.

#. **Bi-directional communication.** When a Python object is deleted, the
   wrapper obviously has a pointer toward the underlying C++ object and
   is able to delete it. But, the reverse case can occurs, meaning that
   you have a C++ object wrapped in Python and the database delete the
   underlying object. The wrapped Python object *must* be informed that
   it no longer refer a valid C++ one. Moreover, as we do not control
   when Python objects gets deleteds (that is, when their reference count
   reaches zero), we can have valid Python object with a dangling
   C++ pointer. So our Python objects can be warned by the C++ objects
   that they are no longer valid and any other operation than the
   deletion should result in a severe non-blocking error.

   To be precise, this apply to persistent object in the C++ database,
   like ``Cell``, ``Net``, ``Instance`` or ``Component``. Short lived
   objects like ``Box`` or ``Point`` retains the classic Python behavior.

   Another aspect is that, for all derived ``DBo`` objects, one and only
   one Python object is associated. For one given ``Instance`` object we
   will always return the *same* ``PyInstance`` object, thanks to the
   bi-directional link. Obviously, the *reference count* of the
   ``PyInstance`` is managed accordingly. This mechanism is implemented
   by the ``PyInstance_Link()`` function.

#. **Linking accross modules.** As far as I understand, the wrappers
   are for monolithic libraries. That is, you wrap the entire library
   in one go. But Hurricane has a modular design, the core database
   then various tools. We do not, and cannot, have one gigantic wrapper
   that would encompass all the libraries in one go. We do one Python
   module for one C++ library.

   This brings another issue, at Python level this time. The Python
   modules for the libraries have to share some functions. Python
   provides a mechanism to pass C function pointers accross modules,
   but I did found it cumbersome. Instead, all our modules are split
   in two:

   * The first part contains the classic Python module code.
   * The second part is to be put in a separate dynamic library that
     will hold the shared functions. The Python module is dynamically linked
     against that library like any other. And any other Python module
     requiring the functions will link against the associated shared
     library.

   Each module file will be compiled *twice*, once to build the Python
   module (``__PYTHON_MODULE`` is defined) and once to build the supporting
   shared library (``__PYTHON_MODULE__`` **not** defined). This tricky
   double compilation is taken care of though the ``add_python_module``
   ``cmake`` macro.

   For the core Hurricane library we will have:

   * ``Hurricane.so`` the Python module (use with: ``import Hurricane``).
   * ``libisobar.so.1.0`` the supporting shared library.
 
   The ``PyLibrary.cpp`` file will have the following structure:

   .. code-block:: c++

      #include "hurricane/isobar/PyLibrary.h"

      namespace  Isobar {
      
        extern "C" {
      
      #if defined(__PYTHON_MODULE__)
      
        // +=================================================================+
        // |               "PyLibrary" Python Module Code Part               |
        // +=================================================================+
        //
        // The classic part of a Python module. Goes into Hurricane.so.
      
      
      #else  // End of Python Module Code Part.
      
        // x=================================================================x
        // |              "PyLibrary" Shared Library Code Part               |
        // x=================================================================x
        //
        // Functions here will be part of the associated shared library and
        // made available to all other Python modules. Goes into libisobar.so.1.0
      
      
      # endif  // Shared Library Code Part.
      
        }  // extern "C".
      
      }  // Isobar namespace.


   This way, we do not rely upon a pointer transmission through Python
   modules, but directly uses linker capabilities.


1.3 Botched Design
~~~~~~~~~~~~~~~~~~~~

The mechanism to compute the signature of a call to a Python function,
the ``__cs`` object, is much too complex and, in fact, not needed.
At some point I may root it out, but it is used in so many places...

What I should have used the ``"O!"`` capablity of ``PyArg_ParseTuple()``,
like in the code below:

|newpage|

.. code-block:: c++

   static PyObject* PyContact_create ( PyObject*, PyObject *args )
   {
     Contact* contact = NULL;
     HTRY
       PyNet*       pyNet       = NULL;
       PyLayer*     pyLayer     = NULL;
       PyComponent* pyComponent = NULL;
       DbU::Unit    x           = 0;
       DbU::Unit    y           = 0;
       DbU::Unit    width       = 0;
       DbU::Unit    height      = 0;

       if (PyArg_ParseTuple( args, "O!O!ll|ll:Contact.create"
                           , &PyTypeNet  , &pyNet
                           , &PyTypeLayer, &pyLayer
                           , &x, &y, &width, &height)) {
         contact = Contact::create( PYNET_O(pyNet), PYLAYER_O(pyLayer)
                                  , x, y, width, height );
       } else {
         PyErr_Clear();
         if (PyArg_ParseTuple( args, "O!O!ll|ll:Contact.create"
                             , &PyTypeComponent, &pyComponent
                             , &PyTypeLayer    , &pyLayer
                             , &x, &y, &width, &height)) {
           contact = Contact::create( PYCOMPONENT_O(pyComponent), PYLAYER_O(pyLayer)
                                    , x, y, width, height );
         } else {
           PyErr_SetString( ConstructorError
                          , "invalid number of parameters for Contact constructor." );
           return NULL;
         }
       }
     HCATCH
     return PyContact_Link( contact );
   }