1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 4<title>boost/python/ptr.hpp</title> 5<link rel="stylesheet" href="../../boostbook.css" type="text/css"> 6<meta name="generator" content="DocBook XSL Stylesheets V1.79.1"> 7<link rel="home" href="../index.html" title="Boost.Python Reference Manual"> 8<link rel="up" href="../function_invocation_and_creation.html" title="Chapter 4. Function Invocation and Creation"> 9<link rel="prev" href="boost_python_overloads_hpp.html" title="boost/python/overloads.hpp"> 10<link rel="next" href="boost_python_raw_function_hpp.html" title="boost/python/raw_function.hpp"> 11</head> 12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> 13<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../../images/boost.png"></td></tr></table> 14<hr> 15<div class="spirit-nav"> 16<a accesskey="p" href="boost_python_overloads_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../function_invocation_and_creation.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="boost_python_raw_function_hpp.html"><img src="../../images/next.png" alt="Next"></a> 17</div> 18<div class="section"> 19<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 20<a name="function_invocation_and_creation.boost_python_ptr_hpp"></a><a class="link" href="boost_python_ptr_hpp.html" title="boost/python/ptr.hpp">boost/python/ptr.hpp</a> 21</h2></div></div></div> 22<div class="toc"><dl class="toc"> 23<dt><span class="section"><a href="boost_python_ptr_hpp.html#function_invocation_and_creation.boost_python_ptr_hpp.introduction">Introduction</a></span></dt> 24<dt><span class="section"><a href="boost_python_ptr_hpp.html#function_invocation_and_creation.boost_python_ptr_hpp.functions">Functions</a></span></dt> 25<dt><span class="section"><a href="boost_python_ptr_hpp.html#function_invocation_and_creation.boost_python_ptr_hpp.class_template_pointer_wrapper">Class 26 template <code class="computeroutput"><span class="identifier">pointer_wrapper</span></code></a></span></dt> 27<dt><span class="section"><a href="boost_python_ptr_hpp.html#function_invocation_and_creation.boost_python_ptr_hpp.class_template_pointer_wrapper_t">Class 28 template <code class="computeroutput"><span class="identifier">pointer_wrapper</span></code> 29 types</a></span></dt> 30<dt><span class="section"><a href="boost_python_ptr_hpp.html#function_invocation_and_creation.boost_python_ptr_hpp.class_template_pointer_wrapper_c">Class 31 template <code class="computeroutput"><span class="identifier">pointer_wrapper</span></code> 32 constructors and destructor</a></span></dt> 33<dt><span class="section"><a href="boost_python_ptr_hpp.html#function_invocation_and_creation.boost_python_ptr_hpp.class_template_pointer_wrapper_o">Class 34 template <code class="computeroutput"><span class="identifier">pointer_wrapper</span></code> 35 observer functions</a></span></dt> 36<dt><span class="section"><a href="boost_python_ptr_hpp.html#function_invocation_and_creation.boost_python_ptr_hpp.metafunctions">Metafunctions</a></span></dt> 37<dt><span class="section"><a href="boost_python_ptr_hpp.html#function_invocation_and_creation.boost_python_ptr_hpp.example">Example</a></span></dt> 38</dl></div> 39<div class="section"> 40<div class="titlepage"><div><div><h3 class="title"> 41<a name="function_invocation_and_creation.boost_python_ptr_hpp.introduction"></a><a class="link" href="boost_python_ptr_hpp.html#function_invocation_and_creation.boost_python_ptr_hpp.introduction" title="Introduction">Introduction</a> 42</h3></div></div></div> 43<p> 44 <boost/python/ptr.hpp> defines the ptr() function template, which 45 allows users to specify how to convert C++ pointer values to python in 46 the context of implementing overridable virtual functions, invoking Python 47 callable objects, or explicitly converting C++ objects to Python. Normally, 48 when passing pointers to Python callbacks, the pointee is copied to ensure 49 that the Python object never holds a dangling reference. To specify that 50 the new Python object should merely contain a copy of a pointer p, the 51 user can pass ptr(p) instead of passing p directly. This interface is meant 52 to mirror the use of boost::ref(), which can be similarly used to prevent 53 copying of referents. 54 </p> 55<p> 56 ptr(p) returns an instance of <a class="link" href="boost_python_ptr_hpp.html#function_invocation_and_creation.boost_python_ptr_hpp.class_template_pointer_wrapper" title="Class template pointer_wrapper"><code class="computeroutput"><span class="identifier">pointer_wrapper</span><span class="special"><></span></code></a>, 57 which can be detected using the <a class="link" href="boost_python_ptr_hpp.html#function_invocation_and_creation.boost_python_ptr_hpp.metafunctions.class_template_is_pointer_wrappe" title="Class template is_pointer_wrapper"><code class="computeroutput"><span class="identifier">is_pointer_wrapper</span><span class="special"><></span></code></a> 58 metafunction; <a class="link" href="boost_python_ptr_hpp.html#function_invocation_and_creation.boost_python_ptr_hpp.metafunctions.class_template_unwrap_pointer" title="Class template unwrap_pointer"><code class="computeroutput"><span class="identifier">unwrap_pointer</span><span class="special"><></span></code></a> 59 is a metafunction which extracts the original pointer type from a <code class="computeroutput"><span class="identifier">pointer_wrapper</span><span class="special"><></span></code>. 60 These classes can be thought of as implementation details. 61 </p> 62</div> 63<div class="section"> 64<div class="titlepage"><div><div><h3 class="title"> 65<a name="function_invocation_and_creation.boost_python_ptr_hpp.functions"></a><a class="link" href="boost_python_ptr_hpp.html#function_invocation_and_creation.boost_python_ptr_hpp.functions" title="Functions">Functions</a> 66</h3></div></div></div> 67<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> 68<span class="identifier">pointer_wrapper</span><span class="special"><</span><span class="identifier">T</span><span class="special">></span> <span class="identifier">ptr</span><span class="special">(</span><span class="identifier">T</span> <span class="identifier">x</span><span class="special">);</span> 69</pre> 70<div class="variablelist"> 71<p class="title"><b></b></p> 72<dl class="variablelist"> 73<dt><span class="term">Requires</span></dt> 74<dd><p> 75 T is a pointer type. 76 </p></dd> 77<dt><span class="term">Returns</span></dt> 78<dd><p> 79 pointer_wrapper<T>(x) 80 </p></dd> 81<dt><span class="term">Throws</span></dt> 82<dd><p> 83 nothing. 84 </p></dd> 85</dl> 86</div> 87</div> 88<div class="section"> 89<div class="titlepage"><div><div><h3 class="title"> 90<a name="function_invocation_and_creation.boost_python_ptr_hpp.class_template_pointer_wrapper"></a><a class="link" href="boost_python_ptr_hpp.html#function_invocation_and_creation.boost_python_ptr_hpp.class_template_pointer_wrapper" title="Class template pointer_wrapper">Class 91 template <code class="computeroutput"><span class="identifier">pointer_wrapper</span></code></a> 92</h3></div></div></div> 93<p> 94 A "type envelope" which is returned by <code class="computeroutput"><span class="identifier">ptr</span><span class="special">()</span></code>, used to indicate reference semantics 95 for pointers passed to Python callbacks. 96 </p> 97<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">python</span> 98<span class="special">{</span> 99 <span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">Ptr</span><span class="special">></span> <span class="keyword">class</span> <span class="identifier">pointer_wrapper</span> 100 <span class="special">{</span> 101 <span class="keyword">public</span><span class="special">:</span> 102 <span class="keyword">typedef</span> <span class="identifier">Ptr</span> <span class="identifier">type</span><span class="special">;</span> 103 104 <span class="keyword">explicit</span> <span class="identifier">pointer_wrapper</span><span class="special">(</span><span class="identifier">Ptr</span> <span class="identifier">x</span><span class="special">);</span> 105 <span class="keyword">operator</span> <span class="identifier">Ptr</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> 106 <span class="identifier">Ptr</span> <span class="identifier">get</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> 107 <span class="special">};</span> 108<span class="special">}}</span> 109</pre> 110</div> 111<div class="section"> 112<div class="titlepage"><div><div><h3 class="title"> 113<a name="function_invocation_and_creation.boost_python_ptr_hpp.class_template_pointer_wrapper_t"></a><a class="link" href="boost_python_ptr_hpp.html#function_invocation_and_creation.boost_python_ptr_hpp.class_template_pointer_wrapper_t" title="Class template pointer_wrapper types">Class 114 template <code class="computeroutput"><span class="identifier">pointer_wrapper</span></code> 115 types</a> 116</h3></div></div></div> 117<pre class="programlisting"><span class="keyword">typedef</span> <span class="identifier">Ptr</span> <span class="identifier">type</span><span class="special">;</span> 118</pre> 119<p> 120 The type of the pointer being wrapped. 121 </p> 122</div> 123<div class="section"> 124<div class="titlepage"><div><div><h3 class="title"> 125<a name="function_invocation_and_creation.boost_python_ptr_hpp.class_template_pointer_wrapper_c"></a><a class="link" href="boost_python_ptr_hpp.html#function_invocation_and_creation.boost_python_ptr_hpp.class_template_pointer_wrapper_c" title="Class template pointer_wrapper constructors and destructor">Class 126 template <code class="computeroutput"><span class="identifier">pointer_wrapper</span></code> 127 constructors and destructor</a> 128</h3></div></div></div> 129<pre class="programlisting"><span class="keyword">explicit</span> <span class="identifier">pointer_wrapper</span><span class="special">(</span><span class="identifier">Ptr</span> <span class="identifier">x</span><span class="special">);</span> 130</pre> 131<div class="variablelist"> 132<p class="title"><b></b></p> 133<dl class="variablelist"> 134<dt><span class="term">Requires</span></dt> 135<dd><p> 136 <code class="computeroutput"><span class="identifier">Ptr</span></code> is a pointer 137 type 138 </p></dd> 139<dt><span class="term">Effects</span></dt> 140<dd><p> 141 Stores <code class="computeroutput"><span class="identifier">x</span></code> in a the 142 <code class="computeroutput"><span class="identifier">pointer_wrapper</span><span class="special"><></span></code>. 143 </p></dd> 144<dt><span class="term">Throws</span></dt> 145<dd><p> 146 nothing. 147 </p></dd> 148</dl> 149</div> 150</div> 151<div class="section"> 152<div class="titlepage"><div><div><h3 class="title"> 153<a name="function_invocation_and_creation.boost_python_ptr_hpp.class_template_pointer_wrapper_o"></a><a class="link" href="boost_python_ptr_hpp.html#function_invocation_and_creation.boost_python_ptr_hpp.class_template_pointer_wrapper_o" title="Class template pointer_wrapper observer functions">Class 154 template <code class="computeroutput"><span class="identifier">pointer_wrapper</span></code> 155 observer functions</a> 156</h3></div></div></div> 157<pre class="programlisting"><span class="keyword">operator</span> <span class="identifier">Ptr</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> 158<span class="identifier">Ptr</span> <span class="identifier">get</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> 159</pre> 160<div class="variablelist"> 161<p class="title"><b></b></p> 162<dl class="variablelist"> 163<dt><span class="term">Returns</span></dt> 164<dd><p> 165 a copy of the stored pointer. 166 </p></dd> 167<dt><span class="term">Rationale</span></dt> 168<dd><p> 169 pointer_wrapper is intended to be a stand-in for the actual pointer 170 type, but sometimes it's better to have an explicit way to retrieve 171 the pointer. 172 </p></dd> 173</dl> 174</div> 175</div> 176<div class="section"> 177<div class="titlepage"><div><div><h3 class="title"> 178<a name="function_invocation_and_creation.boost_python_ptr_hpp.metafunctions"></a><a class="link" href="boost_python_ptr_hpp.html#function_invocation_and_creation.boost_python_ptr_hpp.metafunctions" title="Metafunctions">Metafunctions</a> 179</h3></div></div></div> 180<div class="toc"><dl class="toc"> 181<dt><span class="section"><a href="boost_python_ptr_hpp.html#function_invocation_and_creation.boost_python_ptr_hpp.metafunctions.class_template_is_pointer_wrappe">Class 182 template <code class="computeroutput"><span class="identifier">is_pointer_wrapper</span></code></a></span></dt> 183<dt><span class="section"><a href="boost_python_ptr_hpp.html#function_invocation_and_creation.boost_python_ptr_hpp.metafunctions.class_template_unwrap_pointer">Class 184 template <code class="computeroutput"><span class="identifier">unwrap_pointer</span></code></a></span></dt> 185</dl></div> 186<div class="section"> 187<div class="titlepage"><div><div><h4 class="title"> 188<a name="function_invocation_and_creation.boost_python_ptr_hpp.metafunctions.class_template_is_pointer_wrappe"></a><a class="link" href="boost_python_ptr_hpp.html#function_invocation_and_creation.boost_python_ptr_hpp.metafunctions.class_template_is_pointer_wrappe" title="Class template is_pointer_wrapper">Class 189 template <code class="computeroutput"><span class="identifier">is_pointer_wrapper</span></code></a> 190</h4></div></div></div> 191<p> 192 A unary metafunction whose value is true iff its argument is a pointer_wrapper<>. 193 </p> 194<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">python</span> 195<span class="special">{</span> 196 <span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> <span class="keyword">class</span> <span class="identifier">is_pointer_wrapper</span> 197 <span class="special">{</span> 198 <span class="keyword">static</span> <span class="identifier">unspecified</span> <span class="identifier">value</span> <span class="special">=</span> <span class="special">...;</span> 199 <span class="special">};</span> 200<span class="special">}}</span> 201</pre> 202<div class="variablelist"> 203<p class="title"><b></b></p> 204<dl class="variablelist"> 205<dt><span class="term">Returns</span></dt> 206<dd><p> 207 <code class="computeroutput"><span class="keyword">true</span></code> iff <code class="computeroutput"><span class="identifier">T</span></code> is a specialization of <code class="computeroutput"><span class="identifier">pointer_wrapper</span><span class="special"><></span></code>. 208 value is an integral constant convertible to bool of unspecified 209 type 210 </p></dd> 211</dl> 212</div> 213</div> 214<div class="section"> 215<div class="titlepage"><div><div><h4 class="title"> 216<a name="function_invocation_and_creation.boost_python_ptr_hpp.metafunctions.class_template_unwrap_pointer"></a><a class="link" href="boost_python_ptr_hpp.html#function_invocation_and_creation.boost_python_ptr_hpp.metafunctions.class_template_unwrap_pointer" title="Class template unwrap_pointer">Class 217 template <code class="computeroutput"><span class="identifier">unwrap_pointer</span></code></a> 218</h4></div></div></div> 219<p> 220 A unary metafunction which extracts the wrapped pointer type from a specialization 221 of pointer_wrapper<>. 222 </p> 223<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">python</span> 224<span class="special">{</span> 225 <span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> <span class="keyword">class</span> <span class="identifier">unwrap_pointer</span> 226 <span class="special">{</span> 227 <span class="keyword">typedef</span> <span class="identifier">unspecified</span> <span class="identifier">type</span><span class="special">;</span> 228 <span class="special">};</span> 229<span class="special">}}</span> 230</pre> 231<div class="variablelist"> 232<p class="title"><b></b></p> 233<dl class="variablelist"> 234<dt><span class="term">Returns</span></dt> 235<dd><p> 236 <code class="computeroutput"><span class="identifier">T</span><span class="special">::</span><span class="identifier">type</span></code> if <code class="computeroutput"><span class="identifier">T</span></code> 237 is a specialization of <code class="computeroutput"><span class="identifier">pointer_wrapper</span><span class="special"><></span></code>, <code class="computeroutput"><span class="identifier">T</span></code> 238 otherwise 239 </p></dd> 240</dl> 241</div> 242</div> 243</div> 244<div class="section"> 245<div class="titlepage"><div><div><h3 class="title"> 246<a name="function_invocation_and_creation.boost_python_ptr_hpp.example"></a><a class="link" href="boost_python_ptr_hpp.html#function_invocation_and_creation.boost_python_ptr_hpp.example" title="Example">Example</a> 247</h3></div></div></div> 248<p> 249 This example illustrates the use of ptr() to prevent an object from being 250 copied: 251 </p> 252<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">call</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 253<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">ptr</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 254 255<span class="keyword">class</span> <span class="identifier">expensive_to_copy</span> 256<span class="special">{</span> 257 <span class="special">...</span> 258<span class="special">};</span> 259 260<span class="keyword">void</span> <span class="identifier">pass_as_arg</span><span class="special">(</span><span class="identifier">expensive_to_copy</span><span class="special">*</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">f</span><span class="special">)</span> 261<span class="special">{</span> 262 <span class="comment">// call the Python function f, passing a Python object built around</span> 263 <span class="comment">// which refers to *x by-pointer.</span> 264 <span class="comment">//</span> 265 <span class="comment">// *** Note: ensuring that *x outlives the argument to f() is ***</span> 266 <span class="comment">// *** up to the user! Failure to do so could result in a crash! ***</span> 267 268 <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">::</span><span class="identifier">call</span><span class="special"><</span><span class="keyword">void</span><span class="special">>(</span><span class="identifier">f</span><span class="special">,</span> <span class="identifier">ptr</span><span class="special">(</span><span class="identifier">x</span><span class="special">));</span> 269<span class="special">}</span> 270<span class="special">...</span> 271</pre> 272</div> 273</div> 274<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 275<td align="left"></td> 276<td align="right"><div class="copyright-footer">Copyright © 2002-2005, 2015 David Abrahams, Stefan Seefeld<p> 277 Distributed under the Boost Software License, Version 1.0. (See accompanying 278 file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a> 279 </p> 280</div></td> 281</tr></table> 282<hr> 283<div class="spirit-nav"> 284<a accesskey="p" href="boost_python_overloads_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../function_invocation_and_creation.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="boost_python_raw_function_hpp.html"><img src="../../images/next.png" alt="Next"></a> 285</div> 286</body> 287</html> 288
