This is the mail archive of the
libstdc++@gcc.gnu.org
mailing list for the libstdc++ project.
[v3] docs patch for concept checkers
- To: libstdc++ at gcc dot gnu dot org, gcc-patches at gcc dot gnu dot org
- Subject: [v3] docs patch for concept checkers
- From: Phil Edwards <pedwards at disaster dot jaj dot com>
- Date: Sat, 24 Mar 2001 19:15:00 -0500
Describes the current situation with the concept checkers from SGI, what
they do, what they look like, and how to turn them off. Applied to trunk.
2001-03-24 Phil Edwards <pme@sources.redhat.com>
* docs/html/19_diagnostics/howto.html: HTML fixup. Describe
concept-checking code and current status of same.
* docs/html/ext/howto.html: Ditto.
* docs/html/faq/index.html: Ditto.
* docs/html/faq/index.txt: Regenerated.
Index: docs/html/19_diagnostics/howto.html
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/html/19_diagnostics/howto.html,v
retrieving revision 1.1
diff -u -3 -p -r1.1 howto.html
--- howto.html 2000/12/10 04:04:54 1.1
+++ howto.html 2001/03/24 23:58:28
@@ -44,7 +44,7 @@
struct My_Exception : public runtime_error
{
public:
- My_Exception (const string& whatarg)
+ My_Exception (const string& whatarg)
: runtime_error(whatarg), e(errno), id(GetDataBaseID()) { }
int errno_at_time_of_throw() const { return e; }
DBID id_of_thing_that_threw() const { return id; }
@@ -68,7 +68,9 @@
<HR>
<H2><A NAME="3">Concept checkers</A></H2>
- <P>As part of their 3.3 release, SGI added some nifty macros which
+ <P>First the good news, then the bad news.</P>
+ <P><STRONG>Good news:</STRONG> As part of their 3.3 release, SGI
+ added some nifty macros which
perform assertions on type properties. For example, the Standard
requires that types passed as template parameters to <TT>vector</TT>
be "Assignable" (which means what you think it means).
@@ -83,13 +85,43 @@
<TT>vector<MyType></TT>, compile-time checking can be done on
whether MyType meets the requirements for vectors.
</P>
-<P>This is an extension to the library. This documentation needs updating.</P>
+ <P>Most (all?) of the containers and sequences are capable of performing
+ concept checking during compilation, not just vector.
+ </P>
+ <P>If a concept is violated (thus causing a compilation failure), the
+ error messages printed by the compiler will be of the form
+ <PRE>
+ _STL_ERROR::__<EM>foo</EM>_violation
+ </PRE> where <EM>foo</EM> is a description of the precise violation.
+ For example, if a type is required to support the preincrement
+ operator but doesn't, then you will see
+ _STL_ERROR::__postincrement_operator_requirement_violation, which
+ should give you a hint as to the nature of the problem.
+ </P>
+ <P>Other names might be seen for more specific errors, for example,
+ _ERROR_IN_STL_CONTAINER::__begin_iterator_accessor_requirement_violation.
+ </P>
+ <P>You will probably also see other errors as the malformed code is
+ actually used. The concept checking error messages should be printed
+ before the others, so start at the top and work your way down.
+ </P>
+ <P><STRONG>Bad news:</STRONG> The current checking code is somewhat
+ messy. It results in no runtime overhead, but there is a space
+ penalty (sometimes a very large one) in the generated code. And the
+ code itself has bugs.
+ </P>
+ <P>Concept checking can be disabled when you build your code. Just
+ define (via -D or #define) the macro
+ <TT>_STL_NO_CONCEPT_CHECKS</TT> (yes, with the leading underscore).
+ In fact, this may already be defined in the library by default,
+ depending on what decision we come to.
+ </P>
+ <P><STRONG>More good news:</STRONG> Replacement code has already been
+ written by the same author of the original code. It's available at
+ Boost and we hope to integrate it into the library.
<P>Return <A HREF="#top">to top of page</A> or
<A HREF="../faq/index.html">to the FAQ</A>.
</P>
-
-
-
<!-- ####################################################### -->
Index: docs/html/ext/howto.html
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/html/ext/howto.html,v
retrieving revision 1.1
diff -u -3 -p -r1.1 howto.html
--- howto.html 2000/12/10 04:04:56 1.1
+++ howto.html 2001/03/24 23:58:28
@@ -39,6 +39,7 @@
<LI><A HREF="#1">Ropes and trees and hashes, oh my!</A>
<LI><A HREF="#2">Added members</A>
<LI><A HREF="#3">Allocators</A>
+ <LI><A HREF="#4">Compile-time checks</A>
</UL>
<HR>
@@ -56,7 +57,8 @@
<tree>
</PRE> are all here; <TT><bvector></TT> exposes the old bit_vector
class that was used before specialization of vector<bool> was
- available. <TT><hash_map></TT> and <TT><hash_set></TT>
+ available (it's actually a typedef for the specialization now).
+ <TT><hash_map></TT> and <TT><hash_set></TT>
are discussed further below. <TT><rope></TT> is the SGI
specialization for large strings ("rope," "large
strings," get it? love those SGI folks).
@@ -137,6 +139,16 @@
<A HREF="../faq/index.html">to the FAQ</A>.
</P>
+<HR>
+<H2><A NAME="4">Compile-time checks</A></H2>
+ <P>Currently libstdc++-v3 uses the concept checkers from SGI's STL
+ 3.3 to perform <A HREF="../19_diagnostics/howto.html#3">optional
+ compile-time checking</A> of template instantiations of the standard
+ containers. They are described in the linked-to page.
+ </P>
+ <P>Return <A HREF="#top">to top of page</A> or
+ <A HREF="../faq/index.html">to the FAQ</A>.
+ </P>
Index: docs/html/faq/index.html
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/html/faq/index.html,v
retrieving revision 1.4
diff -u -3 -p -r1.4 index.html
--- index.html 2001/03/01 22:32:23 1.4
+++ index.html 2001/03/24 23:58:29
@@ -69,6 +69,7 @@ http://gcc.gnu.org/onlinedocs/libstdc++/
<LI><A HREF="#4_4_interface">The g++-3 headers are
<STRONG>not ours</STRONG></A>
<LI><A HREF="#4_4_glibc">compilation errors from streambuf.h</A>
+ <LI><A HREF="#4_4_checks">_STL_ERROR::__something_huge_...</A>
</UL>
<LI><A HREF="#4_5">Aw, that's easy to fix!</A>
</OL>
@@ -553,6 +554,21 @@ http://clisp.cons.org/~haible/gccinclude
Note that 2.95.x shipped with the
<A HREF="#4_4_interface">old v2 library</A> which is no longer
maintained.
+ </P>
+ </A>
+ <A NAME="4_4_checks">
+ <P>If you see compilation errors containing messages which begin
+ with _STL_ERROR:: followed by a very verbose name, then most
+ likely you have violated one of the requirements for types used
+ during instantiation of template containers. For example,
+ _STL_ERROR::__equality_comparable_requirement_violation appears
+ if your types must be comparable with == and you have not
+ provided this capability (a typo, or wrong visibility, or you
+ just plain forgot, etc).
+ </P>
+ <P>More information, including how to optionally disable the checks,
+ is available <A HREF="../19_diagnostics/howto.html#3">here</A>.
+ The code itself might be disabled or replaced already.
</P>
</A>