15.7 co_await and Awaiters in Detail

15.7 co_await and Awaiters in Detail

Now that we have introducing awaiters let us discuss them in detail and look up further examples.

15.7.1 Details of the Awaiter Interface

Table Special member functions of awaiters once again lists the key operations that awaiters have to provide.

Table 15.3. Special member functions of awaiters

Let us look at this awaiter interface in detail:

• Constructor

The constructor allows coroutines (or wherever the awaiter is created) to pass arguments to the awaiter. These parameters can be used to impact or change the way the awaiter handles suspensions and resumptions. An awaiter for priority requests of a coroutine is one example.

• bool await_ready()

is called right before the coroutine that this function is called for is suspended.

It can be used to (temporarily) turn off suspension completely. If it returns true, we are “ready” to immediately return from the request to suspend and continue with the coroutine without suspending it.

Usually, this function just returns false (“no, do not avoid/block any suspension”). However, it might conditionally yield true (e.g., if the suspension depends on some data being available).

With its return type, await_suspend() can also signal not to accept a suspension of the coroutine (note that true and false have the opposite meaning there: by returning true in await_suspend(), the suspension is accepted). Not accepting a suspension with await_ready() has the benefit that the program saves the costs of initiating the suspension of the coroutine at all.

Note that inside this function, the coroutine it is called for is not suspended yet. Do not (indirectly) call resume() or destroy() here. You can even call more complex business logic here as long as you can ensure that logic does not call resume() or destroy() for the coroutine that is suspended here.

• auto await_suspend(awaitHdl)

is called right after the coroutine this function is called for is suspended. awaitHdl is the coroutine where the suspension is requested (with co_await). It has the type of the awaiting coroutine handle, std::coroutine_handle<PromiseType>.

Here, you could specify what to do next, including resuming the suspended coroutine or the awaiting coroutine immediately and scheduling the other for later resumption. To support this, special return types may be used (this is discussed below).

You could even destroy the coroutine here. However, in that case you have to ensure that the coroutine is not used anywhere else (such as calling done() in a coroutine interface).

• auto await_resume()

is called when the coroutine this function is called for is resumed after a successful suspension (i.e., if resume() is called for the coroutine handle).

The return type of await_resume() is the type of the value that the co_await or co_yield expression that caused the suspension yields. If it is not void, the context of the coroutine can return a value back to the resumed coroutine.

await_suspend() is the key function here. Its parameters and return values can vary as follows:

•The parameter of await_suspend() could be:

–Using the type of the coroutine handle: std::coroutine_handle<PrmType>

–Using a basic type usable for all coroutine handles:

std::coroutine_handle<void> (or just std::coroutine_handle<>) In that case, you do not have access to the promise.

–Using auto to let the compiler find out the type.

•The return type of await_suspend() could be:

–void to continue with the suspension after performing the statements in await_suspend() and return back to the caller of the coroutine.

–bool to signal whether the suspension should really happen. Here, false means “do not suspend (anymore)” (which is the opposite of the Boolean return values of await_ready()).

–std::coroutine_handle<> to resume another coroutine instead.

This use of await_suspend() is called symmetric transfer and is described later in detail.

In this case, a noop coroutine can be used to signal not to resume any coroutine at all (in the same way as if the function were to return false).

In addition, note the following:

•The member functions are usually const, except when the awaiter has a member that is modified (such as storing the coroutine handle in await_suspend() to have it available on resumption).

•The member functions are usually noexcept (this is necessary to allow use in final_suspend()).

•The member functions can be constexpr.

15.7.2 Letting co_await Update Running Coroutines

Because awaiters can execute code on suspension, you can use them to change the behavior of a system that deals with coroutines. Let us look at an example where we let the coroutine change its priority.

Assume that we manage all coroutines in a scheduler and allow them to change their priorities with co_await. For that, we would first define a default priority and some arguments for co_await to change the priority:

int CoroPrioDefVal = 10;

enum class CoroPrioRequest {same, less, more, def};

The classes CoroPrioScheduler and CoroPrioTask interact as follows:

•The scheduler stores all coroutines in the order of their priority and provides members to store a new coroutine, resume the next coroutine, and change the priority of a coroutine:

class CoroPrioScheduler

{

std::multimap<int, CoroPrioTask> tasks; // all tasks sorted by priority

...

public:

void start(CoroPrioTask&& task); bool resumeNext();

bool changePrio(CoroPrioTask::CoroHdl hdl, CoroPrioRequest pr);

};

•The member function start() of the scheduler stores the passed coroutine in the list and also stores the scheduler in the promise of each task:

class CoroPrioScheduler

{

...

public:

void start(CoroPrioTask&& task) {

//store scheduler in coroutine state: task.hdl.promise().schedPtr = this;

//schedule coroutine with a default priority:

tasks.emplace(CoroPrioDefVal, std::move(task));

}

...

};

•The class CoroPrioTask gives the class CoroPrioScheduler access to the handles, provides members in the promise type to point to the scheduler, and enables the coroutine to use co_await with a

CoroPrioRequest:

For start(), it also provides move semantics the usual way.

The interface between the coroutine and the scheduler is the awaiter of the type CoroPrio. Its constructor takes the priority request and stores it in the promise on suspension (when we get the coroutine handle). For that, the constructor stores the request to have it available in await_suspend():

class CoroPrio { private:

CoroPrioRequest prioRequest; public: CoroPrio(CoroPrioRequest pr)

: prioRequest{pr} { // deal with co_await a CoroPrioRequest

}

...

void await_suspend(CoroPrioTask::CoroHdl h) noexcept { h.promise().schedPtr->changePrio(h, prioRequest);

}

...

};

The rest is just the usual boilerplate code for coroutine interfaces plus the handling of priorities. See coro/coropriosched.hpp for the complete code.

As shown, the main program schedules the three coroutines and loops until all have been processed:

sched.start(coro(5));

sched.start(coro(1));

sched.start(coro(4));

while (sched.resumeNext()) {

}

The output is as follows:

start main() schedule coroutines

loop until all are processed coro(5)

coro(5): 1 coro(1) coro(1): 1 coro(4) coro(4): 1 coro(5): 2 end coro(1) coro(4): 2 coro(5): 3 coro(4): 3 coro(5): 4 coro(4): 4 coro(5): 5 end coro(4) end coro(5)

end main()