-<sect1 id="manual.intro.setup.test" xreflabel="Testing">
+<section xmlns="http://docbook.org/ns/docbook" version="5.0"
+ xml:id="manual.intro.setup.test" xreflabel="Testing">
<?dbhtml filename="test.html"?>
-
-<sect1info>
+
+<info><title>Test</title>
<keywordset>
<keyword>
ISO C++
<keyword>
testsuite
</keyword>
+ <keyword>
+ performance
+ </keyword>
+ <keyword>
+ conformance
+ </keyword>
+ <keyword>
+ ABI
+ </keyword>
+ <keyword>
+ exception safety
+ </keyword>
</keywordset>
-</sect1info>
+</info>
+
+<para>
+The libstdc++ testsuite includes testing for standard conformance,
+regressions, ABI, and performance.
+</para>
+
+<section xml:id="test.organization" xreflabel="Test Organization"><info><title>Organization</title></info>
+
+
+<section xml:id="test.organization.layout" xreflabel="Directory Layout"><info><title>Directory Layout</title></info>
-<title>Test</title>
-<sect2 id="test.organization" xreflabel="test.organization">
-<title>Organization</title>
<para>
The directory <emphasis>libsrcdir/testsuite</emphasis> contains the
individual test cases organized in sub-directories corresponding to
that are packaged in a separate testing library.
</para>
-<para>
+<para>
All test cases for functionality required by the runtime components
of the C++ standard (ISO 14882) are files within the following
directories.
25_algorithms
26_numerics
27_io
+28_regex
+29_atomics
+30_threads
</programlisting>
<para>
demangle Tests for __cxa_demangle, the IA 64 C++ ABI demangler
ext Tests for extensions.
performance Tests for performance analysis, and performance regressions.
-thread Tests for threads.
</programlisting>
-
+
<para>
Some directories don't have test files, but instead contain
- auxiliary information (<ulink url="#internals">more information</ulink>):
+ auxiliary information:
</para>
<programlisting>
</para>
<programlisting>
21_strings/find.cc
- </programlisting>
+ </programlisting>
<para>
However, that practice soon became a liability as the test cases
became huge and unwieldy, and testing new or extended
21_strings/basic_string/find/wchar_t/1.cc
21_strings/basic_string/find/wchar_t/2.cc
21_strings/basic_string/find/wchar_t/3.cc
- </programlisting>
+ </programlisting>
<para>
All new tests should be written with the policy of one test
- case, one file in mind.
+ case, one file in mind.
</para>
+</section>
-</sect2>
-<sect2 id="test.naming" xreflabel="test.naming">
-<title>Naming Conventions</title>
+<section xml:id="test.organization.naming" xreflabel="Naming Conventions"><info><title>Naming Conventions</title></info>
+
<para>
In addition, there are some special names and suffixes that are
used within the testsuite to designate particular kinds of
tests.
</para>
-
+
<itemizedlist>
<listitem>
<para>
to finish or pass. At the moment, the interactive tests are not
run by default. Instead, they are run by hand, like:
</para>
- <programlisting>
+ <programlisting>
g++ 27_io/objects/char/3_xin.cc
cat 27_io/objects/char/3_xin.in | a.out
- </programlisting>
+ </programlisting>
</listitem>
<listitem>
<para>
</listitem>
</itemizedlist>
-</sect2>
+</section>
+</section>
-<sect2 id="test.utils" xreflabel="test.utils">
-<title>Utilities</title>
- <para>
- </para>
- <para>
- The testsuite directory also contains some files that implement
- functionality that is intended to make writing test cases easier,
- or to avoid duplication, or to provide error checking in a way that
- is consistent across platforms and test harnesses. A stand-alone
- executable, called <emphasis>abi_check</emphasis>, and a static
- library called <emphasis>libtestc++</emphasis> are
- constructed. Both of these items are not installed, and only used
- during testing.
- </para>
- <para>
- These files include the following functionality:
- </para>
+<section xml:id="test.run" xreflabel="Running the Testsuite"><info><title>Running the Testsuite</title></info>
- <itemizedlist>
- <listitem>
- <para>
- <emphasis>testsuite_abi.h</emphasis>,
- <emphasis>testsuite_abi.cc</emphasis>,
- <emphasis>testsuite_abi_check.cc</emphasis>
- </para>
- <para>
- Creates the executable <emphasis>abi_check</emphasis>.
- Used to check correctness of symbol versioning, visibility of
- exported symbols, and compatibility on symbols in the shared
- library, for hosts that support this feature. More information
- can be found in the ABI documentation <ulink url="abi.html">here</ulink>
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis>testsuite_allocator.h</emphasis>,
- <emphasis>testsuite_allocator.cc</emphasis>
- </para>
- <para>
- Contains specialized allocators that keep track of construction
- and destruction. Also, support for overriding global new and
- delete operators, including verification that new and delete
- are called during execution, and that allocation over max_size
- fails.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis>testsuite_character.h</emphasis>
- </para>
- <para>
- Contains <code>std::char_traits</code> and
- <code>std::codecvt</code> specializations for a user-defined
- POD.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis>testsuite_hooks.h</emphasis>,
- <emphasis>testsuite_hooks.cc</emphasis>
- </para>
- <para>
- A large number of utilities, including:
- </para>
- <itemizedlist>
- <listitem><para>VERIFY</para></listitem>
- <listitem><para>set_memory_limits</para></listitem>
- <listitem><para>verify_demangle</para></listitem>
- <listitem><para>run_tests_wrapped_locale</para></listitem>
- <listitem><para>run_tests_wrapped_env</para></listitem>
- <listitem><para>try_named_locale</para></listitem>
- <listitem><para>try_mkfifo</para></listitem>
- <listitem><para>func_callback</para></listitem>
- <listitem><para>counter</para></listitem>
- <listitem><para>copy_tracker</para></listitem>
- <listitem><para>copy_constructor</para></listitem>
- <listitem><para>assignment_operator</para></listitem>
- <listitem><para>destructor</para></listitem>
- <listitem>
- <para>pod_char, pod_int and associated char_traits specializations</para>
- </listitem>
- </itemizedlist>
- </listitem>
- <listitem>
- <para>
- <emphasis>testsuite_io.h</emphasis>
- </para>
- <para>
- Error, exception, and constraint checking for
- <code>std::streambuf, std::basic_stringbuf, std::basic_filebuf</code>.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis>testsuite_iterators.h</emphasis>
- </para>
- <para>
- Wrappers for various iterators.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis>testsuite_performance.h</emphasis>
- </para>
- <para>
- A number of class abstractions for performance counters, and
- reporting functions including:
- </para>
- <itemizedlist>
- <listitem><para>time_counter</para></listitem>
- <listitem><para>resource_counter</para></listitem>
- <listitem><para>report_performance</para></listitem>
- </itemizedlist>
- </listitem>
- </itemizedlist>
-
-</sect2>
-<sect2 id="test.run" xreflabel="test.run">
-<title>Running the Testsuite</title>
+ <section xml:id="test.run.basic"><info><title>Basic</title></info>
+
- <sect3 id="test.run.basic" xreflabel="test.run.basic">
- <title>Basic Results</title>
- <para>
- There are several options for running tests, including testing
- the regression tests, testing a subset of the regression tests,
- testing the performance tests, testing just compilation, testing
- installed tools, etc. In addition, there is a special rule for
- checking the exported symbols of the shared library.
- </para>
-
<para>
You can check the status of the build without installing it
using the dejagnu harness, much like the rest of the gcc
the exact command line passed to the compiler, the compiler
output, and the executable output (if any).
</para>
-
+
<para>
Archives of test results for various versions and platforms are
- available on the GCC website in the <ulink
- url="http://gcc.gnu.org/gcc-4.1/buildstat.html">build
- status</ulink> section of each individual release, and are also
- archived on a daily basis on the <ulink
- url="http://gcc.gnu.org/ml/gcc-testresults/current">gcc-testresults</ulink>
+ available on the GCC website in the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/gcc-4.3/buildstat.html">build
+ status</link> section of each individual release, and are also
+ archived on a daily basis on the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/ml/gcc-testresults/current">gcc-testresults</link>
mailing list. Please check either of these places for a similar
combination of source version, operating system, and host CPU.
</para>
- </sect3>
-
- <sect3 id="test.run.options" xreflabel="test.run.options">
- <title>Options</title>
+ </section>
+
+ <section xml:id="test.run.variations"><info><title>Variations</title></info>
+
+ <para>
+ There are several options for running tests, including testing
+ the regression tests, testing a subset of the regression tests,
+ testing the performance tests, testing just compilation, testing
+ installed tools, etc. In addition, there is a special rule for
+ checking the exported symbols of the shared library.
+ </para>
<para>
To debug the dejagnu test harness during runs, try invoking with a
specific argument to the variable RUNTESTFLAGS, as below.
make check-target-libstdc++-v3 RUNTESTFLAGS="--target_board=arm-sim"
</programlisting>
- <para>
+ <para>
Also, here is an example of how to run the libstdc++ testsuite
for a multilibed build directory with different ABI settings:
</para>
<programlisting>
make check-target-libstdc++-v3 RUNTESTFLAGS='--target_board \"unix{-mabi=32,,-mabi=64}\"'
</programlisting>
-
+
<para>
You can run the tests with a compiler and library that have
already been installed. Make sure that the compiler (e.g.,
testsuites in parallel from the same directory.
</para>
- <para>
+ <para>
In addition, there are some testing options that are mostly of
interest to library maintainers and system integrators. As such,
these tests may not work on all cpu and host combinations, and
<para>
<emphasis>testsuite_files</emphasis>
</para>
- <para>
+ <para>
This is a list of all the test cases that will be run. Each
test case is on a separate line, given with an absolute path
from the <emphasis>libsrcdir/testsuite</emphasis> directory.
<para>
<emphasis>testsuite_files_interactive</emphasis>
</para>
- <para>
+ <para>
This is a list of all the interactive test cases, using the
same format as the file list above. These tests are not run
by default.
<para>
<emphasis>testsuite_files_performance</emphasis>
</para>
- <para>
+ <para>
This is a list of all the performance test cases, using the
same format as the file list above. These tests are not run
by default.
<para>
<emphasis>testsuite_thread</emphasis>
</para>
- <para>
+ <para>
This file indicates that the host system can run tests which
involved multiple threads.
</para>
<para>
<emphasis>testsuite_wchar_t</emphasis>
</para>
- <para>
+ <para>
This file indicates that the host system can run the wchar_t
tests, and corresponds to the macro definition <code>
_GLIBCXX_USE_WCHAR_T</code> in the file c++config.h.
<programlisting>
make check-abi
</programlisting>
-
+
<para>
The library ABI can be tested. This involves testing the shared
library against an ABI-defining previous version of symbol
- exports.
+ exports.
</para>
<programlisting>
please email the main libstdc++ mailing list if you see
something odd or have questions.
</para>
- </sect3>
+ </section>
- <sect3 id="test.run.permutations" xreflabel="test.run.permutations">
- <title>Test Permutations</title>
+ <section xml:id="test.run.permutations"><info><title>Permutations</title></info>
+
<para>
- To run the libstdc++ test suite under the <link
- linkend="manual.ext.debug_mode">debug mode</link>, edit
+ To run the libstdc++ test suite under the <link linkend="manual.ext.debug_mode">debug mode</link>, edit
<filename>libstdc++-v3/scripts/testsuite_flags</filename> to add the
compile-time flag <constant>-D_GLIBCXX_DEBUG</constant> to the
result printed by the <literal>--build-cxx</literal>
library or the test suite.
</para>
+ <para>
+ The <link linkend="manual.ext.parallel_mode">parallel
+ mode</link> can be tested in much the same manner, substituting
+ <constant>-D_GLIBCXX_PARALLEL</constant> for
+ <constant>-D_GLIBCXX_DEBUG</constant> in the previous paragraph.
+ </para>
+
<para>
Or, just run the testsuites with <constant>CXXFLAGS</constant>
- set to <constant>-D_GLIBCXX_DEBUG</constant>.
+ set to <constant>-D_GLIBCXX_DEBUG</constant> or
+ <constant>-D_GLIBCXX_PARALLEL</constant>.
</para>
- </sect3>
-</sect2>
+ </section>
+</section>
+
+<section xml:id="test.new_tests"><info><title>Writing a new test case</title></info>
-<sect2 id="test.new_tests" xreflabel="test.new_tests">
-<title>New Test Cases</title>
<para>
The first step in making a new test case is to choose the correct
directory and file name, given the organization as previously
- described.
+ described.
</para>
<para>
// { dg-do compile }
Example 2: Testing for expected warnings on line 36, which all targets fail
-// { dg-warning "string literals" "" { xfail *-*-* } 36
+// { dg-warning "string literals" "" { xfail *-*-* } 36 }
Example 3: Testing for expected warnings on line 36
-// { dg-warning "string literals" "" { target *-*-* } 36
+// { dg-warning "string literals" "" { target *-*-* } 36 }
Example 4: Testing for compilation errors on line 41
// { dg-do compile }
<para>
More examples can be found in the libstdc++-v3/testsuite/*/*.cc files.
</para>
+</section>
+
+<section xml:id="test.harness" xreflabel="Test Harness and Utilities"><info><title>Test Harness and Utilities</title></info>
-</sect2>
-<sect2 id="test.dejagnu" xreflabel="test.dejagnu">
-<title>Test Harness Details</title>
- <para>
- Underlying details of testing are abstracted via the GNU Dejagnu package.
+<section xml:id="test.harness.dejagnu"><info><title>Dejagnu Harness Details</title></info>
+
+ <para>
+ Underlying details of testing for conformance and regressions are
+ abstracted via the GNU Dejagnu package. This is similar to the
+ rest of GCC.
</para>
only default variables.
</para>
-</sect2>
+</section>
+
+<section xml:id="test.harness.utils"><info><title>Utilities</title></info>
-<sect2 id="test.future" xreflabel="test.future">
-<title>Future</title>
- <para>
+ <para>
+ </para>
+ <para>
+ The testsuite directory also contains some files that implement
+ functionality that is intended to make writing test cases easier,
+ or to avoid duplication, or to provide error checking in a way that
+ is consistent across platforms and test harnesses. A stand-alone
+ executable, called <emphasis>abi_check</emphasis>, and a static
+ library called <emphasis>libtestc++</emphasis> are
+ constructed. Both of these items are not installed, and only used
+ during testing.
</para>
+ <para>
+ These files include the following functionality:
+ </para>
-<para>
-Shared runs need to be implemented, for targets that support shared libraries.
-</para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <emphasis>testsuite_abi.h</emphasis>,
+ <emphasis>testsuite_abi.cc</emphasis>,
+ <emphasis>testsuite_abi_check.cc</emphasis>
+ </para>
+ <para>
+ Creates the executable <emphasis>abi_check</emphasis>.
+ Used to check correctness of symbol versioning, visibility of
+ exported symbols, and compatibility on symbols in the shared
+ library, for hosts that support this feature. More information
+ can be found in the ABI documentation <link linkend="appendix.porting.abi">here</link>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>testsuite_allocator.h</emphasis>,
+ <emphasis>testsuite_allocator.cc</emphasis>
+ </para>
+ <para>
+ Contains specialized allocators that keep track of construction
+ and destruction. Also, support for overriding global new and
+ delete operators, including verification that new and delete
+ are called during execution, and that allocation over max_size
+ fails.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>testsuite_character.h</emphasis>
+ </para>
+ <para>
+ Contains <code>std::char_traits</code> and
+ <code>std::codecvt</code> specializations for a user-defined
+ POD.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>testsuite_hooks.h</emphasis>,
+ <emphasis>testsuite_hooks.cc</emphasis>
+ </para>
+ <para>
+ A large number of utilities, including:
+ </para>
+ <itemizedlist>
+ <listitem><para>VERIFY</para></listitem>
+ <listitem><para>set_memory_limits</para></listitem>
+ <listitem><para>verify_demangle</para></listitem>
+ <listitem><para>run_tests_wrapped_locale</para></listitem>
+ <listitem><para>run_tests_wrapped_env</para></listitem>
+ <listitem><para>try_named_locale</para></listitem>
+ <listitem><para>try_mkfifo</para></listitem>
+ <listitem><para>func_callback</para></listitem>
+ <listitem><para>counter</para></listitem>
+ <listitem><para>copy_tracker</para></listitem>
+ <listitem><para>copy_constructor</para></listitem>
+ <listitem><para>assignment_operator</para></listitem>
+ <listitem><para>destructor</para></listitem>
+ <listitem>
+ <para>pod_char, pod_int and associated char_traits specializations</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>testsuite_io.h</emphasis>
+ </para>
+ <para>
+ Error, exception, and constraint checking for
+ <code>std::streambuf, std::basic_stringbuf, std::basic_filebuf</code>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>testsuite_iterators.h</emphasis>
+ </para>
+ <para>
+ Wrappers for various iterators.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>testsuite_performance.h</emphasis>
+ </para>
+ <para>
+ A number of class abstractions for performance counters, and
+ reporting functions including:
+ </para>
+ <itemizedlist>
+ <listitem><para>time_counter</para></listitem>
+ <listitem><para>resource_counter</para></listitem>
+ <listitem><para>report_performance</para></listitem>
+ </itemizedlist>
+ </listitem>
+ </itemizedlist>
+</section>
-<para>
-Diffing of expected output to standard streams needs to be finished off.
-</para>
+</section>
-<para>
-The V3 testing framework supports, or will eventually support,
-additional keywords for the purpose of easing the job of writing
-test cases. All V3-keywords are of the form <code>@xxx@</code>.
-Currently plans for supported keywords include:
-</para>
+<section xml:id="test.special"><info><title>Special Topics</title></info>
-<variablelist>
-<varlistentry><term> <code> @require@ <files> </code> </term>
-<listitem>
- <para>
- The existence of <files> is essential for the test to complete
- successfully. For example, a test case foo.C using bar.baz as
- input file could say
- </para>
- <programlisting>
- // @require@ bar.baz</programlisting>
- <para>
- The special variable % stands for the rootname, e.g. the
- file-name without its `.C' extension. Example of use (taken
- verbatim from 27_io/filebuf.cc)
- </para>
- <programlisting>
- // @require@ %-*.tst %-*.txt</programlisting>
-</listitem></varlistentry>
-<varlistentry><term> <code> @diff@ <first-list> <second-list> </code> </term>
-<listitem>
- <para>
- After the test case compiles and ran successfully, diff
- <first-list> against <second-list>, these lists should
- have the same length. The test fails if diff returns non-zero a
- pair of files.
- </para>
-</listitem></varlistentry>
-</variablelist>
-</sect2>
+<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>
-</sect1>
+</section>
projects / gcc.git / blobdiff