Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/boost_1_34_1/libs/python/doc/v2/errors.html @ 45

Last change on this file since 45 was 29, checked in by landauf, 17 years ago

updated boost from 1_33_1 to 1_34_1
File size: 9.4 KB
Line 
1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2
3<!-- Copyright David Abrahams 2006. Distributed under the Boost -->
4<!-- Software License, Version 1.0. (See accompanying -->
5<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
6<html>
7  <head>
8    <meta name="generator" content=
9    "HTML Tidy for Windows (vers 1st August 2002), see www.w3.org">
10    <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
11    <link rel="stylesheet" type="text/css" href="../boost.css">
12
13    <title>Boost.Python - &lt;boost/python/errors.hpp&gt;</title>
14  </head>
15
16  <body>
17    <table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
18    "header">
19      <tr>
20        <td valign="top" width="300">
21          <h3><a href="../../../../index.htm"><img height="86" width="277"
22          alt="C++ Boost" src="../../../../boost.png" border="0"></a></h3>
23        </td>
24
25        <td valign="top">
26          <h1 align="center"><a href="../index.html">Boost.Python</a></h1>
27
28          <h2 align="center">Header &lt;boost/python/errors.hpp&gt;</h2>
29        </td>
30      </tr>
31    </table>
32    <hr>
33
34    <h2>Contents</h2>
35
36    <dl class="page-index">
37      <dt><a href="#introduction">Introduction</a></dt>
38
39      <dt><a href="#classes">Classes</a></dt>
40
41      <dd>
42        <dl class="page-index">
43          <dt><a href="#error_already_set-spec">Class
44          <code>error_already_set</code></a></dt>
45
46          <dd>
47            <dl class="page-index">
48              <dt><a href="#error_already_set-spec-synopsis">Class
49              <code>error_already_set</code> synopsis</a></dt>
50            </dl>
51          </dd>
52        </dl>
53      </dd>
54
55      <dt><a href="#functions">Functions</a></dt>
56
57      <dd>
58        <dl class="page-index">
59          <dt><a href="#handle_exception-spec">handle_exception</a></dt>
60
61          <dt><a href="#expect_non_null-spec">expect_non_null</a></dt>
62
63          <dt><a href=
64          "#throw_error_already_set-spec">throw_error_already_set</a></dt>
65        </dl>
66      </dd>
67
68      <dt><a href="#examples">Examples</a></dt>
69    </dl>
70    <hr>
71
72    <h2><a name="introduction"></a>Introduction</h2>
73
74    <p><code>&lt;boost/python/errors.hpp&gt;</code> provides types and
75    functions for managing and translating between Python and C++ exceptions.
76    This is relatively low-level functionality that is mostly used internally
77    by Boost.Python. Users should seldom need it.</p>
78
79    <h2><a name="classes"></a>Classes</h2>
80
81    <h3><a name="error_already_set-spec"></a>Class
82    <code>error_already_set</code></h3>
83
84    <p><code>error_already_set</code> is an exception type which can be
85    thrown to indicate that a Python error has occurred. If thrown, the
86    precondition is that <a href=
87    "http://www.python.org/doc/2.2/api/exceptionHandling.html#l2h-71">PyErr_Occurred()</a>
88    returns a value convertible to <code>true</code>. Portable code shouldn't
89    throw this exception type directly, but should instead use <code><a href=
90    "#throw_error_already_set-spec">throw_error_already_set</a>()</code>,
91    below.</p>
92
93    <h4><a name="error_already_set-spec-synopsis"></a>Class error_already_set
94    synopsis</h4>
95<pre>
96namespace boost { namespace python
97{
98    class error_already_set {};
99}}
100</pre>
101
102    <h2><a name="functions"></a>Functions</h2>
103<pre>
104<a name=
105"handle_exception-spec">template &lt;class T&gt; bool handle_exception</a>(T f) throw();
106
107void handle_exception() throw();
108</pre>
109
110    <dl class="handle_exception-semantics">
111      <dt><b>Requires:</b> The first form requires that the expression
112      <code><a href=
113      "../../../../doc/html/functionN.html">function0</a>&lt;void&gt;(f)</code>
114      is valid. The second form requires that a C++ exception is currently
115      being handled (see section 15.1 in the C++ standard).</dt>
116
117      <dt><b>Effects:</b> The first form calls <code>f()</code> inside a
118      <code>try</code> block which first attempts to use all registered <a
119      href="exception_translator.html">exception translators</a>. If none of
120      those translates the exception, the <code>catch</code> clauses then set
121      an appropriate Python exception for the C++ exception caught, returning
122      <code>true</code> if an exception was thrown, <code>false</code>
123      otherwise. The second form passes a function which rethrows the
124      exception currently being handled to the first form.</dt>
125
126      <dt><b>Postconditions:</b> No exception is being handled</dt>
127
128      <dt><b>Throws:</b> nothing</dt>
129
130      <dt><b>Rationale:</b> At inter-language boundaries it is important to
131      ensure that no C++ exceptions escape, since the calling language
132      usually doesn't have the equipment necessary to properly unwind the
133      stack. Use <code>handle_exception</code> to manage exception
134      translation whenever your C++ code is called directly from the Python
135      API. This is done for you automatically by the usual function wrapping
136      facilities: <code><a href=
137      "make_function.html#make_function-spec">make_function</a>()</code>,
138      <code><a href=
139      "make_function.html#make_constructor-spec">make_constructor</a>()</code>,
140      <code><a href="def.html#class_-spec-modifiers">def</a>()</code> and <code><a href=
141      "class.html#def-spec">class_::def</a>()</code>. The second form can be
142      more convenient to use (see the <a href="#examples">example</a> below),
143      but various compilers have problems when exceptions are rethrown from
144      within an enclosing <code>try</code> block.</dt>
145    </dl>
146<pre>
147<a name=
148"expect_non_null-spec">template &lt;class T&gt; T* expect_non_null(T* x);</a>
149</pre>
150
151    <dl class="expect_non_null-semantics">
152      <dt><b>Returns:</b> <code>x</code></dt>
153
154      <dt><b>Throws:</b> <code><a href=
155      "#error_already_set-spec">error_already_set</a>()</code> iff <code>x ==
156      0</code>.</dt>
157
158      <dt><b>Rationale:</b> Simplifies error-handling when calling functions
159      in the <a href="http://www.python.org/doc/2.2/api/api.html">Python/C
160      API</a> which return 0 on error.</dt>
161    </dl>
162<pre>
163<a name="throw_error_already_set-spec">void throw_error_already_set();</a>
164</pre>
165
166    <dl class="throw_error_already_set-semantics">
167      <dt><b>Effects:</b> <code>throw&nbsp;<a href=
168      "#error_already_set-spec">error_already_set</a>();</code></dt>
169    </dl>
170
171    <dl>
172      <dt><b>Rationale:</b> Many platforms and compilers are not able to
173      consistently catch exceptions thrown across shared library boundaries.
174      Using this function from the Boost.Python library ensures that the
175      appropriate <code>catch</code> block in <code><a href=
176      "#handle_exception-spec">handle_exception</a>()</code> can catch the
177      exception.</dt>
178    </dl>
179
180    <h2><a name="examples"></a>Examples</h2>
181<pre>
182#include &lt;string&gt;
183#include &lt;boost/python/errors.hpp&gt;
184#include &lt;boost/python/object.hpp&gt;
185#include &lt;boost/python/handle.hpp&gt;
186
187// Returns a std::string which has the same value as obj's "__name__"
188// attribute.
189std::string get_name(boost::python::object obj)
190{
191   // throws if there's no __name__ attribute
192   PyObject* p = boost::python::expect_non_null(
193      PyObject_GetAttrString(obj.ptr(), "__name__"));
194
195   char const* s = PyString_AsString(p);
196   if (s != 0)
197        Py_DECREF(p);
198
199   // throws if it's not a Python string
200   std::string result(
201      boost::python::expect_non_null(
202         PyString_AsString(p)));
203
204   Py_DECREF(p); // Done with p
205   
206   return result;
207}
208
209//
210// Demonstrate form 1 of handle_exception
211//
212
213// Place into result a Python Int object whose value is 1 if a and b have
214// identical "__name__" attributes, 0 otherwise.
215void same_name_impl(PyObject*&amp; result, boost::python::object a, boost::python::object b)
216{
217   result = PyInt_FromLong(
218      get_name(a) == get_name(a2));
219}
220
221object borrowed_object(PyObject* p)
222{
223   return boost::python::object(
224        boost::python::handle&lt;&gt;(
225             boost::python::borrowed(a1)));
226}
227
228// This is an example Python 'C' API interface function
229extern "C" PyObject*
230same_name(PyObject* args, PyObject* keywords)
231{
232   PyObject* a1;
233   PyObject* a2;
234   PyObject* result = 0;
235
236   if (!PyArg_ParseTuple(args, const_cast&lt;char*&gt;("OO"), &amp;a1, &amp;a2))
237      return 0;
238   
239   // Use boost::bind to make an object compatible with
240   // boost::Function0&lt;void&gt;
241   if (boost::python::handle_exception(
242         boost::bind&lt;void&gt;(same_name_impl, boost::ref(result), borrowed_object(a1), borrowed_object(a2))))
243   {
244      // an exception was thrown; the Python error was set by
245      // handle_exception()
246      return 0;
247   }
248
249   return result;
250}
251
252//
253// Demonstrate form 2 of handle_exception. Not well-supported by all
254// compilers.
255//
256extern "C" PyObject*
257same_name2(PyObject* args, PyObject* keywords)
258{
259   PyObject* a1;
260   PyObject* a2;
261   PyObject* result = 0;
262
263   if (!PyArg_ParseTuple(args, const_cast&lt;char*&gt;("OO"), &amp;a1, &amp;a2))
264      return 0;
265
266   try {
267      return PyInt_FromLong(
268         get_name(borrowed_object(a1)) == get_name(borrowed_object(a2)));
269   }
270   catch(...)
271   {
272      // If an exception was thrown, translate it to Python
273      boost::python::handle_exception();
274      return 0;
275   }
276}
277</pre>
278
279    <p>Revised
280    <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
281  13 November, 2002
282  <!--webbot bot="Timestamp" endspan i-checksum="39359" -->
283    </p>
284
285    <p><i>&copy; Copyright <a href=
286    "../../../../people/dave_abrahams.htm">Dave Abrahams</a> 2002.</i></p>
287  </body>
288</html>
289
Note: See TracBrowser for help on using the repository browser.