pygccxml-commit Mailing List for C++ Python language bindings (Page 72)

SourceForge Headquarters 225 Broadway Suite 1600 San Diego, CA 92101 +1 (858) 422-6466

Revision: 65
Author:   roman_yakovenko
Date:     2006-05-08 00:00:13 -0700 (Mon, 08 May 2006)
ViewCVS:  http://svn.sourceforge.net/pygccxml/?rev=65&view=rev

Log Message:
-----------
adding introduction to call wrapper policies 

Added Paths:
-----------
    pyplusplus_dev/docs/call_wrapper_policies/
    pyplusplus_dev/docs/call_wrapper_policies/introduction.rest
    pyplusplus_dev/docs/call_wrapper_policies/www_configuration.py
Added: pyplusplus_dev/docs/call_wrapper_policies/introduction.rest
===================================================================

--- pyplusplus_dev/docs/call_wrapper_policies/introduction.rest	                        (rev 0)
+++ pyplusplus_dev/docs/call_wrapper_policies/introduction.rest	2006-05-08 07:00:13 UTC (rev 65)
@@ -0,0 +1,241 @@
+=====================
+call wrapper policies
+=====================
+
+.. contents:: Table of contents
+
+-------------------
+What is useful for?
+-------------------
+Not all C++ functions could be exposed to Python as is. For example, next function
+could not be exposed:
+::
+
+  void get_size( int& size );
+
+In order to expose ``get_size`` function, an user need to create next wrapper:
+::
+
+  int get_size_wrapper( ){
+      int size(0);
+      get_size( size );
+      return size;
+  }
+
+|cwp| will provide the user with simple and intuitive way to instruct
+`pyplusplus`_ to generate right wrapper. Also, it will be possible to create
+a custom policies.
+
+--------
+Analysis
+--------
+
+C++ function arguments usage
+----------------------------
+
+In C++ function argument can be used to:
+
+* to pass some data to function ( in )
+
+  there is no need to return variable from the function
+
+* to return some data from function ( out )
+
+  there is no need to force Python programmer to pass the variable as argument
+  to the function
+
+* both ( in/out )
+
+Function-wrapper signature will be a little bit different in every case.
+
+Variable names
+--------------
+I think it should be possible to apply few |cwp| on a single function. Thus, it
+will be possible to create few convinience function, from one single function.
+The main,read unresolved, issue, is management of variable names within function-wrapper.
+I see next problems, that we should solve, before proceeding to implementation:
+
+1. To share variable name, between different pieces of code.
+
+   Right now I think, that every |cwp| will have ``pre-call`` and ``post-call``
+   code creators. This design will allow the user to mix few |cwp|'s within
+   single function-wrapper.
+
+2. To insure name uniqueness.
+
+3. To give meaningful name.
+
+I think, that is it very easy to solve the problem, if I remove "readability"
+requirement.
+
+Call policies
+-------------
+I don't have any solution to the next problem.
+I am going to change a little an example, from `boost.python`_ tutorials:
+http://www.boost.org/libs/python/doc/tutorial/doc/html/python/functions.html#python.call_policies
+::
+
+  //C++ code
+  struct Y
+  {
+      X x; Z* z;
+      int z_value() { return z->value(); }
+  };
+
+  X& f(Y& y, Z* z, int& error)
+  {
+      y.z = z;
+      return y.x;
+  }
+
+  //boost.python code
+  def("f", f, return_internal_reference<1, with_custodian_and_ward<1, 2> >() );
+
+What is the difference? Function ``f`` now takes 3rd argument - ``int&``. This
+function could not be called from `Python`_. ( Hint: numbers are immutable
+objects in `Python`_ ). So in order to expose function ``f`` to `Python`_,
+an user need to create a wrapper. And now he has a problem: how to wrap the function?
+
+I see only one solution user have to change signature of function ``f``.
+Now some speculations:
+
+1. May be it is possible with `boost.python`_ library to set call policies on the
+   part of the return value?
+   ::
+
+     boost::tuple f_wrapper( Y& y, Z* z ){
+         int error(0);
+         X& x = f( y, z, error );
+         return boost::tuple<X&, int>( x, error );
+     }
+
+    def("f", f_wrapper, smart call policies that will work only on first element within the tuple );
+
+2. May be it is possible to create boost.python ``object`` with life-time management
+   hint?
+   ::
+
+     boost::python::tuple f_wrapper( Y& y, Z* z ){
+         int error(0);
+         X& x = f( y, z, error );
+         boost::python::object x_obj( x, x is internal reference of y );
+         return boost::python::make_tuple( x_obj, error );
+     }
+
+Anyway, I think we will just ignore the problem - software ( == boost.python )
+should not be perfect - it should work in most ( != all ) cases!
+
+------------
+Common |cwp|
+------------
+Those names are not final and could( may be should ) be changed.
+
+immutable by reference
+-----------------------
+::
+
+  //function to be exported
+  something f( int& i, std::string& str )
+
+I suppose this is very common use case. More over this use case `pyplusplus`_
+can and will treat by its own - no user action is needed. The wrapper
+generated by `pyplusplus`_ will very similar to the next code:
+::
+
+  void f_wrapper( const int& i, const std::string& str ){
+      int i_out( i );
+      std::string str_out( str );
+      boost::python::object f_return = f( i_out, str_out );
+      return boost::python::make_tuple( f_return, i, str );
+  }
+
+
+The only customization available for user is to setup argument type:
+[in\|out\|in,out]
+
+array
+-----
+Arrays are a little bit different beasts. Python does not have arrays.
+So, `pyplusplus`_, should implement arrays convertion: from/to C++/Python.
+This is not the only difference, consider next function:
+::
+
+  void fill( char* buffer, int index ){
+      buffer[ index ] = 'c';
+  }
+
+
+There are few ways to expose this function:
+::
+
+   ??? fill_wrapper( boost::python:list buffer, index ){
+      long buffer_size = boost::python::extract<long>( buffer.attr("__len__") );
+      boost::scoped_array<char> buffer_( new char[ buffer_size ] );
+      for( long i = 0; i < buffer_size; ++i ){
+          buffer_[ i ] = boost::python::extract<char>( buffer[i] );
+      }
+      fill( buffer_.get(), index );
+      //Now the question: how to return buffer_ to the caller?
+      //by constructing new list?
+      boost::python::list return_;
+      for( long i = 0; i < buffer_size; ++i ){
+        return_.insert( i, buffer_[i] );
+      }
+      return return_;
+      //or by modifying the buffer argument? In this case `pyplusplus`_ will
+      //delete all items from buffer and will copy into it items from buffer_
+      //variable.
+  }
+
+Arrays size
+~~~~~~~~~~~
+1. static array - size of array is known at compile time.
+2. dynamic array
+
+   + size of array is one of the function arguments
+
+   + other ( will not be implemented in the first phase )
+
+      - size of array is some global/local variable
+
+      - ize of array is returned by invocation some function
+
+
+status as exception
+-------------------
+There a lot of code, that returns success status and/or error description by
+using one of the function arguments. It will be possible to instruct `pyplusplus`_
+to create wrapper for those functions, that will throw exception.
+::
+
+  bool do_smth( error_description& error_desc );
+
+  bool do_smth_wrapper(){
+      error_description  error_desc;
+      bool return_ = do_smth( error_desc );
+      if( some user code that will check that error_desc contains error ){
+          throw some user code that will construct an exception from the error_desc;
+      }
+      return return_;
+  }
+
+pythread safe
+-------------
+Why not :-)? See next FAQ: http://boost.org/libs/python/doc/v2/faq.html#threadsupport
+So, how `pyplusplus`_ can help? `pyplusplus`_ can generate exception safe code,
+that will acquire and release Python global interpreter lock.
+
+
+.. _`pyplusplus` : ./../pyplusplus.html
+.. |cwp| replace:: *"call wrapper policies"*
+.. _`boost.python`: http://www.boost.org/libs/python/doc/index.html
+.. _`Python`: http://www.python.org
+.. _`GCC-XML`: http://www.gccxml.org
+
+..
+   Local Variables:
+   mode: indented-text
+   indent-tabs-mode: nil
+   sentence-end-double-space: t
+   fill-column: 70
+   End:

Added: pyplusplus_dev/docs/call_wrapper_policies/www_configuration.py
===================================================================
--- pyplusplus_dev/docs/call_wrapper_policies/www_configuration.py	                        (rev 0)
+++ pyplusplus_dev/docs/call_wrapper_policies/www_configuration.py	2006-05-08 07:00:13 UTC (rev 65)
@@ -0,0 +1,2 @@
+name = 'call wrapper policies'
+main_html_file = 'introduction.html'
\ No newline at end of file


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





2006	Jan	Feb	Mar (190)	Apr (166)	May (170)	Jun (75)	Jul (105)	Aug (131)	Sep (99)	Oct (84)	Nov (67)	Dec (54)
2007	Jan (66)	Feb (49)	Mar (25)	Apr (62)	May (21)	Jun (34)	Jul (9)	Aug (21)	Sep (5)	Oct	Nov (63)	Dec (34)
2008	Jan (10)	Feb (42)	Mar (26)	Apr (25)	May (6)	Jun (40)	Jul (18)	Aug (29)	Sep (6)	Oct (32)	Nov (14)	Dec (56)
2009	Jan (127)	Feb (52)	Mar (2)	Apr (10)	May (29)	Jun (3)	Jul	Aug (16)	Sep (4)	Oct (11)	Nov (8)	Dec (14)
2010	Jan (31)	Feb (1)	Mar (7)	Apr (9)	May (1)	Jun	Jul (2)	Aug	Sep	Oct	Nov	Dec
2011	Jan	Feb (8)	Mar (4)	Apr	May	Jun	Jul	Aug	Sep	Oct	Nov	Dec
2014	Jan	Feb	Mar (1)	Apr	May	Jun	Jul	Aug	Sep	Oct	Nov	Dec