Design of the libstdc++ debug mode

The latest version of this document is always available at http://gcc.gnu.org/onlinedocs/libstdc++/debug_mode.html.

To the libstdc++-v3 homepage.


Debug mode design

The libstdc++ debug mode replaces unsafe (but efficient) standard containers and iterators with semantically equivalent safe standard containers and iterators to aid in debugging user programs. The following goals directed the design of the libstdc++ debug mode:

Other implementations

There are several existing implementations of debug modes for C++ standard library implementations, although none of them directly supports debugging for programs using libstdc++. The existing implementations include:

Debug mode design methodology

This section provides an overall view of the design of the libstdc++ debug mode and details the relationship between design decisions and the stated design goals.

The wrapper model

The libstdc++ debug mode uses a wrapper model where the debugging versions of library components (e.g., iterators and containers) form a layer on top of the release versions of the library components. The debugging components first verify that the operation is correct (aborting with a diagnostic if an error is found) and will then forward to the underlying release-mode container that will perform the actual work. This design decision ensures that we cannot regress release-mode performance (because the release-mode containers are left untouched) and partially enables mixing debug and release code at link time, although that will not be discussed at this time.

Two types of wrappers are used in the implementation of the debug mode: container wrappers and iterator wrappers. The two types of wrappers interact to maintain relationships between iterators and their associated containers, which are necessary to detect certain types of standard library usage errors such as dereferencing past-the-end iterators or inserting into a container using an iterator from a different container.

Safe iterators

Iterator wrappers provide a debugging layer over any iterator that is attached to a particular container, and will manage the information detailing the iterator's state (singular, dereferenceable, etc.) and tracking the container to which the iterator is attached. Because iterators have a well-defined, common interface the iterator wrapper is implemented with the iterator adaptor class template __gnu_debug::_Safe_iterator, which takes two template parameters:

Safe sequences (containers)

Container wrappers provide a debugging layer over a particular container type. Because containers vary greatly in the member functions they support and the semantics of those member functions (especially in the area of iterator invalidation), container wrappers are tailored to the container they reference, e.g., the debugging version of std::list duplicates the entire interface of std::list, adding additional semantic checks and then forwarding operations to the real std::list (a public base class of the debugging version) as appropriate. However, all safe containers inherit from the class template __gnu_debug::_Safe_sequence, instantiated with the type of the safe container itself (an instance of the curiously recurring template pattern).

The iterators of a container wrapper will be safe iterators that reference sequences of this type and wrap the iterators provided by the release-mode base class. The debugging container will use only the safe iterators within its own interface (therefore requiring the user to use safe iterators, although this does not change correct user code) and will communicate with the release-mode base class with only the underlying, unsafe, release-mode iterators that the base class exports.

The debugging version of std::list will have the following basic structure:

template<typename _Tp, typename _Allocator = allocator<_Tp>
  class debug-list :
    public release-list<_Tp, _Allocator>,
    public __gnu_debug::_Safe_sequence<debug-list<_Tp, _Allocator> >
  {
    typedef release-list<_Tp, _Allocator> _Base;
    typedef debug-list<_Tp, _Allocator>   _Self;

  public:
    typedef __gnu_debug::_Safe_iterator<typename _Base::iterator, _Self>       iterator;
    typedef __gnu_debug::_Safe_iterator<typename _Base::const_iterator, _Self> const_iterator;

    // duplicate std::list interface with debugging semantics
  };

Precondition checking

The debug mode operates primarily by checking the preconditions of all standard library operations that it supports. Preconditions that are always checked (regardless of whether or not we are in debug mode) are checked via the __check_xxx macros defined and documented in the source file include/debug/debug.h. Preconditions that may or may not be checked, depending on the debug-mode macro _GLIBCXX_DEBUG, are checked via the __requires_xxx macros defined and documented in the same source file. Preconditions are validated using any additional information available at run-time, e.g., the containers that are associated with a particular iterator, the position of the iterator within those containers, the distance between two iterators that may form a valid range, etc. In the absence of suitable information, e.g., an input iterator that is not a safe iterator, these precondition checks will silently succeed.

The majority of precondition checks use the aforementioned macros, which have the secondary benefit of having prewritten debug messages that use information about the current status of the objects involved (e.g., whether an iterator is singular or what sequence it is attached to) along with some static information (e.g., the names of the function parameters corresponding to the objects involved). When not using these macros, the debug mode uses either the debug-mode assertion macro _GLIBCXX_DEBUG_ASSERT , its pedantic cousin _GLIBCXX_DEBUG_PEDASSERT, or the assertion check macro that supports more advance formulation of error messages, _GLIBCXX_DEBUG_VERIFY. These macros are documented more thoroughly in the debug mode source code.

Release- and debug-mode coexistence

The libstdc++ debug mode is the first debug mode we know of that is able to provide the "Per-use recompilation" (4) guarantee, that allows release-compiled and debug-compiled code to be linked and executed together without causing unpredictable behavior. This guarantee minimizes the recompilation that users are required to perform, shortening the detect-compile-debug bughunting cycle and making the debug mode easier to incorporate into development environments by minimizing dependencies.

Achieving link- and run-time coexistence is not a trivial implementation task. To achieve this goal we required a small extension to the GNU C++ compiler (described in the GCC Manual for C++ Extensions, see strong using), and a complex organization of debug- and release-modes. The end result is that we have achieved per-use recompilation but have had to give up some checking of the std::basic_string class template (namely, safe iterators).

Compile-time coexistence of release- and debug-mode components

Both the release-mode components and the debug-mode components need to exist within a single translation unit so that the debug versions can wrap the release versions. However, only one of these components should be user-visible at any particular time with the standard name, e.g., std::list.

In release mode, we define only the release-mode version of the component with its standard name and do not include the debugging component at all. The release mode version is defined within the namespace std. Minus the namespace associations, this method leaves the behavior of release mode completely unchanged from its behavior prior to the introduction of the libstdc++ debug mode. Here's an example of what this ends up looking like, in C++.

namespace std
{
  template<typename _Tp, typename _Alloc = allocator<_Tp> >
    class list
    {
      // ...
     };
} // namespace std

In debug mode we include the release-mode container (which is now defined in in the namespace __norm) and also the debug-mode container. The debug-mode container is defined within the namespace __debug, which is associated with namespace std via the GNU namespace association extension. This method allows the debug and release versions of the same component to coexist at compile-time and link-time without causing an unreasonable maintenance burden, while minimizing confusion. Again, this boils down to C++ code as follows:

namespace std
{
  namespace __norm
  {
    template<typename _Tp, typename _Alloc = allocator<_Tp> >
      class list
      {
        // ...
      };
  } // namespace __gnu_norm

  namespace __debug
  {
    template<typename _Tp, typename _Alloc = allocator<_Tp> >
      class list
      : public __norm::list<_Tp, _Alloc>,
        public __gnu_debug::_Safe_sequence<list<_Tp, _Alloc> >
      {
        // ...
      };
  } // namespace __norm

  using namespace __debug __attribute__ ((strong));
}

Link- and run-time coexistence of release- and debug-mode components

Because each component has a distinct and separate release and debug implementation, there are are no issues with link-time coexistence: the separate namespaces result in different mangled names, and thus unique linkage.

However, components that are defined and used within the C++ standard library itself face additional constraints. For instance, some of the member functions of std::moneypunct return std::basic_string. Normally, this is not a problem, but with a mixed mode standard library that could be using either debug-mode or release-mode basic_string objects, things get more complicated. As the return value of a function is not encoded into the mangled name, there is no way to specify a release-mode or a debug-mode string. In practice, this results in runtime errors. A simplified example of this problem is as follows.

Take this translation unit, compiled in debug-mode:

// -D_GLIBCXX_DEBUG
#include <string>

std::string test02();
 
std::string test01()
{
  return test02();
}
 
int main()
{
  test01();
  return 0;
}

... and linked to this translation unit, compiled in release mode:

#include <string>
 
std::string
test02()
{
  return std::string("toast");
}

For this reason we cannot easily provide safe iterators for the std::basic_string class template, as it is present throughout the C++ standard library. For instance, locale facets define typedefs that include basic_string: in a mixed debug/release program, should that typedef be based on the debug-mode basic_string or the release-mode basic_string? While the answer could be "both", and the difference hidden via renaming a la the debug/release containers, we must note two things about locale facets:

  1. They exist as shared state: one can create a facet in one translation unit and access the facet via the same type name in a different translation unit. This means that we cannot have two different versions of locale facets, because the types would not be the same across debug/release-mode translation unit barriers.
  2. They have virtual functions returning strings: these functions mangle in the same way regardless of the mangling of their return types (see above), and their precise signatures can be relied upon by users because they may be overridden in derived classes.

With the design of libstdc++ debug mode, we cannot effectively hide the differences between debug and release-mode strings from the user. Failure to hide the differences may result in unpredictable behavior, and for this reason we have opted to only perform basic_string changes that do not require ABI changes. The effect on users is expected to be minimal, as there are simple alternatives (e.g., __gnu_debug::basic_string), and the usability benefit we gain from the ability to mix debug- and release-compiled translation units is enormous.

Alternatives for Coexistence

The coexistence scheme above was chosen over many alternatives, including language-only solutions and solutions that also required extensions to the C++ front end. The following is a partial list of solutions, with justifications for our rejection of each.

Other options may exist for implementing the debug mode, many of which have probably been considered and others that may still be lurking. This list may be expanded over time to include other options that we could have implemented, but in all cases the full ramifications of the approach (as measured against the design goals for a libstdc++ debug mode) should be considered first. The DejaGNU testsuite includes some testcases that check for known problems with some solutions (e.g., the using declaration solution that breaks user specialization), and additional testcases will be added as we are able to identify other typical problem cases. These test cases will serve as a benchmark by which we can compare debug mode implementations.


See license.html for copying conditions. Comments and suggestions are welcome, and may be sent to the libstdc++ mailing list.