en	Layered Streams

en	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:

en	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:

en	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:

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

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

en	Layered Stream Algorithms and Types

en	Name

en	Description

en	[link beast.ref.boost__beast__basic_stream `basic_stream`] [link beast.ref.boost__beast__tcp_stream `tcp_stream`]

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

en	[link beast.ref.boost__beast__buffered_read_stream `buffered_read_stream`]

en	A buffered read stream meets the requirements for synchronous and asynchronous read and write streams, and additionally implements configurable buffering for reads.

en	[link beast.ref.boost__beast__close_socket `close_socket`]

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

en	[link beast.ref.boost__beast__get_lowest_layer `get_lowest_layer`]

en	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]

en	[link beast.ref.boost__beast__http__icy_stream `http::icy_stream`]

en	An ICY stream transparently converts the non-standard "ICY 200 OK" HTTP response from Shoutcast servers into a conforming 200 level HTTP response.

en	[link beast.ref.boost__beast__lowest_layer_type `lowest_layer_type`]

en	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`]

en	Counted Stream __example__

en	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: