Re: [v3] doc update

[Benjamin Kosnik <bkoz at redhat dot com>]

>Three minor nits:
>  - There's a comment about the "__gnu_nom" namespace (should be
>__gnu_norm)

Will fix this, thanks.

>  - The code that puts the list class template into __gnu_debug is a
>little bit of a lie; list should go into __gnu_debug_impl and a strong
>using directive will pull it into __gnu_debug; basic_string goes into
>__gnu_debug directly. (?)

Known. I'm trying to keep that part conceptually simple, so took
liberties to explain the overall concept. I don't want to get into the
actual machinations WRT the debug containers and __gnu_debug. I think
easing people into the general idea behind the debug mode is a better
idea.

If you've got a better way....... I'm all for it.

>  - I don't understand the comment about link_name and vector::push_back
>being a problem (in the section on alternative implementations). The
>debug/release versions of push_back will mangle differently, as they
>should.

Here's what I had from the time (Aug?) that I looked at this:

%nm mixed_mode_include_1.o | grep insert
00000000 W _ZN11__gnu_debug6vectorIiSaIiEE6insertIiEEvNS_14_Safe_iteratorIN9__gnu_cxx17__normal_iteratorIPiSt6vectorIiS1_EEES2_EET_SC_
00000000 W _ZNSt6vectorIiSaIiEE13_M_insert_auxEN9__gnu_cxx17__normal_iteratorIPiS1_EERKi
00000000 W _ZNSt6vectorIiSaIiEE14_M_fill_insertEN9__gnu_cxx17__normal_iteratorIPiS1_EEjRKi


-D_GLIBCXX_DEBUG
%nm mixed_mode_include_1.o | grep insert
00000000 W _ZNSt15_Release_vectorIiSaIiEE13_M_insert_auxEN9__gnu_cxx17__normal_iteratorIPiS1_EERKi
00000000 W _ZNSt15_Release_vectorIiSaIiEE14_M_fill_insertEN9__gnu_cxx17__normal_iteratorIPiS1_EEjRKi
00000000 W _ZNSt6vectorIiSaIiEE6insertIiEEvN11__gnu_debug14_Safe_iteratorIN9__gnu_cxx17__normal_iteratorIPiSt15_Release_vectorIiS0_EEES1_EET_SC_

So, in this case the debug vector::insert call is ok, because the
arguments themselves mangle uniquely. However, if there are no
arguments to do a unique mangle, say for vector::push_back, then ODR
issues resurface.

This can be demonstrated in -O0.

%$bld/H-x86-gcc.debug-apple/bin/g++ -c -O0 odr_1.cc
%nm odr_1.o | grep push_back
00000000 W _ZNSt6vectorIiSaIiEE9push_backERKi  <-- std::push_back()

%objdump -d odr_1.o | grep push_back
Disassembly of section .gnu.linkonce.t._ZNSt6vectorIiSaIiEE9push_backERKi:
00000000 <_ZNSt6vectorIiSaIiEE9push_backERKi>:
  12:   74 1e                   je     32 <_ZNSt6vectorIiSaIiEE9push_backERKi+0x32>
  24:   e8 fc ff ff ff          call   25 <_ZNSt6vectorIiSaIiEE9push_backERKi+0x25>
  30:   eb 2e                   jmp    60 <_ZNSt6vectorIiSaIiEE9push_backERKi+0x60>
  3f:   e8 fc ff ff ff          call   40 <_ZNSt6vectorIiSaIiEE9push_backERKi+0x40>
  5b:   e8 fc ff ff ff          call   5c <_ZNSt6vectorIiSaIiEE9push_backERKi+0x5c>

%$bld/H-x86-gcc.debug-apple/bin/g++ -D_GLIBCXX_DEBUG -c -O0 odr_1.cc  
%nm odr_1.o | grep push_back
00000000 W _ZNSt15_Release_vectorIiSaIiEE9push_backERKi
00000000 W _ZNSt6vectorIiSaIiEE9push_backERKi <-- __gnu_debug::push_back

%objdump -d odr_1.debug.o | grep push_back
Disassembly of section .gnu.linkonce.t._ZNSt6vectorIiSaIiEE9push_backERKi:
00000000 <_ZNSt6vectorIiSaIiEE9push_backERKi>:
   c:   e8 fc ff ff ff          call   d <_ZNSt6vectorIiSaIiEE9push_backERKi+0xd>
  1c:   e8 fc ff ff ff          call   1d <_ZNSt6vectorIiSaIiEE9push_backERKi+0x1d>
  31:   e8 fc ff ff ff          call   32 <_ZNSt6vectorIiSaIiEE9push_backERKi+0x32>
  3a:   74 0e                   je     4a <_ZNSt6vectorIiSaIiEE9push_backERKi+0x4a>
  45:   e8 fc ff ff ff          call   46 <_ZNSt6vectorIiSaIiEE9push_backERKi+0x46>
  50:   e8 fc ff ff ff          call   51 <_ZNSt6vectorIiSaIiEE9push_backERKi+0x51>

Thus, any file that uses vector::push_back would have this issue if
compiled in mixed-mode.

--

Maybe this was wrong? If so, just add in corrections to the docs.

>I'm thrilled this patch is going in. There are a few minor issues we found
>after the 6th patch; I'll try to get a patch in for this in the next few
>days, unless Matt gets to it sooner.

Well I'm thrilled too! Let's try to re-merge the Apple and FSF trees,
huh? Help is definitely needed to keep the FSF code on top of it, and
I'm counting on your help going forward! If you've got doc updates when
you do the other bits, please include them.

Thanks!

-benjamin