Cpp.CoAwaitExpression Class

Namespace: Cpp
Superclasses: AstNodeProperties

Represents the co_await_expression nodes in the syntax tree of your code

Since R2026a

Description

The PQL class CoAwaitExpression represents the node co_await_expression in the syntax tree of your code.

#include <coroutine>

struct Awaitable {
    bool await_ready() const noexcept { return true; }
    void await_suspend(std::coroutine_handle<>) const noexcept {}
    int await_resume() const noexcept { return 42; }
};

auto foo() -> std::coroutine_handle<> {
    co_await Awaitable{};       // co_await_expression (argument is an object construction)
    co_await (1 + 2);          // co_await_expression (argument is a parenthesized expression)
    int x = co_await Awaitable{}; // co_await_expression used in initialization
    co_return;
}

The three co_await occurrences in foo() are co_await_expression nodes matched by this PQL class.

Predicates

expand all

Type

Type	Raisable	Printable
`CoAwaitExpression`	Yes	No

Syntaxes

This class defines these predicates that act on the objects of this class. In addition, objects of this class can access the predicates defined by the base class AstNodeProperties. An object of this class is an object of AstNodeProperties class.

Predicates	Description	Example
`is(required CoAwaitExpression &cae)`	Checks whether a `co_await_expression` node exists and binds it to `&cae` for further inspection.	This PQL defect checks for the presence of any `co_await_expression` node. defect detect_coawait_is = when Cpp.CoAwaitExpression.is(&cae) and cae.nodeText(&txt) raise "found co_await via is: \"{txt}\"" on cae In this C++ code, the defect checks for every `co_await` expression present in the function body. #include <coroutine> struct A { bool await_ready() const noexcept {return true;} int await_resume() const noexcept {return 0;} }; auto f() -> std::coroutine_handle<> { co_await A{}; co_return; }
`cast(Cpp.Node.Node node, required CoAwaitExpression &cast)`	Verifies that a generic `Cpp.Node.Node` is a `co_await_expression` and, if so, exposes it as `&cast` for `CoAwaitExpression`-specific queries.	This PQL defect checks whether a generic node is specifically a `co_await_expression`. defect detect_coawait_cast = when Cpp.Node.is(&node, &,&,&) and Cpp.CoAwaitExpression.cast(node, &cae) and cae.nodeText(&txt) raise "cast to CoAwaitExpression: \"{txt}\"" on cae In this C++ snippet, the defect looks through generic AST nodes and selects those that are `co_await` expressions. #include <coroutine> struct A { bool await_ready() const noexcept {return true;} int await_resume() const noexcept {return 0;} }; auto g() -> std::coroutine_handle<> { co_await A{}; co_return; }
`isa(Cpp.Node.Node node)`	Tests whether the provided `Cpp.Node.Node` is a `co_await_expression`.	This PQL defect checks for nodes that are `co_await_expression` using a boolean test. defect detect_coawait_isa = when Cpp.Node.is(&node, &,&,&) and Cpp.CoAwaitExpression.isa(node) and node.nodeText(&txt) raise "isa detected co_await: \"{txt}\"" on node In this C++ example, the rule flags syntax nodes recognized as `co_await` expressions. #include <coroutine> struct B { bool await_ready() const noexcept {return true;} int await_resume() const noexcept {return 1;} }; auto h() -> std::coroutine_handle<> { int v = co_await B{}; co_return; }
`argument(CoAwaitExpression self, Cpp.Node.Node &child)`	Retrieves the expression being awaited, which is the operand of `co_await`, and returns it as `&child`.	This PQL defect checks for `co_await_expression` nodes and extracts their awaited argument. defect detect_coawait_argument = when Cpp.CoAwaitExpression.is(&cae) and cae.argument(&arg) and arg.nodeText(&txt) raise "co_await argument: \"{txt}\"" on cae In the C++ code below, the defect finds each `co_await` and reports the awaited expression (e.g., `Awaitable{}` or `(1 + 2)`). #include <coroutine> struct A { bool await_ready() const noexcept {return true;} int await_resume() const noexcept {return 0;} }; auto k() -> std::coroutine_handle<> { co_await A{}; // argument -> A{} co_await (1 + 2); // argument -> (1 + 2) co_return; }
`operator(CoAwaitExpression self, Cpp.Node.Node &child)`	Returns the operator token node corresponding to the `co_await` keyword in a `co_await_expression` node.	This PQL defect checks for `co_await_expression` nodes and extracts the `co_await` operator token node. defect detect_coawait_operator = when Cpp.CoAwaitExpression.is(&cae) and cae.operator(&op) and op.nodeText(&txt) raise "co_await operator token: \"{txt}\"" on cae In the C++ example, the rule captures the literal `co_await` token for each await expression. #include <coroutine> struct A { bool await_ready() const noexcept {return true;} int await_resume() const noexcept {return 0;} }; auto m() -> std::coroutine_handle<> { co_await A{}; co_return; }
`getEnclosingCoAwaitExpression(Cpp.Node.Node child, required CoAwaitExpression &parent)`	Finds the nearest ancestor `co_await_expression` node that encloses `child` and returns it as `&parent`.	This PQL defect checks for nodes that are located inside a `co_await_expression`, returning the closest enclosing `co_await`. defect detect_enclosing_coawait = when Cpp.Node.is(&node, &,&,&) and Cpp.CoAwaitExpression.getEnclosingCoAwaitExpression(node, &parent) and parent.nodeText(&txt) raise "node is inside co_await: \"{txt}\"" on node In the C++ snippet, the rule detects `co_await` expressions hat contains any child node. #include <coroutine> struct A { bool await_ready() const noexcept {return true;} int await_resume() const noexcept {return 0;} }; auto n() -> std::coroutine_handle<> { co_await (1 + 2); // the literal `1` and `2` are nodes enclosed by the co_await_expression co_return; }
`isEnclosedInCoAwaitExpression(Cpp.Node.Node child)`	Boolean test that returns true when `child` has a `co_await_expression` among its ancestors.	This PQL defect checks whether a given node lies anywhere inside a `co_await_expression`. defect detect_inside_coawait = when Cpp.Node.is(&node, &,&,&) and Cpp.CoAwaitExpression.isEnclosedInCoAwaitExpression(node) and node.nodeText(&txt) raise "node enclosed by co_await: \"{txt}\"" on node In the following C++ code, the defect find all nodes that are descendent of a `co_await_expression` node. #include <coroutine> struct A { bool await_ready() const noexcept {return true;} int await_resume() const noexcept {return 0;} }; auto p() -> std::coroutine_handle<> { co_await (1 + 2); // nodes `1` and `2` satisfy isEnclosedInCoAwaitExpression co_return; }

Version History

Introduced in R2026a