|
|
Boost-Commit : |
From: emil_at_[hidden]
Date: 2008-04-12 02:08:11
Author: emildotchevski
Date: 2008-04-12 02:08:10 EDT (Sat, 12 Apr 2008)
New Revision: 44342
URL: http://svn.boost.org/trac/boost/changeset/44342
Log:
documentation cleanup
Removed:
trunk/libs/exception/doc/adding_data_at_throw.html
trunk/libs/exception/doc/adding_data_later.html
trunk/libs/exception/doc/cloning_and_rethrowing.html
trunk/libs/exception/doc/grouping_data.html
trunk/libs/exception/doc/using_enable_cloning.html
Text files modified:
trunk/libs/exception/doc/reno.css | 7 +++++++
1 files changed, 7 insertions(+), 0 deletions(-)
Deleted: trunk/libs/exception/doc/adding_data_at_throw.html
==============================================================================
--- trunk/libs/exception/doc/adding_data_at_throw.html 2008-04-12 02:08:10 EDT (Sat, 12 Apr 2008)
+++ (empty file)
@@ -1,73 +0,0 @@
-<!DOCTYPE html PUBLIC '-//W3C//DTD XHTML 1.0 Strict//EN'
-'http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd'>
-<html xmlns='http://www.w3.org/1999/xhtml' xml:lang='en' lang='en'>
-<head>
- <meta http-equiv='Content-Type' content='text/html; charset=utf-8'/>
- <title>Tutorial: Adding of Arbitrary Data at the Point of the Throw</title>
- <link href='reno.css' type='text/css' rel='stylesheet'/>
-</head>
-<body>
-<div class="body-0">
-<div class="body-1">
-<div class="body-2">
-<div>
-<div id="boost_logo">
-
-</div>
-<h1>Boost Exception</h1>
-</div>
-<div class="RenoIncludeDIV"><h3>Adding of Arbitrary Data at the Point of the Throw</h3>
-<p>The following example demonstrates how <tt>errno</tt> can be stored in exception objects using Boost Exception:</p>
-<pre>#include <<span class="RenoLink">boost/exception.hpp</span>>
-#include <errno.h>
-#include <iostream>
-
-typedef boost::<span class="RenoLink">error_info</span><struct tag_errno,int> errno_info; //(1)
-
-class my_error: public boost::<span class="RenoLink">exception</span>, public std::exception { }; //(2)
-
-void
-f()
- {
- throw my_error() << errno_info(errno); //(3)
- }
-</pre>
-<p>First, we instantiate the <tt><span class="RenoLink">error_info</span></tt> template using a unique identifier -- <tt>tag_errno</tt>, and the type of the info it identifies -- <tt>int</tt>. This provides compile-time type safety for the various values stored in exception objects.</p>
-<p>Second, we define class <tt>my_error</tt>, which derives from <tt>boost::<span class="RenoLink">exception</span></tt>.</p>
-<p>Finally, (3) illustrates how the <tt>typedef</tt> from (1) can be used with <tt><span class="RenoLink">operator<<</span>()</tt> to store values in exception objects at the point of the throw.</p>
-<p>The stored <tt>errno</tt> value can be recovered at a later time like this:</p>
-<pre>// ...continued
-
-void
-g()
- {
- try
- {
- f();
- }
- catch(
- my_error & x )
- {
- if( boost::shared_ptr<int const> err=boost::<span class="RenoLink">get_error_info</span><errno_info>(x) )
- std::cerr << "Error code: " << *err;
- }
- }</pre>
-<p>The <tt><span class="RenoLink">get_error_info</span>()</tt> function template is instantiated with the <tt>typedef</tt> from (1), and is passed an exception object of any type that derives publicly from <tt>boost::<span class="RenoLink">exception</span></tt>. If the exception object contains the requested value, the returned <tt><span class="RenoLink">shared_ptr</span></tt> will point to it; otherwise an empty <tt><span class="RenoLink">shared_ptr</span></tt> is returned.</p>
-</div><h3>See also:</h3>
-<div class="RenoPageList"><a href="transporting_data.html">Tutorial: Transporting of Arbitrary Data to the Catch Site<br/>
-</a></div>
-<div id="footer">
-<p> </p>
-<hr/>
-<p>
-<a class="logo" href="http://jigsaw.w3.org/css-validator/validator?uri=http://revergestudios.com/boost-exception/reno.css"><img class="logo_pic" src="valid-css.png" alt="Valid CSS" height="31" width="88"/></a>
-<a class="logo" href="http://validator.w3.org/check?uri=referer"><img class="logo_pic" src="valid-xhtml.png" alt="Valid XHTML 1.0" height="31" width="88"/></a>
-<small>Copyright (c) 2006-2008 by Emil Dotchevski and Reverge Studios, Inc.<br/>
-Distributed under the Boost Software License, Version 1.0.</small>
-</p>
-</div>
-</div>
-</div>
-</div>
-</body>
-</html>
Deleted: trunk/libs/exception/doc/adding_data_later.html
==============================================================================
--- trunk/libs/exception/doc/adding_data_later.html 2008-04-12 02:08:10 EDT (Sat, 12 Apr 2008)
+++ (empty file)
@@ -1,116 +0,0 @@
-<!DOCTYPE html PUBLIC '-//W3C//DTD XHTML 1.0 Strict//EN'
-'http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd'>
-<html xmlns='http://www.w3.org/1999/xhtml' xml:lang='en' lang='en'>
-<head>
- <meta http-equiv='Content-Type' content='text/html; charset=utf-8'/>
- <title>Tutorial: Adding of Arbitrary Data to Active Exception Objects</title>
- <link href='reno.css' type='text/css' rel='stylesheet'/>
-</head>
-<body>
-<div class="body-0">
-<div class="body-1">
-<div class="body-2">
-<div>
-<div id="boost_logo">
-
-</div>
-<h1>Boost Exception</h1>
-</div>
-<div class="RenoIncludeDIV"><h3>Adding of Arbitrary Data to Active Exception Objects</h3>
-<p>Sometimes the throw site does not have all the information that is needed at the catch site to make sense of what went wrong. Here is an example:</p>
-<pre>#include <stdio.h>
-#include <string>
-
-class
-file_read_error
- {
- public:
-
- explicit
- file_read_error( std::string const & fn ):
- fn_(fn)
- {
- };
-
- std::string const &
- file_name() const
- {
- return fn_;
- }
-
- private:
-
- std::string fn_;
- };
-
-void
-file_read( FILE * f, void * buffer, size_t size )
- {
- if( size!=fread(buffer,1,size,f) )
- throw file_read_error("????");
- }</pre>
-<p>We have defined an exception class <tt>file_read_error</tt> which can store a file name, so that when we catch a <tt>file_read_error</tt> object, we know which file the failure is related to. However, the <tt>file_read</tt> function does not have the file name at the time of the throw; all it has is a <tt>FILE</tt> handle.</p>
-<p>One possible solution is to not use <tt>FILE</tt> handles directly. We could have our own <tt>class file</tt> which stores both a <tt>FILE</tt> handle and a file name, and pass that to <tt>file_read()</tt>. However, this could be problematic if we communicate with 3rd party code that does not use our <tt>class file</tt> (probably because they have their own similar class.)</p>
-<p>A better solution is to make class <tt>file_read_error</tt> derive (possibly indirectly) from <tt>boost::<span class="RenoLink">exception</span></tt>, and free the <tt>file_read()</tt> function from the burden of storing the file name in exceptions it throws:</p>
-<pre>#include <<span class="RenoLink">boost/exception.hpp</span>>
-#include <stdio.h>
-#include <errno.h>
-
-typedef boost::<span class="RenoLink">error_info</span><struct tag_errno,int> errno_info;
-
-class file_read_error: public boost::<span class="RenoLink">exception</span> { };
-
-void
-file_read( FILE * f, void * buffer, size_t size )
- {
- if( size!=fread(buffer,1,size,f) )
- throw file_read_error() << errno_info(errno);
- }</pre>
-<p>If <tt>file_read()</tt> detects a failure, it throws an exception which contains the information that is available at the time, namely the <tt>errno</tt>. Other relevant information, such as the file name, can be added in a context higher up the call stack, where it is known naturally:</p>
-<pre>#include <<span class="RenoLink">boost/exception.hpp</span>>
-#include <boost/shared_ptr.hpp>
-#include <stdio.h>
-#include <string>
-
-typedef boost::<span class="RenoLink">error_info</span><struct tag_file_name,std::string> file_name_info;
-
-boost::shared_ptr<FILE> file_open( char const * file_name, char const * mode );
-void file_read( FILE * f, void * buffer, size_t size );
-
-void
-parse_file( char const * file_name )
- {
- boost::shared_ptr<FILE> f = file_open(file_name,"rb");
- assert(f);
- try
- {
- char buf[1024];
- file_read( f.get(), buf, sizeof(buf) );
- }
- catch(
- boost::<span class="RenoLink">exception</span> & e )
- {
- e << file_name_info(file_name);
- throw;
- }
- }</pre>
-<p>The above function is (almost) exception-neutral -- if an exception is emitted by any function call within the <tt>try</tt> block, <tt>parse_file()</tt> does not need to do any real work, but it intercepts any <tt>boost::<span class="RenoLink">exception</span></tt> object, stores the file name, and re-throws using a throw-expression with no operand (15.1.6). The rationale for catching any <tt>boost::<span class="RenoLink">exception</span></tt> object is that the file name is relevant to any failure that occurs in <tt>parse_file()</tt>, <i>even if the failure is unrelated to file I/O</i>.</p>
-<p>As usual, the stored data can be retrieved using <tt><span class="RenoLink">get_error_info</span>()</tt>.</p>
-</div><h3>See also:</h3>
-<div class="RenoPageList"><a href="transporting_data.html">Tutorial: Transporting of Arbitrary Data to the Catch Site<br/>
-</a></div>
-<div id="footer">
-<p> </p>
-<hr/>
-<p>
-<a class="logo" href="http://jigsaw.w3.org/css-validator/validator?uri=http://revergestudios.com/boost-exception/reno.css"><img class="logo_pic" src="valid-css.png" alt="Valid CSS" height="31" width="88"/></a>
-<a class="logo" href="http://validator.w3.org/check?uri=referer"><img class="logo_pic" src="valid-xhtml.png" alt="Valid XHTML 1.0" height="31" width="88"/></a>
-<small>Copyright (c) 2006-2008 by Emil Dotchevski and Reverge Studios, Inc.<br/>
-Distributed under the Boost Software License, Version 1.0.</small>
-</p>
-</div>
-</div>
-</div>
-</div>
-</body>
-</html>
Deleted: trunk/libs/exception/doc/cloning_and_rethrowing.html
==============================================================================
--- trunk/libs/exception/doc/cloning_and_rethrowing.html 2008-04-12 02:08:10 EDT (Sat, 12 Apr 2008)
+++ (empty file)
@@ -1,75 +0,0 @@
-<!DOCTYPE html PUBLIC '-//W3C//DTD XHTML 1.0 Strict//EN'
-'http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd'>
-<html xmlns='http://www.w3.org/1999/xhtml' xml:lang='en' lang='en'>
-<head>
- <meta http-equiv='Content-Type' content='text/html; charset=utf-8'/>
- <title>Tutorial: Cloning and Re-throwing an Exception</title>
- <link href='reno.css' type='text/css' rel='stylesheet'/>
-</head>
-<body>
-<div class="body-0">
-<div class="body-1">
-<div class="body-2">
-<div>
-<div id="boost_logo">
-
-</div>
-<h1>Boost Exception</h1>
-</div>
-<div class="RenoIncludeDIV"><h3>Cloning and Re-throwing an Exception</h3>
-<p>When you catch a <tt>boost::<span class="RenoLink">exception</span></tt>, you can call <tt><span class="RenoLink">clone_exception</span>()</tt> to get an <tt><span class="RenoLink">exception_ptr</span></tt> object:</p>
-<pre>#include <<span class="RenoLink">boost/exception/cloning.hpp</span>>
-#include <boost/thread.hpp>
-#include <boost/bind.hpp>
-
-void do_work(); //throws cloning-enabled boost::<span class="RenoLink">exception</span>s
-
-void
-worker_thread( boost::<span class="RenoLink">exception_ptr</span> & error )
- {
- try
- {
- do_work();
- error = boost::<span class="RenoLink">exception_ptr</span>();
- }
- catch(
- boost::<span class="RenoLink">exception</span> & e )
- {
- error = boost::<span class="RenoLink">clone_exception</span>(e);
- }
- }</pre>
-<p>In the above example, note that <tt><span class="RenoLink">clone_exception</span>()</tt> captures the original type of the exception object, even though <tt>e</tt> refers to the base type <tt>boost::<span class="RenoLink">exception</span></tt>. This original type can be thrown again using the <tt><span class="RenoLink">rethrow_exception</span>()</tt> function:</p>
-<pre>// ...continued
-
-void
-work()
- {
- boost::<span class="RenoLink">exception_ptr</span> error;
- boost::<span class="RenoLink">thread</span> t( boost::<span class="RenoLink">bind</span>(worker_thread,boost::<span class="RenoLink">ref</span>(error)) );
- t.<span class="RenoLink">join</span>();
- if( error )
- boost::<span class="RenoLink">rethrow_exception</span>(error);
- }</pre>
-<p><tt><span class="RenoLink">Clone_exception</span>()</tt> could fail to copy the original exception object in the following cases:</p>
-<div><ul><li> if there is not enough memory, in which case the returned <tt><span class="RenoLink">exception_ptr</span></tt> points to an instance of <tt>std::bad_alloc</tt>, or</li>
-<li> if <tt><span class="RenoLink">enable_exception_cloning</span>()</tt> was not used in the throw-expression passed to the original <tt>throw</tt> statement, in which case the returned <tt><span class="RenoLink">exception_ptr</span></tt> points to an instance of <tt><span class="RenoLink">unknown_exception</span></tt>.</li>
-</ul></div>
-<p>Regardless, the use of <tt><span class="RenoLink">clone_exception</span>()</tt> and <tt><span class="RenoLink">rethrow_exception</span>()</tt> in the above examples is well-formed.</p>
-</div><h3>See also:</h3>
-<div class="RenoPageList"><a href="cloning.html">Tutorial: Transporting of Exceptions between Threads<br/>
-</a></div>
-<div id="footer">
-<p> </p>
-<hr/>
-<p>
-<a class="logo" href="http://jigsaw.w3.org/css-validator/validator?uri=http://revergestudios.com/boost-exception/reno.css"><img class="logo_pic" src="valid-css.png" alt="Valid CSS" height="31" width="88"/></a>
-<a class="logo" href="http://validator.w3.org/check?uri=referer"><img class="logo_pic" src="valid-xhtml.png" alt="Valid XHTML 1.0" height="31" width="88"/></a>
-<small>Copyright (c) 2006-2008 by Emil Dotchevski and Reverge Studios, Inc.<br/>
-Distributed under the Boost Software License, Version 1.0.</small>
-</p>
-</div>
-</div>
-</div>
-</div>
-</body>
-</html>
Deleted: trunk/libs/exception/doc/grouping_data.html
==============================================================================
--- trunk/libs/exception/doc/grouping_data.html 2008-04-12 02:08:10 EDT (Sat, 12 Apr 2008)
+++ (empty file)
@@ -1,62 +0,0 @@
-<!DOCTYPE html PUBLIC '-//W3C//DTD XHTML 1.0 Strict//EN'
-'http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd'>
-<html xmlns='http://www.w3.org/1999/xhtml' xml:lang='en' lang='en'>
-<head>
- <meta http-equiv='Content-Type' content='text/html; charset=utf-8'/>
- <title>Tutorial: Adding Grouped Data to Exceptions</title>
- <link href='reno.css' type='text/css' rel='stylesheet'/>
-</head>
-<body>
-<div class="body-0">
-<div class="body-1">
-<div class="body-2">
-<div>
-<div id="boost_logo">
-
-</div>
-<h1>Boost Exception</h1>
-</div>
-<div class="RenoIncludeDIV"><h3>Adding Grouped Data to Exceptions</h3>
-<p>The code snippet below demonstrates how <tt>boost::<span class="RenoLink">tuple</span></tt> can be used to bundle the name of the function that failed, together with the reported <tt>errno</tt> so that they can be added to exception objects more conveniently together:</p>
-<pre>#include <<span class="RenoLink">boost/exception/info_tuple.hpp</span>>
-#include <boost/shared_ptr.hpp>
-#include <stdio.h>
-#include <string>
-#include <errno>
-
-typedef boost::<span class="RenoLink">error_info</span><struct tag_file_name,std::string> file_name_info;
-typedef boost::<span class="RenoLink">error_info</span><struct tag_function,char const *> function_info;
-typedef boost::<span class="RenoLink">error_info</span><struct tag_errno,int> errno_info;
-typedef boost::tuple<function_info,errno_info> clib_failure;
-
-class file_open_error: public boost::<span class="RenoLink">exception</span> { };
-
-boost::shared_ptr<FILE>
-file_open( char const * name, char const * mode )
- {
- if( FILE * f=fopen(name,mode) )
- return boost::shared_ptr<FILE>(f,fclose);
- else
- throw file_open_error() <<
- file_name_info(name) <<
- clib_failure("fopen",errno);
- }</pre>
-<p>Note that the members of a <tt>boost::<span class="RenoLink">tuple</span></tt> are stored separately in exception objects; they can only be retrieved individually, using <tt><span class="RenoLink">get_error_info</span>()</tt>.</p>
-</div><h3>See also:</h3>
-<div class="RenoPageList"><a href="transporting_data.html">Tutorial: Transporting of Arbitrary Data to the Catch Site<br/>
-</a></div>
-<div id="footer">
-<p> </p>
-<hr/>
-<p>
-<a class="logo" href="http://jigsaw.w3.org/css-validator/validator?uri=http://revergestudios.com/boost-exception/reno.css"><img class="logo_pic" src="valid-css.png" alt="Valid CSS" height="31" width="88"/></a>
-<a class="logo" href="http://validator.w3.org/check?uri=referer"><img class="logo_pic" src="valid-xhtml.png" alt="Valid XHTML 1.0" height="31" width="88"/></a>
-<small>Copyright (c) 2006-2008 by Emil Dotchevski and Reverge Studios, Inc.<br/>
-Distributed under the Boost Software License, Version 1.0.</small>
-</p>
-</div>
-</div>
-</div>
-</div>
-</body>
-</html>
Modified: trunk/libs/exception/doc/reno.css
==============================================================================
--- trunk/libs/exception/doc/reno.css (original)
+++ trunk/libs/exception/doc/reno.css 2008-04-12 02:08:10 EDT (Sat, 12 Apr 2008)
@@ -1,3 +1,10 @@
+/*
+ * Copyright (c) 2006-2008 Emil Dotchevski and Reverge Studios, Inc.
+ *
+ * Distributed under the Boost Software License, Version 1.0. (See accompanying
+ * file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ */
+
body
{
font-family: Trebuchet, Verdana, Arial, Helvetica, Sans;
Deleted: trunk/libs/exception/doc/using_enable_cloning.html
==============================================================================
--- trunk/libs/exception/doc/using_enable_cloning.html 2008-04-12 02:08:10 EDT (Sat, 12 Apr 2008)
+++ (empty file)
@@ -1,54 +0,0 @@
-<!DOCTYPE html PUBLIC '-//W3C//DTD XHTML 1.0 Strict//EN'
-'http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd'>
-<html xmlns='http://www.w3.org/1999/xhtml' xml:lang='en' lang='en'>
-<head>
- <meta http-equiv='Content-Type' content='text/html; charset=utf-8'/>
- <title>Tutorial: Using enable_exception_cloning() at the Time of the Throw</title>
- <link href='reno.css' type='text/css' rel='stylesheet'/>
-</head>
-<body>
-<div class="body-0">
-<div class="body-1">
-<div class="body-2">
-<div>
-<div id="boost_logo">
-
-</div>
-<h1>Boost Exception</h1>
-</div>
-<div class="RenoIncludeDIV"><h3>Using enable_exception_cloning() at the Time of the Throw</h3>
-<p>Here is how cloning can be enabled in a throw-expression (15.1):</p>
-<pre>#include <<span class="RenoLink">boost/exception/enable_exception_cloning.hpp</span>>
-#include <<span class="RenoLink">boost/exception/info.hpp</span>>
-#include <stdio.h>
-#include <errno.h>
-
-typedef boost::error_info<struct tag_errno,int> errno_info;
-
-class file_read_error: public boost::<span class="RenoLink">exception</span> { };
-
-void
-file_read( FILE * f, void * buffer, size_t size )
- {
- if( size!=fread(buffer,1,size,f) )
- throw boost::<span class="RenoLink">enable_exception_cloning</span>(file_read_error()) <<
- errno_info(errno);
- }</pre>
-</div><h3>See also:</h3>
-<div class="RenoPageList"><a href="cloning.html">Tutorial: Transporting of Exceptions between Threads<br/>
-</a></div>
-<div id="footer">
-<p> </p>
-<hr/>
-<p>
-<a class="logo" href="http://jigsaw.w3.org/css-validator/validator?uri=http://revergestudios.com/boost-exception/reno.css"><img class="logo_pic" src="valid-css.png" alt="Valid CSS" height="31" width="88"/></a>
-<a class="logo" href="http://validator.w3.org/check?uri=referer"><img class="logo_pic" src="valid-xhtml.png" alt="Valid XHTML 1.0" height="31" width="88"/></a>
-<small>Copyright (c) 2006-2008 by Emil Dotchevski and Reverge Studios, Inc.<br/>
-Distributed under the Boost Software License, Version 1.0.</small>
-</p>
-</div>
-</div>
-</div>
-</div>
-</body>
-</html>
Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk