diff --git a/doc/v2/with_custodian_and_ward.html b/doc/v2/with_custodian_and_ward.html new file mode 100644 index 00000000..ebcbcaa0 --- /dev/null +++ b/doc/v2/with_custodian_and_ward.html @@ -0,0 +1,278 @@ + + + + + + Boost.Python - <boost/python/with_custodian_and_ward.hpp> + + + +
+

+

+ + 		+

Boost.Python

+ +

Header <boost/python/with_custodian_and_ward.hpp>

+
+
+ +

Contents

+ +
+
Introduction + + +
Classes + +
+
+
Class Template with_custodian_and_ward + +
+
+ +
Class Template + with_custodian_and_ward synopsis + +
Class + with_custodian_and_ward static functions +
+
+ + +
Example +
+
+ +

Introduction

+ + This header provides faciliites for establishing a lifetime + dependency between two of a function's Python argument or result + objects. The ward object will not be destroyed until after + the custodian as long as the custodian object supports weak + references (Boost.Python extension classes all support weak + references). The two class templates + with_custodian_and_ward and + with_custodian_and_ward_postcall differ in the point + at which they take effect. + +

In order to reduce the chance of inadvertently + creating dangling pointers, the default is to do lifetime binding + before the underlying C++ object is invoked. However, + before invocation the result object is not available, so + with_custodian_and_ward_postcall is provided to bind + lifetimes after invocation. Also, if a C++ exception is thrown + after with_custodian_and_ward<>::precall but + before the underlying C++ object actually stores a pointer, the + lifetime of the custodian and ward objects will be artificially + bound together, so one might choose + with_custodian_and_ward_postcall instead, depending + on the semantics of the function being wrapped. + +

Classes

+ +

Class template with_custodian_and_ward

+ + + + + + + + +
+ with_custodian_and_ward template parameters +
Parameter + + Requirements + + Description + + Default + +
custodian + + A positive compile-time constant of type + std::size_t. + + The 1-based index of the parameter which is the dependency in the + lifetime relationship to be established. If used to + wrap a member function, parameter 1 is the target object + (*this). Note that if the target Python object + type doesn't support weak references, a Python + TypeError exception will be raised when the + C++ object being wrapped is called. + + +
ward + + A positive compile-time constant of type + std::size_t. + + The 1-based index of the parameter which is the dependent in the + lifetime relationship to be established. If used to + wrap a member function, parameter 1 is the target object + (*this). + + +
Base + + A model of CallPolicies + + Used for policy composition. + + default_call_policies + +
+ +

Class template with_custodian_and_ward synopsis

+
+namespace boost { namespace python
+{
+   template <std::size_t custodian, std::size_t ward, class Base = default_call_policies>
+   struct with_custodian_and_ward : Base
+   {
+      static bool precall(PyObject* args);
+   };
+}}
+
+ +

Class + default_call_policies static functions

+ +
+bool precall(PyObject* args);
+
+ +
+
Requires: PyTuple_Check(args) != 0 +
Effects: Makes the lifetime of the argument indicated + by ward dependent on the lifetime of the argument + indicated by custodian. + +
Returns: false and PyErr_Occurred() != 0 + upon failure, true otherwise. +
+ + + + +

Class template with_custodian_and_ward_postcall

+ + + + + + + + +
+ with_custodian_and_ward_postcall template parameters +
Parameter + + Requirements + + Description + + Default + +
custodian + + A compile-time constant of type + std::size_t. + + The index of the parameter which is the dependency in the + lifetime relationship to be established. Zero indicates the + result object; 1 indicates the first argument. If used to wrap + a member function, parameter 1 is the target object + (*this). Note that if the target Python object + type doesn't support weak references, a Python + TypeError exception will be raised when the + C++ object being wrapped is called. + + +
ward + + A compile-time constant of type std::size_t. + + The index of the parameter which is the dependent in the + lifetime relationship to be established. Zero indicates the + result object; 1 indicates the first argument. If used to wrap + a member function, parameter 1 is the target object + (*this). + +
Base + + A model of CallPolicies + + Used for policy + composition. + + default_call_policies + +
+ +

Class template with_custodian_and_ward_postcall synopsis

+
+namespace boost { namespace python
+{
+   template <std::size_t custodian, std::size_t ward, class Base = default_call_policies>
+   struct with_custodian_and_ward_postcall : Base
+   {
+      static PyObject* postcall(PyObject* args, PyObject* result);
+   };
+}}
+
+ +

Class + default_call_policies static functions

+ +
+PyObject* postcall(PyObject* args, PyObject* result);
+
+ +
+
Requires: PyTuple_Check(args) + != 0, result != 0. + +
Effects: Makes the lifetime of the object indicated + by ward dependent on the lifetime of the object + indicated by custodian. + +
Returns: 0 and PyErr_Occurred() != 0 + upon failure, true otherwise. +
+ + + +

Example

+ +The following example shows how +with_custodian_and_ward_postcall is used by the library +to implement return_internal_reference + +
+template 
+struct return_internal_reference
+    : with_custodian_and_ward_postcall<0, owner_arg, Base>
+{
+   typedef reference_existing_object result_converter;
+};
+
+ +

Revised + + 19 February, 2002 + + +

© Copyright Dave + Abrahams 2002. All Rights Reserved. +