123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104 |
- [/
- 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]
|