1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 4<title>boost/python/exception_translator.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="../high_level_components.html" title="Chapter 2. High Level Components"> 9<link rel="prev" href="boost_python_errors_hpp.html" title="boost/python/errors.hpp"> 10<link rel="next" href="boost_python_init_hpp.html" title="boost/python/init.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_errors_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../high_level_components.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_init_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="high_level_components.boost_python_exception_translato"></a><a class="link" href="boost_python_exception_translato.html" title="boost/python/exception_translator.hpp">boost/python/exception_translator.hpp</a> 21</h2></div></div></div> 22<div class="toc"><dl class="toc"> 23<dt><span class="section"><a href="boost_python_exception_translato.html#high_level_components.boost_python_exception_translato.introduction">Introduction</a></span></dt> 24<dt><span class="section"><a href="boost_python_exception_translato.html#high_level_components.boost_python_exception_translato.function_register_exception_tran">Function 25 <code class="computeroutput"><span class="identifier">register_exception_translator</span></code></a></span></dt> 26<dt><span class="section"><a href="boost_python_exception_translato.html#high_level_components.boost_python_exception_translato.example">Example</a></span></dt> 27</dl></div> 28<div class="section"> 29<div class="titlepage"><div><div><h3 class="title"> 30<a name="high_level_components.boost_python_exception_translato.introduction"></a><a class="link" href="boost_python_exception_translato.html#high_level_components.boost_python_exception_translato.introduction" title="Introduction">Introduction</a> 31</h3></div></div></div> 32<p> 33 As described <a class="link" href="boost_python_errors_hpp.html#high_level_components.boost_python_errors_hpp.introduction" title="Introduction">here</a>, 34 it is important to make sure that exceptions thrown by C++ code do not 35 pass into the Python interpreter core. By default, Boost.Python translates 36 all C++ exceptions thrown by wrapped functions and module init functions 37 into Python, but the default translators are extremely limited: most C++ 38 exceptions will appear in Python as a <a href="http://www.python.org/doc/current/lib/module-exceptions.html" target="_top">RuntimeError</a> 39 exception whose representation is 'Unidentifiable C++ Exception'. To produce 40 better error messages, users can register additional exception translators 41 as described below. 42 </p> 43</div> 44<div class="section"> 45<div class="titlepage"><div><div><h3 class="title"> 46<a name="high_level_components.boost_python_exception_translato.function_register_exception_tran"></a><a class="link" href="boost_python_exception_translato.html#high_level_components.boost_python_exception_translato.function_register_exception_tran" title="Function register_exception_translator">Function 47 <code class="computeroutput"><span class="identifier">register_exception_translator</span></code></a> 48</h3></div></div></div> 49<pre class="programlisting"><span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">ExceptionType</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Translate</span><span class="special">></span> 50<span class="keyword">void</span> <span class="identifier">register_exception_translator</span><span class="special">(</span><span class="identifier">Translate</span> <span class="identifier">translate</span><span class="special">);</span> 51</pre> 52<div class="variablelist"> 53<p class="title"><b></b></p> 54<dl class="variablelist"> 55<dt><span class="term">Requires</span></dt> 56<dd> 57<p> 58 Translate is CopyConstructible, and the following code must be well-formed: 59 </p> 60<pre class="programlisting"><span class="keyword">void</span> <span class="identifier">f</span><span class="special">(</span><span class="identifier">ExceptionType</span> <span class="identifier">x</span><span class="special">)</span> <span class="special">{</span> <span class="identifier">translate</span><span class="special">(</span><span class="identifier">x</span><span class="special">);</span> <span class="special">}</span></pre> 61<p> 62 . The expression <code class="computeroutput"><span class="identifier">translate</span><span class="special">(</span><span class="identifier">x</span><span class="special">)</span></code> must either throw a C++ exception, 63 or a subsequent call to <code class="computeroutput"><span class="identifier">PyErr_Occurred</span><span class="special">()</span></code> must return 1. 64 </p> 65</dd> 66<dt><span class="term">Effects</span></dt> 67<dd><p> 68 Adds a copy of translate to the sequence of exception translators 69 tried when Boost.Python catches an exception that is about to pass 70 into Python's core interpreter. The new translator will get "first 71 shot" at translating all exceptions matching the catch clause 72 shown above. Any subsequently-registered translators will be allowed 73 to translate the exception earlier. A translator which cannot translate 74 a given C++ exception can re-throw it, and it will be handled by 75 a translator which was registered earlier (or by the default translator). 76 </p></dd> 77</dl> 78</div> 79</div> 80<div class="section"> 81<div class="titlepage"><div><div><h3 class="title"> 82<a name="high_level_components.boost_python_exception_translato.example"></a><a class="link" href="boost_python_exception_translato.html#high_level_components.boost_python_exception_translato.example" title="Example">Example</a> 83</h3></div></div></div> 84<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">module</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 85<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">def</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 86<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">exception_translator</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 87<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">exception</span><span class="special">></span> 88 89<span class="keyword">struct</span> <span class="identifier">my_exception</span> <span class="special">:</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">exception</span> 90<span class="special">{</span> 91 <span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">what</span><span class="special">()</span> <span class="keyword">throw</span><span class="special">()</span> <span class="special">{</span> <span class="keyword">return</span> <span class="string">"One of my exceptions"</span><span class="special">;</span> <span class="special">}</span> 92<span class="special">};</span> 93 94<span class="keyword">void</span> <span class="identifier">translate</span><span class="special">(</span><span class="identifier">my_exception</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">e</span><span class="special">)</span> 95<span class="special">{</span> 96 <span class="comment">// Use the Python 'C' API to set up an exception object</span> 97 <span class="identifier">PyErr_SetString</span><span class="special">(</span><span class="identifier">PyExc_RuntimeError</span><span class="special">,</span> <span class="identifier">e</span><span class="special">.</span><span class="identifier">what</span><span class="special">());</span> 98<span class="special">}</span> 99 100<span class="keyword">void</span> <span class="identifier">something_which_throws</span><span class="special">()</span> 101<span class="special">{</span> 102 <span class="special">...</span> 103 <span class="keyword">throw</span> <span class="identifier">my_exception</span><span class="special">();</span> 104 <span class="special">...</span> 105<span class="special">}</span> 106 107<span class="identifier">BOOST_PYTHON_MODULE</span><span class="special">(</span><span class="identifier">exception_translator_ext</span><span class="special">)</span> 108<span class="special">{</span> 109 <span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">;</span> 110 <span class="identifier">register_exception_translator</span><span class="special"><</span><span class="identifier">my_exception</span><span class="special">>(&</span><span class="identifier">translate</span><span class="special">);</span> 111 112 <span class="identifier">def</span><span class="special">(</span><span class="string">"something_which_throws"</span><span class="special">,</span> <span class="identifier">something_which_throws</span><span class="special">);</span> 113<span class="special">}</span> 114</pre> 115</div> 116</div> 117<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 118<td align="left"></td> 119<td align="right"><div class="copyright-footer">Copyright © 2002-2005, 2015 David Abrahams, Stefan Seefeld<p> 120 Distributed under the Boost Software License, Version 1.0. (See accompanying 121 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> 122 </p> 123</div></td> 124</tr></table> 125<hr> 126<div class="spirit-nav"> 127<a accesskey="p" href="boost_python_errors_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../high_level_components.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_init_hpp.html"><img src="../../images/next.png" alt="Next"></a> 128</div> 129</body> 130</html> 131
