diff --git a/doc/v2/with_custodian_and_ward.html b/doc/v2/with_custodian_and_ward.html index 89ecb42c..e6fc15df 100644 --- a/doc/v2/with_custodian_and_ward.html +++ b/doc/v2/with_custodian_and_ward.html @@ -1,149 +1,199 @@ - - + + + + - - Boost.Python - <boost/python/with_custodian_and_ward.hpp> - - + + Boost.Python - <boost/python/with_custodian_and_ward.hpp> + + + +
+
-

-

- +

+ C++ Boost + +

+ 		-

Boost.Python

- -

Header <boost/python/with_custodian_and_ward.hpp>

+

+ Boost.Python +

+

+ Header <boost/python/with_custodian_and_ward.hpp> +

+
- -

Contents

- +

+ Contents +

-
Introduction - - -
Classes +
+ Introduction +
+
+ Classes +
-
- -
Class Template with_custodian_and_ward +
+ Class Template + with_custodian_and_ward +
- -
Class Template - with_custodian_and_ward synopsis - -
Class - with_custodian_and_ward static functions +
+ Class + Template with_custodian_and_ward synopsis +
+
+ Class + with_custodian_and_ward static functions +
- -
Class Template with_custodian_and_ward_postcall +
+
+ Class Template + with_custodian_and_ward_postcall +
- -
Class Template - with_custodian_and_ward_postcall synopsis - -
Class - with_custodian_and_ward_postcall static functions +
+ Class + Template with_custodian_and_ward_postcall + synopsis +
+
+ Class + with_custodian_and_ward_postcall static + functions +
+
- - -
Example + +
+ 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 +

+ 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). If the custodian object does not support weak - references and is not None, an appropriate exception - will be thrown. 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

- - + references and is not None, an appropriate exception will be + thrown. 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. +

+

+ Please note that this is not the appropriate tool to use when + wrapping functions which transfer ownership of a raw pointer + across the function-call boundary. Please see the FAQ if you want to do that. +

+

+ Classes +

+

+ Class template + with_custodian_and_ward +

- + + + + - + + + - + + + - + + + +
with_custodian_and_ward template parameters
Parameter - - Requirements - - Description - - Default - + + 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. - - + + 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). - - + + 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 - + + Base + + A model of CallPolicies + + Used for policy + composition. + + default_call_policies +
- -

Class template with_custodian_and_ward synopsis

-
+    

+      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>
@@ -153,85 +203,107 @@ namespace boost { namespace python
    };
 }}
 

-
-    
Class
-    with_custodian_and_ward static functions

-
-
+    

+      Class
+      with_custodian_and_ward 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

-
-
-    
+      

+        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
+        with_custodian_and_ward_postcall template
+        parameters
       
       
Parameter
-        
-        Requirements
-
-        Description
-
-        Default
-
+        
+          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.
-
-
+        
+          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). 
-
+        
+          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
-
+        
+          Base
+        
+          A model of CallPolicies
+        
+          Used for policy
+          composition.
+        
+          default_call_policies
+        

     

-
-    
Class template with_custodian_and_ward_postcall synopsis

-
+    

+      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>
@@ -241,51 +313,55 @@ namespace boost { namespace python
    };
 }}
 

-
-    
Class
-    with_custodian_and_ward_postcall static functions

-
-
+    

+      Class
+      with_custodian_and_ward_postcall 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.
+      

+        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
-
-
+    

+      Example
+    
The following example shows how
+    with_custodian_and_ward_postcall is used by the library to
+    implement return_internal_reference
+    
+    
 template <std::size_t owner_arg = 1, class Base = default_call_policies>
 struct return_internal_reference
     : with_custodian_and_ward_postcall<0, owner_arg, Base>
 {
-   typedef reference_existing_object result_converter;
+   typedef reference_existing_object result_converter;
 };
 

-
-    
Revised 
-    
-  13 November, 2002
-  
-
-    
© Copyright Dave
-    Abrahams 2002. All Rights Reserved.
-
+    

+      Revised 
+      
+       13 November, 2002 
+      
+      

+    

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

+  
+