|
From: <rom...@us...> - 2008-07-22 18:55:03
|
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.
|
