bslstl_syncbuf

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Usage
    • Example 1: Usage with existing ostream

Purpose

Provide a C++20-compatible basic_syncbuf class template.

Classes

• bsl::basic_syncbuf: C++20-compatible basic_syncbuf class template.
• bsl::syncbuf: C++20-compatible syncbuf class.
• bsl::wsyncbuf: C++20-compatible wsyncbuf class.

Canonical header: bsl_syncstream.h

See also

bslstl_osyncstream

Description

This component is for internal use only. Please include <bsl_syncstream.h> instead.

This component defines a class template, bsl::basic_syncbuf, that is a wrapper for a bsl::basic_streambuf (provided at construction time as a pointer). It accumulates output in its own internal buffer, and atomically transmits its entire contents to the wrapped buffer on destruction and when explicitly requested, so that they appear as a contiguous sequence of characters. It guarantees that there are no data races and no interleaving of characters sent to the wrapped buffer as long as all other outputs made to the same buffer are made through, possibly different, instances of bsl::basic_syncbuf.

Each bsl::basic_syncbuf has the associated "emit-on-sync" boolean flag that is false after the object construction and its value can be changed using the set_emit_on_sync member function call. If this flag has value true, the emit function is called by each sync call.

Types bsl::syncbuf and bsl::wsyncbuf are aliases for bsl::basic_syncbuf<char> and bsl::basic_syncbuf<wchar_t>, respectively.

Usage

This section illustrates possible use of this component. But note that this component is not intended for direct usage - usually osyncstream should be used instead.

Example 1: Usage with existing ostream

The following example demonstrates temporary replacement of the underlying streambuf within the existing ostream object.

/// Write atomically to the specified `os` output stream.
void writeSync(bsl::ostream& os)
{
    // Temporarily replace the underlying `streambuf`
    bsl::syncbuf buf(os.rdbuf());
    os.rdbuf(&buf);
 
    // Write to the `syncbuf`
    os << "Hello, ";
    os << "World!\n";
 
    // Restore the underlying `streambuf`
    os.rdbuf(buf.get_wrapped());
 
    // The accumulated output will be atomically flushed/emitted here
}

Now call the function:

writeSync(bsl::cout);