77 lines
3.4 KiB
ReStructuredText
77 lines
3.4 KiB
ReStructuredText
.. -*- Mode: 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 3.6.
|
|
|
|
|
|
1.1 About Technical Choices
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Some would say, why not use *off the shelf* wrappers like ``swig``,
|
|
``boost::python`` or ``pybind11``, 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 ``PyTypeManager::_link()`` method.
|
|
|
|
#. **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 Coriolis 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 each 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,
|
|
(``Capsule``) but I did not fully understand it.
|
|
|
|
Instead, we register all the newly defined Python type object
|
|
in the ``PyTypeManager`` and we link the associated C++ library
|
|
into all Python modules. So all types and ancillary functions can
|
|
easily be seen accross modules.
|
|
|
|
This way, we do not rely upon a pointer transmission through Python
|
|
modules, but directly uses linker capabilities.
|
|
|
|
**The PyTypeManager** approach also suppress the need to *split* into
|
|
two libraries the Python modules like in the C-Macros implementation,
|
|
and the double compilation pass.
|
|
|