asio/src/doc/requirements/Receiver.qbk

[/
 / Copyright (c) 2003-2021 Christopher M. Kohlhoff (chris at kohlhoff 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:Receiver Receiver concepts]

A receiver represents the continuation of an asynchronous operation. An
asynchronous operation may complete with a (possibly empty) set of values, an
error, or it may be cancelled. A receiver has three principal operations
corresponding to the three ways an asynchronous operation may complete:
`set_value`, `set_error`, and `set_done`. These are collectively known as a
receiver’s ['completion-signal operations].


        template<class T, class E = exception_ptr>
        concept receiver =
          move_constructible<remove_cvref_t<T>> &&
          constructible_from<remove_cvref_t<T>, T> &&
          requires(remove_cvref_t<T>&& t, E&& e) {
            { execution::set_done(std::move(t)) } noexcept;
            { execution::set_error(std::move(t), (E&&) e) } noexcept;
          };

        template<class T, class... An>
        concept receiver_of =
          receiver<T> &&
          requires(remove_cvref_t<T>&& t, An&&... an) {
            execution::set_value(std::move(t), (An&&) an...);
          };

The receiver’s completion-signal operations have semantic requirements that are
collectively known as the ['receiver contract], described below:

* None of a receiver’s completion-signal operations shall be invoked before
  `execution::start` has been called on the operation state object that was
  returned by `execution::connect` to connect that receiver to a sender.

* Once `execution::start` has been called on the operation state object,
  exactly one of the receiver’s completion-signal operations shall complete
  non-exceptionally before the receiver is destroyed.

* If `execution::set_value` exits with an exception, it is still valid to call
  `execution::set_error` or `execution::set_done` on the receiver.

Once one of a receiver’s completion-signal operations has completed
non-exceptionally, the receiver contract has been satisfied.

[endsect]