2017-07-15 10:35:02 -05:00
<!DOCTYPE html>
<!-- [if IE 8]><html class="no - js lt - ie9" lang="en" > <![endif] -->
<!-- [if gt IE 8]><! --> < html class = "no-js" lang = "en" > <!-- <![endif] -->
< head >
< meta charset = "utf-8" >
< meta name = "viewport" content = "width=device-width, initial-scale=1.0" >
< title > 1. Introduction — Coriolis 2 documentation< / title >
< link rel = "stylesheet" href = "../_static/SoC.css" type = "text/css" / >
2017-10-30 09:33:37 -05:00
< link rel = "index" title = "Index"
href="../genindex.html"/>
< link rel = "search" title = "Search" href = "../search.html" / >
2017-07-15 10:35:02 -05:00
< link rel = "top" title = "Coriolis 2 documentation" href = "../index.html" / >
< link rel = "up" title = "Hurricane Python/C++ API Tutorial" href = "index.html" / >
< link rel = "next" title = "2. Basic File Structure and CMake configuration" href = "Configuration.html" / >
< link rel = "prev" title = "Hurricane Python/C++ API Tutorial" href = "index.html" / >
< script src = "_static/js/modernizr.min.js" > < / script >
< / head >
< body class = "wy-body-for-nav" role = "document" >
< div class = "wy-grid-for-nav" >
< nav data-toggle = "wy-nav-shift" class = "wy-nav-side" >
< div class = "wy-side-nav-search" >
< a href = "../index.html" class = "icon icon-home" > Coriolis
< / a >
< div role = "search" >
< form id = "rtd-search-form" class = "wy-form" action = "../search.html" method = "get" >
< input type = "text" name = "q" placeholder = "Search docs" / >
< input type = "hidden" name = "check_keywords" value = "yes" / >
< input type = "hidden" name = "area" value = "default" / >
< / form >
< / div >
< / div >
< div class = "wy-menu wy-menu-vertical" data-spy = "affix" role = "navigation" aria-label = "main navigation" >
< ul class = "current" >
< li class = "toctree-l1" > < a class = "reference internal" href = "../UsersGuide/index.html" > Coriolis User’ s Guide< / a > < ul >
< li class = "toctree-l2" > < a class = "reference internal" href = "../UsersGuide/LicenseCredits.html" > Credits & License< / a > < / li >
< li class = "toctree-l2" > < a class = "reference internal" href = "../UsersGuide/Releases.html" > Release Notes< / a > < ul >
< li class = "toctree-l3" > < a class = "reference internal" href = "../UsersGuide/Releases.html#release-1-0-1475" > Release 1.0.1475< / a > < / li >
< li class = "toctree-l3" > < a class = "reference internal" href = "../UsersGuide/Releases.html#release-1-0-1963" > Release 1.0.1963< / a > < / li >
< li class = "toctree-l3" > < a class = "reference internal" href = "../UsersGuide/Releases.html#release-1-0-2049" > Release 1.0.2049< / a > < / li >
< li class = "toctree-l3" > < a class = "reference internal" href = "../UsersGuide/Releases.html#release-v2-0-1" > Release v2.0.1< / a > < / li >
< li class = "toctree-l3" > < a class = "reference internal" href = "../UsersGuide/Releases.html#release-v2-1" > Release v2.1< / a > < / li >
< li class = "toctree-l3" > < a class = "reference internal" href = "../UsersGuide/Releases.html#release-v2-2" > < strong > Release v2.2< / strong > < / a > < / li >
< / ul >
< / li >
< li class = "toctree-l2" > < a class = "reference internal" href = "../UsersGuide/Installation.html" > Installation< / a > < ul >
< li class = "toctree-l3" > < a class = "reference internal" href = "../UsersGuide/Installation.html#fixed-directory-tree" > Fixed Directory Tree< / a > < / li >
< li class = "toctree-l3" > < a class = "reference internal" href = "../UsersGuide/Installation.html#building-coriolis" > Building Coriolis< / a > < ul >
< li class = "toctree-l4" > < a class = "reference internal" href = "../UsersGuide/Installation.html#building-the-devel-branch" > Building the Devel Branch< / a > < / li >
< li class = "toctree-l4" > < a class = "reference internal" href = "../UsersGuide/Installation.html#additionnal-requirement-under-macos" > Additionnal Requirement under < span class = "sc" > MacOS< / span > < / a > < / li >
< / ul >
< / li >
< li class = "toctree-l3" > < a class = "reference internal" href = "../UsersGuide/Installation.html#packaging-coriolis" > Packaging Coriolis< / a > < / li >
< li class = "toctree-l3" > < a class = "reference internal" href = "../UsersGuide/Installation.html#hooking-up-into-alliance" > Hooking up into < span class = "sc" > Alliance< / span > < / a > < / li >
< li class = "toctree-l3" > < a class = "reference internal" href = "../UsersGuide/Installation.html#setting-up-the-environment-coriolisenv-py" > Setting up the Environment (coriolisEnv.py)< / a > < / li >
< / ul >
< / li >
< li class = "toctree-l2" > < a class = "reference internal" href = "../UsersGuide/Configuration.html" > Coriolis Configuration & Initialisation< / a > < ul >
< li class = "toctree-l3" > < a class = "reference internal" href = "../UsersGuide/Configuration.html#general-software-architecture" > General Software Architecture< / a > < / li >
< li class = "toctree-l3" > < a class = "reference internal" href = "../UsersGuide/Configuration.html#first-stage-symbolic-technology-selection" > First Stage: Symbolic Technology Selection< / a > < / li >
< li class = "toctree-l3" > < a class = "reference internal" href = "../UsersGuide/Configuration.html#second-stage-technology-configuration-loading" > Second Stage: Technology Configuration Loading< / a > < / li >
< li class = "toctree-l3" > < a class = "reference internal" href = "../UsersGuide/Configuration.html#configuration-helpers" > Configuration Helpers< / a > < ul >
< li class = "toctree-l4" > < a class = "reference internal" href = "../UsersGuide/Configuration.html#alliance-helper" > < span class = "sc" > Alliance< / span > Helper< / a > < / li >
< li class = "toctree-l4" > < a class = "reference internal" href = "../UsersGuide/Configuration.html#tools-configuration-helpers" > Tools Configuration Helpers< / a > < / li >
< / ul >
< / li >
< li class = "toctree-l3" > < a class = "reference internal" href = "../UsersGuide/Configuration.html#hacking-the-configuration-files" > Hacking the Configuration Files< / a > < / li >
< / ul >
< / li >
< li class = "toctree-l2" > < a class = "reference internal" href = "../UsersGuide/ViewerTools.html" > CGT - The Graphical Interface< / a > < ul >
< li class = "toctree-l3" > < a class = "reference internal" href = "../UsersGuide/ViewerTools.html#viewer-tools" > Viewer & Tools< / a > < ul >
< li class = "toctree-l4" > < a class = "reference internal" href = "../UsersGuide/ViewerTools.html#stratus-netlist-capture" > < span class = "sc" > Stratus< / span > Netlist Capture< / a > < / li >
< li class = "toctree-l4" > < a class = "reference internal" href = "../UsersGuide/ViewerTools.html#the-hurricane-data-base" > The < span class = "sc" > Hurricane< / span > Data-Base< / a > < / li >
< li class = "toctree-l4" > < a class = "reference internal" href = "../UsersGuide/ViewerTools.html#synthetizing-and-loading-a-design" > Synthetizing and loading a design< / a > < / li >
< li class = "toctree-l4" > < a class = "reference internal" href = "../UsersGuide/ViewerTools.html#etesian-placer" > Etesian – Placer< / a > < / li >
< li class = "toctree-l4" > < a class = "reference internal" href = "../UsersGuide/ViewerTools.html#knik-global-router" > Knik – Global Router< / a > < / li >
< li class = "toctree-l4" > < a class = "reference internal" href = "../UsersGuide/ViewerTools.html#kite-detailed-router" > Kite – Detailed Router< / a > < / li >
< li class = "toctree-l4" > < a class = "reference internal" href = "../UsersGuide/ViewerTools.html#executing-python-scripts-in-cgt" > Executing Python Scripts in Cgt< / a > < / li >
< li class = "toctree-l4" > < a class = "reference internal" href = "../UsersGuide/ViewerTools.html#printing-snapshots" > Printing & Snapshots< / a > < / li >
< li class = "toctree-l4" > < a class = "reference internal" href = "../UsersGuide/ViewerTools.html#memento-of-shortcuts-in-graphic-mode" > Memento of Shortcuts in Graphic Mode< / a > < / li >
< li class = "toctree-l4" > < a class = "reference internal" href = "../UsersGuide/ViewerTools.html#cgt-command-line-options" > Cgt Command Line Options< / a > < / li >
< li class = "toctree-l4" > < a class = "reference internal" href = "../UsersGuide/ViewerTools.html#miscellaneous-settings" > Miscellaneous Settings< / a > < / li >
< / ul >
< / li >
< li class = "toctree-l3" > < a class = "reference internal" href = "../UsersGuide/ViewerTools.html#the-controller" > The Controller< / a > < ul >
< li class = "toctree-l4" > < a class = "reference internal" href = "../UsersGuide/ViewerTools.html#the-look-tab" > The Look Tab< / a > < / li >
< li class = "toctree-l4" > < a class = "reference internal" href = "../UsersGuide/ViewerTools.html#the-filter-tab" > The Filter Tab< / a > < / li >
< li class = "toctree-l4" > < a class = "reference internal" href = "../UsersGuide/ViewerTools.html#the-layers-go-tab" > The Layers& Go Tab< / a > < / li >
< li class = "toctree-l4" > < a class = "reference internal" href = "../UsersGuide/ViewerTools.html#the-netlist-tab" > The Netlist Tab< / a > < / li >
< li class = "toctree-l4" > < a class = "reference internal" href = "../UsersGuide/ViewerTools.html#the-selection-tab" > The Selection Tab< / a > < / li >
< li class = "toctree-l4" > < a class = "reference internal" href = "../UsersGuide/ViewerTools.html#the-inspector-tab" > The Inspector Tab< / a > < / li >
< li class = "toctree-l4" > < a class = "reference internal" href = "../UsersGuide/ViewerTools.html#the-settings-tab" > The Settings Tab< / a > < / li >
< / ul >
< / li >
< / ul >
< / li >
< li class = "toctree-l2" > < a class = "reference internal" href = "../UsersGuide/ScriptsPlugins.html" > Python Interface for < span class = "sc" > Hurricane< / span > / < span class = "sc" > Coriolis< / span > < / a > < ul >
< li class = "toctree-l3" > < a class = "reference internal" href = "../UsersGuide/ScriptsPlugins.html#plugins" > Plugins< / a > < ul >
< li class = "toctree-l4" > < a class = "reference internal" href = "../UsersGuide/ScriptsPlugins.html#chip-placement" > Chip Placement< / a > < / li >
< li class = "toctree-l4" > < a class = "reference internal" href = "../UsersGuide/ScriptsPlugins.html#clock-tree" > Clock Tree< / a > < / li >
< li class = "toctree-l4" > < a class = "reference internal" href = "../UsersGuide/ScriptsPlugins.html#recursive-save-rsave" > Recursive-Save (RSave)< / a > < / li >
< / ul >
< / li >
< li class = "toctree-l3" > < a class = "reference internal" href = "../UsersGuide/ScriptsPlugins.html#a-simple-example-am2901" > A Simple Example: AM2901< / a > < / li >
< / ul >
< / li >
< / ul >
< / li >
< li class = "toctree-l1" > < a class = "reference internal" href = "../Stratus/Stratus.html" > Stratus Reference< / a > < / li >
< li class = "toctree-l1" > < a class = "reference internal" href = "../DpGen/DpGen.html" > DpGen Reference< / a > < / li >
< li class = "toctree-l1" > < a class = "reference internal" href = "../Patterns/Patterns.html" > Patterns Reference< / a > < / li >
< li class = "toctree-l1" > < a class = "reference internal" href = "../Hurricane/Hurricane.html" > Hurricane Reference< / a > < / li >
< li class = "toctree-l1" > < a class = "reference internal" href = "../Viewer/Viewer.html" > Viewer Reference< / a > < / li >
< li class = "toctree-l1" > < a class = "reference internal" href = "../CrlCore/CrlCore.html" > CRL Core Reference< / a > < / li >
2017-07-17 12:12:18 -05:00
< li class = "toctree-l1" > < a class = "reference internal" href = "../Katabatic/Katabatic.html" > Katabatic Reference< / a > < / li >
< li class = "toctree-l1" > < a class = "reference internal" href = "../Kite/Kite.html" > Kite Reference< / a > < / li >
2017-07-15 10:35:02 -05:00
< li class = "toctree-l1" > < a class = "reference internal" href = "../Unicorn/Unicorn.html" > Unicorn Reference< / a > < / li >
< li class = "toctree-l1 current" > < a class = "reference internal" href = "index.html" > Hurricane Python/C++ API Tutorial< / a > < ul class = "current" >
2017-10-30 09:33:37 -05:00
< li class = "toctree-l2 current" > < a class = "current reference internal" href = "#" > 1. Introduction< / a > < ul >
2017-07-15 10:35:02 -05:00
< li class = "toctree-l3" > < a class = "reference internal" href = "#first-a-disclaimer" > 1.1 First, A Disclaimer< / a > < / li >
< li class = "toctree-l3" > < a class = "reference internal" href = "#about-technical-choices" > 1.2 About Technical Choices< / a > < / li >
< li class = "toctree-l3" > < a class = "reference internal" href = "#botched-design" > 1.3 Botched Design< / a > < / li >
< / ul >
< / li >
< li class = "toctree-l2" > < a class = "reference internal" href = "Configuration.html" > 2. Basic File Structure and CMake configuration< / a > < / li >
< li class = "toctree-l2" > < a class = "reference internal" href = "DBoStandalone.html" > 3. Case 1 - DBo Derived, Standalone< / a > < ul >
< li class = "toctree-l3" > < a class = "reference internal" href = "DBoStandalone.html#class-associated-header-file" > 3.1 Class Associated Header File< / a > < / li >
< li class = "toctree-l3" > < a class = "reference internal" href = "DBoStandalone.html#class-associated-file" > 3.2 Class Associated File< / a > < ul >
< li class = "toctree-l4" > < a class = "reference internal" href = "DBoStandalone.html#head-of-the-file" > 3.2.1 Head of the file< / a > < / li >
< li class = "toctree-l4" > < a class = "reference internal" href = "DBoStandalone.html#the-python-module-part" > 3.2.2 The Python Module Part< / a > < / li >
< li class = "toctree-l4" > < a class = "reference internal" href = "DBoStandalone.html#python-type-linking" > 3.2.3 Python Type Linking< / a > < / li >
< li class = "toctree-l4" > < a class = "reference internal" href = "DBoStandalone.html#the-shared-library-part" > 3.2.4 The Shared Library Part< / a > < / li >
< / ul >
< / li >
< li class = "toctree-l3" > < a class = "reference internal" href = "DBoStandalone.html#python-module-c-namespace" > 3.3 Python Module (C++ namespace)< / a > < / li >
< / ul >
< / li >
< li class = "toctree-l2" > < a class = "reference internal" href = "DBoHierarchy.html" > 4. Case 2 - Hierarchy of DBo Derived Classes< / a > < ul >
< li class = "toctree-l3" > < a class = "reference internal" href = "DBoHierarchy.html#base-class-header" > 4.1 Base Class Header< / a > < / li >
< li class = "toctree-l3" > < a class = "reference internal" href = "DBoHierarchy.html#base-class-file" > 4.2 Base Class File< / a > < / li >
< li class = "toctree-l3" > < a class = "reference internal" href = "DBoHierarchy.html#intermediate-class-header" > 4.3 Intermediate Class Header< / a > < / li >
< li class = "toctree-l3" > < a class = "reference internal" href = "DBoHierarchy.html#intermediate-class-file" > 4.4 Intermediate Class File< / a > < / li >
< li class = "toctree-l3" > < a class = "reference internal" href = "DBoHierarchy.html#terminal-class-header" > 4.5 Terminal Class Header< / a > < / li >
< li class = "toctree-l3" > < a class = "reference internal" href = "DBoHierarchy.html#terminal-class-file" > 4.6 Terminal Class File< / a > < / li >
< li class = "toctree-l3" > < a class = "reference internal" href = "DBoHierarchy.html#python-module" > 4.8 Python Module< / a > < / li >
< / ul >
< / li >
< li class = "toctree-l2" > < a class = "reference internal" href = "NonDBo.html" > 5. Case 3 - Non-DBo Standalone Classe< / a > < ul >
< li class = "toctree-l3" > < a class = "reference internal" href = "NonDBo.html#class-header" > 5.1 Class Header< / a > < / li >
< li class = "toctree-l3" > < a class = "reference internal" href = "NonDBo.html#class-file" > 5.2 Class File< / a > < / li >
< li class = "toctree-l3" > < a class = "reference internal" href = "NonDBo.html#id1" > 5.2 Class File< / a > < / li >
< / ul >
< / li >
< li class = "toctree-l2" > < a class = "reference internal" href = "DbU.html" > 6. Encapsulating DbU< / a > < / li >
< li class = "toctree-l2" > < a class = "reference internal" href = "Name.html" > 7. No C++ Hurricane::Name encapsulation< / a > < / li >
< / ul >
< / li >
< li class = "toctree-l1" > < a class = "reference internal" href = "../RDS/index.html" > Symbolic to Real Conversion in Alliance< / a > < ul >
< li class = "toctree-l2" > < a class = "reference internal" href = "../RDS/RDSpage.html" > Symbolic Layout< / a > < ul >
< li class = "toctree-l3" > < a class = "reference internal" href = "../RDS/RDSpage.html#symbolic-components" > Symbolic Components< / a > < / li >
< li class = "toctree-l3" > < a class = "reference internal" href = "../RDS/RDSpage.html#symbolic-segments" > Symbolic Segments< / a > < / li >
< / ul >
< / li >
< li class = "toctree-l2" > < a class = "reference internal" href = "../RDS/RDSpage.html#the-rds-file" > The RDS File< / a > < ul >
< li class = "toctree-l3" > < a class = "reference internal" href = "../RDS/RDSpage.html#physical-grid-lambda-value" > Physical Grid & Lambda Value< / a > < / li >
2017-10-30 09:33:37 -05:00
< li class = "toctree-l3" > < a class = "reference internal" href = "../RDS/RDSpage.html#the-mbk-to-rds-segment-table" > The < code class = "docutils literal" > < span class = "pre" > MBK_TO_RDS_SEGMENT< / span > < / code > table< / a > < / li >
< li class = "toctree-l3" > < a class = "reference internal" href = "../RDS/RDSpage.html#the-mbk-to-rds-via-table" > The < code class = "docutils literal" > < span class = "pre" > MBK_TO_RDS_VIA< / span > < / code > table< / a > < / li >
< li class = "toctree-l3" > < a class = "reference internal" href = "../RDS/RDSpage.html#the-mbk-to-rds-bigvia-hole-table" > The < code class = "docutils literal" > < span class = "pre" > MBK_TO_RDS_BIGVIA_HOLE< / span > < / code > table< / a > < / li >
< li class = "toctree-l3" > < a class = "reference internal" href = "../RDS/RDSpage.html#the-mbk-to-rds-bigvia-metal-table" > The < code class = "docutils literal" > < span class = "pre" > MBK_TO_RDS_BIGVIA_METAL< / span > < / code > table< / a > < / li >
< li class = "toctree-l3" > < a class = "reference internal" href = "../RDS/RDSpage.html#the-mbk-wiresetting-table" > The < code class = "docutils literal" > < span class = "pre" > MBK_WIRESETTING< / span > < / code > table< / a > < / li >
2017-07-15 10:35:02 -05:00
< / ul >
< / li >
< / ul >
< / li >
2017-10-30 09:33:37 -05:00
< li class = "toctree-l1" > < a class = "reference internal" href = "../lefapi/lefapi.html" > LEF API Reference< / a > < / li >
< li class = "toctree-l1" > < a class = "reference internal" href = "../defapi/defapi.html" > DEF API Reference< / a > < / li >
< li class = "toctree-l1" > < a class = "reference internal" href = "../lefdef/lefdef.html" > LEF/DEF Language Reference< / a > < / li >
2017-07-15 10:35:02 -05:00
< / ul >
< / div >
< / nav >
< section data-toggle = "wy-nav-shift" class = "wy-nav-content-wrap" >
< nav class = "wy-nav-top" role = "navigation" aria-label = "top navigation" >
< i data-toggle = "wy-nav-top" class = "fa fa-bars" > < / i >
< a href = "../index.html" > Coriolis< / a >
< / nav >
< div class = "wy-nav-content" >
< div class = "rst-content" >
< div role = "navigation" aria-label = "breadcrumbs navigation" >
< ul class = "wy-breadcrumbs" >
< li > < a href = "../index.html" > Docs< / a > » < / li >
< li > < a href = "index.html" > Hurricane Python/C++ API Tutorial< / a > » < / li >
< li > 1. Introduction< / li >
< li class = "wy-breadcrumbs-aside" >
< / li >
< / ul >
< hr / >
< / div >
< div role = "main" class = "document" >
< div class = "section" id = "introduction" >
< h1 > 1. Introduction< a class = "headerlink" href = "#introduction" title = "Permalink to this headline" > ¶< / a > < / h1 >
< ul class = "simple" >
< li > This document is written for people already familiar with the
< a class = "reference external" href = "https://docs.python.org/2/c-api/index.html" > Python/C API Reference Manual< / a > .< / li >
< li > 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.< / li >
< li > Coriolis is build against Python 2.7.< / li >
< / ul >
< div class = "section" id = "first-a-disclaimer" >
< h2 > 1.1 First, A Disclaimer< a class = "headerlink" href = "#first-a-disclaimer" title = "Permalink to this headline" > ¶< / a > < / h2 >
< p > 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.< / p >
< p > It is my hope that at some point in the future I will have time to completly
2017-10-30 09:33:37 -05:00
rewrite it, borrowing the interface from < code class = "docutils literal" > < span class = "pre" > boost::python< / span > < / code > .< / p >
2017-07-15 10:35:02 -05:00
< / div >
< div class = "section" id = "about-technical-choices" >
< h2 > 1.2 About Technical Choices< a class = "headerlink" href = "#about-technical-choices" title = "Permalink to this headline" > ¶< / a > < / h2 >
2017-10-30 09:33:37 -05:00
< p > Some would say, why not use < em > off the shelf< / em > wrappers like < code class = "docutils literal" > < span class = "pre" > swig< / span > < / code >
or < code class = "docutils literal" > < span class = "pre" > boost::python< / span > < / code > , here are some clues.< / p >
2017-07-15 10:35:02 -05:00
< ol class = "arabic" >
< li > < p class = "first" > < strong > Partial exposure of the C++ class tree.< / strong > 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.
2017-10-30 09:33:37 -05:00
For instance < code class = "docutils literal" > < span class = "pre" > Library< / span > < / code > is derived from < code class = "docutils literal" > < span class = "pre" > DBo< / span > < / code > , but we won’ t see
2017-07-15 10:35:02 -05:00
it under Python.< / p >
< / li >
< li > < p class = "first" > < strong > Bi-directional communication.< / strong > 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 < em > must< / em > 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.< / p >
< p > To be precise, this apply to persistent object in the C++ database,
2017-10-30 09:33:37 -05:00
like < code class = "docutils literal" > < span class = "pre" > Cell< / span > < / code > , < code class = "docutils literal" > < span class = "pre" > Net< / span > < / code > , < code class = "docutils literal" > < span class = "pre" > Instance< / span > < / code > or < code class = "docutils literal" > < span class = "pre" > Component< / span > < / code > . Short lived
objects like < code class = "docutils literal" > < span class = "pre" > Box< / span > < / code > or < code class = "docutils literal" > < span class = "pre" > Point< / span > < / code > retains the classic Python behavior.< / p >
< p > Another aspect is that, for all derived < code class = "docutils literal" > < span class = "pre" > DBo< / span > < / code > objects, one and only
one Python object is associated. For one given < code class = "docutils literal" > < span class = "pre" > Instance< / span > < / code > object we
will always return the < em > same< / em > < code class = "docutils literal" > < span class = "pre" > PyInstance< / span > < / code > object, thanks to the
2017-07-15 10:35:02 -05:00
bi-directional link. Obviously, the < em > reference count< / em > of the
2017-10-30 09:33:37 -05:00
< code class = "docutils literal" > < span class = "pre" > PyInstance< / span > < / code > is managed accordingly. This mechanism is implemented
by the < code class = "docutils literal" > < span class = "pre" > PyInstance_Link()< / span > < / code > function.< / p >
2017-07-15 10:35:02 -05:00
< / li >
< li > < p class = "first" > < strong > Linking accross modules.< / strong > 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.< / p >
< p > 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:< / p >
< ul class = "simple" >
< li > The first part contains the classic Python module code.< / li >
< li > 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.< / li >
< / ul >
< p > Each module file will be compiled < em > twice< / em > , once to build the Python
2017-10-30 09:33:37 -05:00
module (< code class = "docutils literal" > < span class = "pre" > __PYTHON_MODULE< / span > < / code > is defined) and once to build the supporting
shared library (< code class = "docutils literal" > < span class = "pre" > __PYTHON_MODULE__< / span > < / code > < strong > not< / strong > defined). This tricky
double compilation is taken care of though the < code class = "docutils literal" > < span class = "pre" > add_python_module< / span > < / code >
< code class = "docutils literal" > < span class = "pre" > cmake< / span > < / code > macro.< / p >
2017-07-15 10:35:02 -05:00
< p > For the core Hurricane library we will have:< / p >
< ul class = "simple" >
2017-10-30 09:33:37 -05:00
< li > < code class = "docutils literal" > < span class = "pre" > Hurricane.so< / span > < / code > the Python module (use with: < code class = "docutils literal" > < span class = "pre" > import< / span > < span class = "pre" > Hurricane< / span > < / code > ).< / li >
< li > < code class = "docutils literal" > < span class = "pre" > libisobar.so.1.0< / span > < / code > the supporting shared library.< / li >
2017-07-15 10:35:02 -05:00
< / ul >
2017-10-30 09:33:37 -05:00
< p > The < code class = "docutils literal" > < span class = "pre" > PyLibrary.cpp< / span > < / code > file will have the following structure:< / p >
< div class = "highlight-c++" > < div class = "highlight" > < pre > < span > < / span > < span class = "cp" > #include< / span > < span class = "cpf" > " hurricane/isobar/PyLibrary.h" < / span > < span class = "cp" > < / span >
2017-07-15 10:35:02 -05:00
< span class = "k" > namespace< / span > < span class = "n" > Isobar< / span > < span class = "p" > {< / span >
< span class = "k" > extern< / span > < span class = "s" > " C" < / span > < span class = "p" > {< / span >
< span class = "cp" > #if defined(__PYTHON_MODULE__)< / span >
2017-10-30 09:33:37 -05:00
< span class = "c1" > // +=================================================================+< / span >
< span class = "c1" > // | " PyLibrary" Python Module Code Part |< / span >
< span class = "c1" > // +=================================================================+< / span >
< span class = "c1" > //< / span >
< span class = "c1" > // The classic part of a Python module. Goes into Hurricane.so.< / span >
2017-07-15 10:35:02 -05:00
< span class = "cp" > #else < / span > < span class = "c1" > // End of Python Module Code Part.< / span >
2017-10-30 09:33:37 -05:00
< span class = "c1" > // x=================================================================x< / span >
< span class = "c1" > // | " PyLibrary" Shared Library Code Part |< / span >
< span class = "c1" > // x=================================================================x< / span >
< span class = "c1" > //< / span >
< span class = "c1" > // Functions here will be part of the associated shared library and< / span >
< span class = "c1" > // made available to all other Python modules. Goes into libisobar.so.1.0< / span >
2017-07-15 10:35:02 -05:00
< span class = "cp" > # endif < / span > < span class = "c1" > // Shared Library Code Part.< / span >
< span class = "p" > }< / span > < span class = "c1" > // extern " C" .< / span >
< span class = "p" > }< / span > < span class = "c1" > // Isobar namespace.< / span >
< / pre > < / div >
< / div >
< p > This way, we do not rely upon a pointer transmission through Python
modules, but directly uses linker capabilities.< / p >
< / li >
< / ol >
< / div >
< div class = "section" id = "botched-design" >
< h2 > 1.3 Botched Design< a class = "headerlink" href = "#botched-design" title = "Permalink to this headline" > ¶< / a > < / h2 >
< p > The mechanism to compute the signature of a call to a Python function,
2017-10-30 09:33:37 -05:00
the < code class = "docutils literal" > < span class = "pre" > __cs< / span > < / code > object, is much too complex and, in fact, not needed.
2017-07-15 10:35:02 -05:00
At some point I may root it out, but it is used in so many places...< / p >
2017-10-30 09:33:37 -05:00
< p > What I should have used the < code class = "docutils literal" > < span class = "pre" > " O!" < / span > < / code > capablity of < code class = "docutils literal" > < span class = "pre" > PyArg_ParseTuple()< / span > < / code > ,
2017-07-15 10:35:02 -05:00
like in the code below:< / p >
< p > < / p >
2017-10-30 09:33:37 -05:00
< div class = "highlight-c++" > < div class = "highlight" > < pre > < span > < / span > < span class = "k" > static< / span > < span class = "n" > PyObject< / span > < span class = "o" > *< / span > < span class = "nf" > PyContact_create< / span > < span class = "p" > (< / span > < span class = "n" > PyObject< / span > < span class = "o" > *< / span > < span class = "p" > ,< / span > < span class = "n" > PyObject< / span > < span class = "o" > *< / span > < span class = "n" > args< / span > < span class = "p" > )< / span >
2017-07-15 10:35:02 -05:00
< span class = "p" > {< / span >
< span class = "n" > Contact< / span > < span class = "o" > *< / span > < span class = "n" > contact< / span > < span class = "o" > =< / span > < span class = "nb" > NULL< / span > < span class = "p" > ;< / span >
< span class = "n" > HTRY< / span >
< span class = "n" > PyNet< / span > < span class = "o" > *< / span > < span class = "n" > pyNet< / span > < span class = "o" > =< / span > < span class = "nb" > NULL< / span > < span class = "p" > ;< / span >
< span class = "n" > PyLayer< / span > < span class = "o" > *< / span > < span class = "n" > pyLayer< / span > < span class = "o" > =< / span > < span class = "nb" > NULL< / span > < span class = "p" > ;< / span >
< span class = "n" > PyComponent< / span > < span class = "o" > *< / span > < span class = "n" > pyComponent< / span > < span class = "o" > =< / span > < span class = "nb" > NULL< / span > < span class = "p" > ;< / span >
< span class = "n" > DbU< / span > < span class = "o" > ::< / span > < span class = "n" > Unit< / span > < span class = "n" > x< / span > < span class = "o" > =< / span > < span class = "mi" > 0< / span > < span class = "p" > ;< / span >
< span class = "n" > DbU< / span > < span class = "o" > ::< / span > < span class = "n" > Unit< / span > < span class = "n" > y< / span > < span class = "o" > =< / span > < span class = "mi" > 0< / span > < span class = "p" > ;< / span >
< span class = "n" > DbU< / span > < span class = "o" > ::< / span > < span class = "n" > Unit< / span > < span class = "n" > width< / span > < span class = "o" > =< / span > < span class = "mi" > 0< / span > < span class = "p" > ;< / span >
< span class = "n" > DbU< / span > < span class = "o" > ::< / span > < span class = "n" > Unit< / span > < span class = "n" > height< / span > < span class = "o" > =< / span > < span class = "mi" > 0< / span > < span class = "p" > ;< / span >
< span class = "k" > if< / span > < span class = "p" > (< / span > < span class = "n" > PyArg_ParseTuple< / span > < span class = "p" > (< / span > < span class = "n" > args< / span > < span class = "p" > ,< / span > < span class = "s" > " O!O!ll|ll:Contact.create" < / span >
< span class = "p" > ,< / span > < span class = "o" > & < / span > < span class = "n" > PyTypeNet< / span > < span class = "p" > ,< / span > < span class = "o" > & < / span > < span class = "n" > pyNet< / span >
< span class = "p" > ,< / span > < span class = "o" > & < / span > < span class = "n" > PyTypeLayer< / span > < span class = "p" > ,< / span > < span class = "o" > & < / span > < span class = "n" > pyLayer< / span >
< span class = "p" > ,< / span > < span class = "o" > & < / span > < span class = "n" > x< / span > < span class = "p" > ,< / span > < span class = "o" > & < / span > < span class = "n" > y< / span > < span class = "p" > ,< / span > < span class = "o" > & < / span > < span class = "n" > width< / span > < span class = "p" > ,< / span > < span class = "o" > & < / span > < span class = "n" > height< / span > < span class = "p" > ))< / span > < span class = "p" > {< / span >
< span class = "n" > contact< / span > < span class = "o" > =< / span > < span class = "n" > Contact< / span > < span class = "o" > ::< / span > < span class = "n" > create< / span > < span class = "p" > (< / span > < span class = "n" > PYNET_O< / span > < span class = "p" > (< / span > < span class = "n" > pyNet< / span > < span class = "p" > ),< / span > < span class = "n" > PYLAYER_O< / span > < span class = "p" > (< / span > < span class = "n" > pyLayer< / span > < span class = "p" > )< / span >
< span class = "p" > ,< / span > < span class = "n" > x< / span > < span class = "p" > ,< / span > < span class = "n" > y< / span > < span class = "p" > ,< / span > < span class = "n" > width< / span > < span class = "p" > ,< / span > < span class = "n" > height< / span > < span class = "p" > );< / span >
< span class = "p" > }< / span > < span class = "k" > else< / span > < span class = "p" > {< / span >
< span class = "n" > PyErr_Clear< / span > < span class = "p" > ();< / span >
< span class = "k" > if< / span > < span class = "p" > (< / span > < span class = "n" > PyArg_ParseTuple< / span > < span class = "p" > (< / span > < span class = "n" > args< / span > < span class = "p" > ,< / span > < span class = "s" > " O!O!ll|ll:Contact.create" < / span >
< span class = "p" > ,< / span > < span class = "o" > & < / span > < span class = "n" > PyTypeComponent< / span > < span class = "p" > ,< / span > < span class = "o" > & < / span > < span class = "n" > pyComponent< / span >
< span class = "p" > ,< / span > < span class = "o" > & < / span > < span class = "n" > PyTypeLayer< / span > < span class = "p" > ,< / span > < span class = "o" > & < / span > < span class = "n" > pyLayer< / span >
< span class = "p" > ,< / span > < span class = "o" > & < / span > < span class = "n" > x< / span > < span class = "p" > ,< / span > < span class = "o" > & < / span > < span class = "n" > y< / span > < span class = "p" > ,< / span > < span class = "o" > & < / span > < span class = "n" > width< / span > < span class = "p" > ,< / span > < span class = "o" > & < / span > < span class = "n" > height< / span > < span class = "p" > ))< / span > < span class = "p" > {< / span >
< span class = "n" > contact< / span > < span class = "o" > =< / span > < span class = "n" > Contact< / span > < span class = "o" > ::< / span > < span class = "n" > create< / span > < span class = "p" > (< / span > < span class = "n" > PYCOMPONENT_O< / span > < span class = "p" > (< / span > < span class = "n" > pyComponent< / span > < span class = "p" > ),< / span > < span class = "n" > PYLAYER_O< / span > < span class = "p" > (< / span > < span class = "n" > pyLayer< / span > < span class = "p" > )< / span >
< span class = "p" > ,< / span > < span class = "n" > x< / span > < span class = "p" > ,< / span > < span class = "n" > y< / span > < span class = "p" > ,< / span > < span class = "n" > width< / span > < span class = "p" > ,< / span > < span class = "n" > height< / span > < span class = "p" > );< / span >
< span class = "p" > }< / span > < span class = "k" > else< / span > < span class = "p" > {< / span >
< span class = "n" > PyErr_SetString< / span > < span class = "p" > (< / span > < span class = "n" > ConstructorError< / span >
< span class = "p" > ,< / span > < span class = "s" > " invalid number of parameters for Contact constructor." < / span > < span class = "p" > );< / span >
< span class = "k" > return< / span > < span class = "nb" > NULL< / span > < span class = "p" > ;< / span >
< span class = "p" > }< / span >
< span class = "p" > }< / span >
< span class = "n" > HCATCH< / span >
< span class = "k" > return< / span > < span class = "n" > PyContact_Link< / span > < span class = "p" > (< / span > < span class = "n" > contact< / span > < span class = "p" > );< / span >
< span class = "p" > }< / span >
< / pre > < / div >
< / div >
< / div >
< / div >
< / div >
< footer >
< div class = "rst-footer-buttons" role = "navigation" aria-label = "footer navigation" >
< a href = "Configuration.html" class = "btn btn-neutral float-right" title = "2. Basic File Structure and CMake configuration" accesskey = "n" > Next < span class = "fa fa-arrow-circle-right" > < / span > < / a >
< a href = "index.html" class = "btn btn-neutral" title = "Hurricane Python/C++ API Tutorial" accesskey = "p" > < span class = "fa fa-arrow-circle-left" > < / span > Previous< / a >
< / div >
< hr / >
< div role = "contentinfo" >
< table class = "footer1" >
< tr >
< td class = "LFooter" > < small >
Generated by < a href = "http://sphinx-doc.org/" > Sphinx< / a >
2017-10-30 09:33:37 -05:00
using a < a href = "https://readthedocs.org" > RTD< / a > theme on Oct 30, 2017.
2017-07-15 10:35:02 -05:00
< / small > < / td >
< td class = "RFooter" > < / td >
< / tr >
< / table >
< table class = "footer2" >
< tr >
< td class = "LFooter" > Coriolis 2 Documentation< / td >
< td class = "RFooter" > < small >
© Copyright 2000-2017, UPMC.
< / small > < / td >
< / tr >
< / table >
< / div >
< / footer >
< / div >
< / div >
< / section >
< / div >
< script type = "text/javascript" >
var DOCUMENTATION_OPTIONS = {
URL_ROOT:'../',
VERSION:'2',
COLLAPSE_INDEX:false,
FILE_SUFFIX:'.html',
HAS_SOURCE: true
};
< / script >
< script type = "text/javascript" src = "../_static/jquery.js" > < / script >
< script type = "text/javascript" src = "../_static/underscore.js" > < / script >
< script type = "text/javascript" src = "../_static/doctools.js" > < / script >
< script type = "text/javascript" src = "../_static/js/theme.js" > < / script >
< script type = "text/javascript" >
jQuery(function () {
SphinxRtdTheme.StickyNav.enable();
});
< / script >
< / body >
< / html >
