# Flushable

## Description

A Flushable Sink or OutputFilter provides a means for the user to request that all buffered characters be sent downstream.

## Refinement of

## Associated Types

Same as Filter or Device, with the following additional requirement:

Category | A type convertible to `flushable_tag`

## Notation

`F` | - | A type which is a model of Flushable
`D` | - | A type which is a model of Sink, with the same character type as `F`
`f` | - | Object of type `F`
`d` | - | Object of type `D`

## Valid Expressions / Semantics

Expression | Expression Type | Precondition | Semantics
--- | --- | --- | ---
    boost::iostreams::flush(f)
| `bool` | Category convertible to `device_tag` | Attempts to send all buffered characters downstream, returning `true` unless an error occurs.[1]
    boost::iostreams::flush(f, d)
| `bool` | Category convertible to `filter_tag` | Attempts to write all buffered characters to d, returning `true` if all buffered characters were written.

## Exceptions

Errors which occur during the execution of `flush` are be indicated by throwing exceptions. Such exceptions are caught and ignored if they occur during the execution of stream or stream buffer destructor.

## Models

Several of the Filters and Devices provided by the Iostreams library are Flushable, but this is an implementation detail.

[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.

Revised 02 Feb 2008

© Copyright 2008 CodeRage, LLC
© Copyright 2004-2007 Jonathan Turkanis

Distributed under the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)