[/
    Copyright (c) 2016-2019 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)

    Official repository: https://github.com/boostorg/beast
]

[section:layered_streams Layered Streams]

Networking's __ssl_stream__ is a class template meeting the requirements
of both synchronous and asynchronous read and write streams, implemented
in terms of a "next layer" object whose type is determined by a class
template parameter. The SSL stream constructs an instance of the next
layer object internally, while allowing external access through the
observer `net::ssl::stream::next_layer()`. This declares an SSL stream
which uses a regular TCP/IP socket as the next layer:

[code_core_4_layers_1]

Objects using this design pattern are referred to in networking as "a
stack of stream layers". In Beast we use the term ['layered stream],
although the property of having a next layer is not exclusive to streams.
As with the SSL stream, __websocket_stream__ is a class template
parameterized on a next layer object. This declares a websocket
stream which uses a regular TCP/IP socket as the next layer:

[code_core_4_layers_2]

If a Secure WebSockets stream is desired, this is accomplished simply
by changing the type of the next layer and adjusting the constructor
arguments to match:

[code_core_4_layers_3]

Higher level abstractions can be developed in this fashion by nesting
stream layers to arbitrary degree. The stack of stream layers effectively
forms a compile-time singly linked list. The object at the end of
this list is called the ['lowest layer], and is special from the
others because it typically represents the underlying socket.

Beast comes with several layered stream wrappers, as well as
facilities for authoring and working with layered streams:

[table Layered Stream Algorithms and Types
[[Name][Description]]
[[
    [link beast.ref.boost__beast__basic_stream `basic_stream`]
    [link beast.ref.boost__beast__tcp_stream `tcp_stream`]
][
    This stream can be used for synchronous and asynchronous reading
    and writing. It allows timeouts to be set on logical operations,
    and can have an executor associated with the stream which is
    used to invoke completion handlers. This lets you set a strand
    on the stream once, which is then used for all asynchronous
    operations automatically.
]]
[[
    [link beast.ref.boost__beast__buffered_read_stream `buffered_read_stream`]
][
    A buffered read stream meets the requirements for synchronous and
    asynchronous read and write streams, and additionally implements
    configurable buffering for reads.
]]
[[
    [link beast.ref.boost__beast__close_socket `close_socket`]
][
    This function closes a socket by performing an unqualified call
    to the
    [link beast.ref.boost__beast__beast_close_socket `beast_close_socket`]
    customization point, allowing sockets to be closed in generic
    contexts in an extensible fashion.
]]
[[
    [link beast.ref.boost__beast__flat_stream `flat_stream`]
][
    A flat stream operates as a transparent stream which helps to work around
    a limitation of `net::ssl::stream`. It is used in the implementation
    of [link beast.ref.boost__beast__ssl_stream `ssl_stream`].
]]
[[
    [link beast.ref.boost__beast__get_lowest_layer `get_lowest_layer`]
][
    Returns the lowest layer in a stack of stream layers by recursively
    calling the `next_layer` member function on each object until reaching
    an object which lacks the member. This example
    puts a layered stream into non-blocking mode by retrieving the
    TCP/IP socket in the lowest layer and changing the socket option:

    [code_core_4_layers_4]
]]
[[
    [link beast.ref.boost__beast__http__icy_stream `http::icy_stream`]
][
    An ICY stream transparently converts the non-standard "ICY 200 OK"
    HTTP response from Shoutcast servers into a conforming 200 level
    HTTP response.
]]
[[
    [link beast.ref.boost__beast__lowest_layer_type `lowest_layer_type`]
][
    A metafunction to return the type of the lowest layer used in
    a type representing a stack of stream layers. This is the type
    of reference returned by
    [link beast.ref.boost__beast__get_lowest_layer `get_lowest_layer`]
]]
[[
    [link beast.ref.boost__beast__ssl_stream `ssl_stream`]
][
    The SSL stream is a drop-in replacement for `net::ssl::stream` which
    allows for move-construction and move-assignment, and also implements
    a work-around for a performance limitation in the original SSL stream.
]]
]

[/-----------------------------------------------------------------------------]

[section Counted Stream __example__]

This example shows the definition of a layered stream which keeps individual
counts of the total number of bytes read from and written to the next layer.
It meets the requirements for synchronous and asynchronous read and write
streams:

[code_core_4_layers_5]

[endsect]

[/-----------------------------------------------------------------------------]

[endsect]