29 Input/output library [input.output]

29.10 Synchronized output streams [syncstream]

29.10.3 Class template basic_­osyncstream [syncstream.osyncstream]

29.10.3.1 Overview [syncstream.osyncstream.overview]

namespace std {
  template<class charT, class traits = char_traits<charT>, class Allocator = allocator<charT>>
  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();

    // 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 const_cast<syncbuf_type*>(addressof(sb)); }

  private:
    syncbuf_type sb;    // exposition only
  };
}
1
#
Allocator shall meet the Cpp17Allocator requirements (Table 36).
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
]

29.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<charT, traits>(addressof(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
#
Postconditions: 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(addressof(sb)).
5
#
Postconditions: 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.

29.10.3.3 Member functions [syncstream.osyncstream.members]

🔗
void emit();
1
#
Effects: Calls sb.emit().
If that call returns false, calls setstate(ios_­base​::​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
]