std::noop_coroutine(3)

💖 NAME 💖

std::noop_coroutine — std::noop_coroutine 💅 (and yes bestie, this is the std::noop_coroutine(3) page from the C++ Standard Libary, welcome to the no-op coroutine club 🫶).

---

✨ Synopsis ✨

Defined in header <coroutine>:

std::noop_coroutine_handle noop_coroutine() noexcept;  (since C++20)

Returns a coroutine handle referring to a no-op coroutine. Basically it hands you a handle to a little do-nothing coroutine 💤.

If there has already been a coroutine state of no-op coroutine, it is unspecified whether a subsequent call to noop_coroutine returns a previously obtained coroutine handle, or a coroutine handle referring to a new coroutine state of no-op coroutine. So like… maybe it's the old one, maybe it's a fresh state — the standard is not committing, and honestly same 😭.

---

🍓 Parameters 🍓

(none) — truly nothing. No args, no drama, just vibes 🫶.

---

🎀 Return value 🎀

A std::noop_coroutine_handle referring to a no-op coroutine. That's it. That's the whole return value 💖.

---

💅 Notes 💅

• Return values from different calls to noop_coroutine may and may not compare equal. So don't assume they're the same handle, and don't assume they're different either — it's giving mystery 🔥.
• noop_coroutine may only return a noop_coroutine_handle referring to a coroutine state object without starting a coroutine. It does not start the coroutine, periodt ✨.

---

🌈 Example 🌈

okay this example is a full little coroutine demo and it's highkey main character energy 👑. Here's the code exactly as served:

        // Run this code

        #include <coroutine>
        #include <iostream>
        #include <utility>

        template<class T>
        struct task
        {
            struct promise_type
            {
                auto get_return_object()
                {
                    return
       task(std::coroutine_handle<promise_type>::from_promise(*this));
                }
                std::suspend_always initial_suspend() { return {}; }
                struct final_awaiter
                {
                    bool await_ready() noexcept { return false; }
                    void await_resume() noexcept {}
                    std::coroutine_handle<>
                        await_suspend(std::coroutine_handle<promise_type> h)
       noexcept
                    {
                        // final_awaiter::await_suspend is called when the
       execution of the
                        // current coroutine (referred to by 'h') is about to
       finish.
                        // If the current coroutine was resumed by another
       coroutine via
                        // co_await get_task(), a handle to that coroutine has
       been stored
                        // as h.promise().previous. In that case, return the
       handle to resume
                        // the previous coroutine.
                        // Otherwise, return noop_coroutine(), whose resumption
       does nothing.

                        if (auto previous = h.promise().previous; previous)
                            return previous;
                        else
                            return std::noop_coroutine();
                    }
                };
                final_awaiter final_suspend() noexcept { return {}; }
                void unhandled_exception() { throw; }
                void return_value(T value) { result = std::move(value); }

                T result;
                std::coroutine_handle<> previous;
            };

            task(std::coroutine_handle<promise_type> h) : coro(h) {}
            task(task&& t) = delete;
            ~task() { coro.destroy(); }

            struct awaiter
            {
                bool await_ready() { return false; }
                T await_resume() { return std::move(coro.promise().result); }
                auto await_suspend(std::coroutine_handle<> h)
                {
                    coro.promise().previous = h;
                    return coro;
                }
                std::coroutine_handle<promise_type> coro;
            };
            awaiter operator co_await() { return awaiter{coro}; }
            T operator()()
            {
                coro.resume();
                return std::move(coro.promise().result);
            }

        private:
            std::coroutine_handle<promise_type> coro;
        };

        task<int> get_random()
        {
            std::cout << "in get_random()\n";
            co_return 4;
        }

        task<int> test()
        {
            task<int> v = get_random();
            task<int> u = get_random();
            std::cout << "in test()\n";
            int x = (co_await v + co_await u);
            co_return x;
        }

        int main()
        {
            task<int> t = test();
            int result = t();
            std::cout << result << '\n';
        }

Output:

        in test()
        in get_random()
        in get_random()
        8

---

🦋 See also 🦋

• noop_coroutine_promise — used for coroutines with no observable effects (C++20) (class).
• noop_coroutine_handle — std::coroutine_handle<std::noop_coroutine_promise>, intended to refer to a no-op coroutine (C++20) (typedef).

---

xoxo, your cppreference bestie 💖 source: http://cppreference.com · version/date: 2024.06.10 · page: std::noop_coroutine(3) ✨