29 Input/output library [input.output]

29.10 Synchronized output streams [syncstream]

29.10.1 Header <syncstream> synopsis [syncstream.syn]

#include <ostream>  // see [ostream.syn]

namespace std {
  template<class charT, class traits = char_traits<charT>, class Allocator = allocator<charT>>
    class basic_syncbuf;

  using syncbuf = basic_syncbuf<char>;
  using wsyncbuf = basic_syncbuf<wchar_t>;

  template<class charT, class traits = char_traits<charT>, class Allocator = allocator<charT>>
    class basic_osyncstream;

  using osyncstream = basic_osyncstream<char>;
  using wosyncstream = basic_osyncstream<wchar_t>;
}
1
#
The header <syncstream> provides a mechanism to synchronize execution agents writing to the same stream.

29.10.2 Class template basic_­syncbuf [syncstream.syncbuf]

29.10.2.1 Overview [syncstream.syncbuf.overview]

namespace std {
  template<class charT, class traits = char_traits<charT>, class Allocator = allocator<charT>>
  class basic_syncbuf : public basic_streambuf<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>;

    // [syncstream.syncbuf.cons], construction and destruction
    basic_syncbuf()
      : basic_syncbuf(nullptr) {}
    explicit basic_syncbuf(streambuf_type* obuf)
      : basic_syncbuf(obuf, Allocator()) {}
    basic_syncbuf(streambuf_type*, const Allocator&);
    basic_syncbuf(basic_syncbuf&&);
    ~basic_syncbuf();

    // [syncstream.syncbuf.assign], assignment and swap
    basic_syncbuf& operator=(basic_syncbuf&&);
    void swap(basic_syncbuf&);

    // [syncstream.syncbuf.members], member functions
    bool emit();
    streambuf_type* get_wrapped() const noexcept;
    allocator_type get_allocator() const noexcept;
    void set_emit_on_sync(bool) noexcept;

  protected:
    // [syncstream.syncbuf.virtuals], overridden virtual functions
    int sync() override;

  private:
    streambuf_type* wrapped;    // exposition only
    bool emit_on_sync{};        // exposition only
  };

  // [syncstream.syncbuf.special], specialized algorithms
  template<class charT, class traits, class Allocator>
    void swap(basic_syncbuf<charT, traits, Allocator>&,
              basic_syncbuf<charT, traits, Allocator>&);
}
1
#
Class template basic_­syncbuf stores character data written to it, known as the associated output, into internal buffers allocated using the object's allocator.
The associated output is transferred to the wrapped stream buffer object *wrapped when emit() is called or when the basic_­syncbuf object is destroyed.
Such transfers are atomic with respect to transfers by other basic_­syncbuf objects with the same wrapped stream buffer object.

29.10.2.2 Construction and destruction [syncstream.syncbuf.cons]

🔗
basic_syncbuf(streambuf_type* obuf, const Allocator& allocator);
1
#
Effects: Sets wrapped to obuf.
2
#
Remarks: A copy of allocator is used to allocate memory for internal buffers holding the associated output.
3
#
Throws: Nothing unless an exception is thrown by the construction of a mutex or by memory allocation.
4
#
Postconditions: get_­wrapped() == obuf and get_­allocator() == allocator are true.
🔗
basic_syncbuf(basic_syncbuf&& other);
5
#
Postconditions: The value returned by this->get_­wrapped() is the value returned by other.get_­wrapped() prior to calling this constructor.
Output stored in other prior to calling this constructor will be stored in *this afterwards.
other.rdbuf()->pbase() == other.rdbuf()->pptr() and other.get_­wrapped() == nullptr are true.
6
#
Remarks: This constructor disassociates other from its wrapped stream buffer, ensuring destruction of other produces no output.
🔗
~basic_syncbuf();
7
#
Effects: Calls emit().
8
#
Throws: Nothing.
If an exception is thrown from emit(), the destructor catches and ignores that exception.

29.10.2.3 Assignment and swap [syncstream.syncbuf.assign]

🔗
basic_syncbuf& operator=(basic_syncbuf&& rhs) noexcept;
1
#
Effects: Calls emit() then move assigns from rhs.
After the move assignment *this has the observable state it would have had if it had been move constructed from rhs ([syncstream.syncbuf.cons]).
2
#
Returns: *this.
3
#
Postconditions:
  • (3.1)
    rhs.get_­wrapped() == nullptr is true.
  • (3.2)
    this->get_­allocator() == rhs.get_­allocator() is true when 
    allocator_traits<Allocator>::propagate_on_container_move_assignment::value
    is true; otherwise, the allocator is unchanged.
4
#
Remarks: This assignment operator disassociates rhs from its wrapped stream buffer, ensuring destruction of rhs produces no output.
🔗
void swap(basic_syncbuf& other) noexcept;
5
#
Preconditions: Either allocator_­traits<Allocator>​::​propagate_­on_­container_­swap​::​value is true or this->get_­allocator() == other.get_­allocator() is true.
6
#
Effects: Exchanges the state of *this and other.

29.10.2.4 Member functions [syncstream.syncbuf.members]

🔗
bool emit();
1
#
Effects: Atomically transfers the associated output of *this to the stream buffer *wrapped, so that it appears in the output stream as a contiguous sequence of characters.
wrapped->pubsync() is called if and only if a call was made to sync() since the most recent call to emit(), if any.
2
#
Returns: true if all of the following conditions hold; otherwise false:
  • (2.1)
    wrapped == nullptr is false.
  • (2.2)
    All of the characters in the associated output were successfully transferred.
  • (2.3)
    The call to wrapped->pubsync() (if any) succeeded.
3
#
Postconditions: On success, the associated output is empty.
4
#
Synchronization: All emit() calls transferring characters to the same stream buffer object appear to execute in a total order consistent with the “happens before” relation ([intro.races]), where each emit() call synchronizes with subsequent emit() calls in that total order.
5
#
Remarks: May call member functions of wrapped while holding a lock uniquely associated with wrapped.
🔗
streambuf_type* get_wrapped() const noexcept;
6
#
Returns: wrapped.
🔗
allocator_type get_allocator() const noexcept;
7
#
Returns: A copy of the allocator that was set in the constructor or assignment operator.
🔗
void set_emit_on_sync(bool b) noexcept;
8
#
Effects: emit_­on_­sync = b.

29.10.2.5 Overridden virtual functions [syncstream.syncbuf.virtuals]

🔗
int sync() override;
1
#
Effects: Records that the wrapped stream buffer is to be flushed.
Then, if emit_­on_­sync is true, calls emit().
[Note
:
If emit_­on_­sync is false, the actual flush is delayed until a call to emit().
— end note
]
2
#
Returns: If emit() was called and returned false, returns -1; otherwise 0.

29.10.2.6 Specialized algorithms [syncstream.syncbuf.special]

🔗
template<class charT, class traits, class Allocator> void swap(basic_syncbuf<charT, traits, Allocator>& a, basic_syncbuf<charT, traits, Allocator>& b) noexcept;
1
#
Effects: Equivalent to a.swap(b).

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
]