27 Input/output library [input.output]

27.10 Synchronized output streams [syncstream]

27.10.3 Class template basic_­osyncstream [syncstream.osyncstream]

27.10.3.1 Overview [syncstream.osyncstream.overview]

namespace std {
  template<class charT, class traits, class Allocator>
  class basic_osyncstream : public basic_ostream<charT, traits> {
  public:
    using char_type   = charT;
    using int_type    = typename traits::int_type;
    using pos_type    = typename traits::pos_type;
    using off_type    = typename traits::off_type;
    using traits_type = traits;

    using allocator_type = Allocator;
    using streambuf_type = basic_streambuf<charT, traits>;
    using syncbuf_type   = basic_syncbuf<charT, traits, Allocator>;

    // [syncstream.osyncstream.cons], construction and destruction
    basic_osyncstream(streambuf_type*, const Allocator&);
    explicit basic_osyncstream(streambuf_type* obuf)
      : basic_osyncstream(obuf, Allocator()) {}
    basic_osyncstream(basic_ostream<charT, traits>& os, const Allocator& allocator)
      : basic_osyncstream(os.rdbuf(), allocator) {}
    explicit basic_osyncstream(basic_ostream<charT, traits>& os)
      : basic_osyncstream(os, Allocator()) {}
    basic_osyncstream(basic_osyncstream&&) noexcept;
    ~basic_osyncstream();

    // [syncstream.osyncstream.assign], assignment
    basic_osyncstream& operator=(basic_osyncstream&&) noexcept;

    // [syncstream.osyncstream.members], member functions
    void emit();
    streambuf_type* get_wrapped() const noexcept;
    syncbuf_type* rdbuf() const noexcept { return &sb ; }

  private:
    syncbuf_type sb;    // exposition only
  };
}
1
#
Allocator shall satisfy the Cpp17Allocator requirements (Table 33).
2
#
[ Example
:
A named variable can be used within a block statement for streaming.
{
  osyncstream bout(cout);
  bout << "Hello, ";
  bout << "World!";
  bout << endl; // flush is noted
  bout << "and more!\n";
}   // characters are transferred and cout is flushed
— end example
 ]
3
#
[ Example
:
A temporary object can be used for streaming within a single statement.
osyncstream(cout) << "Hello, " << "World!" << '\n';
In this example, cout is not flushed.
— end example
 ]

27.10.3.2 Construction and destruction [syncstream.osyncstream.cons]

🔗
basic_osyncstream(streambuf_type* buf, const Allocator& allocator);
1
#
Effects: Initializes sb from buf and allocator.
Initializes the base class with basic_­ostream(&sb).
2
#
[ Note
:
The member functions of the provided stream buffer might be called from emit() while a lock is held.
Care should be taken to ensure that this does not result in deadlock.
— end note
 ]
3
#
Ensures: get_­wrapped() == buf is true.
🔗
basic_osyncstream(basic_osyncstream&& other) noexcept;
4
#
Effects: Move constructs the base class and sb from the corresponding subobjects of other, and calls basic_­ostream<charT, traits>​::​set_­rdbuf(&sb).
5
#
Ensures: The value returned by get_­wrapped() is the value returned by os.get_­wrapped() prior to calling this constructor.
nullptr == other.get_­wrapped() is true.
🔗
~basic_osyncstream();
6
#
Effects: Calls emit().
If an exception is thrown from emit(), that exception is caught and ignored.

27.10.3.3 Assignment [syncstream.osyncstream.assign]

🔗
basic_osyncstream& operator=(basic_osyncstream&& rhs) noexcept;
1
#
Effects: First, calls emit().
If an exception is thrown from emit(), that exception is caught and ignored.
Move assigns sb from rhs.sb.
[ Note
:
This disassociates rhs from its wrapped stream buffer ensuring destruction of rhs produces no output.
— end note
 ]
2
#
Ensures: nullptr == rhs.get_­wrapped() is true.
get_­wrapped() returns the value previously returned by rhs.get_­wrapped().

27.10.3.4 Member functions [syncstream.osyncstream.members]

🔗
void emit();
1
#
Effects: Calls sb.emit().
If that call returns false, calls setstate(ios​::​badbit).
2
#
[ Example
:
A flush on a basic_­osyncstream does not flush immediately: 
{
  osyncstream bout(cout);
  bout << "Hello," << '\n';     // no flush
  bout.emit();                  // characters transferred; cout not flushed
  bout << "World!" << endl;     // flush noted; cout not flushed
  bout.emit();                  // characters transferred; cout flushed
  bout << "Greetings." << '\n'; // no flush
}   // characters transferred; cout not flushed
— end example
 ]
3
#
[ Example
:
The function emit() can be used to handle exceptions from operations on the underlying stream.
{
  osyncstream bout(cout);
  bout << "Hello, " << "World!" << '\n';
  try {
    bout.emit();
  } catch (...) {
    // handle exception
  }
}
— end example
 ]
🔗
streambuf_type* get_wrapped() const noexcept;
4
#
Returns: sb.get_­wrapped().
5
#
[ Example
:
Obtaining the wrapped stream buffer with get_­wrapped() allows wrapping it again with an osyncstream.
For example, 
{
  osyncstream bout1(cout);
  bout1 << "Hello, ";
  {
    osyncstream(bout1.get_wrapped()) << "Goodbye, " << "Planet!" << '\n';
  }
  bout1 << "World!" << '\n';
}
produces the uninterleaved output
Goodbye, Planet! Hello, World!
— end example
 ]