1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta name="generator" content=
"HTML Tidy for Windows (vers 1st August 2002), 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/exception_translator.hpp></title>
</head>
<body>
<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>
<td valign="top">
<h1 align="center"><a href="../index.html">Boost.Python</a></h1>
<h2 align="center">Header
<boost/python/exception_translator.hpp></h2>
</td>
</tr>
</table>
<hr>
<h2>Contents</h2>
<dl class="page-index">
<dt><a href="#introduction">Introduction</a></dt>
<dt><a href="#functions">Functions</a></dt>
<dd>
<dl class="page-index">
<dt><a href=
"#register_exception_translator-spec">register_exception_translator</a></dt>
</dl>
</dd>
<dt><a href="#examples">Example(s)</a></dt>
</dl>
<hr>
<h2><a name="introduction"></a>Introduction</h2>
<p>As described <a href="errors.html#handle_exception-spec">here</a>, it
is important to make sure that exceptions thrown by C++ code do not pass
into the Python interpreter core. By default, Boost.Python translates all
C++ exceptions thrown by wrapped functions and module init functions into
Python, but the default translators are extremely limited: most C++
exceptions will appear in Python as a <a href=
"http://www.python.org/doc/current/lib/module-exceptions.html">RuntimeError</a>
exception whose representation is
<code>'Unidentifiable C++ Exception'</code>. To produce better
error messages, users can register additional exception translators as
described below.</p>
<h2><a name="functions"></a>Functions</h2>
<h3><code><a name="register_exception_translator-spec">register_exception_translator</a></code></h3>
<pre>
<a name="register_exception_translator-spec">template<class ExceptionType, class Translate></a>
void register_exception_translator(Translate translate);
</pre>
<dl class="function-semantics">
<dt><b>Requires:</b></dt>
<dd>
<code>Translate</code> is <a href=
"../../../utility/CopyConstructible.html">Copyconstructible</a>, and
the following code must be well-formed:
<pre>
void f(ExceptionType x) { translate(x); }
</pre>
The expression <code>translate(x)</code> must either throw a C++
exception, or a subsequent call to <code><a href=
"http://www.python.org/doc/current/api/exceptionHandling.html">PyErr_Occurred</a>()</code>
must return 1.
</dd>
<p>
<dt><b>Effects:</b> Adds a copy of <code>translate</code> to the sequence of
exception translators tried when Boost.Python catches an exception that
is about to pass into Python's core interpreter. The new translator
will get "first shot" at translating all exceptions matching the catch
clause shown above. Any subsequently-registered translators will be
allowed to translate the exception earlier. A translator which cannot
translate a given C++ exception can re-throw it, and it will be handled
by a translator which was registered earlier (or by the default
translator).</dt>
</dl>
<h2><a name="examples"></a>Example</h2>
<pre>
#include <boost/python/module.hpp>
#include <boost/python/def.hpp>
#include <boost/python/exception_translator.hpp>
#include <exception>
struct my_exception : std::exception
{
char const* what() throw() { return "One of my exceptions"; }
};
void translate(my_exception const& e)
{
// Use the Python 'C' API to set up an exception object
PyErr_SetString(PyExc_RuntimeError, e.what());
}
void something_which_throws()
{
...
throw my_exception();
...
}
BOOST_PYTHON_MODULE(exception_translator_ext)
{
using namespace boost::python;
register_exception_translator<my_exception>(&translate);
def("something_which_throws", something_which_throws);
}
</pre>
<br>
<br>
<hr>
<p>Revised 03 October, 2002</p>
<p><i>© Copyright <a href=
"../../../../people/dave_abrahams.htm">Dave Abrahams</a> 2002.</i></p>
</body>
</html>
|
