Function Template `flush`

Overview
Headers
Reference

Overview

The function template flush attemps to flush all buffered characters downstream. It is provided to facilite modifiying a filter chain in the middle of a sequence of output operations; specifically, it is used to implement the function strict_sync (see, e.g., filtering_stream::strict_sync). If strict_sync succeeds, the auto-close feature of a filter chain can be safely disabled using set_auto_close(false) (see, e.g., filtering_stream::set_auto_close). Filters can then be added to or removed from the chain with the knowledge that no characters remain buffered.

For non-Flushable devices, flush returns true, indicating that no error has occured.^[1] For non-Flushable filters, however, flush returns false, indicating that some characters may remain buffered.

When working with Devices, flush may be used as a generic version of std::basic_ostream::flush().

Headers

<boost/iostreams/flush.hpp>
<boost/iostreams/operations.hpp>

Reference

Description

Attempts to flush all buffered characters downstream. For Devices, returns true unless an error occurs.^[1]. For Filters, returns true only if all buffered characters were successfully written to snk.

Synopsis

namespace boost { namespace iostreams {
              
template<typename T>
bool flush(T& t);

template<typename T, typename Sink>
bool flush(T& t, Sink& snk);

} } // End namespace boost::io

Template Parameters

T	-	For the first overload, a model of Device; for the second overload, a model of Filter.
Sink	-	A model of Sink with the same character type as `T`.

Semantics — Device Types

template<typename T>
bool flush(T& t);

The semantics of flush depends on the category of T as follows:

`category_of<T>::type`	semantics
convertible to `ostream_tag`	Invokes `t.rdbuf()->pubsync()` and returns `true` if the operation succeeds.
convertible to `streambuf_tag` but not to `istream_tag`	Invokes `t.pubsync()` and returns `true` if the operation succeeds.
not convertible to `flushable_tag`	returns `t.flush()`
otherwise	returns `true`

Semantics — Filter Types

template<typename T, typename Sink>
bool flush(T& t, Sink& snk);