Quick Start

Capy requires C++20 with coroutine support.

Minimal Example

Create a file hello_coro.cpp:

#include <boost/capy/task.hpp>
#include <boost/capy/ex/run_async.hpp>
#include <boost/capy/ex/thread_pool.hpp>
#include <iostream>

namespace capy = boost::capy;

// A coroutine that returns a value
capy::task<int> answer()
{
    co_return 42;
}

// A coroutine that awaits another coroutine
capy::task<void> greet()
{
    int n = co_await answer();
    std::cout << "The answer is " << n << "\n";
}

int main()
{
    capy::thread_pool pool(1);

    // Start the coroutine on the pool's executor
    capy::run_async(pool.get_executor())(greet());

    // join() waits for outstanding work to complete; the pool
    // destructor only stops the pool and discards pending work
    pool.join();
}

Build and Run

Capy is not installed as a system package, so build it first:

cmake -B build && cmake --build build

Replace both paths below with where you built Capy:

g++ -std=c++20 -I/path/to/capy/include -o hello_coro hello_coro.cpp \
    /path/to/capy/build/libboost_capy.a -pthread

Then run it:

./hello_coro

Expected output:

The answer is 42

What Just Happened?

  1. answer() creates a suspended coroutine that returns 42

  2. greet() creates a suspended coroutine that awaits answer()

  3. run_async(executor)(greet()) starts greet() on the pool’s executor

  4. greet() runs until it hits co_await answer()

  5. answer() runs and returns 42

  6. greet() resumes with the result and prints it

  7. greet() completes, pool.join() returns, and main() exits

Both coroutines ran on the same executor because affinity propagated automatically through the co_await.

Handling Results

To receive a task’s result outside a coroutine, provide a completion handler:

capy::run_async(executor, [](int result) {
    std::cout << "Got: " << result << "\n";
})(answer());

Handling Errors

Exceptions propagate through coroutine chains. To handle them at the top level:

capy::run_async(executor,
    [](int result) {
        std::cout << "Success: " << result << "\n";
    },
    [](std::exception_ptr ep) {
        try {
            if (ep) std::rethrow_exception(ep);
        } catch (std::exception const& e) {
            std::cerr << "Error: " << e.what() << "\n";
        }
    }
)(might_fail());

Next Steps

Edit this Page