std::coroutine_handle, std::noop_coroutine_handle

 

C++

コンパイラサポート

フリースタンディングとホスト

言語

標準ライブラリ

標準ライブラリヘッダー

名前付き要件

機能テストマクロ (C++20)

言語サポートライブラリ

コンセプトライブラリ (C++20)

診断ライブラリ

メモリ管理ライブラリ

メタプログラミングライブラリ (C++11)

汎用ユーティリティライブラリ

コンテナライブラリ

イテレータライブラリ

Rangesライブラリ (C++20)

アルゴリズムライブラリ

文字列ライブラリ

テキスト処理ライブラリ

数値ライブラリ

日付と時刻ライブラリ

入出力ライブラリ

ファイルシステムライブラリ (C++17)

並行サポートライブラリ (C++11)

実行制御ライブラリ (C++26)

Technical specifications (技術仕様)

シンボルインデックス

外部ライブラリ

 

ユーティリティライブラリ

言語サポート 型のサポート (基本型、RTTI) ライブラリ機能検査マクロ (C++20) プログラムユーティリティ 可変引数関数 initializer_list (C++11) is_constant_evaluated (C++20) is_within_lifetime (C++26) source_location (C++20) コルーチンサポート (C++20) 契約サポート (C++26) 三方比較 three_way_comparablethree_way_comparable_with (C++20)(C++20) strong_ordering (C++20) weak_ordering (C++20) partial_ordering (C++20) common_comparison_category (C++20) compare_three_way_result (C++20) compare_three_way (C++20) strong_order (C++20) weak_order (C++20) partial_order (C++20) compare_strong_order_fallback (C++20) compare_weak_order_fallback (C++20) compare_partial_order_fallback (C++20)   is_eqis_ltis_lteq (C++20)(C++20)(C++20)   is_neqis_gtis_gteq (C++20)(C++20)(C++20)

汎用ユーティリティ 関数オブジェクト ビット操作 (C++20) bitset hash (C++11) 関係演算子 (C++20で非推奨) rel_ops::operator!=rel_ops::operator>    rel_ops::operator<=rel_ops::operator>= 整数比較関数 cmp_equalcmp_lesscmp_less_than (C++20)(C++20)(C++20)   cmp_not_equalcmp_greatercmp_greater_than (C++20)(C++20)(C++20) in_range (C++20) スワップと型操作 swap ranges::swap (C++20) exchange (C++14) declval (C++11) to_underlying (C++23) forward (C++11) forward_like (C++23) move (C++11) move_if_noexcept (C++11) as_const (C++17) 共通語彙型 pair tuple (C++11) optional (C++17) any (C++17) variant (C++17) tuple_size (C++11) tuple_element (C++11) apply (C++17) make_from_tuple (C++17) expected (C++23)

 

コルーチンサポート

コルーチントレイト

coroutine_traits (C++20)

コルーチンハンドル

coroutine_handle (C++20)

No-opコルーチン

noop_coroutine_promise (C++20)

noop_coroutine (C++20)

自明なawaitable

suspend_never (C++20)

suspend_always (C++20)

Rangeジェネレータ

generator (C++23)

 

std::coroutine_handle

メンバ関数

coroutine_handle::coroutine_handle

coroutine_handle::operator=

coroutine_handle::from_promise

変換

coroutine_handle::operator coroutine_handle<>

監視

coroutine_handle::done

coroutine_handle::operator bool

制御

coroutine_handle::operator()coroutine_handle::resume

coroutine_handle::destroy

Promiseへのアクセス

coroutine_handle::promise

エクスポート/インポート

coroutine_handle::address

coroutine_handle::from_address

非メンバ関数

operator==operator<=>

ヘルパークラス

hash<std::coroutine_handle>

 

ヘッダ <coroutine> で定義
template< class Promise = void > struct coroutine_handle;	(1)	(C++20以降)
template<> struct coroutine_handle<void>;	(2)	(C++20以降)
template<> struct coroutine_handle<std::noop_coroutine_promise>;	(3)	(C++20以降)
using noop_coroutine_handle =     std::coroutine_handle<std::noop_coroutine_promise>;	(4)	(C++20以降)

クラス テンプレート coroutine_handle は、中断された、または実行中のコルーチンを参照するために使用できます。coroutine_handle のすべての特殊化は LiteralType です。

1) プライマリ テンプレート。型 Promise の promise オブジェクトから作成できます。

2) 特殊化 std::coroutine_handle<void> は promise 型を消去します。他の特殊化から変換可能です。

3) 特殊化 std::coroutine_handle<std::noop_coroutine_promise> は、no-op コルーチンを参照します。promise オブジェクトから作成することはできません。

一般的な実装では、std::coroutine_handle のすべての特殊化は TriviallyCopyable です。

プログラムが std::coroutine_handle の特殊化を追加した場合、その動作は未定義です。

データメンバー

メンバ名	定義
ptr (private)	コルーチン状態への void* ポインタ。 (説明用のメンバオブジェクト*)

メンバ関数

(コンストラクタ)	coroutine_handle オブジェクトを構築する (public メンバ関数)
operator=	coroutine_handle オブジェクトを代入する (public メンバ関数)
変換
operator coroutine_handle<>	型消去された coroutine_handle を取得する (public メンバ関数)
監視
done	コルーチンが完了したかチェックする (public メンバ関数)
operator bool	ハンドルがコルーチンを表すかチェックする (public メンバ関数)
制御
operator()resume	コルーチンの実行を再開する (public メンバ関数)
destroy	コルーチンを破棄する (public メンバ関数)
Promiseへのアクセス
promise	コルーチンのpromiseにアクセスする (public メンバ関数)
from_promise [static]	コルーチンのpromiseオブジェクトから coroutine_handle を作成する (public static メンバ関数)
エクスポート/インポート
address	基となるアドレス、すなわちコルーチンを裏付けるポインタをエクスポートする (public メンバ関数)
from_address [static]	ポインタからコルーチンをインポートする (public static メンバ関数)

非メンバ関数

operator==operator<=> (C++20)

2つの coroutine_handle オブジェクトを比較する (関数)

ヘルパークラス

std::hash<std::coroutine_handle> (C++20)

std::coroutine_handle のハッシュサポート (クラステンプレートの特殊化)

注釈

coroutine_handle はダングリング状態になる可能性があり、その場合、未定義の動作を避けるために coroutine_handle を慎重に使用する必要があります。

例

このコードを実行

#include <coroutine>
#include <iostream>
#include <optional>
 
template<std::movable T>
class Generator
{
public:
    struct promise_type
    {
        Generator<T> get_return_object()
        {
            return Generator{Handle::from_promise(*this)};
        }
        static std::suspend_always initial_suspend() noexcept
        {
            return {};
        }
        static std::suspend_always final_suspend() noexcept
        {
            return {};
        }
        std::suspend_always yield_value(T value) noexcept
        {
            current_value = std::move(value);
            return {};
        }
        // Disallow co_await in generator coroutines.
        void await_transform() = delete;
        [[noreturn]]
        static void unhandled_exception() { throw; }
 
        std::optional<T> current_value;
    };
 
    using Handle = std::coroutine_handle<promise_type>;
 
    explicit Generator(const Handle coroutine) :
        m_coroutine{coroutine}
    {}
 
    Generator() = default;
    ~Generator()
    {
        if (m_coroutine)
            m_coroutine.destroy();
    }
 
    Generator(const Generator&) = delete;
    Generator& operator=(const Generator&) = delete;
 
    Generator(Generator&& other) noexcept :
        m_coroutine{other.m_coroutine}
    {
        other.m_coroutine = {};
    }
    Generator& operator=(Generator&& other) noexcept
    {
        if (this != &other)
        {
            if (m_coroutine)
                m_coroutine.destroy();
            m_coroutine = other.m_coroutine;
            other.m_coroutine = {};
        }
        return *this;
    }
 
    // Range-based for loop support.
    class Iter
    {
    public:
        void operator++()
        {
            m_coroutine.resume();
        }
        const T& operator*() const
        {
            return *m_coroutine.promise().current_value;
        }
        bool operator==(std::default_sentinel_t) const
        {
            return !m_coroutine || m_coroutine.done();
        }
 
        explicit Iter(const Handle coroutine) :
            m_coroutine{coroutine}
        {}
 
    private:
        Handle m_coroutine;
    };
 
    Iter begin()
    {
        if (m_coroutine)
            m_coroutine.resume();
        return Iter{m_coroutine};
    }
 
    std::default_sentinel_t end() { return {}; }
 
private:
    Handle m_coroutine;
};
 
template<std::integral T>
Generator<T> range(T first, const T last)
{
    while (first < last)
        co_yield first++;
}
 
int main()
{
    for (const char i : range(65, 91))
        std::cout << i << ' ';
    std::cout << '\n';
}

出力

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

欠陥報告

以下の動作変更を伴う欠陥報告が、以前に公開されたC++標準に遡って適用されました。

DR	適用対象	公開された動作	正しい動作
LWG 3460	C++20	coroutine_handle の公開基底クラスは、望ましくない状態になる可能性がある	継承が削除されました

関連項目

generator (C++23)

同期的なコルーチンジェネレータを表す view (クラステンプレート)