stdcxx-issues mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Martin Sebor (JIRA)" <j...@apache.org>
Subject [jira] Created: (STDCXX-1030) documentation of ios::nolock and ios::nolockbuf incorrect
Date Sun, 25 Jan 2009 23:04:59 GMT
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.


Mime
View raw message