fdf64a4550
* dynamic_buffer_ref is removed, because Asio / Networking has introduced the DynamicBuffer_v2 concept which is incompatible with Beast's storage types. The next version of Beast (1.70) will provide changes to interoperate with Asio / Networking's new concepts.
105 lines
4.5 KiB
Plaintext
105 lines
4.5 KiB
Plaintext
[/
|
|
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 Writing Composed Operations]
|
|
|
|
Asynchronous operations are started by calling a free function or member
|
|
function known as an asynchronous ['__async_initfn__]. This function accepts
|
|
parameters specific to the operation as well as a __CompletionToken__. The
|
|
token is either a completion handler, or a type defining how the caller is
|
|
informed of the asynchronous operation result. Networking provides the
|
|
special tokens __use_future__ and __yield_context__ for using futures
|
|
and coroutines respectively. This system of customizing the return value
|
|
and method of completion notification is known as the
|
|
['Universal Asynchronous Model] described in __N3747__, and a built in
|
|
to __NetTS__. Here is an example of an initiating function which reads a
|
|
line from the stream and echoes it back. This function is developed
|
|
further in the next section:
|
|
|
|
[example_core_echo_op_1]
|
|
|
|
[tip
|
|
This initiating function receives the dynamic buffer by lvalue-reference,
|
|
instead of by rvalue-reference as specified in networking. An explanation
|
|
for this difference may be found in
|
|
[@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p1100r0.html [P1100R0] Efficient composition with DynamicBuffer].
|
|
]
|
|
Authors using Beast can reuse the library's primitives to create their
|
|
own initiating functions for performing a series of other, intermediate
|
|
asynchronous operations before invoking a final completion handler.
|
|
The set of intermediate actions produced by an initiating function is
|
|
known as a
|
|
[@http://blog.think-async.com/2009/08/composed-operations-coroutines-and-code.html ['composed operation]].
|
|
To ensure full interoperability and well-defined behavior, __Asio__ imposes
|
|
requirements on the implementation of composed operations. These classes
|
|
and functions make it easier to develop initiating functions and their
|
|
composed operations:
|
|
|
|
[table Asynchronous Helpers
|
|
[[Name][Description]]
|
|
[[
|
|
[link beast.ref.boost__beast__async_base `async_op_base`]
|
|
[link beast.ref.boost__beast__stable_async_base `stable_async_base`]
|
|
][
|
|
This class is designed to be used as a base class when authoring
|
|
composed asynchronous operations expressed as an intermediate
|
|
completion handler. This eliminates the need for the extensive
|
|
boilerplate to propagate the associated executor, associated
|
|
allocator, and legacy completion handler hooks.
|
|
]]
|
|
[[
|
|
[link beast.ref.boost__beast__allocate_stable `allocate_stable`]
|
|
][
|
|
For composed operation algorithms which need stable storage for
|
|
temporary objects, this function may be used. Memory for the
|
|
stable storage is allocated using the allocator associated with
|
|
the final completion handler. The implementation automatically
|
|
destroys the temporary object before the final completion handler
|
|
is invoked, or when the intermediate completion handler is
|
|
destroyed.
|
|
]]
|
|
[[
|
|
[link beast.ref.boost__beast__bind_handler `bind_handler`]
|
|
][
|
|
This function creates a new handler which, when invoked, calls
|
|
the original handler with the list of bound arguments. Any
|
|
parameters passed in the invocation will be substituted for
|
|
placeholders present in the list of bound arguments. Parameters
|
|
which are not matched to placeholders are silently discarded.
|
|
|
|
The passed handler and arguments are forwarded into the returned
|
|
handler, whose associated allocator and associated executor will
|
|
be the same as those of the original handler.
|
|
]]
|
|
[[
|
|
[link beast.ref.boost__beast__bind_front_handler `bind_front_handler`]
|
|
][
|
|
This function creates a new handler which, when invoked, calls
|
|
the original handler with the list of bound arguments, along with
|
|
the list of invoked arguments at either the front or the back of
|
|
the argument list. Placeholders are not supported.
|
|
|
|
The passed handler and arguments are forwarded into the returned
|
|
handler, whose associated allocator and associated executor will
|
|
will be the same as those of the original handler.
|
|
]]
|
|
[[
|
|
[link beast.ref.boost__beast__saved_handler `saved_handler`]
|
|
][
|
|
This wrapper safely stores a completion handler so it may be invoked
|
|
later, allowing an implementation to "pause" an operation until some
|
|
condition is met.
|
|
]]
|
|
]
|
|
|
|
[include 7a_echo.qbk]
|
|
[include 7b_detect_ssl.qbk]
|
|
|
|
[endsect]
|