std::coroutine_handle, std::noop_coroutine_handle

 

C++

Compiler-Unterstützung

Freestanding und gehostet

Sprache

Standardbibliothek

Header der Standardbibliothek

Benannte Anforderungen

Feature-Test-Makros (C++20)

Bibliothek für Sprachunterstützung

Konzepte-Bibliothek (C++20)

Diagnostik-Bibliothek

Speicherverwaltungsbibliothek

Metaprogrammierungsbibliothek (C++11)

Allgemeine Dienstprogramme-Bibliothek

Container-Bibliothek

Iterator-Bibliothek

Ranges-Bibliothek (C++20)

Algorithmen-Bibliothek

Bibliothek für Zeichenketten

Textverarbeitungsbibliothek

Numerik-Bibliothek

Datums- und Zeitbibliothek

Ein-/Ausgabe-Bibliothek

Dateisystembibliothek (C++17)

Unterstützung für nebenläufige Programmierung (C++11)

Ausführungssteuerungsbibliothek (C++26)

Technische Spezifikationen

Symbolverzeichnis

Externe Bibliotheken

 

Dienstprogramm-Bibliotheken

Sprachunterstützung Typunterstützung (Basistypen, RTTI) Bibliotheks-Feature-Test-Makros (C++20) Programm-Dienstprogramme Variadische Funktionen initializer_list (C++11) is_constant_evaluated (C++20) is_within_lifetime (C++26) source_location (C++20) Coroutine-Unterstützung (C++20) Vertragsunterstützung (C++26) Drei-Wege-Vergleich 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)

Allgemeine Hilfsmittel Funktionsobjekte Bit-Manipulation (C++20) bitset hash (C++11) Relationale Operatoren (in C++20 veraltet) rel_ops::operator!=rel_ops::operator>    rel_ops::operator<=rel_ops::operator>= Ganzzahl-Vergleichsfunktionen 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 und Typ-Operationen 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) Gemeinsame Vokabulartypen 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 support

Coroutine traits

coroutine_traits (C++20)

Coroutine handle

coroutine_handle (C++20)

No-op coroutines

noop_coroutine_promise (C++20)

noop_coroutine (C++20)

Trivial awaitables

suspend_never (C++20)

suspend_always (C++20)

Range generators

generator (C++23)

 

std::coroutine_handle

Memberfunktionen

coroutine_handle::coroutine_handle

coroutine_handle::operator=

coroutine_handle::from_promise

Konversion

coroutine_handle::operator coroutine_handle<>

Observer

coroutine_handle::done

coroutine_handle::operator bool

Steuerung

coroutine_handle::operator()coroutine_handle::resume

coroutine_handle::destroy

Zugriff auf Promise

coroutine_handle::promise

Export/Import

coroutine_handle::address

coroutine_handle::from_address

Nicht-Member-Funktionen

operator==operator<=>

Hilfsklassen

hash<std::coroutine_handle>

 

Definiert in Header <coroutine>
template< class Promise = void > struct coroutine_handle;	(1)	(seit C++20)
template<> struct coroutine_handle<void>;	(2)	(seit C++20)
template<> struct coroutine_handle<std::noop_coroutine_promise>;	(3)	(seit C++20)
using noop_coroutine_handle =     std::coroutine_handle<std::noop_coroutine_promise>;	(4)	(seit C++20)

Die Klassenschablone coroutine_handle kann verwendet werden, um auf eine pausierte oder ausgeführte Coroutine zu verweisen. Jede Spezialisierung von coroutine_handle ist ein LiteralType.

1) Primäre Schablone, kann aus dem Promise-Objekt vom Typ Promise erstellt werden.

2) Spezialisierung std::coroutine_handle<void> löscht den Promise-Typ. Sie ist von anderen Spezialisierungen konvertierbar.

3) Spezialisierung std::coroutine_handle<std::noop_coroutine_promise> verweist auf No-Op-Coroutinen. Sie kann nicht aus einem Promise-Objekt erstellt werden.

Bei typischen Implementierungen ist jede Spezialisierung von std::coroutine_handle TriviallyCopyable.

Wenn das Programm Spezialisierungen für std::coroutine_handle hinzufügt, ist das Verhalten undefiniert.

Datenmember

Member-Name	Definition
ptr (private)	Ein Zeiger void* auf den Coroutine-Zustand. ((exposition-only member object*)

Member-Funktionen

(Konstruktor)	konstruiert ein coroutine_handle-Objekt (public member function)
operator=	weist das coroutine_handle-Objekt zu (public member function)
Konversion
operator coroutine_handle<>	ruft ein typ-gelöschtes coroutine_handle ab (public member function)
Observer
done	prüft, ob die Coroutine abgeschlossen ist (public member function)
operator bool	prüft, ob der Handle eine Coroutine repräsentiert (public member function)
Steuerung
operator()resume	setzt die Ausführung der Coroutine fort (public member function)
destroy	zerstört eine Coroutine (public member function)
Zugriff auf Promise
promise	greift auf das Promise einer Coroutine zu (public member function)
from_promise [static]	erstellt ein coroutine_handle aus dem Promise-Objekt einer Coroutine (public static member function)
Export/Import
address	exportiert die zugrundeliegende Adresse, d.h. den Zeiger, der die Coroutine unterstützt (public member function)
from_address [static]	importiert eine Coroutine aus einem Zeiger (public static member function)

Nicht-Member-Funktionen

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

vergleicht zwei coroutine_handle-Objekte (Funktion)

Hilfsklassen

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

Hash-Unterstützung für std::coroutine_handle (Klassentemplate-Spezialisierung)

Hinweise

Ein coroutine_handle kann verwaist sein, in diesem Fall muss der coroutine_handle vorsichtig verwendet werden, um undefiniertes Verhalten zu vermeiden.

Beispiel

Führen Sie diesen Code aus

#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';
}

Ausgabe

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

Fehlerberichte

Die folgenden Verhaltensändernden Fehlerberichte wurden rückwirkend auf zuvor veröffentlichte C++-Standards angewendet.

DR	angewendet auf	Verhalten wie veröffentlicht	Korrigiertes Verhalten
LWG 3460	C++20	die öffentliche Basisklasse von coroutine_handle könnte sie in einem unerwünschten Zustand hinterlassen	Vererbung entfernt

Siehe auch

generator (C++23)

Eine view, die einen synchronen Coroutine-Generator repräsentiert (Klassentemplate)