cppdraft_translate/cppdraft/syncstream/syncbuf.md

[syncstream.syncbuf]

# 31 Input/output library [[input.output]](./#input.output)

## 31.11 Synchronized output streams [[syncstream]](syncstream#syncbuf)

### 31.11.2 Class template basic_syncbuf [syncstream.syncbuf]

#### [31.11.2.1](#overview) Overview [[syncstream.syncbuf.overview]](syncstream.syncbuf.overview)

[🔗](#lib:basic_syncbuf)

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]](#cons "31.11.2.2 Construction and destruction"), 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]](#assign "31.11.2.3 Assignment and swap"), assignment and swap basic_syncbuf& operator=(basic_syncbuf&&); void swap(basic_syncbuf&); // [[syncstream.syncbuf.members]](#members "31.11.2.4 Member functions"), member functionsbool emit();
 streambuf_type* get_wrapped() const noexcept;
 allocator_type get_allocator() const noexcept; void set_emit_on_sync(bool) noexcept; protected:// [[syncstream.syncbuf.virtuals]](#virtuals "31.11.2.5 Overridden virtual functions"), overridden virtual functionsint sync() override; private: streambuf_type* *wrapped*; // *exposition only*bool *emit-on-sync*{}; // *exposition only*};}

[1](#overview-1)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L12649)

Class template basic_syncbuf stores character data
written to it, known as the associated output, into internal
buffers allocated using the object's allocator[.](#overview-1.sentence-1)

The associated output is transferred to the
wrapped stream buffer object **wrapped* when emit() is called
or when the basic_syncbuf object is destroyed[.](#overview-1.sentence-2)

Such transfers are atomic with respect to transfers
by other basic_syncbuf objects
with the same wrapped stream buffer object[.](#overview-1.sentence-3)

#### [31.11.2.2](#cons) Construction and destruction [[syncstream.syncbuf.cons]](syncstream.syncbuf.cons)

[🔗](#lib:basic_syncbuf,constructor)

`basic_syncbuf(streambuf_type* obuf, const Allocator& allocator);
`

[1](#cons-1)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L12669)

*Effects*: Sets *wrapped* to obuf[.](#cons-1.sentence-1)

[2](#cons-2)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L12673)

*Postconditions*: get_wrapped() == obuf andget_allocator() == allocator are true[.](#cons-2.sentence-1)

[3](#cons-3)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L12678)

*Throws*: Nothing unless an exception is thrown
by the construction of a mutex or
by memory allocation[.](#cons-3.sentence-1)

[4](#cons-4)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L12684)

*Remarks*: A copy of allocator is used
to allocate memory for internal buffers
holding the associated output[.](#cons-4.sentence-1)

[🔗](#lib:basic_syncbuf,constructor_)

`basic_syncbuf(basic_syncbuf&& other);
`

[5](#cons-5)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L12697)

*Postconditions*: The value returned by this->get_wrapped() is the value returned by other.get_wrapped() prior to calling this constructor[.](#cons-5.sentence-1)

Output stored in other prior to calling this constructor
will be stored in *this afterwards[.](#cons-5.sentence-2)

other.pbase() == other.pptr() andother.get_wrapped() == nullptr are true[.](#cons-5.sentence-3)

[6](#cons-6)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L12710)

*Remarks*: This constructor disassociates other from its wrapped stream buffer,
ensuring destruction of other produces no output[.](#cons-6.sentence-1)

[🔗](#lib:basic_syncbuf,destructor)

`~basic_syncbuf();
`

[7](#cons-7)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L12723)

*Effects*: Calls emit()[.](#cons-7.sentence-1)

[8](#cons-8)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L12727)

*Throws*: Nothing[.](#cons-8.sentence-1)

If an exception is thrown from emit(),
the destructor catches and ignores that exception[.](#cons-8.sentence-2)

#### [31.11.2.3](#assign) Assignment and swap [[syncstream.syncbuf.assign]](syncstream.syncbuf.assign)

[🔗](#lib:operator=,basic_syncbuf)

`basic_syncbuf& operator=(basic_syncbuf&& rhs);
`

[1](#assign-1)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L12742)

*Effects*: Calls emit() then
move assigns from rhs[.](#assign-1.sentence-1)

After the move assignment *this has the observable state it would have had if
it had been move constructed from rhs ([[syncstream.syncbuf.cons]](#cons "31.11.2.2 Construction and destruction"))[.](#assign-1.sentence-2)

[2](#assign-2)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L12750)

*Postconditions*: 

- [(2.1)](#assign-2.1)

rhs.get_wrapped() == nullptr is true.

- [(2.2)](#assign-2.2)

this->get_allocator() == rhs.get_allocator() is true whenallocator_traits<Allocator>::propagate_on_container_move_assignment::value is true; otherwise, the allocator is unchanged.

[3](#assign-3)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L12763)

*Returns*: *this[.](#assign-3.sentence-1)

[4](#assign-4)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L12767)

*Remarks*: This assignment operator disassociates rhs from its wrapped stream buffer,
ensuring destruction of rhs produces no output[.](#assign-4.sentence-1)

[🔗](#lib:swap,basic_syncbuf)

`void swap(basic_syncbuf& other);
`

[5](#assign-5)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L12780)

*Preconditions*: Eitherallocator_traits<Allocator>​::​propagate_on_container_swap​::​value is true orthis->get_allocator() == other.get_allocator() is true[.](#assign-5.sentence-1)

[6](#assign-6)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L12789)

*Effects*: Exchanges the state of *this and other[.](#assign-6.sentence-1)

#### [31.11.2.4](#members) Member functions [[syncstream.syncbuf.members]](syncstream.syncbuf.members)

[🔗](#lib:emit,basic_syncbuf)

`bool emit();
`

[1](#members-1)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L12802)

*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[.](#members-1.sentence-1)

*wrapped*->pubsync() is called
if and only if a call was made to sync() since the most recent call to emit(), if any[.](#members-1.sentence-2)

[2](#members-2)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L12812)

*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]](intro.races "6.10.2.2 Data races")),
where each emit() call
synchronizes with
subsequent emit() calls in that total order[.](#members-2.sentence-1)

[3](#members-3)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L12822)

*Postconditions*: On success, the associated output is empty[.](#members-3.sentence-1)

[4](#members-4)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L12826)

*Returns*: true if all of the following conditions hold;
otherwise false:

- [(4.1)](#members-4.1)

  *wrapped* == nullptr is false[.](#members-4.1.sentence-1)

- [(4.2)](#members-4.2)

  All of the characters in the associated output were successfully transferred[.](#members-4.2.sentence-1)

- [(4.3)](#members-4.3)

  The call to *wrapped*->pubsync() (if any) succeeded[.](#members-4.3.sentence-1)

[5](#members-5)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L12836)

*Remarks*: May call member functions of *wrapped* while holding a lock uniquely associated with *wrapped*[.](#members-5.sentence-1)

[🔗](#lib:get_wrapped,basic_syncbuf)

`streambuf_type* get_wrapped() const noexcept;
`

[6](#members-6)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L12848)

*Returns*: *wrapped*[.](#members-6.sentence-1)

[🔗](#lib:get_allocator,basic_syncbuf)

`allocator_type get_allocator() const noexcept;
`

[7](#members-7)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L12859)

*Returns*: A copy of the allocator that was set in the constructor or assignment operator[.](#members-7.sentence-1)

[🔗](#lib:set_emit_on_sync,basic_syncbuf)

`void set_emit_on_sync(bool b) noexcept;
`

[8](#members-8)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L12870)

*Effects*: *emit-on-sync* = b[.](#members-8.sentence-1)

#### [31.11.2.5](#virtuals) Overridden virtual functions [[syncstream.syncbuf.virtuals]](syncstream.syncbuf.virtuals)

[🔗](#lib:sync,basic_syncbuf)

`int sync() override;
`

[1](#virtuals-1)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L12883)

*Effects*: Records that the wrapped stream buffer is to be flushed[.](#virtuals-1.sentence-1)

Then, if *emit-on-sync* is true, calls emit()[.](#virtuals-1.sentence-2)

[*Note [1](#virtuals-note-1)*:

If *emit-on-sync* is false,
the actual flush is delayed until a call to emit()[.](#virtuals-1.sentence-3)

— *end note*]

[2](#virtuals-2)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L12892)

*Returns*: If emit() was called and returned false,
returns -1; otherwise 0[.](#virtuals-2.sentence-1)

#### [31.11.2.6](#special) Specialized algorithms [[syncstream.syncbuf.special]](syncstream.syncbuf.special)

[🔗](#lib:swap,basic_syncbuf_)

`template<class charT, class traits, class Allocator>
  void swap(basic_syncbuf<charT, traits, Allocator>& a,
            basic_syncbuf<charT, traits, Allocator>& b);
`

[1](#special-1)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L12908)

*Effects*: Equivalent to a.swap(b)[.](#special-1.sentence-1)