Stream Types

A Stream is a communication channel where data is transferred as an ordered sequence of octet buffers. Streams are either synchronous or asynchronous, and may allow reading, writing, or both. Note that a particular type may model more than one concept. For example, the Asio types boost::asio::ip::tcp::socket and boost::asio::ssl::stream support both SyncStream and AsyncStream. All stream algorithms in Beast are declared as template functions using these concepts:

Table 1.2. Stream Concepts

Concept	Description
SyncReadStream	Supports buffer-oriented blocking reads.
SyncWriteStream	Supports buffer-oriented blocking writes.
SyncStream	A stream supporting buffer-oriented blocking reads and writes.
AsyncReadStream	Supports buffer-oriented asynchronous reads.
AsyncWriteStream	Supports buffer-oriented asynchronous writes.
AsyncStream	A stream supporting buffer-oriented asynchronous reads and writes.

These template metafunctions check whether a given type meets the requirements for the various stream concepts, and some additional useful utilities. The library uses these type checks internally and also provides them as public interfaces so users may use the same techniques to augment their own code. The use of these type checks helps provide more concise errors during compilation:

Table 1.3. Stream Type Checks

Name	Description
`get_lowest_layer`	Returns `T::lowest_layer_type` if it exists, else returns `T`.
`has_get_executor`	Determine if the `get_executor` member function is present.
`is_async_read_stream`	Determine if a type meets the requirements of AsyncReadStream.
`is_async_stream`	Determine if a type meets the requirements of both AsyncReadStream and AsyncWriteStream.
`is_async_write_stream`	Determine if a type meets the requirements of AsyncWriteStream.
`is_completion_handler`	Determine if a type meets the requirements of CompletionHandler, and is callable with a specified signature.
`is_sync_read_stream`	Determine if a type meets the requirements of SyncReadStream.
`is_sync_stream`	Determine if a type meets the requirements of both SyncReadStream and SyncWriteStream.
`is_sync_write_stream`	Determine if a type meets the requirements of SyncWriteStream.

Using the type checks with static_assert on function or class template types will provide users with helpful error messages and prevent undefined behaviors. This example shows how a template function which writes to a synchronous stream may check its argument:

template<class SyncWriteStream>
void write_string(SyncWriteStream& stream, string_view s)
{
    static_assert(is_sync_write_stream<SyncWriteStream>::value,
        "SyncWriteStream requirements not met");
    boost::asio::write(stream, boost::asio::const_buffer(s.data(), s.size()));
}

Boost C++ Libraries

Stream Types