boost/test
2
0
Fork 0
mirror of https://github.com/boostorg/test.git synced 2026-02-21 03:22:09 +00:00
Code Issues Projects Releases Wiki Activity
Files
ddbf1cfd0b55c279bca53cccd889c5bfb20fd0ca
test/doc/v2/html/boost_test/components/section_pem/usage.html
Raffi Enficiaud 7a1a469493 Some link fixes 
Some cleanups of the PEM and EM + adding some internal links
2014-08-24 16:32:08 +02:00

240 lines
16 KiB
HTML
Raw Blame History

<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Usage</title>
<link rel="stylesheet" href="../../../../../../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
<link rel="home" href="../../../index.html" title="Boost.Test">
<link rel="up" href="../section_pem.html" title="Program Execution Monitor">
<link rel="prev" href="../section_pem.html" title="Program Execution Monitor">
<link rel="next" href="runtime_configuration.html" title="Runtime configuration">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../boost.png"></td>
<td align="center"><a href="../../../../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="../section_pem.html"><img src="../../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../section_pem.html"><img src="../../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="runtime_configuration.html"><img src="../../../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="boost_test.components.section_pem.usage"></a><a class="link" href="usage.html" title="Usage">Usage</a>
</h4></div></div></div>
<p>
To facilitate uniform error reporting the <span class="emphasis"><em>PEM</em></span> supplies
function <code class="computeroutput"><span class="identifier">main</span><span class="special">()</span></code>
as part if it's implementation. To use the <span class="emphasis"><em>PEM</em></span> instead
of regular function <code class="computeroutput"><span class="identifier">main</span></code>
your program is required to supply a function <code class="computeroutput"><span class="identifier">cpp_main</span><span class="special">()</span></code> with same signature.
</p>
<p>
Here is the traditional <span class="emphasis"><em>Hello World</em></span> program implemented
using the <span class="emphasis"><em>PEM</em></span>:
</p>
<div class="table">
<a name="boost_test.components.section_pem.usage.id_example24"></a><p class="title"><b>Table&#160;37.&#160;Hello World with the Program Execution Monitor</b></p>
<div class="table-contents"><table class="table" summary="Hello World with the Program Execution Monitor">
<colgroup>
<col>
<col>
</colgroup>
<thead><tr>
<th>
<p>
Code
</p>
</th>
<th>
<p>
Output
</p>
</th>
</tr></thead>
<tbody><tr>
<td>
<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">iostream</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">test</span><span class="special">/</span><span class="identifier">included</span><span class="special">/</span><span class="identifier">prg_exec_monitor</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="keyword">int</span> <span class="identifier">cpp_main</span><span class="special">(</span> <span class="keyword">int</span><span class="special">,</span> <span class="keyword">char</span><span class="special">*</span> <span class="special">[]</span> <span class="special">)</span> <span class="comment">// note name cpp_main, not main.</span>
<span class="special">{</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Hello, world\n"</span><span class="special">;</span>
<span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
<span class="special">}</span>
</pre>
</td>
<td>
<pre class="programlisting"><span class="identifier">Hello</span><span class="special">,</span> <span class="identifier">world</span>
<span class="identifier">no</span> <span class="identifier">errors</span> <span class="identifier">detected</span>
</pre>
</td>
</tr></tbody>
</table></div>
</div>
<br class="table-break"><p>
It really is that simple - just change the name of your initial function
from <code class="computeroutput"><span class="identifier">main</span><span class="special">()</span></code>
to <code class="computeroutput"><span class="identifier">cpp_main</span><span class="special">()</span></code>.
Do make sure the <code class="computeroutput"><span class="identifier">argc</span></code> and
<code class="computeroutput"><span class="identifier">argv</span></code> parameters are specified
(although you don't have to name them if you don't use them).
</p>
<p>
The <span class="emphasis"><em>PEM</em></span> treats as errors:
</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
Exceptions thrown from <code class="computeroutput"><span class="identifier">cpp_main</span><span class="special">()</span></code>
</li>
<li class="listitem">
Non-zero return from <code class="computeroutput"><span class="identifier">cpp_main</span><span class="special">()</span></code>
</li>
</ul></div>
<p>
So what if some function had thrown a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">runtime_error</span></code>
with the message "big trouble" and it is not trapped by any catch
clause? Like in a following example:
</p>
<div class="table">
<a name="boost_test.components.section_pem.usage.id_example25"></a><p class="title"><b>Table&#160;38.&#160;Standard exception detection within the Program Execution Monitor</b></p>
<div class="table-contents"><table class="table" summary="Standard exception detection within the Program Execution Monitor">
<colgroup>
<col>
<col>
</colgroup>
<thead><tr>
<th>
<p>
Code
</p>
</th>
<th>
<p>
Output
</p>
</th>
</tr></thead>
<tbody><tr>
<td>
<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">stdexcept</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">test</span><span class="special">/</span><span class="identifier">included</span><span class="special">/</span><span class="identifier">prg_exec_monitor</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="keyword">int</span> <span class="identifier">foo</span><span class="special">()</span> <span class="special">{</span> <span class="keyword">throw</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">runtime_error</span><span class="special">(</span> <span class="string">"big trouble"</span> <span class="special">);</span> <span class="special">}</span>
<span class="keyword">int</span> <span class="identifier">cpp_main</span><span class="special">(</span> <span class="keyword">int</span><span class="special">,</span> <span class="keyword">char</span><span class="special">*</span> <span class="special">[]</span> <span class="special">)</span> <span class="comment">// note the name</span>
<span class="special">{</span>
<span class="identifier">foo</span><span class="special">();</span>
<span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
<span class="special">}</span>
</pre>
</td>
<td>
<pre class="programlisting"><span class="special">****</span> <span class="identifier">exception</span><span class="special">(</span><span class="number">205</span><span class="special">):</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">runtime_error</span><span class="special">:</span> <span class="identifier">big</span> <span class="identifier">trouble</span>
<span class="special">********</span> <span class="identifier">errors</span> <span class="identifier">detected</span><span class="special">;</span> <span class="identifier">see</span> <span class="identifier">standard</span> <span class="identifier">output</span> <span class="keyword">for</span> <span class="identifier">details</span> <span class="special">********</span>
</pre>
</td>
</tr></tbody>
</table></div>
</div>
<br class="table-break"><div class="note"><table border="0" summary="Note">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../../../doc/src/images/note.png"></td>
<th align="left">Note</th>
</tr>
<tr><td align="left" valign="top"><p>
Note that in both examples above we used <a class="link" href="section_pem_compilation/section_pem_full_include.html" title="Including the PEM directly into your program">single-header
variant</a> of the <span class="emphasis"><em>PEM</em></span>. Alternatively the binaries
may be built and linked with a <a class="link" href="section_pem_compilation/section_pem_standalone.html" title="Standalone library compilation">standalone
library</a> (in case of static library we are not required to include
any <span class="emphasis"><em>PEM</em></span> related headers).
</p></td></tr>
</table></div>
<p>
Let's consider an example where function <code class="computeroutput"><span class="identifier">cpp_main</span><span class="special">()</span></code> had bubbled up a return code of 5:
</p>
<div class="table">
<a name="boost_test.components.section_pem.usage.id_example26"></a><p class="title"><b>Table&#160;39.&#160;Error return code detection of the <span class="emphasis"><em>PEM</em></span></b></p>
<div class="table-contents"><table class="table" summary="Error return code detection of the PEM">
<colgroup>
<col>
<col>
</colgroup>
<thead><tr>
<th>
<p>
Code
</p>
</th>
<th>
<p>
Output
</p>
</th>
</tr></thead>
<tbody><tr>
<td>
<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">test</span><span class="special">/</span><span class="identifier">prg_exec_monitor</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span> <span class="comment">// this header is optional</span>
<span class="keyword">int</span> <span class="identifier">cpp_main</span><span class="special">(</span> <span class="keyword">int</span><span class="special">,</span> <span class="keyword">char</span><span class="special">*</span> <span class="special">[]</span> <span class="special">)</span> <span class="comment">// note the name</span>
<span class="special">{</span>
<span class="keyword">return</span> <span class="number">5</span><span class="special">;</span>
<span class="special">}</span>
</pre>
</td>
<td>
<pre class="programlisting"><span class="special">****</span> <span class="identifier">error</span> <span class="keyword">return</span> <span class="identifier">code</span><span class="special">:</span> <span class="number">5</span>
<span class="special">********</span> <span class="identifier">errors</span> <span class="identifier">detected</span><span class="special">;</span> <span class="identifier">see</span> <span class="identifier">standard</span> <span class="identifier">output</span> <span class="keyword">for</span> <span class="identifier">details</span> <span class="special">********</span>
</pre>
</td>
</tr></tbody>
</table></div>
</div>
<br class="table-break"><p>
The <span class="emphasis"><em>PEM</em></span> reports errors to both <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span></code>
(details) and <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">cerr</span></code> (summary). Primary detailed error
messages appear on standard output stream so that it is properly interlaced
with other output, thus aiding error analysis. While the final error notification
message appears on standard error stream. This increases the visibility
of error notification if standard output and error streams are directed
to different devices or files.
</p>
<p>
The <span class="emphasis"><em>PEM</em></span>'s supplied <code class="computeroutput"><span class="identifier">main</span><span class="special">()</span></code> will return following result codes:
</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
<code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">exit_success</span></code> - no errors
</li>
<li class="listitem">
<code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">exit_failure</span></code> - non-zero and <code class="computeroutput"><span class="identifier">non</span><span class="special">-</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">exit_success</span></code> return code from <code class="computeroutput"><span class="identifier">cpp_main</span><span class="special">()</span></code>
</li>
<li class="listitem">
<code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">exit_exception_failure</span></code> - <code class="computeroutput"><span class="identifier">cpp_main</span><span class="special">()</span></code>
throw an exception
</li>
</ul></div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright &#169; 2001-2014 Gennadiy
Rozental<p>
Distributed under the Boost Software License, Version 1.0. (See accompanying
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>)
</p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="../section_pem.html"><img src="../../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../section_pem.html"><img src="../../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="runtime_configuration.html"><img src="../../../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink