ISO/IEC JTC1 SC22 WG21 N3892 - 2014-01-20
Lawrence Crowl, Lawrence@Crowl.org
Introduction
Solution
Wording
27.8.1 Overview [string.stream.overview]
27.8.8 Class template basic_ostream_buffer [ostream.buffer]
27.8.8.1 Constructor [ostream.buffer.ctor]
27.8.8.2 Destructor [ostream.buffer.dtor]
Revisions
References
At present, stream output operations guarantee that they will not produce race conditions, but do not guarantee that the effect will be sensible. Some form of external synchronization is required. Unfortunately, without a standard mechanism for synchronizing, independently developed software will be unable to synchronize.
N3535 C++ Stream Mutexes proposed a standard mechanism for finding and sharing a mutex on streams. At the Spring 2013 standards meeting, the Concurrency Study Group requested a change away from a full mutex definition to a definition that also enabled buffering.
N3678 C++ Stream Guards proposed a standard mechanism for batching operations on a stream. That batching may be implemented as mutexees, as buffering, or some combination of both. It was the response to the Concurrency Study Group. A draft of that paper was reviewed in the Library Working Group, who found too many open issues on what was reasonably exposed to the 'buffering' part.
N3665 Uninterleaved Sring Output Streaming
proposed making streaming of strings of length less than BUFSIZ
appear uninterleaved in the output.
It was a "minimal" functionality change to the existing standard
to address the problem.
The full Committee chose not to adopt that minimal solution.
The general consensus in the July 2013 meeting of the Concurrency Study Group was that buffering should be explicit. This paper proposes such an explicit buffering.
We propose a basic_ostream_buffer,
that provides access to a matching basic_ostringstream
for buffering output operations.
The basic_ostream_buffer,
will atomically transfer the contents
of the basic_ostringstream to an ostream
on destruction of the basic_ostream_buffer.
The transfer on destruction simplifies the code and ensures at least some output in the presence of an exception.
The intent is that the basic_ostream_buffer
is an automatic-duration variable
with a relatively small scope
which constructs the text to appear uninterleaved.
For example,
....
{
std::ostream_buffer bout(std::cout);
bout << "Hello, " << "World!" << std::endl;
}
....
The wording below
permits implementation of basic_ostream_buffer
with either a stream_mutex
from
N3535
or with implementations suitable for
N3665,
e.g. with Posix file locks
[PSL]
This wording is relative to N3691.
Edit within paragraph 1 as follows.
The header
<sstream>defines four class templates and eight types that associate stream buffers with objects of classbasic_string, as described in 21.3. It also defines a class templatebasic_ostream_bufferto buffer abasic_ostringstreaminto anostream.
Edit within the synopsis as follows.
template <class charT, class traits = char_traits<charT>,
class Allocator = allocator<charT> >
class basic_stringstream;
typedef basic_stringstream<char> stringstream;
typedef basic_stringstream<wchar_t> wstringstream;
template <class charT,
class traits = std::char_traits<charT>,
class Allocator = std::allocator<charT> >
class basic_ostream_buffer
typedef basic_ostream_buffer<char> ostream_buffer;
typedef basic_ostream_buffer<wchar_t> wostream_buffer;
}
basic_ostream_buffer [ostream.buffer]Add a new section.
template <class charT, class traits = std::char_traits<charT>, class Allocator = std::allocator<charT> > class basic_ostream_buffer : public std::basic_ostringstream<charT,traits,Allocator> { public: basic_ostream_buffer(std::basic_ostream<charT,traits> &os); ~basic_ostream_buffer(); };The class template
basic_ostream_buffersupports buffering into abasic_ostringstreamand then indivisibly transfering the contents of thebasic_ostringstreamto abasic_ostream.[Example:
....{ std::ostream_buffer bout(std::cout); bout << "Hello, " << "World!" << std::endl; }....—end example]
Add a new section.
basic_ostream_buffer(std::basic_ostream<charT,traits> &os);Effects: Constructs the base
basic_ostringstream. May construct a lock.
Add a new section.
~basic_ostream_buffer();Effects: Transfers the contents of the base
basic_ostringstreamto the stream specified in the constructor as an indivisible uninterleaved sequence of characters, with respect to all other uses ofbasic_ostream_bufferon that stream. May destroy a lock.Synchronization: May or may not acquire a mutex while transfering characters.
This paper revises N3750 C++ Ostream Buffers
Change name to basic_ostream_buffer
and add the usual typedefs.
Change interface to inherit from basic_ostringstream
rather than provide access to a member of that type.
Add a Revisions section.