+<section xml:id="test.exception.safety"><info><title>
+ Qualifying Exception Safety Guarantees
+ <indexterm>
+ <primary>Test</primary>
+ <secondary>Exception Safety</secondary>
+ </indexterm>
+</title></info>
+
+
+<section xml:id="test.exception.safety.overview"><info><title>Overview</title></info>
+
+
+ <para>
+ Testing is composed of running a particular test sequence,
+ and looking at what happens to the surrounding code when
+ exceptions are thrown. Each test is composed of measuring
+ initial state, executing a particular sequence of code under
+ some instrumented conditions, measuring a final state, and
+ then examining the differences between the two states.
+ </para>
+
+ <para>
+ Test sequences are composed of constructed code sequences
+ that exercise a particular function or member function, and
+ either confirm no exceptions were generated, or confirm the
+ consistency/coherency of the test subject in the event of a
+ thrown exception.
+ </para>
+
+ <para>
+ Random code paths can be constructed using the basic test
+ sequences and instrumentation as above, only combined in a
+ random or pseudo-random way.
+ </para>
+
+ <para> To compute the code paths that throw, test instruments
+ are used that throw on allocation events
+ (<classname>__gnu_cxx::throw_allocator_random</classname>
+ and <classname>__gnu_cxx::throw_allocator_limit</classname>)
+ and copy, assignment, comparison, increment, swap, and
+ various operators
+ (<classname>__gnu_cxx::throw_type_random</classname>
+ and <classname>__gnu_cxx::throw_type_limit</classname>). Looping
+ through a given test sequence and conditionally throwing in
+ all instrumented places. Then, when the test sequence
+ completes without an exception being thrown, assume all
+ potential error paths have been exercised in a sequential
+ manner.
+ </para>
+</section>
+
+
+<section xml:id="test.exception.safety.status"><info><title>
+ Existing tests
+</title></info>
+
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ Ad Hoc
+ </para>
+ <para>
+ For example,
+ <filename>testsuite/23_containers/list/modifiers/3.cc</filename>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Policy Based Data Structures
+ </para>
+ <para>
+ For example, take the test
+ functor <classname>rand_reg_test</classname> in
+ in <filename>testsuite/ext/pb_ds/regression/tree_no_data_map_rand.cc</filename>. This uses <classname>container_rand_regression_test</classname> in
+<filename>testsuite/util/regression/rand/assoc/container_rand_regression_test.h</filename>.
+
+ </para>
+
+ <para>
+ Which has several tests for container member functions,
+Includes control and test container objects. Configuration includes
+random seed, iterations, number of distinct values, and the
+probability that an exception will be thrown. Assumes instantiating
+container uses an extension
+allocator, <classname>__gnu_cxx::throw_allocator_random</classname>,
+as the allocator type.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ C++11 Container Requirements.
+ </para>
+
+ <para>
+ Coverage is currently limited to testing container
+ requirements for exception safety,
+ although <classname>__gnu_cxx::throw_type</classname> meets
+ the additional type requirements for testing numeric data
+ structures and instantiating algorithms.
+ </para>
+
+ <para>
+ Of particular interest is extending testing to algorithms and
+ then to parallel algorithms. Also io and locales.
+ </para>
+
+ <para>
+ The test instrumentation should also be extended to add
+ instrumentation to <classname>iterator</classname>
+ and <classname>const_iterator</classname> types that throw
+ conditionally on iterator operations.
+ </para>
+ </listitem>
+ </itemizedlist>
+</section>
+
+
+<section xml:id="test.exception.safety.containers"><info><title>
+C++11 Requirements Test Sequence Descriptions
+</title></info>
+
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ Basic
+ </para>
+
+ <para>
+ Basic consistency on exception propagation tests. For
+ each container, an object of that container is constructed,
+ a specific member function is exercised in
+ a <literal>try</literal> block, and then any thrown
+ exceptions lead to error checking in the appropriate
+ <literal>catch</literal> block. The container's use of
+ resources is compared to the container's use prior to the
+ test block. Resource monitoring is limited to allocations
+ made through the container's <type>allocator_type</type>,
+ which should be sufficient for container data
+ structures. Included in these tests are member functions
+ are <type>iterator</type> and <type>const_iterator</type>
+ operations, <function>pop_front</function>, <function>pop_back</function>, <function>push_front</function>, <function>push_back</function>, <function>insert</function>, <function>erase</function>, <function>swap</function>, <function>clear</function>,
+ and <function>rehash</function>. The container in question is
+ instantiated with two instrumented template arguments,
+ with <classname>__gnu_cxx::throw_allocator_limit</classname>
+ as the allocator type, and
+ with <classname>__gnu_cxx::throw_type_limit</classname> as
+ the value type. This allows the test to loop through
+ conditional throw points.
+ </para>
+
+ <para>
+ The general form is demonstrated in
+ <filename>testsuite/23_containers/list/requirements/exception/basic.cc
+ </filename>. The instantiating test object is <classname>__gnu_test::basic_safety</classname> and is detailed in <filename>testsuite/util/exception/safety.h</filename>.
+ </para>
+ </listitem>
+
+
+ <listitem>
+ <para>
+ Generation Prohibited
+ </para>
+
+ <para>
+ Exception generation tests. For each container, an object of
+ that container is constructed and all member functions
+ required to not throw exceptions are exercised. Included in
+ these tests are member functions
+ are <type>iterator</type> and <type>const_iterator</type> operations, <function>erase</function>, <function>pop_front</function>, <function>pop_back</function>, <function>swap</function>,
+ and <function>clear</function>. The container in question is
+ instantiated with two instrumented template arguments,
+ with <classname>__gnu_cxx::throw_allocator_random</classname>
+ as the allocator type, and
+ with <classname>__gnu_cxx::throw_type_random</classname> as
+ the value type. This test does not loop, an instead is sudden
+ death: first error fails.
+ </para>
+ <para>
+ The general form is demonstrated in
+ <filename>testsuite/23_containers/list/requirements/exception/generation_prohibited.cc
+ </filename>. The instantiating test object is <classname>__gnu_test::generation_prohibited</classname> and is detailed in <filename>testsuite/util/exception/safety.h</filename>.
+ </para>
+ </listitem>
+
+
+ <listitem>
+ <para>
+ Propagation Consistent
+ </para>
+
+ <para>
+ Container rollback on exception propagation tests. For
+ each container, an object of that container is constructed,
+ a specific member function that requires rollback to a previous
+ known good state is exercised in
+ a <literal>try</literal> block, and then any thrown
+ exceptions lead to error checking in the appropriate
+ <literal>catch</literal> block. The container is compared to
+ the container's last known good state using such parameters
+ as size, contents, and iterator references. Included in these
+ tests are member functions
+ are <function>push_front</function>, <function>push_back</function>, <function>insert</function>,
+ and <function>rehash</function>. The container in question is
+ instantiated with two instrumented template arguments,
+ with <classname>__gnu_cxx::throw_allocator_limit</classname>
+ as the allocator type, and
+ with <classname>__gnu_cxx::throw_type_limit</classname> as
+ the value type. This allows the test to loop through
+ conditional throw points.
+ </para>
+
+ <para>
+ The general form demonstrated in
+ <filename>testsuite/23_containers/list/requirements/exception/propagation_coherent.cc
+ </filename>. The instantiating test object is <classname>__gnu_test::propagation_coherent</classname> and is detailed in <filename>testsuite/util/exception/safety.h</filename>.
+ </para>
+ </listitem>
+ </itemizedlist>
+
+</section>
+
+</section>
+
+</section>
projects / gcc.git / blobdiff