mirror of
https://github.com/boostorg/python.git
synced 2026-01-19 16:32:16 +00:00
220 lines
6.8 KiB
HTML
220 lines
6.8 KiB
HTML
<!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>
|