Differences between revisions 1 and 11 (spanning 10 versions)
Revision 1 as of 2002-11-16 02:01:48
Size: 913
Editor: MikeRovner
Comment:
Revision 11 as of 2003-10-24 17:44:08
Size: 2507
Editor: MikeRovner
Comment:
Deletions are marked like this. Additions are marked like this.
Line 1: Line 1:
CallPolicy allows boost.python to deal with raw references and pointers. `CallPolicy` allows ["boost.python"] to deal with raw references and pointers.
Line 6: Line 6:
== with_custodian_and_ward ==
ties lifetimes of the arguments
== with_custodian_and_ward<M,N> ==
Keeps N-th argument as long as M-th is alive.
Line 9: Line 9:
== with_custodian_and_ward_postcall == Use of template parameters M,N:
 * 1 - 1st argument (self for method calls)
 * 2 - 2nd argument (1st for method calls)
 * ...

For example, container operation ''append'' usualy uses {{{with_custodian_and_ward<1,2>}}} which means keep argument alive while container itself is alive.

== with_custodian_and_ward_postcall<M,N> ==
Line 12: Line 19:
M,N same as before but also you can use 0 - result
Line 13: Line 22:
ties lifetime of one argument to that of result
keep the owning object alive as long as the owned objects are also alive.
Builds a Python object around a pointer to
the C++ result object (which must have a class_<> wrapper somewhere),
and applies some lifetime management to keep the "self" object alive
as long as the Python result is alive. NULL pointer returning as None.
Line 22: Line 33:
["boost.python/ResultConverterGenerator"] which can be used to wrap C++ functions returning
a reference or pointer to a C++ object.

When the wrapped function is called, the value referenced by its return value is not copied. [[BR]]
A new Python object is created which contains an unowned U* pointer to the referent of the wrapped function's return value, and no attempt is made to ensure that the lifetime of the referent is at least as long as that of the corresponding Python object.

This class is used in the implementation of return_internal_reference.
Also NULL pointer returning as None.
Line 25: Line 45:
Boost.Python v1 approach BoostPython v1 approach
Line 28: Line 48:
Adopt a pointer and hold the instance BoostPython/ResultConverterGenerator which can be used to wrap C++ functions returning
a pointer to an object allocated with a ''new-expression'' and
expecting the caller to take responsibility for deleting that C++ object from heap.
["boost.python"] will do it as part of Python object destruction.
Line 36: Line 59:
def("Tfactory", factory, return_value_policy<manage_new_object> ); def("Tfactory", factory, return_value_policy<manage_new_object>() );
Line 38: Line 61:

=== return_by_value ===
["boost.python/ResultConverterGenerator"] which can be used to wrap C++ functions returning
any reference or value type.[[BR]]
The return value is copied into a new Python object.

CallPolicy allows ["boost.python"] to deal with raw references and pointers. Different policies specifies different strategies of managing object ownership.

TableOfContents

with_custodian_and_ward<M,N>

Keeps N-th argument as long as M-th is alive.

Use of template parameters M,N:

  • 1 - 1st argument (self for method calls)
  • 2 - 2nd argument (1st for method calls)
  • ...

For example, container operation append usualy uses with_custodian_and_ward<1,2> which means keep argument alive while container itself is alive.

with_custodian_and_ward_postcall<M,N>

ties lifetimes of the arguments and results

M,N same as before but also you can use 0 - result

return_internal_reference

Builds a Python object around a pointer to the C++ result object (which must have a class_<> wrapper somewhere), and applies some lifetime management to keep the "self" object alive as long as the Python result is alive. NULL pointer returning as None.

return_value_policy<T>

with T one of:

reference_existing_object

naïve (dangerous) approach

["boost.python/ResultConverterGenerator"] which can be used to wrap C++ functions returning a reference or pointer to a C++ object.

When the wrapped function is called, the value referenced by its return value is not copied. BR A new Python object is created which contains an unowned U* pointer to the referent of the wrapped function's return value, and no attempt is made to ensure that the lifetime of the referent is at least as long as that of the corresponding Python object.

This class is used in the implementation of return_internal_reference. Also NULL pointer returning as None.

copy_non_const_reference

copy_const_reference

BoostPython v1 approach

manage_new_object

BoostPython/ResultConverterGenerator which can be used to wrap C++ functions returning a pointer to an object allocated with a new-expression and expecting the caller to take responsibility for deleting that C++ object from heap. ["boost.python"] will do it as part of Python object destruction.

Use case:

T* factory() { return new T(); }

class_<T>("T");

def("Tfactory", factory, return_value_policy<manage_new_object>() );

return_by_value

["boost.python/ResultConverterGenerator"] which can be used to wrap C++ functions returning any reference or value type.BR The return value is copied into a new Python object.

boost.python/CallPolicy (last edited 2008-11-15 14:01:02 by localhost)

Unable to edit the page? See the FrontPage for instructions.