# User's Guide

## 3.6 Asynchronous and Non-Blocking I/O

Overview
Devices
Filters
Streams and Stream Buffers

## Overview

The Filter and Device concepts provided by Boost.Iostreams have been designed to allow a future version of Boost.Iostreams to support asynchronous and non-blocking i/o. This has been accomplished by providing the functions `get`, `read`, `put` and `write` with a way to indicate that fewer characters than requested have been produced or consumed, despite the fact that the end of stream has not been reached and no error has occurred. We'll call such an indication a temporary failure notification. The main challenge was presented by the function `get`: to allow `get` to indicate that input is temporarily unavailable, it was necessary to introduce the class template `boost::iostreams::char_traits`, a replacement for `std::char_traits` having an additional member function `would_block`.

For full details, see the definitions of the Filter and Device concepts.

## Devices

The current Device concepts can handle non-blocking i/o but not asynchronous i/o; additional Device concepts will be required for full support of asynchronous i/o. This is to be expected, since synchronous and asynychronous Devices operate very differently. See Blocking.

## Filters

Filters are allowed to propagate temporary failure notifications: if a downstream Device consumes or produces fewer characters than requested by a Filter, and if as a result the Filter is not able to satisfy a read or write request, the Filter may return a value indicating that input or output is temporarily unavailable. It is hoped that this ability will suffice to allow the current Filter concepts to be used with both aynchronous and non-blocking i/o. However, in order to be useful with blocking i/o as well, a Filter must never return a temporary failure notification unless it has received a such notification from a downstream Device. This requirement is summarized by stating that Filters must be blocking-preserving. See Blocking.

## Streams and Stream Buffers

Although the Boost.Iostreams Filter and Device concepts can accommodate non-blocking i/o, the C++ standard library stream and stream buffer interfaces cannot, since they lack a means to distinguish between temporary and permanent failures to satisfy a read or write request. As a result, non-blocking Devices do not work properly with the templates `stream`, `stream_buffer`, `filtering_stream` and `filtering_streambuf`.

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)