Example Programs

These examples demonstrate how the pieces you have learned—tasks, buffers, streams, cancellation, composition—fit together in practice.

Each example builds from its own directory under example/. Some directories hold several programs that share a header. Each page names any optional dependency that its program needs.

For a reading order for your role, start with Protocol Anatomy. It lists what to read next for application developers, framework authors, and I/O library authors.

Library Code and Example Code

The code under example/, headers included, is not part of Capy. It has no reference page and no stability guarantee, even where it declares names in namespace boost::capy. Copy it and adapt it to your program. For example, the quitter task type on Writing Your Own Task Type (Early Quitter) is example code, not a Capy type.

What This Section Covers

Hello Task — The minimal Capy program: a task that prints a message.
Producer-Consumer — Two tasks communicating via an async event, with strand serialization.
Buffer Composition — Composing buffer sequences without allocation for scatter/gather I/O.
Mock Stream Testing — Unit testing protocol code with mock streams and error injection.
Type-Erased Echo — An echo server demonstrating the compilation firewall pattern.
Timeout with Cancellation — Racing a slow operation against a deadline, and cancelling it with a stop token.
Parallel Fetch — Running multiple operations concurrently with when_all.
Strand Serialization — Protecting shared state with a strand instead of a mutex.
Async Mutex — Fair FIFO coroutine locking with async_mutex.
Parallel Tasks — Distributing CPU-bound work across a thread pool and collecting results.
Custom Executor — Implementing the Executor concept with a single-threaded run loop.
Bridging a P2300 Sender — Awaiting a std::execution (P2300) sender from a Capy coroutine.
Calling Asio from a Capy Coroutine — Using Boost.Asio operations directly through a use_capy completion token.
Using a Capy Stream from Asio — Driving a Capy stream with Asio completion tokens, through an adapter built on async_initiate.
GUI Integration — Running a Capy coroutine on a GUI event loop, resuming on the GUI thread to update widgets.
Writing Your Own Task Type (Early Quitter) — A second task type, whose coroutines a stop ends at their current co_await with no checks.

Other Programs in the Repository

These programs have no page of their own. Some need an optional compiler or library, and some only check that code compiles.

Directory What it is How it is built

Directory	What it is	How it is built
`asio/any_stream.cpp`	Stream algorithms written against a header with no Asio includes. The Dimovian Ideal walks through it.	The `capy_example_any_stream` target, when a `Boost::asio` target exists, or the `b2` target `any_stream`
`awaitable-sender/`	A Capy awaitable wrapped as a `stdexec` sender, the reverse of Bridging a P2300 Sender	`BOOST_CAPY_BUILD_P2300_EXAMPLES=ON` and C++23. The build fetches NVIDIA stdexec. Its test is `capy_example_awaitable_sender_test`.
`any-sender-size/`	A measurement of the operation state of `exec::any_sender`, and of the heap allocations made by `connect` and `start`	The same flag as `awaitable-sender/`. Its test is `capy_example_any_sender_size`.
`fabrics/`	Compile-only listings from P4251R0 for HPC fabric libraries	The default build. Each fabric check builds when the build finds its library.
`cuda/batched-write/`	A batched `write_some` to a CUDA device stream	`BOOST_CAPY_BUILD_CUDA_EXAMPLES=ON`, C++20, and the CUDA toolkit. Its test is `capy_example_cuda_batched_write`.
`cuda/datamovement/`	Compile-only CUDA data-movement listings from P4251R0	The CUDA flag
`cuda/notification-strategies/`	One GPU completion, awaited in three different ways	The CUDA flag
`cuda/pipeline/`	Capy tasks and senders on the `stream_scheduler` of NVIDIA `nvexec`	The CUDA flag, plus `BOOST_CAPY_BUILD_NVEXEC_EXAMPLES=ON`. That flag needs `BOOST_CAPY_BUILD_STDEXEC_EXAMPLES=ON` and C++23.
`echo-server-corosio/`	An echo server on Corosio	The default build, when a `Boost::corosio` target exists, or its own `Jamfile`
`when-any-cancellation/`	A race of three data sources with `when_any`. Out of date: its comments say that the first child to complete wins, and its losing children report success. For the current rules, see The canceled Convention and Timeout with Cancellation.	The default build, or `b2`

asio/any_stream.cpp

Stream algorithms written against a header with no Asio includes. The Dimovian Ideal walks through it.

The capy_example_any_stream target, when a Boost::asio target exists, or the b2 target any_stream

awaitable-sender/

A Capy awaitable wrapped as a stdexec sender, the reverse of Bridging a P2300 Sender

BOOST_CAPY_BUILD_P2300_EXAMPLES=ON and C++23. The build fetches NVIDIA stdexec. Its test is capy_example_awaitable_sender_test.

any-sender-size/

A measurement of the operation state of exec::any_sender, and of the heap allocations made by connect and start

The same flag as awaitable-sender/. Its test is capy_example_any_sender_size.

fabrics/

Compile-only listings from P4251R0 for HPC fabric libraries

The default build. Each fabric check builds when the build finds its library.

cuda/batched-write/

A batched write_some to a CUDA device stream

BOOST_CAPY_BUILD_CUDA_EXAMPLES=ON, C++20, and the CUDA toolkit. Its test is capy_example_cuda_batched_write.

cuda/datamovement/

Compile-only CUDA data-movement listings from P4251R0

The CUDA flag

cuda/notification-strategies/

One GPU completion, awaited in three different ways

The CUDA flag

cuda/pipeline/

Capy tasks and senders on the stream_scheduler of NVIDIA nvexec

The CUDA flag, plus BOOST_CAPY_BUILD_NVEXEC_EXAMPLES=ON. That flag needs BOOST_CAPY_BUILD_STDEXEC_EXAMPLES=ON and C++23.

echo-server-corosio/

An echo server on Corosio

The default build, when a Boost::corosio target exists, or its own Jamfile

when-any-cancellation/

A race of three data sources with when_any. Out of date: its comments say that the first child to complete wins, and its losing children report success. For the current rules, see The canceled Convention and Timeout with Cancellation.

The default build, or b2

BOOST_CAPY_BUILD_CUDA_EXAMPLES=ON adds all four cuda/ programs at once, cuda/pipeline included. So a build with that flag also needs the cuda/pipeline flags, or its configure step fails. Those flags are BOOST_CAPY_BUILD_NVEXEC_EXAMPLES=ON and BOOST_CAPY_BUILD_STDEXEC_EXAMPLES=ON, with C++23.

Edit this Page