17 Language support library [support]

17.12 Coroutines [support.coroutine]

1
#
The header <coroutine> defines several types providing compile and run-time support for coroutines in a C++ program.

17.12.1 Header <coroutine> synopsis [coroutine.syn]

#include <compare>              // see [compare.syn]

namespace std {
  // [coroutine.traits], coroutine traits
  template<class R, class... ArgTypes>
    struct coroutine_traits;

  // [coroutine.handle], coroutine handle
  template<class Promise = void>
    struct coroutine_handle;

  // [coroutine.handle.compare], comparison operators
  constexpr bool operator==(coroutine_handle<> x, coroutine_handle<> y) noexcept;
  constexpr strong_ordering operator<=>(coroutine_handle<> x, coroutine_handle<> y) noexcept;

  // [coroutine.handle.hash], hash support
  template<class T> struct hash;
  template<class P> struct hash<coroutine_handle<P>>;

  // [coroutine.noop], no-op coroutines
  struct noop_coroutine_promise;

  template<> struct coroutine_handle<noop_coroutine_promise>;
  using noop_coroutine_handle = coroutine_handle<noop_coroutine_promise>;

  noop_coroutine_handle noop_coroutine() noexcept;

  // [coroutine.trivial.awaitables], trivial awaitables
  struct suspend_never;
  struct suspend_always;
}

17.12.2 Coroutine traits [coroutine.traits]

1
#
This subclause defines requirements on classes representing coroutine traits, and defines the class template coroutine_­traits that meets those requirements.

17.12.2.1 Class template coroutine_­traits [coroutine.traits.primary]

1
#
The header <coroutine> defines the primary template coroutine_­traits such that if ArgTypes is a parameter pack of types and if the qualified-id R​::​promise_­type is valid and denotes a type ([temp.deduct]), then coroutine_­traits<R,ArgTypes...> has the following publicly accessible member:
using promise_type = typename R::promise_type;
Otherwise, coroutine_­traits<R,ArgTypes...> has no members.
2
#
Program-defined specializations of this template shall define a publicly accessible nested type named promise_­type.

17.12.3 Class template coroutine_­handle [coroutine.handle]

namespace std {
  template<>
  struct coroutine_handle<void>
  {
    // [coroutine.handle.con], construct/reset
    constexpr coroutine_handle() noexcept;
    constexpr coroutine_handle(nullptr_t) noexcept;
    coroutine_handle& operator=(nullptr_t) noexcept;

    // [coroutine.handle.export.import], export/import
    constexpr void* address() const noexcept;
    static constexpr coroutine_handle from_address(void* addr);

    // [coroutine.handle.observers], observers
    constexpr explicit operator bool() const noexcept;
    bool done() const;

    // [coroutine.handle.resumption], resumption
    void operator()() const;
    void resume() const;
    void destroy() const;

  private:
    void* ptr;  // exposition only
  };

  template<class Promise>
  struct coroutine_handle : coroutine_handle<>
  {
    // [coroutine.handle.con], construct/reset
    using coroutine_handle<>::coroutine_handle;
    static coroutine_handle from_promise(Promise&);
    coroutine_handle& operator=(nullptr_t) noexcept;

    // [coroutine.handle.export.import], export/import
    static constexpr coroutine_handle from_address(void* addr);

    // [coroutine.handle.promise], promise access
    Promise& promise() const;
  };
}
1
#
An object of type coroutine_­handle<T> is called a coroutine handle and can be used to refer to a suspended or executing coroutine.
A default-constructed coroutine_­handle object does not refer to any coroutine.
2
#
If a program declares an explicit or partial specialization of coroutine_­handle, the behavior is undefined.

17.12.3.1 Construct/reset [coroutine.handle.con]

🔗
constexpr coroutine_handle() noexcept; constexpr coroutine_handle(nullptr_t) noexcept;
1
#
Postconditions: address() == nullptr.
🔗
static coroutine_handle from_promise(Promise& p);
2
#
Preconditions: p is a reference to a promise object of a coroutine.
3
#
Returns: A coroutine handle h referring to the coroutine.
4
#
Postconditions: addressof(h.promise()) == addressof(p).
🔗
coroutine_handle& operator=(nullptr_t) noexcept;
5
#
Postconditions: address() == nullptr.
6
#
Returns: *this.

17.12.3.2 Export/import [coroutine.handle.export.import]

🔗
constexpr void* address() const noexcept;
1
#
Returns: ptr.
🔗
static constexpr coroutine_handle<> coroutine_handle<>::from_address(void* addr); static constexpr coroutine_handle<Promise> coroutine_handle<Promise>::from_address(void* addr);
2
#
Preconditions: addr was obtained via a prior call to address.
3
#
Postconditions: from_­address(address()) == *this.

17.12.3.3 Observers [coroutine.handle.observers]

🔗
constexpr explicit operator bool() const noexcept;
1
#
Returns: address() != nullptr.
🔗
bool done() const;
2
#
Preconditions: *this refers to a suspended coroutine.
3
#
Returns: true if the coroutine is suspended at its final suspend point, otherwise false.

17.12.3.4 Resumption [coroutine.handle.resumption]

1
#
Resuming a coroutine via resume, operator(), or destroy on an execution agent other than the one on which it was suspended has implementation-defined behavior unless each execution agent either is an instance of std​::​thread or std​::​jthread, or is the thread that executes main.
[Note
:
A coroutine that is resumed on a different execution agent should avoid relying on consistent thread identity throughout, such as holding a mutex object across a suspend point.
— end note
]
[Note
:
A concurrent resumption of the coroutine may result in a data race.
— end note
]
🔗
void operator()() const; void resume() const;
2
#
Preconditions: *this refers to a suspended coroutine.
The coroutine is not suspended at its final suspend point.
3
#
Effects: Resumes the execution of the coroutine.
🔗
void destroy() const;
4
#
Preconditions: *this refers to a suspended coroutine.
5
#
Effects: Destroys the coroutine ([dcl.fct.def.coroutine]).

17.12.3.5 Promise access [coroutine.handle.promise]

🔗
Promise& promise() const;
1
#
Preconditions: *this refers to a coroutine.
2
#
Returns: A reference to the promise of the coroutine.

17.12.3.6 Comparison operators [coroutine.handle.compare]

🔗
constexpr bool operator==(coroutine_handle<> x, coroutine_handle<> y) noexcept;
1
#
Returns: x.address() == y.address().
🔗
constexpr strong_ordering operator<=>(coroutine_handle<> x, coroutine_handle<> y) noexcept;
2
#
Returns: compare_­three_­way()(x.address(), y.address()).

17.12.3.7 Hash support [coroutine.handle.hash]

🔗
template<class P> struct hash<coroutine_handle<P>>;
1
#
The specialization is enabled ([unord.hash]).

17.12.4 No-op coroutines [coroutine.noop]

17.12.4.1 Class noop_­coroutine_­promise [coroutine.promise.noop]

🔗
struct noop_coroutine_promise {};
1
#
The class noop_­coroutine_­promise defines the promise type for the coroutine referred to by noop_­coroutine_­handle ([coroutine.syn]).

17.12.4.2 Class coroutine_­handle<noop_­coroutine_­promise> [coroutine.handle.noop]

namespace std {
  template<>
  struct coroutine_handle<noop_coroutine_promise> : coroutine_handle<>
  {
    // [coroutine.handle.noop.observers], observers
    constexpr explicit operator bool() const noexcept;
    constexpr bool done() const noexcept;

    // [coroutine.handle.noop.resumption], resumption
    constexpr void operator()() const noexcept;
    constexpr void resume() const noexcept;
    constexpr void destroy() const noexcept;

    // [coroutine.handle.noop.promise], promise access
    noop_coroutine_promise& promise() const noexcept;

    // [coroutine.handle.noop.address], address
    constexpr void* address() const noexcept;
  private:
    coroutine_handle(unspecified);
  };
}

17.12.4.2.1 Observers [coroutine.handle.noop.observers]

🔗
constexpr explicit operator bool() const noexcept;
1
#
Returns: true.
🔗
constexpr bool done() const noexcept;
2
#
Returns: false.

17.12.4.2.2 Resumption [coroutine.handle.noop.resumption]

🔗
constexpr void operator()() const noexcept; constexpr void resume() const noexcept; constexpr void destroy() const noexcept;
1
#
Effects: None.
2
#
Remarks: If noop_­coroutine_­handle is converted to coroutine_­handle<>, calls to operator(), resume and destroy on that handle will also have no observable effects.

17.12.4.2.3 Promise access [coroutine.handle.noop.promise]

🔗
noop_coroutine_promise& promise() const noexcept;
1
#
Returns: A reference to the promise object associated with this coroutine handle.

17.12.4.2.4 Address [coroutine.handle.noop.address]

🔗
constexpr void* address() const noexcept;
1
#
Returns: ptr.
2
#
Remarks: A noop_­coroutine_­handle's ptr is always a non-null pointer value.

17.12.4.3 Function noop_­coroutine [coroutine.noop.coroutine]

🔗
noop_coroutine_handle noop_coroutine() noexcept;
1
#
Returns: A handle to a coroutine that has no observable effects when resumed or destroyed.
2
#
Remarks: A handle returned from noop_­coroutine may or may not compare equal to a handle returned from another invocation of noop_­coroutine.

17.12.5 Trivial awaitables [coroutine.trivial.awaitables]

namespace std {
  struct suspend_never {
    constexpr bool await_ready() const noexcept { return true; }
    constexpr void await_suspend(coroutine_handle<>) const noexcept {}
    constexpr void await_resume() const noexcept {}
  };
  struct suspend_always {
    constexpr bool await_ready() const noexcept { return false; }
    constexpr void await_suspend(coroutine_handle<>) const noexcept {}
    constexpr void await_resume() const noexcept {}
  };
}
1
#
[Note
:
The types suspend_­never and suspend_­always can be used to indicate that an await-expression should either never suspend or always suspend, and in either case not produce a value.
— end note
]