Reference

task is Capy’s only task type, the return type for coroutines that perform I/O. A task’s body does not run until the task is awaited or started. run_async and run start any type that satisfies ContextRunnable. Authors of other task types build their promise type from the mixins in this section. See The task Type and The ContextAwaitable Protocol.

A results value bundles an error code with the values an operation produces. Test an error code against the portable conditions in cond, such as cond::canceled. Capy’s own codes are in error. See The results Type.

run_async starts a task from code that is not a coroutine. Inside a coroutine, co_await run to execute a task on a chosen executor, or with its own stop token or frame allocator. when_all and when_any concurrently run several awaitables that return results. when_all waits for all of them, and when_any picks the first one that succeeds. See Starting Coroutines and Concurrent Composition.

An executor dispatches or posts continuations to its execution context. An execution context, such as thread_pool, provides executors bound to its own resources. strand serializes the coroutines dispatched through it. Authors of custom executors queue continuation objects and resume their handles with safe_resume. See Executors and Execution Contexts and Custom Executor.

Each coroutine in a chain receives an await_context that carries its executor, stop token, frame allocator, and segment owner. Inside a task, co_await an object from this_coro to read the executor, stop token, or frame allocator, or this_coro::environment to read them all. For example, co_await this_coro::stop_token fetches the running coroutine’s stop token. See The ContextAwaitable Protocol and Stop Tokens and Cancellation.

Authors of awaitables, streams, and combinators use these names. A ContextAwaitable receives the coroutine’s environment when it suspends. immediate and ready wrap a result that is already available. See The ContextAwaitable Protocol.

These primitives suspend a task instead of blocking its thread. async_mutex grants exclusive access, async_event resumes every waiter, and async_waker hands one wakeup to one waiter. To serialize all work without a lock, use the strand from Executors and Execution Contexts. See Async Mutex, Producer-Consumer, and Timeout with Cancellation.

A task’s operator new takes its frame from the thread’s current frame allocator. run_async sets that allocator before it creates the task. Without an explicit allocator, it uses the execution context’s frame allocator, which is the recycling allocator unless replaced. Code that resumes a coroutine handle directly calls safe_resume, which restores the thread’s frame allocator after the coroutine yields control. Promise types get allocator support from frame_alloc_mixin, listed under Tasks and Promise Types. See Frame Allocators.

Each segment of a coroutine chain has a chain_owner. A holder that can never resume a suspended coroutine gives it up with abandon. Execution contexts do this when they shut down, and so do strands when their execution context shuts down. Abandonment also travels up a chain: when a coroutine started by when_all, when_any or run is abandoned, its caller is abandoned too. A destroyed async_mutex or other primitive instead resumes its waiters with a canceled error. See Lifetime and Ownership.

A buffer refers to a contiguous region of memory. A buffer sequence is one buffer or a range of them. make_buffer makes a buffer from a region of memory, a string view, or a contiguous range. The other functions measure a buffer sequence, copy it, return its first buffer, or iterate over its buffers or bytes. Each archetype satisfies its sequence concept but has no default constructor. See Buffer Sequences.

A stream reads into or writes from buffer sequences. read fills the whole buffer sequence, and write writes all of it, unless an error stops them first. Each function in this section is awaited with co_await. The type-erased wrappers accept any stream that satisfies the matching concept and hide its type. See Streams.

The tools in test drive tasks and streams without a real I/O backend. test::run_blocking starts a task and waits on the calling thread until it completes. test::fuse injects a failure at a different point on each pass. set_current_thread_name is in boost::capy, but its header is <boost/capy/test/thread_name.hpp>. See Testing.