[syncstream.syncbuf] (original) (raw)

31 Input/output library [input.output]

31.11 Synchronized output streams [syncstream]

31.11.2 Class template basic_syncbuf [syncstream.syncbuf]

31.11.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>; 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(); basic_syncbuf& operator=(basic_syncbuf&&);void swap(basic_syncbuf&);bool emit(); streambuf_type* get_wrapped() const noexcept; allocator_type get_allocator() const noexcept;void set_emit_on_sync(bool) noexcept;protected: int sync() override;private: streambuf_type* wrapped; bool emit-on-sync{}; };}

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.

31.11.2.2 Construction and destruction [syncstream.syncbuf.cons]

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

Effects: Sets wrapped to obuf.

Postconditions: get_wrapped() == obuf andget_allocator() == allocator are true.

Throws: Nothing unless an exception is thrown by the construction of a mutex or by memory allocation.

Remarks: A copy of allocator is used to allocate memory for internal buffers holding the associated output.

basic_syncbuf(basic_syncbuf&& other);

Postconditions: The value returned by this->get_wrapped()is the value returned by other.get_wrapped()prior to calling this constructor.

Output stored in otherprior to calling this constructor will be stored in *this afterwards.

other.pbase() == other.pptr()andother.get_wrapped() == nullptrare true.

Remarks: This constructor disassociates otherfrom its wrapped stream buffer, ensuring destruction of other produces no output.

Throws: Nothing.

If an exception is thrown from emit(), the destructor catches and ignores that exception.

31.11.2.3 Assignment and swap [syncstream.syncbuf.assign]

basic_syncbuf& operator=(basic_syncbuf&& rhs);

Effects: Calls emit() then move assigns from rhs.

After the move assignment *thishas the observable state it would have had if it had been move constructed from rhs ([syncstream.syncbuf.cons]).

Postconditions:

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

Remarks: This assignment operator disassociates rhsfrom its wrapped stream buffer, ensuring destruction of rhs produces no output.

void swap(basic_syncbuf& other);

Preconditions: Eitherallocator_traits<Allocator>​::​propagate_on_container_swap​::​valueis trueorthis->get_allocator() == other.get_allocator()is true.

Effects: Exchanges the state of *this and other.

31.11.2.4 Member functions [syncstream.syncbuf.members]

Effects: Atomically transfers the associated output of *thisto 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.

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.

Postconditions: On success, the associated output is empty.

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

• wrapped == nullptr is false.
• All of the characters in the associated output were successfully transferred.
• The call to _wrapped_->pubsync() (if any) succeeded.

Remarks: May call member functions of _wrapped_while holding a lock uniquely associated with wrapped.

streambuf_type* get_wrapped() const noexcept;

allocator_type get_allocator() const noexcept;

Returns: A copy of the allocator that was set in the constructor or assignment operator.

void set_emit_on_sync(bool b) noexcept;

Effects: emit-on-sync = b.

31.11.2.5 Overridden virtual functions [syncstream.syncbuf.virtuals]

Effects: Records that the wrapped stream buffer is to be flushed.

Then, if emit-on-sync is true, calls emit().

[Note 1:

If emit-on-sync is false, the actual flush is delayed until a call to emit().

— _end note_]

Returns: If emit() was called and returned false, returns -1; otherwise 0.

31.11.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);

Effects: Equivalent to a.swap(b).