[Bug libstdc++/60489] New: Document which functions can be recursively reentered

[redi at gcc dot gnu.org]

http://gcc.gnu.org/bugzilla/show_bug.cgi?id=60489

            Bug ID: 60489
           Summary: Document which functions can be recursively reentered
           Product: gcc
           Version: 4.9.0
            Status: UNCONFIRMED
          Keywords: documentation
          Severity: normal
          Priority: P3
         Component: libstdc++
          Assignee: unassigned at gcc dot gnu.org
          Reporter: redi at gcc dot gnu.org

The standard says:

17.6.5.8 Reentrancy [reentrancy]
Except where explicitly specified in this standard, it is
implementation-defined which functions in the Standard C ++ library may be
recursively reentered.

Our docs on implementation-defined properties (with the C++03 section number)
say:

"[17.4.4.5] Non-reentrant functions are probably best discussed in the various
sections on multithreading (see above)."

While that may be true, (1) the sections on multithreading are not "above" and
(2) don't say anything about reentrancy.

This affects whether, for example, an element being erased from a container
during a call to clear() can call clear() on the container again, see
http://stackoverflow.com/q/20755194/981959 (we probably *could* make that work
if we wanted to, but it would require more work to support a very uncommon
case).

I think the simplest solution is to document that for our implementation no
functions are reentrant unless specified otherwise, then specify otherwise
later for particular functions.