1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 4<title>Chapter 1. Concepts</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="index.html" title="Boost.Python Reference Manual"> 9<link rel="prev" href="index.html" title="Boost.Python Reference Manual"> 10<link rel="next" href="concepts/dereferenceable.html" title="Dereferenceable"> 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="index.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="index.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="concepts/dereferenceable.html"><img src="../images/next.png" alt="Next"></a> 17</div> 18<div class="chapter"> 19<div class="titlepage"><div><div><h1 class="title"> 20<a name="concepts"></a>Chapter 1. Concepts</h1></div></div></div> 21<div class="toc"> 22<p><b>Table of Contents</b></p> 23<dl class="toc"> 24<dt><span class="section"><a href="concepts.html#concepts.callpolicies">CallPolicies</a></span></dt> 25<dd><dl> 26<dt><span class="section"><a href="concepts.html#concepts.callpolicies.introduction">Introduction</a></span></dt> 27<dt><span class="section"><a href="concepts.html#concepts.callpolicies.callpolicies_composition">CallPolicies 28 Composition</a></span></dt> 29<dt><span class="section"><a href="concepts.html#concepts.callpolicies.concept_requirements">Concept 30 Requirements</a></span></dt> 31</dl></dd> 32<dt><span class="section"><a href="concepts/dereferenceable.html">Dereferenceable</a></span></dt> 33<dd><dl> 34<dt><span class="section"><a href="concepts/dereferenceable.html#concepts.dereferenceable.introduction">Introduction</a></span></dt> 35<dt><span class="section"><a href="concepts/dereferenceable.html#concepts.dereferenceable.concept_requirements">Concept 36 Requirements</a></span></dt> 37</dl></dd> 38<dt><span class="section"><a href="concepts/extractor.html">Extractor</a></span></dt> 39<dd><dl> 40<dt><span class="section"><a href="concepts/extractor.html#concepts.extractor.introduction">Introduction</a></span></dt> 41<dt><span class="section"><a href="concepts/extractor.html#concepts.extractor.concept_requirements">Concept Requirements</a></span></dt> 42<dt><span class="section"><a href="concepts/extractor.html#concepts.extractor.notes">Notes</a></span></dt> 43</dl></dd> 44<dt><span class="section"><a href="concepts/holdergenerator.html">HolderGenerator</a></span></dt> 45<dd><dl> 46<dt><span class="section"><a href="concepts/holdergenerator.html#concepts.holdergenerator.introduction">Introduction</a></span></dt> 47<dt><span class="section"><a href="concepts/holdergenerator.html#concepts.holdergenerator.concept_requirements">Concept 48 Requirements</a></span></dt> 49</dl></dd> 50<dt><span class="section"><a href="concepts/resultconverter.html">ResultConverter</a></span></dt> 51<dd><dl> 52<dt><span class="section"><a href="concepts/resultconverter.html#concepts.resultconverter.introduction">Introduction</a></span></dt> 53<dt><span class="section"><a href="concepts/resultconverter.html#concepts.resultconverter.resultconverter_concept_requirem">ResultConverter 54 Concept Requirements</a></span></dt> 55<dt><span class="section"><a href="concepts/resultconverter.html#concepts.resultconverter.resultconvertergenerator_concept">ResultConverterGenerator 56 Concept Requirements</a></span></dt> 57</dl></dd> 58<dt><span class="section"><a href="concepts/objectwrapper.html">ObjectWrapper</a></span></dt> 59<dd><dl> 60<dt><span class="section"><a href="concepts/objectwrapper.html#concepts.objectwrapper.introduction">Introduction</a></span></dt> 61<dt><span class="section"><a href="concepts/objectwrapper.html#concepts.objectwrapper.objectwrapper_concept_requiremen">ObjectWrapper 62 Concept Requirements</a></span></dt> 63<dt><span class="section"><a href="concepts/objectwrapper.html#concepts.objectwrapper.typewrapper_concept_requirements">TypeWrapper 64 Concept Requirements</a></span></dt> 65<dt><span class="section"><a href="concepts/objectwrapper.html#concepts.objectwrapper.caveat">Caveat</a></span></dt> 66</dl></dd> 67</dl> 68</div> 69<div class="section"> 70<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 71<a name="concepts.callpolicies"></a><a class="link" href="concepts.html#concepts.callpolicies" title="CallPolicies">CallPolicies</a> 72</h2></div></div></div> 73<div class="toc"><dl class="toc"> 74<dt><span class="section"><a href="concepts.html#concepts.callpolicies.introduction">Introduction</a></span></dt> 75<dt><span class="section"><a href="concepts.html#concepts.callpolicies.callpolicies_composition">CallPolicies 76 Composition</a></span></dt> 77<dt><span class="section"><a href="concepts.html#concepts.callpolicies.concept_requirements">Concept 78 Requirements</a></span></dt> 79</dl></div> 80<div class="section"> 81<div class="titlepage"><div><div><h3 class="title"> 82<a name="concepts.callpolicies.introduction"></a><a class="link" href="concepts.html#concepts.callpolicies.introduction" title="Introduction">Introduction</a> 83</h3></div></div></div> 84<p> 85 Models of the CallPolicies concept are used to specialize the behavior 86 of Python callable objects generated by Boost.Python to wrapped C++ objects 87 like function and member function pointers, providing three behaviors: 88 </p> 89<div class="orderedlist"><ol class="orderedlist" type="1"> 90<li class="listitem"> 91 <code class="computeroutput"><span class="identifier">precall</span></code> - Python argument 92 tuple management before the wrapped object is invoked 93 </li> 94<li class="listitem"> 95 <code class="computeroutput"><span class="identifier">result_converter</span></code> - 96 C++ return value handling 97 </li> 98<li class="listitem"> 99 <code class="computeroutput"><span class="identifier">postcall</span></code> - Python argument 100 tuple and result management after the wrapped object is invoked 101 </li> 102<li class="listitem"> 103 <code class="computeroutput"><span class="identifier">extract_return_type</span></code> 104 - metafunction for extracting the return type from a given signature 105 type sequence 106 </li> 107</ol></div> 108</div> 109<div class="section"> 110<div class="titlepage"><div><div><h3 class="title"> 111<a name="concepts.callpolicies.callpolicies_composition"></a><a class="link" href="concepts.html#concepts.callpolicies.callpolicies_composition" title="CallPolicies Composition">CallPolicies 112 Composition</a> 113</h3></div></div></div> 114<p> 115 In order to allow the use of multiple models of CallPolicies in the same 116 callable object, Boost.Python's CallPolicies class templates provide a 117 chaining interface which allows them to be recursively composed. This interface 118 takes the form of an optional template parameter, <code class="computeroutput"><span class="identifier">Base</span></code>, 119 which defaults to <code class="computeroutput"><span class="identifier">default_call_policies</span></code>. 120 By convention, the <code class="computeroutput"><span class="identifier">precall</span></code> 121 function of the <code class="computeroutput"><span class="identifier">Base</span></code> is 122 invoked after the <code class="computeroutput"><span class="identifier">precall</span></code> 123 function supplied by the <code class="computeroutput"><span class="identifier">outer</span></code> 124 template, and the <code class="computeroutput"><span class="identifier">postcall</span></code> 125 function of the <code class="computeroutput"><span class="identifier">Base</span></code> is 126 invoked before the <code class="computeroutput"><span class="identifier">postcall</span></code> 127 function of the <code class="computeroutput"><span class="identifier">outer</span></code> template. 128 If a <code class="computeroutput"><span class="identifier">result_converter</span></code> is 129 supplied by the <code class="computeroutput"><span class="identifier">outer</span></code> template, 130 it replaces any <code class="computeroutput"><span class="identifier">result_converter</span></code> 131 supplied by the <code class="computeroutput"><span class="identifier">Base</span></code>. For 132 an example, see <code class="computeroutput"><span class="identifier">return_internal_reference</span></code>. 133 </p> 134</div> 135<div class="section"> 136<div class="titlepage"><div><div><h3 class="title"> 137<a name="concepts.callpolicies.concept_requirements"></a><a class="link" href="concepts.html#concepts.callpolicies.concept_requirements" title="Concept Requirements">Concept 138 Requirements</a> 139</h3></div></div></div> 140<div class="informaltable"><table class="table"> 141<colgroup> 142<col> 143<col> 144<col> 145</colgroup> 146<thead><tr> 147<th> 148 <p> 149 Expression 150 </p> 151 </th> 152<th> 153 <p> 154 Type 155 </p> 156 </th> 157<th> 158 <p> 159 Result/Semantics 160 </p> 161 </th> 162</tr></thead> 163<tbody> 164<tr> 165<td> 166 <p> 167 <code class="computeroutput"><span class="identifier">x</span><span class="special">.</span><span class="identifier">precall</span><span class="special">(</span><span class="identifier">a</span><span class="special">)</span></code> 168 </p> 169 </td> 170<td> 171 <p> 172 convertible to <code class="computeroutput"><span class="keyword">bool</span></code> 173 </p> 174 </td> 175<td> 176 <p> 177 returns <code class="computeroutput"><span class="keyword">false</span></code> and 178 <code class="computeroutput"><span class="identifier">PyErr_Occurred</span><span class="special">()</span> <span class="special">!=</span> 179 <span class="number">0</span></code> upon failure, <code class="computeroutput"><span class="keyword">true</span></code> otherwise. 180 </p> 181 </td> 182</tr> 183<tr> 184<td> 185 <p> 186 <code class="computeroutput"><span class="identifier">P</span><span class="special">::</span><span class="identifier">result_converter</span></code> 187 </p> 188 </td> 189<td> 190 <p> 191 A model of <code class="computeroutput"><span class="identifier">ResultConverterGenerator</span></code>. 192 </p> 193 </td> 194<td> 195 <p> 196 An MPL unary Metafunction Class used produce the "preliminary" 197 result object. 198 </p> 199 </td> 200</tr> 201<tr> 202<td> 203 <p> 204 <code class="computeroutput"><span class="identifier">x</span><span class="special">.</span><span class="identifier">postcall</span><span class="special">(</span><span class="identifier">a</span><span class="special">,</span> 205 <span class="identifier">r</span><span class="special">)</span></code> 206 </p> 207 </td> 208<td> 209 <p> 210 convertible to <code class="computeroutput"><span class="identifier">PyObject</span><span class="special">*</span></code> 211 </p> 212 </td> 213<td> 214 <p> 215 <code class="computeroutput"><span class="number">0</span></code> and <code class="computeroutput"><span class="identifier">PyErr_Occurred</span><span class="special">()</span> 216 <span class="special">!=</span> <span class="number">0</span></code> 217 upon failure. Must "conserve references" even in the 218 event of an exception. In other words, if <code class="computeroutput"><span class="identifier">r</span></code> 219 is not returned, its reference count must be decremented; if 220 another existing object is returned, its reference count must 221 be incremented. 222 </p> 223 </td> 224</tr> 225<tr> 226<td> 227 <p> 228 <code class="computeroutput"><span class="identifier">P</span><span class="special">::</span><span class="identifier">extract_return_type</span></code> 229 </p> 230 </td> 231<td> 232 <p> 233 A model of Metafunction. 234 </p> 235 </td> 236<td> 237 <p> 238 An MPL unary Metafunction used extract the return type from a 239 given signature. By default it is derived from <code class="computeroutput"><span class="identifier">mpl</span><span class="special">::</span><span class="identifier">front</span></code>. 240 </p> 241 </td> 242</tr> 243</tbody> 244</table></div> 245</div> 246</div> 247</div> 248<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 249<td align="left"></td> 250<td align="right"><div class="copyright-footer">Copyright © 2002-2005, 2015 David Abrahams, Stefan Seefeld<p> 251 Distributed under the Boost Software License, Version 1.0. (See accompanying 252 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> 253 </p> 254</div></td> 255</tr></table> 256<hr> 257<div class="spirit-nav"> 258<a accesskey="p" href="index.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="index.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="concepts/dereferenceable.html"><img src="../images/next.png" alt="Next"></a> 259</div> 260</body> 261</html> 262
