diff options
Diffstat (limited to 'libs/python/doc/v2/instance_holder.html')
| -rw-r--r-- | libs/python/doc/v2/instance_holder.html | 219 |
1 files changed, 219 insertions, 0 deletions
diff --git a/libs/python/doc/v2/instance_holder.html b/libs/python/doc/v2/instance_holder.html new file mode 100644 index 000000000..87571d1da --- /dev/null +++ b/libs/python/doc/v2/instance_holder.html @@ -0,0 +1,219 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> + + +<!-- Copyright David Abrahams 2006. Distributed under the Boost --> +<!-- Software License, Version 1.0. (See accompanying --> +<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> +<html> + <head> + <meta name="generator" content="HTML Tidy, see www.w3.org"> + <meta http-equiv="Content-Type" content= + "text/html; charset=iso-8859-1"> + <link rel="stylesheet" type="text/css" href="../boost.css"> + + <title>Boost.Python - <boost/python/instance_holder.hpp></title> + </head> + +<style type="text/css"> + p.c4 {font-style: italic} + span.c3 {color: #ff0000} + h2.c2 {text-align: center} + h1.c1 {text-align: center} +</style> + + <body link="#0000ff" vlink="#800080"> + <table border="0" cellpadding="7" cellspacing="0" width="100%" + summary="header"> + <tr> + <td valign="top" width="300"> + <h3><a href="../../../../index.htm"><img height="86" width= + "277" alt="C++ Boost" src="../../../../boost.png" border= + "0"></a></h3> + + <td valign="top"> + <h1 class="c1"><a href="../index.html">Boost.Python</a></h1> + + <h2 class="c2">Header <boost/python/instance_holder.hpp></h2> + </table> + <hr> + + <h2>Contents</h2> + + <dl class="page-index"> + <dt><a href="#introduction">Introduction</a> + + <dt><a href="#classes">Classes</a> + + <dd> + <dl class="page-index"> + <dt><a href="#instance_holder-spec">Class + <code>instance_holder</code></a> + + <dd> + <dl class="page-index"> + <dt><a href="#instance_holder-spec-synopsis">Class + <code>instance_holder</code> synopsis</a> + + <dt><a href="#instance_holder-spec-ctors">Class + <code>instance_holder</code> destructor</a> + + <dt><a href="#instance_holder-spec-modifiers">Class + <code>instance_holder</code> modifier functions</a> + + <dt><a href="#instance_holder-spec-observers">Class + <code>instance_holder</code> observer functions</a> + </dl> + </dl> + + <dt><a href="#examples">Example</a> + </dl> + <hr> + + <h2><a name="introduction"></a>Introduction</h2> + + <p><code><boost/python/instance_holder.hpp></code> provides + <code>class instance_holder</code>, the base class for types + which hold C++ instances of wrapped classes. + + <h2><a name="classes"></a>Classes</h2> + + <h3><a name="instance_holder-spec"></a>Class <code>instance_holder</code></h3> + + <p><code>instance_holder</code> is an abstract base class whose + concrete derived classes hold C++ class instances within their + Python object wrappers. To allow multiple inheritance in Python + from C++ class wrappers, each such Python object contains a chain + of <code>instance_holder</code>s. When an <code>__init__</code> + function for a wrapped C++ class is invoked, a new + <code>instance_holder</code> instance is created and installed in + the Python object using its <code><a + href="#instance_holder-spec-modifiers">install</a></code>() + function. Each concrete class derived from + <code>instance_holder</code> must provide a <code><a + href="#instance_holder-spec-observers">holds</a>()</code> + implementation which allows Boost.Python to query it for the + type(s) it is holding. In order to support the held type's wrapped + constructor(s), the class must also provide constructors that can + accept an initial <code>PyObject*</code> argument referring to the + owning Python object, and which forward the rest of their + arguments to the constructor of the held type. The initial + argument is needed to enable virtual function overriding in + Python, and may be ignored, depending on the specific + <code>instance_holder</code> subclass. + + <h4><a name="instance_holder-spec-synopsis"></a>Class instance_holder + synopsis</h4> +<pre> +namespace boost { namespace python +{ + class instance_holder : <a href="../../../utility/utility.htm#Class_noncopyable">noncopyable</a> + { + public: + // destructor + virtual ~instance_holder(); + + // instance_holder modifiers + void install(PyObject* inst) throw(); + + // instance_holder observers + virtual void* holds(type_info) = 0; + }; +}} +</pre> + + <h4><a name="instance_holder-spec-ctors">Class <code>instance_holder</code> + destructor</a></h4> +<pre> +virtual ~instance_holder(); +</pre> + + <dl class="function-semantics"> + <dt><b>Effects:</b> destroys the object + </dl> + + <h4><a name="instance_holder-spec-modifiers">Class + <code>instance_holder</code> modifiers</a></h4> +<pre> +void install(PyObject* inst) throw(); +</pre> + + <dl class="function-semantics"> + <dt><b>Requires:</b> <code>inst</code> is a Python instance of a + wrapped C++ class type, or is a type derived from a wrapped C++ + class type. + <dt><b>Effects:</b> installs the new instance at the head of the + Python object's chain of held instances. + <dt><b>Throws:</b> nothing + </dl> + + <h4><a name="instance_holder-spec-observers">Class <code>instance_holder</code> + observers</a></h4> +<pre> +virtual void* holds(type_info x) = 0; +</pre> + + <dl class="function-semantics"> + <dt><b>Returns:</b> A pointer to an object of the type described + by <code>x</code> if <code>*this</code> contains such an object, + 0 otherwise. + </dl> + + <h2><a name="examples"></a>Example</h2> + +The following is a simplified version of the instance holder template +used by Boost.Python to wrap classes held by smart pointers: +<pre> +template <class SmartPtr, class Value> +struct pointer_holder : instance_holder +{ + // construct from the SmartPtr type + pointer_holder(SmartPtr p) + :m_p(p) + + // Forwarding constructors for the held type + pointer_holder(PyObject*) + :m_p(new Value()) + { + } + + template<class A0> + pointer_holder(PyObject*,A0 a0) + :m_p(new Value(a0)) + { + } + + template<class A0,class A1> + pointer_holder(PyObject*,A0 a0,A1 a1) + :m_p(new Value(a0,a1)) + { + } + ... + + private: // required holder implementation + void* holds(type_info dst_t) + { + // holds an instance of the SmartPtr type... + if (dst_t == python::type_id<SmartPtr>()) + return &this->m_p; + + // ...and an instance of the SmartPtr's element_type, if the + // pointer is non-null + return python::type_id<Value>() == dst_t ? &*this->m_p : 0; + } + + private: // data members + SmartPtr m_p; +}; +</pre> + + <p>Revised + <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> + 13 November, 2002 + <!--webbot bot="Timestamp" endspan i-checksum="39359" --> + + + <p class="c4">© Copyright <a href= + "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002. + + </body> +</html> |