Espacios de nombres
Variantes
Acciones

std::coroutine_handle, std::noop_coroutine_handle

De cppreference.com
< cpp‎ | coroutine
 
 
Biblioteca de servicios
 
Apoyo de corrutinas
Rasgos de corrutinas
Identificador de corrutina
coroutine_handle
(C++20)
Corrutinas no operativas
En espera triviales
 
 
Definido en el archivo de encabezado <coroutine>
template< class Promise = void > struct coroutine_handle;
(1) (desde C++20)
template<> struct coroutine_handle<void>;
(2) (desde C++20)
template<> struct coroutine_handle<std::noop_coroutine_promise>;
(3) (desde C++20)
using noop_coroutine_handle =
    std::coroutine_handle<std::noop_coroutine_promise>;
(4) (desde C++20)

La plantilla de clase coroutine_handle puede usarse para referirse a una corrutina suspendida o en ejecución. Cada especialización del identificador de corrutina, coroutine_handle, es un LiteralType.

1) Plantilla primaria, puede crearse a partir del objeto promesa de tipo Promise.
2) La especialización std::coroutine_handle<void> que borra el tipo promesa. Es convertible desde otras especializaciones.
3) La especialización std::coroutine_handle<std::noop_coroutine_promise> se refiere a corrutinas no operativas. No puede crearse a partir de un objeto promesa.

En implementaciones típicas, cada especialización de std::coroutine_handle es TriviallyCopyable, y alberga un puntero al estado de corrutina como su único dato miembro no estático.

El comportamiento de un programa que añade especializaciones para coroutine_handle no está definido.

Contenido

[editar] Funciones miembro

Construye una objeto identificador de corrutina, coroutine_handle
(función miembro pública) [editar]
(C++20)
Asigna el objeto identificador de corrutina, coroutine_handle
(función miembro pública) [editar]
[estático] (C++20)
Crea un identificador de corrutina, coroutine_handle, del objeto promesa de una corrutina
(función miembro estática pública) [editar]
Conversión
Obtiene un identificador de corrutina, coroutine_handle, con tipo borrado
(función miembro pública) [editar]
Observadores
(C++20)
Comprueba si la corrutina se ha completado
(función miembro pública) [editar]
Comprueba si el identificador representa una corrutina
(función miembro pública) [editar]
Control
Reanuda la ejecución de la corrutina
(función miembro pública) [editar]
(C++20)
Destruye una corrutina
(función miembro pública) [editar]
Acceso a promesa
(C++20)
Accede a la promesa de una corrutina
(función miembro pública) [editar]
Exportar/importar
(C++20)
Exporta la dirección subyacente, es decir, el puntero que respalda la corrutina
(función miembro pública) [editar]
[estático] (C++20)
Importa una corrutina de un puntero
(función miembro estática pública) [editar]

[editar] Funciones no miembro

Compara dos objetos identificadores de corrutinas (coroutine_handle)
(función) [editar]

[editar] Clases auxiliares

Soporte hash (resumen) para un identificador de corrutina (std::coroutine_handle)
(especialización de plantilla de clase) [editar]

[editar] Notas

Un identificador de corrutina, coroutine_handle, puede quedar pendiente, en cuyo caso el identificador tiene que usarse cuidadosamente para evitar comportamiento no definido.

[editar] Ejemplo

#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 {};
        }
        // No permitir co_await en corrutinas generadoras.
        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;
    }
 
    // Soporte para bucle for basado en rango.
    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';
}

Salida:

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

[editar] Informes de defectos

Los siguientes informes de defectos de cambio de comportamiento se aplicaron de manera retroactiva a los estándares de C++ publicados anteriormente.

ID Aplicado a Comportamiento según lo publicado Comportamiento correcto
LWG 3460 C++20 La clase base pública de coroutine_handle podría dejarlo en un estado no deseado. Se eliminó la herencia