OpenCores
URL https://opencores.org/ocsvn/openrisc_me/openrisc_me/trunk

Subversion Repositories openrisc_me

[/] [openrisc/] [trunk/] [gnu-src/] [gcc-4.5.1/] [libstdc++-v3/] [doc/] [html/] [manual/] [bk01pt12ch30s04.html] - Blame information for rev 424

Details | Compare with Previous | View Log

Line No. Rev Author Line
1 424 jeremybenn 
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
2 
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3 
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Design</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /><meta name="keywords" content="&#10;      C++&#10;    , &#10;      library&#10;    , &#10;      debug&#10;    " /><meta name="keywords" content="&#10;      ISO C++&#10;    , &#10;      library&#10;    " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="debug_mode.html" title="Chapter 30. Debug Mode" /><link rel="prev" href="bk01pt12ch30s03.html" title="Using" /><link rel="next" href="parallel_mode.html" title="Chapter 31. Parallel Mode" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Design</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt12ch30s03.html">Prev</a> </td><th width="60%" align="center">Chapter 30. Debug Mode</th><td width="20%" align="right"> <a accesskey="n" href="parallel_mode.html">Next</a></td></tr></table><hr /></div><div class="sect1" title="Design"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.ext.debug_mode.design"></a>Design</h2></div></div></div><p>
4 
  </p><div class="sect2" title="Goals"><div class="titlepage"><div><div><h3 class="title"><a id="debug_mode.design.goals"></a>Goals</h3></div></div></div><p>
5 
    </p><p> The libstdc++ debug mode replaces unsafe (but efficient) standard
6 
  containers and iterators with semantically equivalent safe standard
7 
  containers and iterators to aid in debugging user programs. The
8 
  following goals directed the design of the libstdc++ debug mode:</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>Correctness</em></span>: the libstdc++ debug mode must not change
9 
    the semantics of the standard library for all cases specified in
10 
    the ANSI/ISO C++ standard. The essence of this constraint is that
11 
    any valid C++ program should behave in the same manner regardless
12 
    of whether it is compiled with debug mode or release mode. In
13 
    particular, entities that are defined in namespace std in release
14 
    mode should remain defined in namespace std in debug mode, so that
15 
    legal specializations of namespace std entities will remain
16 
    valid. A program that is not valid C++ (e.g., invokes undefined
17 
    behavior) is not required to behave similarly, although the debug
18 
    mode will abort with a diagnostic when it detects undefined
19 
    behavior.</p></li><li class="listitem"><p><span class="emphasis"><em>Performance</em></span>: the additional of the libstdc++ debug mode
20 
    must not affect the performance of the library when it is compiled
21 
    in release mode. Performance of the libstdc++ debug mode is
22 
    secondary (and, in fact, will be worse than the release
23 
    mode).</p></li><li class="listitem"><p><span class="emphasis"><em>Usability</em></span>: the libstdc++ debug mode should be easy to
24 
    use. It should be easily incorporated into the user's development
25 
    environment (e.g., by requiring only a single new compiler switch)
26 
    and should produce reasonable diagnostics when it detects a
27 
    problem with the user program. Usability also involves detection
28 
    of errors when using the debug mode incorrectly, e.g., by linking
29 
    a release-compiled object against a debug-compiled object if in
30 
    fact the resulting program will not run correctly.</p></li><li class="listitem"><p><span class="emphasis"><em>Minimize recompilation</em></span>: While it is expected that
31 
    users recompile at least part of their program to use debug
32 
    mode, the amount of recompilation affects the
33 
    detect-compile-debug turnaround time. This indirectly affects the
34 
    usefulness of the debug mode, because debugging some applications
35 
    may require rebuilding a large amount of code, which may not be
36 
    feasible when the suspect code may be very localized. There are
37 
    several levels of conformance to this requirement, each with its
38 
    own usability and implementation characteristics. In general, the
39 
    higher-numbered conformance levels are more usable (i.e., require
40 
    less recompilation) but are more complicated to implement than
41 
    the lower-numbered conformance levels.
42 
      </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p><span class="emphasis"><em>Full recompilation</em></span>: The user must recompile his or
43 
        her entire application and all C++ libraries it depends on,
44 
        including the C++ standard library that ships with the
45 
        compiler. This must be done even if only a small part of the
46 
        program can use debugging features.</p></li><li class="listitem"><p><span class="emphasis"><em>Full user recompilation</em></span>: The user must recompile
47 
        his or her entire application and all C++ libraries it depends
48 
        on, but not the C++ standard library itself. This must be done
49 
        even if only a small part of the program can use debugging
50 
        features. This can be achieved given a full recompilation
51 
        system by compiling two versions of the standard library when
52 
        the compiler is installed and linking against the appropriate
53 
        one, e.g., a multilibs approach.</p></li><li class="listitem"><p><span class="emphasis"><em>Partial recompilation</em></span>: The user must recompile the
54 
        parts of his or her application and the C++ libraries it
55 
        depends on that will use the debugging facilities
56 
        directly. This means that any code that uses the debuggable
57 
        standard containers would need to be recompiled, but code
58 
        that does not use them (but may, for instance, use IOStreams)
59 
        would not have to be recompiled.</p></li><li class="listitem"><p><span class="emphasis"><em>Per-use recompilation</em></span>: The user must recompile the
60 
        parts of his or her application and the C++ libraries it
61 
        depends on where debugging should occur, and any other code
62 
        that interacts with those containers. This means that a set of
63 
        translation units that accesses a particular standard
64 
        container instance may either be compiled in release mode (no
65 
        checking) or debug mode (full checking), but must all be
66 
        compiled in the same way; a translation unit that does not see
67 
        that standard container instance need not be recompiled. This
68 
        also means that a translation unit <span class="emphasis"><em>A</em></span> that contains a
69 
        particular instantiation
70 
        (say, <code class="code">std::vector&lt;int&gt;</code>) compiled in release
71 
        mode can be linked against a translation unit <span class="emphasis"><em>B</em></span> that
72 
        contains the same instantiation compiled in debug mode (a
73 
        feature not present with partial recompilation). While this
74 
        behavior is technically a violation of the One Definition
75 
        Rule, this ability tends to be very important in
76 
        practice. The libstdc++ debug mode supports this level of
77 
        recompilation. </p></li><li class="listitem"><p><span class="emphasis"><em>Per-unit recompilation</em></span>: The user must only
78 
        recompile the translation units where checking should occur,
79 
        regardless of where debuggable standard containers are
80 
        used. This has also been dubbed "<code class="code">-g</code> mode",
81 
        because the <code class="code">-g</code> compiler switch works in this way,
82 
        emitting debugging information at a per--translation-unit
83 
        granularity. We believe that this level of recompilation is in
84 
        fact not possible if we intend to supply safe iterators, leave
85 
        the program semantics unchanged, and not regress in
86 
        performance under release mode because we cannot associate
87 
        extra information with an iterator (to form a safe iterator)
88 
        without either reserving that space in release mode
89 
        (performance regression) or allocating extra memory associated
90 
        with each iterator with <code class="code">new</code> (changes the program
91 
        semantics).</p></li></ol></div><p>
92 
    </p></li></ul></div></div><div class="sect2" title="Methods"><div class="titlepage"><div><div><h3 class="title"><a id="debug_mode.design.methods"></a>Methods</h3></div></div></div><p>
93 
    </p><p>This section provides an overall view of the design of the
94 
  libstdc++ debug mode and details the relationship between design
95 
  decisions and the stated design goals.</p><div class="sect3" title="The Wrapper Model"><div class="titlepage"><div><div><h4 class="title"><a id="debug_mode.design.methods.wrappers"></a>The Wrapper Model</h4></div></div></div><p>The libstdc++ debug mode uses a wrapper model where the
96 
  debugging versions of library components (e.g., iterators and
97 
  containers) form a layer on top of the release versions of the
98 
  library components. The debugging components first verify that the
99 
  operation is correct (aborting with a diagnostic if an error is
100 
  found) and will then forward to the underlying release-mode
101 
  container that will perform the actual work. This design decision
102 
  ensures that we cannot regress release-mode performance (because the
103 
  release-mode containers are left untouched) and partially
104 
  enables <a class="link" href="bk01pt12ch30s04.html#methods.coexistence.link" title="Link- and run-time coexistence of release- and debug-mode components">mixing debug and
105 
  release code</a> at link time, although that will not be
106 
  discussed at this time.</p><p>Two types of wrappers are used in the implementation of the debug
107 
  mode: container wrappers and iterator wrappers. The two types of
108 
  wrappers interact to maintain relationships between iterators and
109 
  their associated containers, which are necessary to detect certain
110 
  types of standard library usage errors such as dereferencing
111 
  past-the-end iterators or inserting into a container using an
112 
  iterator from a different container.</p><div class="sect4" title="Safe Iterators"><div class="titlepage"><div><div><h5 class="title"><a id="debug_mode.design.methods.safe_iter"></a>Safe Iterators</h5></div></div></div><p>Iterator wrappers provide a debugging layer over any iterator that
113 
  is attached to a particular container, and will manage the
114 
  information detailing the iterator's state (singular,
115 
  dereferenceable, etc.) and tracking the container to which the
116 
  iterator is attached. Because iterators have a well-defined, common
117 
  interface the iterator wrapper is implemented with the iterator
118 
  adaptor class template <code class="code">__gnu_debug::_Safe_iterator</code>,
119 
  which takes two template parameters:</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><code class="code">Iterator</code>: The underlying iterator type, which must
120 
    be either the <code class="code">iterator</code> or <code class="code">const_iterator</code>
121 
    typedef from the sequence type this iterator can reference.</p></li><li class="listitem"><p><code class="code">Sequence</code>: The type of sequence that this iterator
122 
  references. This sequence must be a safe sequence (discussed below)
123 
  whose <code class="code">iterator</code> or <code class="code">const_iterator</code> typedef
124 
  is the type of the safe iterator.</p></li></ul></div></div><div class="sect4" title="Safe Sequences (Containers)"><div class="titlepage"><div><div><h5 class="title"><a id="debug_mode.design.methods.safe_seq"></a>Safe Sequences (Containers)</h5></div></div></div><p>Container wrappers provide a debugging layer over a particular
125 
  container type. Because containers vary greatly in the member
126 
  functions they support and the semantics of those member functions
127 
  (especially in the area of iterator invalidation), container
128 
  wrappers are tailored to the container they reference, e.g., the
129 
  debugging version of <code class="code">std::list</code> duplicates the entire
130 
  interface of <code class="code">std::list</code>, adding additional semantic
131 
  checks and then forwarding operations to the
132 
  real <code class="code">std::list</code> (a public base class of the debugging
133 
  version) as appropriate. However, all safe containers inherit from
134 
  the class template <code class="code">__gnu_debug::_Safe_sequence</code>,
135 
  instantiated with the type of the safe container itself (an instance
136 
  of the curiously recurring template pattern).</p><p>The iterators of a container wrapper will be
137 
  <a class="link" href="bk01pt12ch30s04.html#debug_mode.design.methods.safe_iter" title="Safe Iterators">safe
138 
  iterators</a> that reference sequences of this type and wrap the
139 
  iterators provided by the release-mode base class. The debugging
140 
  container will use only the safe iterators within its own interface
141 
  (therefore requiring the user to use safe iterators, although this
142 
  does not change correct user code) and will communicate with the
143 
  release-mode base class with only the underlying, unsafe,
144 
  release-mode iterators that the base class exports.</p><p> The debugging version of <code class="code">std::list</code> will have the
145 
  following basic structure:</p><pre class="programlisting">
146 
template&lt;typename _Tp, typename _Allocator = allocator&lt;_Tp&gt;
147 
  class debug-list :
148 
    public release-list&lt;_Tp, _Allocator&gt;,
149 
    public __gnu_debug::_Safe_sequence&lt;debug-list&lt;_Tp, _Allocator&gt; &gt;
150 
  {
151 
    typedef release-list&lt;_Tp, _Allocator&gt; _Base;
152 
    typedef debug-list&lt;_Tp, _Allocator&gt;   _Self;
153 
 
154 
  public:
155 
    typedef __gnu_debug::_Safe_iterator&lt;typename _Base::iterator, _Self&gt;       iterator;
156 
    typedef __gnu_debug::_Safe_iterator&lt;typename _Base::const_iterator, _Self&gt; const_iterator;
157 
 
158 
    // duplicate std::list interface with debugging semantics
159 
  };
160 
</pre></div></div><div class="sect3" title="Precondition Checking"><div class="titlepage"><div><div><h4 class="title"><a id="debug_mode.design.methods.precond"></a>Precondition Checking</h4></div></div></div><p>The debug mode operates primarily by checking the preconditions of
161 
  all standard library operations that it supports. Preconditions that
162 
  are always checked (regardless of whether or not we are in debug
163 
  mode) are checked via the <code class="code">__check_xxx</code> macros defined
164 
  and documented in the source
165 
  file <code class="code">include/debug/debug.h</code>. Preconditions that may or
166 
  may not be checked, depending on the debug-mode
167 
  macro <code class="code">_GLIBCXX_DEBUG</code>, are checked via
168 
  the <code class="code">__requires_xxx</code> macros defined and documented in the
169 
  same source file. Preconditions are validated using any additional
170 
  information available at run-time, e.g., the containers that are
171 
  associated with a particular iterator, the position of the iterator
172 
  within those containers, the distance between two iterators that may
173 
  form a valid range, etc. In the absence of suitable information,
174 
  e.g., an input iterator that is not a safe iterator, these
175 
  precondition checks will silently succeed.</p><p>The majority of precondition checks use the aforementioned macros,
176 
  which have the secondary benefit of having prewritten debug
177 
  messages that use information about the current status of the
178 
  objects involved (e.g., whether an iterator is singular or what
179 
  sequence it is attached to) along with some static information
180 
  (e.g., the names of the function parameters corresponding to the
181 
  objects involved). When not using these macros, the debug mode uses
182 
  either the debug-mode assertion
183 
  macro <code class="code">_GLIBCXX_DEBUG_ASSERT</code> , its pedantic
184 
  cousin <code class="code">_GLIBCXX_DEBUG_PEDASSERT</code>, or the assertion
185 
  check macro that supports more advance formulation of error
186 
  messages, <code class="code">_GLIBCXX_DEBUG_VERIFY</code>. These macros are
187 
  documented more thoroughly in the debug mode source code.</p></div><div class="sect3" title="Release- and debug-mode coexistence"><div class="titlepage"><div><div><h4 class="title"><a id="debug_mode.design.methods.coexistence"></a>Release- and debug-mode coexistence</h4></div></div></div><p>The libstdc++ debug mode is the first debug mode we know of that
188 
  is able to provide the "Per-use recompilation" (4) guarantee, that
189 
  allows release-compiled and debug-compiled code to be linked and
190 
  executed together without causing unpredictable behavior. This
191 
  guarantee minimizes the recompilation that users are required to
192 
  perform, shortening the detect-compile-debug bug hunting cycle
193 
  and making the debug mode easier to incorporate into development
194 
  environments by minimizing dependencies.</p><p>Achieving link- and run-time coexistence is not a trivial
195 
  implementation task. To achieve this goal we required a small
196 
  extension to the GNU C++ compiler (since incorporated into the C++0x language specification, described in the GCC Manual for the C++ language as
197 
  <a class="ulink" href="http://gcc.gnu.org/onlinedocs/gcc/Namespace-Association.html#Namespace-Association" target="_top">namespace
198 
  association</a>), and a complex organization of debug- and
199 
  release-modes. The end result is that we have achieved per-use
200 
  recompilation but have had to give up some checking of the
201 
  <code class="code">std::basic_string</code> class template (namely, safe
202 
  iterators).
203 
</p><div class="sect4" title="Compile-time coexistence of release- and debug-mode components"><div class="titlepage"><div><div><h5 class="title"><a id="methods.coexistence.compile"></a>Compile-time coexistence of release- and debug-mode components</h5></div></div></div><p>Both the release-mode components and the debug-mode
204 
  components need to exist within a single translation unit so that
205 
  the debug versions can wrap the release versions. However, only one
206 
  of these components should be user-visible at any particular
207 
  time with the standard name, e.g., <code class="code">std::list</code>. </p><p>In release mode, we define only the release-mode version of the
208 
  component with its standard name and do not include the debugging
209 
  component at all. The release mode version is defined within the
210 
  namespace <code class="code">std</code>. Minus the namespace associations, this
211 
  method leaves the behavior of release mode completely unchanged from
212 
  its behavior prior to the introduction of the libstdc++ debug
213 
  mode. Here's an example of what this ends up looking like, in
214 
  C++.</p><pre class="programlisting">
215 
namespace std
216 
{
217 
  template&lt;typename _Tp, typename _Alloc = allocator&lt;_Tp&gt; &gt;
218 
    class list
219 
    {
220 
      // ...
221 
     };
222 
} // namespace std
223 
</pre><p>In debug mode we include the release-mode container (which is now
224 
defined in in the namespace <code class="code">__norm</code>) and also the
225 
debug-mode container. The debug-mode container is defined within the
226 
namespace <code class="code">__debug</code>, which is associated with namespace
227 
<code class="code">std</code> via the C++0x namespace association language feature.  This
228 
method allows the debug and release versions of the same component to
229 
coexist at compile-time and link-time without causing an unreasonable
230 
maintenance burden, while minimizing confusion. Again, this boils down
231 
to C++ code as follows:</p><pre class="programlisting">
232 
namespace std
233 
{
234 
  namespace __norm
235 
  {
236 
    template&lt;typename _Tp, typename _Alloc = allocator&lt;_Tp&gt; &gt;
237 
      class list
238 
      {
239 
        // ...
240 
      };
241 
  } // namespace __gnu_norm
242 
 
243 
  namespace __debug
244 
  {
245 
    template&lt;typename _Tp, typename _Alloc = allocator&lt;_Tp&gt; &gt;
246 
      class list
247 
      : public __norm::list&lt;_Tp, _Alloc&gt;,
248 
        public __gnu_debug::_Safe_sequence&lt;list&lt;_Tp, _Alloc&gt; &gt;
249 
      {
250 
        // ...
251 
      };
252 
  } // namespace __norm
253 
 
254 
  // namespace __debug __attribute__ ((strong));
255 
  inline namespace __debug { }
256 
}
257 
</pre></div><div class="sect4" title="Link- and run-time coexistence of release- and debug-mode components"><div class="titlepage"><div><div><h5 class="title"><a id="methods.coexistence.link"></a>Link- and run-time coexistence of release- and
258 
    debug-mode components</h5></div></div></div><p>Because each component has a distinct and separate release and
259 
debug implementation, there are are no issues with link-time
260 
coexistence: the separate namespaces result in different mangled
261 
names, and thus unique linkage.</p><p>However, components that are defined and used within the C++
262 
standard library itself face additional constraints. For instance,
263 
some of the member functions of <code class="code"> std::moneypunct</code> return
264 
<code class="code">std::basic_string</code>. Normally, this is not a problem, but
265 
with a mixed mode standard library that could be using either
266 
debug-mode or release-mode <code class="code"> basic_string</code> objects, things
267 
get more complicated.  As the return value of a function is not
268 
encoded into the mangled name, there is no way to specify a
269 
release-mode or a debug-mode string. In practice, this results in
270 
runtime errors. A simplified example of this problem is as follows.
271 
</p><p> Take this translation unit, compiled in debug-mode: </p><pre class="programlisting">
272 
// -D_GLIBCXX_DEBUG
273 
#include &lt;string&gt;
274 
 
275 
std::string test02();
276 
 
277 
std::string test01()
278 
{
279 
  return test02();
280 
}
281 
 
282 
int main()
283 
{
284 
  test01();
285 
  return 0;
286 
}
287 
</pre><p> ... and linked to this translation unit, compiled in release mode:</p><pre class="programlisting">
288 
#include &lt;string&gt;
289 
 
290 
std::string
291 
test02()
292 
{
293 
  return std::string("toast");
294 
}
295 
</pre><p> For this reason we cannot easily provide safe iterators for
296 
  the <code class="code">std::basic_string</code> class template, as it is present
297 
  throughout the C++ standard library. For instance, locale facets
298 
  define typedefs that include <code class="code">basic_string</code>: in a mixed
299 
  debug/release program, should that typedef be based on the
300 
  debug-mode <code class="code">basic_string</code> or the
301 
  release-mode <code class="code">basic_string</code>? While the answer could be
302 
  "both", and the difference hidden via renaming a la the
303 
  debug/release containers, we must note two things about locale
304 
  facets:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>They exist as shared state: one can create a facet in one
305 
  translation unit and access the facet via the same type name in a
306 
  different translation unit. This means that we cannot have two
307 
  different versions of locale facets, because the types would not be
308 
  the same across debug/release-mode translation unit barriers.</p></li><li class="listitem"><p>They have virtual functions returning strings: these functions
309 
  mangle in the same way regardless of the mangling of their return
310 
  types (see above), and their precise signatures can be relied upon
311 
  by users because they may be overridden in derived classes.</p></li></ol></div><p>With the design of libstdc++ debug mode, we cannot effectively hide
312 
  the differences between debug and release-mode strings from the
313 
  user. Failure to hide the differences may result in unpredictable
314 
  behavior, and for this reason we have opted to only
315 
  perform <code class="code">basic_string</code> changes that do not require ABI
316 
  changes. The effect on users is expected to be minimal, as there are
317 
  simple alternatives (e.g., <code class="code">__gnu_debug::basic_string</code>),
318 
  and the usability benefit we gain from the ability to mix debug- and
319 
  release-compiled translation units is enormous.</p></div><div class="sect4" title="Alternatives for Coexistence"><div class="titlepage"><div><div><h5 class="title"><a id="methods.coexistence.alt"></a>Alternatives for Coexistence</h5></div></div></div><p>The coexistence scheme above was chosen over many alternatives,
320 
  including language-only solutions and solutions that also required
321 
  extensions to the C++ front end. The following is a partial list of
322 
  solutions, with justifications for our rejection of each.</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>Completely separate debug/release libraries</em></span>: This is by
323 
  far the simplest implementation option, where we do not allow any
324 
  coexistence of debug- and release-compiled translation units in a
325 
  program. This solution has an extreme negative affect on usability,
326 
  because it is quite likely that some libraries an application
327 
  depends on cannot be recompiled easily. This would not meet
328 
  our <span class="emphasis"><em>usability</em></span> or <span class="emphasis"><em>minimize recompilation</em></span> criteria
329 
  well.</p></li><li class="listitem"><p><span class="emphasis"><em>Add a <code class="code">Debug</code> boolean template parameter</em></span>:
330 
  Partial specialization could be used to select the debug
331 
  implementation when <code class="code">Debug == true</code>, and the state
332 
  of <code class="code">_GLIBCXX_DEBUG</code> could decide whether the
333 
  default <code class="code">Debug</code> argument is <code class="code">true</code>
334 
  or <code class="code">false</code>. This option would break conformance with the
335 
  C++ standard in both debug <span class="emphasis"><em>and</em></span> release modes. This would
336 
  not meet our <span class="emphasis"><em>correctness</em></span> criteria. </p></li><li class="listitem"><p><span class="emphasis"><em>Packaging a debug flag in the allocators</em></span>: We could
337 
    reuse the <code class="code">Allocator</code> template parameter of containers
338 
    by adding a sentinel wrapper <code class="code">debug&lt;&gt;</code> that
339 
    signals the user's intention to use debugging, and pick up
340 
    the <code class="code">debug&lt;&gt;</code> allocator wrapper in a partial
341 
    specialization. However, this has two drawbacks: first, there is a
342 
    conformance issue because the default allocator would not be the
343 
    standard-specified <code class="code">std::allocator&lt;T&gt;</code>. Secondly
344 
    (and more importantly), users that specify allocators instead of
345 
    implicitly using the default allocator would not get debugging
346 
    containers. Thus this solution fails the <span class="emphasis"><em>correctness</em></span>
347 
    criteria.</p></li><li class="listitem"><p><span class="emphasis"><em>Define debug containers in another namespace, and employ
348 
      a <code class="code">using</code> declaration (or directive)</em></span>: This is an
349 
      enticing option, because it would eliminate the need for
350 
      the <code class="code">link_name</code> extension by aliasing the
351 
      templates. However, there is no true template aliasing mechanism
352 
      is C++, because both <code class="code">using</code> directives and using
353 
      declarations disallow specialization. This method fails
354 
      the <span class="emphasis"><em>correctness</em></span> criteria.</p></li><li class="listitem"><p><span class="emphasis"><em> Use implementation-specific properties of anonymous
355 
    namespaces. </em></span>
356 
    See <a class="ulink" href="http://gcc.gnu.org/ml/libstdc++/2003-08/msg00004.html" target="_top"> this post
357 
    </a>
358 
    This method fails the <span class="emphasis"><em>correctness</em></span> criteria.</p></li><li class="listitem"><p><span class="emphasis"><em>Extension: allow reopening on namespaces</em></span>: This would
359 
    allow the debug mode to effectively alias the
360 
    namespace <code class="code">std</code> to an internal namespace, such
361 
    as <code class="code">__gnu_std_debug</code>, so that it is completely
362 
    separate from the release-mode <code class="code">std</code> namespace. While
363 
    this will solve some renaming problems and ensure that
364 
    debug- and release-compiled code cannot be mixed unsafely, it ensures that
365 
    debug- and release-compiled code cannot be mixed at all. For
366 
    instance, the program would have two <code class="code">std::cout</code>
367 
    objects! This solution would fails the <span class="emphasis"><em>minimize
368 
    recompilation</em></span> requirement, because we would only be able to
369 
    support option (1) or (2).</p></li><li class="listitem"><p><span class="emphasis"><em>Extension: use link name</em></span>: This option involves
370 
    complicated re-naming between debug-mode and release-mode
371 
    components at compile time, and then a g++ extension called <span class="emphasis"><em>
372 
    link name </em></span> to recover the original names at link time. There
373 
    are two drawbacks to this approach. One, it's very verbose,
374 
    relying on macro renaming at compile time and several levels of
375 
    include ordering. Two, ODR issues remained with container member
376 
    functions taking no arguments in mixed-mode settings resulting in
377 
    equivalent link names, <code class="code"> vector::push_back() </code> being
378 
    one example.
379 
    See <a class="ulink" href="http://gcc.gnu.org/ml/libstdc++/2003-08/msg00177.html" target="_top">link
380 
    name</a> </p></li></ul></div><p>Other options may exist for implementing the debug mode, many of
381 
  which have probably been considered and others that may still be
382 
  lurking. This list may be expanded over time to include other
383 
  options that we could have implemented, but in all cases the full
384 
  ramifications of the approach (as measured against the design goals
385 
  for a libstdc++ debug mode) should be considered first. The DejaGNU
386 
  testsuite includes some testcases that check for known problems with
387 
  some solutions (e.g., the <code class="code">using</code> declaration solution
388 
  that breaks user specialization), and additional testcases will be
389 
  added as we are able to identify other typical problem cases. These
390 
  test cases will serve as a benchmark by which we can compare debug
391 
  mode implementations.</p></div></div></div><div class="sect2" title="Other Implementations"><div class="titlepage"><div><div><h3 class="title"><a id="debug_mode.design.other"></a>Other Implementations</h3></div></div></div><p>
392 
    </p><p> There are several existing implementations of debug modes for C++
393 
  standard library implementations, although none of them directly
394 
  supports debugging for programs using libstdc++. The existing
395 
  implementations include:</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><a class="ulink" href="http://www.mathcs.sjsu.edu/faculty/horstman/safestl.html" target="_top">SafeSTL</a>:
396 
  SafeSTL was the original debugging version of the Standard Template
397 
  Library (STL), implemented by Cay S. Horstmann on top of the
398 
  Hewlett-Packard STL. Though it inspired much work in this area, it
399 
  has not been kept up-to-date for use with modern compilers or C++
400 
  standard library implementations.</p></li><li class="listitem"><p><a class="ulink" href="http://www.stlport.org/" target="_top">STLport</a>: STLport is a free
401 
  implementation of the C++ standard library derived from the <a class="ulink" href="http://www.sgi.com/tech/stl/" target="_top">SGI implementation</a>, and
402 
  ported to many other platforms. It includes a debug mode that uses a
403 
  wrapper model (that in some ways inspired the libstdc++ debug mode
404 
  design), although at the time of this writing the debug mode is
405 
  somewhat incomplete and meets only the "Full user recompilation" (2)
406 
  recompilation guarantee by requiring the user to link against a
407 
  different library in debug mode vs. release mode.</p></li><li class="listitem"><p>Metrowerks CodeWarrior: The C++ standard library
408 
  that ships with Metrowerks CodeWarrior includes a debug mode. It is
409 
  a full debug-mode implementation (including debugging for
410 
  CodeWarrior extensions) and is easy to use, although it meets only
411 
  the "Full recompilation" (1) recompilation
412 
  guarantee.</p></li></ul></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt12ch30s03.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="debug_mode.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="parallel_mode.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Using </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 31. Parallel Mode</td></tr></table></div></body></html>

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.