123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262 |
- <?xml version="1.0" encoding="UTF-8"?>
- <!DOCTYPE section PUBLIC "-//Boost//DTD BoostBook XML V1.1//EN"
- "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
- <section id="safe_numeric.exception_policies">
- <title>exception_policy<AE, IDB, UB, UV></title>
- <?dbhtml stop-chunking?>
- <section>
- <title>Description</title>
- <para>Create a valid exception policy from 4 function objects. This
- specifies the actions to be taken for different types of invalid
- results.</para>
- </section>
- <section>
- <title>Template Parameters</title>
- <informaltable>
- <tgroup cols="3">
- <colspec align="left" colwidth="1*"/>
- <colspec align="left" colwidth="6*"/>
- <colspec align="left" colwidth="9*"/>
- <thead>
- <row>
- <entry align="left">Parameter</entry>
- <entry align="left">Type Requirements</entry>
- <entry>Invoked when:</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><code>AE</code></entry>
- <entry>Function object callable with the expression AE(e,
- message)</entry>
- <entry><para>The operation cannot produce valid arithmetic result
- such as overflows, divide by zero, etc.</para></entry>
- </row>
- <row>
- <entry><code>UB</code></entry>
- <entry>Function object callable with the expression UB(e,
- message)</entry>
- <entry><para>The result is undefined by the C++
- standard</para></entry>
- </row>
- <row>
- <entry><code>IDB</code></entry>
- <entry>Function object callable with the expression IDB(e,</entry>
- <entry><para>The result depends upon implementation defined
- behavior according to the C++ standard</para></entry>
- </row>
- <row>
- <entry><code>UV</code></entry>
- <entry>Function object callable with the expression UV(e,
- message)</entry>
- <entry><para>A variable is not initialized</para></entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </section>
- <section>
- <title>Model of</title>
- <para><link
- linkend="safe_numerics.promotion_policy">ExceptionPolicy</link></para>
- </section>
- <section>
- <title>Inherited Valid Expressions</title>
- <para>This class implements all the valid operations from the type
- requirements <link
- linkend="safe_numerics.promotion_policy">ExceptionPolicy</link>. Aside
- from these, there are no other operations implemented.</para>
- </section>
- <section>
- <title>Function Objects</title>
- <para>In order to create an exception policy, one needs some function
- objects. The library includes some appropriate examples of these:</para>
- <informaltable>
- <tgroup cols="2">
- <colspec align="left" colwidth="1*"/>
- <colspec align="left" colwidth="3*"/>
- <thead>
- <row>
- <entry align="left">Name</entry>
- <entry align="left">Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><code>ignore_exception</code></entry>
- <entry>Ignore any runtime exception and just return - thus
- propagating the error. This is what would happen with unsafe data
- types</entry>
- </row>
- <row>
- <entry><code>throw_exception</code></entry>
- <entry>throw an exception of type std::system_error</entry>
- </row>
- <row>
- <entry><code>trap_exception</code></entry>
- <entry>Invoke a function which is undefined. Compilers will
- include this function if and only if there is a possibility of a
- runtime error. Conversely, This will create a compile time error
- if there is any possibility that the operation will fail at
- runtime. Use the action to guarantee that your application will
- never produce an invalid result. Any operation invoke</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- <para>But of course one is free to provide his own. Here is an example of
- a function object which would could be used exception conditions.</para>
- <programlisting>// log an exception condition but continue processing as though nothing has happened
- // this would emulate the behavior of an unsafe type.
- struct log_runtime_exception {
- log_runtime_exception(const safe_numerics_error & e, const char * message){
- std::cout << "Caught system_error with code " << e.code()
- << " meaning " << e.what() << '\n';
- }
- };
- </programlisting>
- </section>
- <section>
- <title>Policies Provided by the library</title>
- <para>The above function object can be composed into an exception policy
- by this class. The library provides common policies all ready to use. In
- the table below, the word "loose" is used to indicate that implementation
- defined and undefined behavior is not considered an exceptional condition,
- while "strict" means the opposite. The word "exception" means that a
- runtime exception will be thrown. The word "trap" means that the mere
- possibility of an error condition will result in a compile time
- error.</para>
- <para><informaltable>
- <tgroup cols="2">
- <colspec align="left" colwidth="1*"/>
- <colspec align="left" colwidth="3*"/>
- <thead>
- <row>
- <entry align="left">Name</entry>
- <entry align="left">Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry
- id="safe_numerics.exception_policies.loose_exception_policy"><link
- linkend="safe_numerics.exception_policies.loose_exception_policy">loose_exception_policy</link></entry>
- <entry>Throws runtime exception on any arithmetic error.
- Undefined and implementation defined behavior is permitted as
- long as it does not produce an arithmetic error.</entry>
- </row>
- <row>
- <entry
- id="safe_numerics.exception_policies.loose_trap_policy"><code><link
- linkend="safe_numerics.exception_policies.loose_trap_policy">loose_trap_policy</link></code></entry>
- <entry>Invoke a compile time error in any case where it's
- possible to result in an arithmetic error.</entry>
- </row>
- <row>
- <entry
- id="safe_numerics.exception_policies.strict_exception_policy"><code><link
- linkend="safe_numerics.exception_policies.strict_exception_policy">strict_exception_policy</link></code></entry>
- <entry>Throws runtime exception on any arithmetic error. Any
- undefined or implementation defined behavior also results in
- throwing an exception.</entry>
- </row>
- <row>
- <entry
- id="safe_numerics.exception_policies.strict_trap_policy"><code><link
- linkend="safe_numerics.exception_policies.strict_trap_policy">strict_trap_policy</link></code></entry>
- <entry>Invoke a compile time error in any case where it's
- possible to result in an arithmetic error, undefined behavior or
- implementation defined behavior</entry>
- </row>
- <row>
- <entry
- id="safe_numerics.exception_policies.default_exception_policy"><code><link
- linkend="safe_numerics.exception_policies.default_exception_policy">default_exception_policy</link></code></entry>
- <entry>an alias for <code><link
- linkend="safe_numerics.exception_policies.strict_exception_policy">strict_exception_policy</link></code></entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>If none of the above suit your needs, you're free to
- create your own. Here is one where use the logging function object defined
- above as a component in a loose exception policy which logs any arithmetic
- errors and ignores any other types of errors.</para>
- <para><programlisting>// logging policy
- // log arithmetic errors but ignore them and continue to execute
- // implementation defined and undefined behavior is just executed
- // without logging.
- using logging_exception_policy = exception_policy<
- log_runtime_exception, // arithmetic error
- ignore_exception, // implementation defined behavior
- ignore_exception, // undefined behavior
- ignore_exception // uninitialized value
- >;
- </programlisting></para>
- </section>
- <section>
- <title>Header</title>
- <para><ulink
- url="../../include/boost/safe_numerics/concept/exception_policy.hpp"><code>#include
- <boost/numeric/safe_numerics/concept/exception_policy.hpp></code></ulink></para>
- </section>
- </section>
|