[pygccxml-commit] SF.net SVN: pygccxml:[1376] pyplusplus_dev/docs/documentation/ ctypes_integration.rest

[<rom...@us...>]

Revision: 1376
          http://pygccxml.svn.sourceforge.net/pygccxml/?rev=1376&view=rev
Author:   roman_yakovenko
Date:     2008-07-22 18:55:08 +0000 (Tue, 22 Jul 2008)

Log Message:
-----------
adding "ctypes integration" documentation

Added Paths:
-----------
    pyplusplus_dev/docs/documentation/ctypes_integration.rest

Added: pyplusplus_dev/docs/documentation/ctypes_integration.rest
===================================================================
--- pyplusplus_dev/docs/documentation/ctypes_integration.rest	                        (rev 0)
+++ pyplusplus_dev/docs/documentation/ctypes_integration.rest	2008-07-22 18:55:08 UTC (rev 1376)
@@ -0,0 +1,148 @@
+==================
+ctypes integration
+==================
+
+.. contents:: Table of contents
+
+------------
+Introduction
+------------
+
+`Boost.Python`_ is really a very powerful library, but if you are working
+with code written in plain "C" - you've got a problem. You have to create
+wrappers for almost every function or variable.
+
+In general, if you want to work with plain "C" code from `Python`_
+you don't have to create any wrapper - you can use `ctypes`_ package.
+
+About ctypes
+------------
+`ctypes`_ is a foreign function library for Python. It provides C
+compatible data types, and allows to call functions in dlls/shared
+libraries. It can be used to wrap these libraries in pure Python.
+
+
+
+The idea behind "ctypes integration" functionality is simple: you
+configure `Py++`_ to expose address of the variables or return
+values, as integer and than you can use `ctypes`_ `from_address`_
+functionality to access the data.
+
+Obviously, this approach has its price:
+
+* it could be very dangerous - you can corrupt your application memory
+
+* managing memory is not something a typical `Python`_ user get used to.
+  It is too "low level".
+
+In my opinion, the better way to go is to "mix":
+
+1. expose your native code using `Boost.Python`_ and "ctypes integration"
+   functionality
+
+2. use `ctypes`_ module to access your data
+
+3. create high level API: the wrappers, which will ensure the constraints
+   and will provide more "natural" interface
+
+--------------
+Usage examples
+--------------
+
+Variables
+---------
+
+Lets say you have the following C++ code:
+
+  .. code-block:: C++
+
+     struct bytes_t{
+         bytes_t(){
+             data = new int[5];
+             for(int i=0; i<5; i++){
+                 data[i] = i;
+             }
+         }
+        ...
+        int* data;
+        static int* x;
+     };
+
+     //somewhere in a cpp file
+     int* bytes_t::x = new int( 1997 );
+
+In order to get access to the ``bytes_t::data`` and ``bytes_t::x`` you
+have to turn on ``expose_address`` property to ``True``:
+
+  .. code-block:: Python
+
+    mb = module_builder_t( ... )
+    bytes = mb.class_( 'bytes_t' )
+    bytes.vars().expose_address = True
+
+`Py++`_ will generate code, which will expose the address of the variables.
+
+and now it is a time to show some `ctypes`_ magic:
+
+  .. code-block:: Python
+
+    import ctypes
+    import your_module as m
+
+    bytes = m.bytes_t()
+
+    data_type = ctypes.POINTER( ctypes.c_int )
+    data = data_type.from_address( bytes.data )
+    for j in range(5):
+        print '%d : %d' % ( j, data[j] )
+
+    data_type = ctypes.POINTER( ctypes.c_int )
+    data = data_type.from_address( m.bytes_t.x )
+    print x.contents.value
+
+
+"this" pointer
+--------------
+
+`Py++`_ can expose "this" pointer value to `Python`_:
+
+  .. code-block:: Python
+
+    mb = module_builder_t( ... )
+    mb.class_( 'bytes_t' ).expose_this = True
+
+and the usage example:
+
+  .. code-block:: Python
+
+    import ctypes
+    import your_module as m
+
+    print m.bytes_t().this
+
+
+Warning: I hope you know what you are doing, otherwise don't blame me :-)
+
+-----------------
+Future directions
+-----------------
+
+The functionality is going to be developed father and I intend to add
+next features:
+
+* to expose the result of "sizeof" applied on a class or variable
+
+* to add new call policy, which will return value of a pointer as integer
+
+* to port this functionality to 64bit systems
+
+* to add support for unions
+
+.. _`ctypes` : http://docs.python.org/lib/module-ctypes.html
+.. _`from_address` : http://docs.python.org/lib/ctypes-data-types.html
+.. _`Py++` : ./../pyplusplus.html
+.. _`pygccxml` : ./../../pygccxml/pygccxml.html
+.. _`Boost.Python`: http://www.boost.org/libs/python/doc/index.html
+.. _`Python`: http://www.python.org
+.. _`GCC-XML`: http://www.gccxml.org
+


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.