forked from boostorg/beast
132 lines
3.9 KiB
Plaintext
132 lines
3.9 KiB
Plaintext
[/
|
|
Copyright (c) 2013-2017 Vinnie Falco (vinnie dot falco at gmail dot com)
|
|
|
|
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)
|
|
]
|
|
|
|
[section:streams Using Streams]
|
|
|
|
A __Stream__ is a communication channel where data expressed as octet
|
|
buffers is transferred sequentially. 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
|
|
[@http://www.boost.org/doc/html/boost_asio/reference/ip__tcp/socket.html `boost::asio::ip::tcp::socket`]
|
|
and
|
|
[@http://www.boost.org/doc/html/boost_asio/reference/ssl__stream.html `boost::asio::ssl::stream`]
|
|
support everything. All stream algorithms in Beast are declared as
|
|
template functions with specific concept requirements chosen from
|
|
this list:
|
|
|
|
[table 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 Stream Type Checks
|
|
[[Name][Description]]
|
|
[[
|
|
[link beast.ref.get_lowest_layer `get_lowest_layer`]
|
|
][
|
|
Returns `T::lowest_layer_type` if it exists, else returns `T`.
|
|
]]
|
|
[[
|
|
[link beast.ref.has_get_io_service `has_get_io_service`]
|
|
][
|
|
Determine if the `get_io_service` member function is present,
|
|
and returns an __io_service__.
|
|
]]
|
|
[[
|
|
[link beast.ref.is_async_read_stream `is_async_read_stream`]
|
|
][
|
|
Determine if a type meets the requirements of __AsyncReadStream__.
|
|
]]
|
|
[[
|
|
[link beast.ref.is_async_stream `is_async_stream`]
|
|
][
|
|
Determine if a type meets the requirements of both __AsyncReadStream__
|
|
and __AsyncWriteStream__.
|
|
]]
|
|
[[
|
|
[link beast.ref.is_async_write_stream `is_async_write_stream`]
|
|
][
|
|
Determine if a type meets the requirements of __AsyncWriteStream__.
|
|
]]
|
|
[[
|
|
[link beast.ref.is_completion_handler `is_completion_handler`]
|
|
][
|
|
Determine if a type meets the requirements of __CompletionHandler__,
|
|
and is callable with a specified signature.
|
|
]]
|
|
[[
|
|
[link beast.ref.is_sync_read_stream `is_sync_read_stream`]
|
|
][
|
|
Determine if a type meets the requirements of __SyncReadStream__.
|
|
]]
|
|
[[
|
|
[link beast.ref.is_sync_stream `is_sync_stream`]
|
|
][
|
|
Determine if a type meets the requirements of both __SyncReadStream__
|
|
and __SyncWriteStream__.
|
|
]]
|
|
[[
|
|
[link beast.ref.is_sync_write_stream `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_buffers_1(s.data(), s.size()));
|
|
}
|
|
```
|
|
|
|
[endsect]
|