[jira] Created: (STDCXX-1030) documentation of ios::nolock and ios::nolockbuf incorrect

["Martin Sebor (JIRA)" <ji...@apache.org>]

documentation of ios::nolock and ios::nolockbuf incorrect
---------------------------------------------------------

                 Key: STDCXX-1030
                 URL: https://issues.apache.org/jira/browse/STDCXX-1030
             Project: C++ Standard Library
          Issue Type: Bug
          Components: Documentation
    Affects Versions: 4.2.1
            Reporter: Martin Sebor
            Assignee: Martin Sebor
             Fix For: 4.2.2


Sounds like the documentation of the two bits in the User Guide is backwards. Quoting from this [post|http://www.nabble.com/Documentation-User%27s-Guide%3A-44.1-Multithread-Safe%3A-Level-2-td21587519.html]:
{quote}
This is a documentation issue in the multi-thread safe section of the users guide for the stdcxx iostreams.

In addition, I am posting the error we observed so others can search for similar errors.

The following is the error that was observed. However, the error only showed up intermittently when the system was under sufficient load:

{noformat}
stopped in __rw::__rw_sputn<char,std::char_traits<char> > at 0x84028
0x00084028: __rw_sputn+0x00e0:  stb      %l1, [%l0]
{noformat}

We were able to solve the problem using the information in the users guide, but the section was a little confusing in regards to applying the code change.

When it became obvious this was a multi-thread issue with the standard stdcxx C++ library iostreams. Searching the documentation we found the following in the Stdcxx Library User's Guide section [44.1 Multithread-Safe: Level 2|http://stdcxx.apache.org/doc/stdlibug/44-1.html].


The part that is a little confusing is the following:

Thread safety is controlled by two bits, {{ios_base::nolock}} and {{ios_base::nolockbuf}}. These bits can be set on an iostream object (such as {{std::cout}}) using the public member function {{std::ios_base::setf()}}. When the bits are set, the object behaves in a thread-safe way as described above. The public member function {{std::ios_base::unsetf()}} clears both bits. When the bits are not set, the object is not thread-safe. It is also possible to set the bits individually to allow the stream thread-unsafe access on the stream data ({{nolock}}), or to prevent the stream from locking prior to accessing the stream buffer ({{nolockbuf}}).


Particularly the part that reads as follows:
??"These bits can be set on an iostream object (such as {{std::cout}}) using the public member function {{std::ios_base::setf()}}. When the bits are set, the object behaves in a thread-safe way as described above. "??
 
And in the following sentence as well:

??"When the bits are not set, the object is not thread-safe."??

If you want thread-safe iostreams you would do the following:
{{std::ios_base::unsetf(  std::ios_base::nolock | std::ios_base::nolockbuf )}}

If you do not want a thread-safe iostreams you would do the following:

{{std::ios_base::setf(  std::ios_base::nolock | std::ios_base::nolockbuf )}}

The documentation is rather confusing on exactly how this needs to be set for thread-safe or the default with no thread-safe behavior. 
{quote}

-- 
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.