最終更新日時(UTC):
が更新

履歴 編集

customization point object
<execution>

std::execution::as_awaitable(C++26)

namespace std::execution {
  struct as_awaitable_t { unspecified };
  inline constexpr as_awaitable_t as_awaitable{};
}

概要

as_awaitableは、オブジェクトを特定のコルーチン内でAwaitableに変換するカスタマイゼーションポイントオブジェクトである。

Promise型pをもつコルーチンにおいて、Await式co_await as_awaitable(expr, p)は下記のように動作する。

  • expr.as_awaitable(p)が有効ならば、同式が返すAwaitableオブジェクトに対してAwait式を実行する。
  • expr単一の値を送信するSenderであり、Promise型が停止完了ハンドラを定義するならば、下記動作を行う。
    • Senderを接続(connect)し、結果Operation StateをAwaitableオブジェクトに格納する。
    • コルーチンを中断し、Operation Stateを開始(start)する。
    • クエリオブジェクトによるReceiver環境への問い合わせは、Promise型に関連付けられた環境(get_env)へと転送される。
    • Senderが値完了した場合、送信値をAwait式の結果としてコルーチンを再開する。
    • Senderがエラー完了した場合、エラー値を例外としてコルーチンから再スローする。
    • Senderが停止完了した場合、停止完了ハンドラ(unhandled_stopped)が返す別のコルーチンを再開させる。
  • そうでなければ、式exprに対してAwait式を実行する。

効果

説明用の式exprと左辺値pに対して、型Exprdecltype((expr))、型Promisedecay_t<decltype((p))>とする。

呼び出し式as_awaitable(expr, p)は、exprpの評価が不定順で順序付けられることを除いて、下記と等価。

  • 適格であるならば、式expr.as_awaitable(p)
  • そうではなく、説明用の型UPromiseとは異なりかつawait_transformメンバ関数を持たない未規定の型としたとき、is-awaitable<Expr, U> == trueならば、式(void(p), expr)
    • 事前条件 : is-awaitable<Expr, Promise> == true、かつPromise型Uのコルーチンにおける式co_await exprがPromise型Promiseのコルーチンにおける同式と等しさを保持すること。
  • そうではなく、awaitable-sender<Expr, Promise>ならば、式sender-awaitable{expr, p}
  • そうでなければ、式(void(p), expr)

説明専用エンティティ

コンセプトawaitable-sender

namespace std::execution {
  template<class Sndr, class Promise>
  concept awaitable-sender =
    single-sender<Sndr, env_of_t<Promise>> &&
    sender_to<Sndr, awaitable-receiver> &&  // see below
    requires (Promise& p) {
      { p.unhandled_stopped() } -> convertible_to<coroutine_handle<>>;
    };
}

クラステンプレートsender-awaitable

namespace std::execution {
  template<class Sndr, class Promise>
  class sender-awaitable {
    struct unit {};                                           // exposition only
    using value-type =                                        // exposition only
      single-sender-value-type<Sndr, env_of_t<Promise>>;
    using result-type =                                       // exposition only
      conditional_t<is_void_v<value-type>, unit, value-type>;
    struct awaitable-receiver;                                // exposition only

    variant<monostate, result-type, exception_ptr> result{};  // exposition only
    connect_result_t<Sndr, awaitable-receiver> state;         // exposition only

  public:
    sender-awaitable(Sndr&& sndr, Promise& p);
    static constexpr bool await_ready() noexcept { return false; }
    void await_suspend(coroutine_handle<Promise>) noexcept { start(state); }
    value-type await_resume();
  };
}

AS-EXCEPT-PTR

説明用の式errに対してdecltype((err))を型Errとしたとき、式AS-EXCEPT-PTR(err)を下記の通り定義する。

クラステンプレートawaitable-receiver

説明専用のクラステンプレートsender-awaitable<Sndr, Promise>::awaitable-receiverは下記の通り定義される。

struct awaitable-receiver {
  using receiver_concept = receiver_t;
  variant<monostate, result-type, exception_ptr>* result-ptr;  // exposition only
  coroutine_handle<Promise> continuation;                      // exposition only
  // see below
};

説明用の式rcvrawaitable-reciever型の右辺値、crcvrrcvrをconst参照する左辺値、vsを式パック、errErr型の式とする。このとき

sender-awaitable(Sndr&& sndr, Promise& p);

value-type await_resume();

カスタマイゼーションポイント

exprに対して、適格であるならば式expr.as_awaitable(p)が呼び出される。

バージョン

言語

  • C++26

処理系

関連項目

参照