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 occurred.[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>::typesemantics
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);

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

category_of<T>::typesemantics
convertible to flushable_tag returns t.flush(snk)
otherwise returns false

[1]It was noticed late in developement that to be consistent with the policy of reporting errors using exceptions (see Exceptions), flush should have been specified to return void when invoked on a Device. Until the specification is changed, Devices should always return true when flushed.