Subject: [Boost-commit] svn:boost r49138 - trunk/libs/system/doc
From: bdawes_at_[hidden]
Date: 2008-10-05 09:02:02
Author: bemandawes
Date: 2008-10-05 09:02:01 EDT (Sun, 05 Oct 2008)
New Revision: 49138
URL: http://svn.boost.org/trac/boost/changeset/49138
Log:
System: add throws object specification, including semantics
Text files modified:
trunk/libs/system/doc/reference.html | 47 ++++++++++++++++++++++++++++++++-------
1 files changed, 38 insertions(+), 9 deletions(-)
Modified: trunk/libs/system/doc/reference.html
==============================================================================
--- trunk/libs/system/doc/reference.html (original)
+++ trunk/libs/system/doc/reference.html 2008-10-05 09:02:01 EDT (Sun, 05 Oct 2008)
@@ -57,6 +57,8 @@
Class error_condition constructors<br>
Class error_condition modifiers<br>
Class error_condition observers<br>
+ throws object<br>
+ Semantics of throws object<br>
<a href="#Non-member-functions">Non-member functions</a><br>
<a href="#Header-system_error">Header <boost/system/system_error.hpp></a><br>
Class system_error<br>
@@ -223,6 +225,11 @@
template<> struct is_error_condition_enum<posix::posix_errno><errc::errc_t>
{ static const bool value = true; };
+ // predefined error_code object used as "throw on error" tag
+ extern error_code throws;
+
+ // non-member functions
+
bool operator==( const error_code & lhs, const error_code & rhs );
bool operator==( const error_code & code, const error_condition & condition );
bool operator==( const error_condition & condition, const error_code & code );
@@ -370,7 +377,7 @@
<h3><a name="Class-error_category-predefined-objects">Class <code>error_category</code>
predefined objects</a></h3>
<p>Predefined objects <code>system_category</code>
-and <code>generic_category</code> identify operating system error codes and portable error conditions, respectively.</p>
+and <code>generic_category</code> identify system specific error codes and portable error conditions, respectively.</p>
<h2><a name="Class-error_code">Class <code>
error_code</code></a></h2>
<p>The class <code>error_code</code> describes an object used to hold error code
@@ -603,7 +610,29 @@
eliminating some sources of user error. One possible implementation choice for
this type is pointer to member. <i>--end note</i> <i>]</i></p>
</blockquote>
- <h2><a name="Non-member-functions">Non-member functions</a></h2>
+ <h2><a name="throws-object"><code>throws</code> object</a></h2>
+ <pre>extern error_code throws;</pre>
+<p>The predefined <code>error_code</code> object <code>throws</code> is supplied
+for use as a "throw on error" tag.</p>
+<h2><a name="Semantics-of-throws">Semantics of <code>throws</code></a> object</h2>
+<p>Functions that specify an argument in the form <code>error_code& ec=throws</code>,
+with appropriate namespace qualifiers, have the following error handling
+semantics:</p>
+<blockquote>
+ <p><i>Effects:</i> If <code>ec != throws</code>:</p>
+ <ul>
+ <li>If an error occurs, and sets <code>ec</code> to an appropriate <code>
+ error_code</code> that identifies the error
+ value and category. The category should be the most specific <code>
+ error_category</code> applicable to the
+ particular error.</li>
+ <li>if an error does not occur, <code>ec.clear()</code>.</li>
+ </ul>
+ <p><i>Throws:</i> If <code>ec == throws</code>, throws an exception of type
+ <code>system_error</code> or of a type
+ derived from <code>system_error</code>.</p>
+</blockquote>
+<h2><a name="Non-member-functions">Non-member functions</a></h2>
<pre>bool operator==( const error_code & lhs, const error_code & rhs );</pre>
<blockquote>
<p><i>Returns:</i> <code>lhs.category() == rhs.category() && lhs.value() ==
@@ -677,8 +706,7 @@
<h3><a name="Class-system_error">Class <code>
system_error</code></a></h3>
<p>The class <code>system_error</code> describes an exception object used to
-report error conditions that have an associated error code. Such error
-conditions typically originate from the operating system or other low-level
+report errors that have an associated <code>error_code</code>. Such errors typically originate from operating system or other low-level
application program interfaces.</p>
<blockquote>
<pre>namespace boost
@@ -754,14 +782,15 @@
</blockquote>
<hr>
-<p>© Copyright Beman Dawes, 2006, 2007<br>
-Distributed under the Boost Software License, Version 1.0. See
-www.boost.org/LICENSE_1_0.txt</p>
-
<p>Revised
-<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%B %d, %Y" startspan -->June 25, 2008<!--webbot bot="Timestamp" endspan i-checksum="14296" --> </font>
+<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%B %d, %Y" startspan -->October 05, 2008<!--webbot bot="Timestamp" endspan i-checksum="30983" --> </font>
</p>
+<p>© Copyright Beman Dawes, 2006, 2007, 2008</p>
+
+<p>Distributed under the Boost Software License, Version 1.0. See
+www.boost.org/LICENSE_1_0.txt</p>
+
</body>
</html>
\ No newline at end of file