February 2026 - Boost - lists.boost.org

Building boost-python for pyodide/emscripten
by fxcoudert＠ik.me 23 Feb '26

23 Feb '26

Hello, I'm working on adding boost-python to the pyodide distribution (https://github.com/pyodide/pyodide-recipes/pull/513) i.e., compile boost-python with emscripten. My bootstrap command is: ./bootstrap.sh --prefix=${INSTALL_DIR} --with-libraries=python --with-python=python$PYMAJOR.$PYMINOR It seems to detect the Python install in the correct env: Detecting Python version... 3.13 Detecting Python root... /home/runner/miniconda3/envs/pyodide-env The b2 command is a bit more complex, but it works for a lot of other boost libraries: ./b2 variant=release toolset=clang-emscripten link=static threading=single --disable-icu \ cxxflags="$SIDE_MODULE_CXXFLAGS -fwasm-exceptions -DBOOST_SP_DISABLE_THREADS=1" \ cflags="$SIDE_MODULE_CFLAGS -fwasm-exceptions -DBOOST_SP_DISABLE_THREADS=1" \ linkflags="-fpic $SIDE_MODULE_LDFLAGS" \ python=$PYMAJOR.$PYMINOR \ --layout=system -j"${PYODIDE_JOBS:-3}" --prefix=${INSTALL_DIR} \ -d2 install It says: - python : building which seems good, but then the only thing it installs are cmake files: /home/runner/work/pyodide-recipes/pyodide-recipes/packages/.libs /home/runner/work/pyodide-recipes/pyodide-recipes/packages/.libs/lib /home/runner/work/pyodide-recipes/pyodide-recipes/packages/.libs/lib/cmake /home/runner/work/pyodide-recipes/pyodide-recipes/packages/.libs/lib/cmake/Boost -1.84.0 /home/runner/work/pyodide-recipes/pyodide-recipes/packages/.libs/lib/cmake/Boost -1.84.0/BoostConfigVersion.cmake /home/runner/work/pyodide-recipes/pyodide-recipes/packages/.libs/lib/cmake/Boost -1.84.0/BoostConfig.cmake /home/runner/work/pyodide-recipes/pyodide-recipes/packages/.libs/lib/cmake/Boost DetectToolset-1.84.0.cmake The libraries I expect, libboost_python and the numpy module, are not installed. I don't think they're compiled at all, but there is no error. Do you have any idea what I am missing? Thanks, FX

1 0

Capy: Request for endorsements
by Vinnie Falco 20 Feb '26

20 Feb '26

Hi. We are proposing a new library "Capy" as a candidate library and seeking endorsements for formal review: https://github.com/cppalliance/capy https://master.capy.cpp.al/capy/index.html This library provides facilities which use C++20 coroutines to perform I/O. It is not a networking library, yet it is the perfect foundation upon which networking libraries, or any libraries that perform I/O, may be built. It introduces concepts for representing buffers of data, and moving those buffers of data through processing pipelines driven entirely by C++20 coroutines. The design of the library is based on one simple observation from Peter Dimov: An API designed from the ground up to use C++20 coroutines can achieve performance and ergonomics which cannot otherwise be obtained. Capy is currently the foundation for another new library (not yet proposed) called "Corosio" https://github.com/cppalliance/corosio https://master.corosio.cpp.al/corosio/index.html Corosio is a complete portable networking library which is built on the facilities that Capy offers. We intend to propose this library soon as the successor to the immensely popular Boost.Asio library. Capy is also the foundation for yet another new library (not yet proposed) called "Http" https://github.com/cppalliance/http https://master.http.cpp.al/http/index.html The Http library uses Capy, yet does not use Corosio. That is because Http is "Sans/IO." It provides the algorithms and data structures which implement the HTTP protocol at a high level, while remaining agnostic to the particular network implementation. This is possible thanks to the powerful stream abstractions which Capy offers. Capy is also used by Beast2, which is yet another new library (not yet proposed) and also the name for a family of libraries: https://github.com/cppalliance/beast2 Beast2 uses the Capy, Corosio, and Http libraries to implement high-level HTTP servers written in a C++ version of Express JS routers. This is the successor to Boost.Beast (which will continue to be maintained independently ). The Beast2 family of libraries includes: Capy — The library currently being proposed, the foundation of I/O. Corosio — Coroutine-only portable networking. This is the successor to Boost.Asio. Http — Sans-I/O HTTP/1.1. This is a high-level library: servers, clients, Express JS middleware. Websocket — Sans-I/O Websocket. This is also a high-level library. Beast2 — High-level HTTP and WebSocket servers. Express.js-style routing Burl — High-level HTTP client. curl features, coroutine ergonomics of coroutines, and Python Requests inspired API Currently, the C++ Standard does not deliver facilities optimized for networking I/O. We believe that Capy should become a standard library component to fill this gap. Our first paper based on Capy, introduces the " IoAwaitable" family of concepts: https://github.com/cppalliance/wg21-papers/blob/master/source/d4003-io-awai… The Beman Way We are bringing Capy to Boost because this is what Boost was created for. The project exists to incubate high-quality libraries destined for standardization. Beman Dawes founded Boost on the principle that the best path to the standard is through proven practice: build it, ship it, let users depend on it, learn from real-world feedback, then propose standardization. Smart pointers, regular expressions, filesystem, threading primitives—all followed this path from Boost to the standard library. Capy represents Boost returning to its role as a leader in C++ standardization efforts. The library addresses a real gap in C++26: there is no standard foundation optimized for coroutine-based I/O. Rather than waiting for a committee to design something in the abstract, or adapting networking to a framework built for different requirements, Capy takes the proven approach. It exists. It works. It powers real networking code today. Now it needs the scrutiny and refinement that only the Boost review process can provide. The Problem Capy Solves When an I/O operation completes, the operating system wakes up some thread, such as a completion port thread, an epoll reactor, or an io_uring worker. Without affinity tracking, your coroutine resumes on that arbitrary thread, forcing you to add synchronization everywhere or risk data races. This is the fundamental problem that coroutine-based networking must solve. Capy's answer is the IoAwaitable protocol. When you launch a coroutine with a designated executor, every child coroutine inherits that executor affinity automatically. Execution context flows forward through `co_await` chains, not backward through P3826 queries, to ensure every coroutine in the chain runs in the same context. When I/O completes on some OS thread, the IoAwaitable protocol ensures your coroutine resumes on its designated executor. The data flow is explicit and testable. There are no thread-local globals, no implicit context, no surprises. Capy's `task` type uses the compiler to enforce invariants. Cancellation follows the same forward-propagation model. Stop tokens flow forward from the launch of a coroutine chain alongside the execution context, to arrive at the platform API boundary, providing a uniform cancellation interface across all operations. Frame allocation is where coroutine overhead traditionally hurts performance. Capy addresses this with thread-local recycling pools that achieve zero steady-state allocations after warmup. The coroutine launch site controls allocation policy, enabling per-deployment customization: bounded pools for real-time systems, per-tenant budgets for multi-tenant servers, or tracking allocators for debugging. Buffer handling is essential for networking, and Asio's twenty five years of experience showed us how. Capy provides buffer sequence algorithms: think `std::ranges` but for buffers. These are the vocabulary types and operations that networking code needs: slicing, copying, concatenating, and iterating over discontiguous memory. One million scatter/gather buffers, if you will. The design is driven by real-world usage, not theoretical completeness. Capy is opinionated on the things that matter for I/O: - An executor model for coroutine affinity and completion dispatch - Stop token integration: uniform cancellation, always available - Allocator control over frame allocation with zero-overhead recycling - Forward propagation of the full context through every `co_await` - A `task` type that enforces the _IoAwaitable_ protocol at compile time - Composition primitives for launching and coordinating coroutines - A strand for safe concurrency without mutexes - Buffer sequences: `std::ranges` for untyped bytes - Type erasure by default: no combinatorial explosion of templates Proven Through Corosio Capy is not speculation. It powers Corosio, a coroutine-only networking library that we are developing together. Corosio provides real sockets, acceptors, TLS streams, timers, DNS resolution, and multiple implementations of SSL streams, all built on Capy's foundation. This is the successor library to the incredibly popular Boost.Asio. It demonstrates what networking could look like if designed for coroutines from the start rather than adapted from callback-based models. The standardization strategy follows from this layering. Capy is the foundation piece that belongs in the standard: executor model, task types, buffer algorithms, cancellation integration. These are stable abstractions that networking libraries can build upon. Corosio, the networking piece, can remain outside the standard to mitigate risk: sockets and protocol implementations typically experience difficulty achieving consensus even after years of committee attention. Corosio can mature externally where it can evolve based on user feedback, while Capy provides the stable foundation that the standard library lacks. Call to Action We are requesting endorsements from Boost members to proceed with formal review. If you believe that Boost should provide a foundation for coroutine-based I/O—and that proven practice is the right path to standardization, your endorsement would be welcomed. The team is also happy to receive feedback on the design, the implementation, and the documentation. The library is ready for serious evaluation. Clone it, build it, write code against it, and tell us what works and what does not. This is Boost doing what Boost does best: building the libraries that C++ needs, proving them in practice, and paving the way for standardization. Distributed under the Boost Software License, Version 1.0. (See accompanying file [LICENSE_1_0.txt](LICENSE_1_0.txt) or copy at https://www.boost.org/LICENSE_1_0.txt)

18 66

Porting Boost.Redis to Corosio and Capy
by Ruben Perez 19 Feb '26

19 Feb '26

Hi all, As you might remember, last week I endorsed Vinnie's Capy+Corosio submission and promised to talk about how I had managed to port Boost.Redis to use these libraries [1] [2]. This is the post. It's somehow a mini-review. Warning label: it might be a little lengthy. Disclaimer: I'm affiliated with the C++ Alliance. I'm trying to write this as a potential user, rather than as an Alliance member. Why Boost-Redis =============== As you might know, I authored Boost.MySQL and co-maintain Boost.Redis with Marcelo. I chose Boost.Redis because it has a smaller API surface than MySQL, while still exercising similar functionality regarding networking. Note that Boost.Redis is a high-level library. In addition to parsing and serializing messages, it manages connection lifecycle, automatically reconnects on failure, pipelines multiple requests into a single round trip when possible, and handles health-check pings to detect dead connections. Library requirements ==================== A library like this requires lots of networking and concurrency primitives, like: * Reading and writing data. * Establishing TCP connections. * Establishing UNIX domain socket connections. * TLS. * Cancellation. * Running tasks in parallel. * Waiting for events to happen (e.g. "block my task until the user submits a new request"). * Waiting periods of time (timers). * Setting timeouts to operations. Some of these primitives (like timers) are only present in Corosio, so using Capy alone isn't an option. This is one of the reasons why I endorse having them reviewed together. I understand the rationale behind keeping them separate, but users like me benefit the most if both of them are present. Porting strategy ================ If you've ever written universal Asio async operations, you might know that Asio's composition mechanism, async_compose, is hard. It works, but it leads to heavily templated code, lengthy compiler errors, and code difficult to test. For this reason, most of Boost.Redis code today is written as finite-state machines (FSMs) that decouple logic from I/O. The FSM is a hand-wired generator that yields actions (i.e. "what should I do next? read from the server? write data? wait?"). The I/O layer just executes these actions. [3] is the FSM for the task that reads data from the server, with [4] being its I/O layer. This is the code as it is today. This disposition has made the port pretty straightforward. You just need to replace the I/O layer with Corosio's primitives and go. The reader becomes [5]. Code managing connection establishment required slightly more work, but nothing unsurmountable. I've ported some integration tests, too [9] to prove that the port works. There is still much to do on my side here, though. The port is currently functional, but it could use some refactoring. Coroutines enable separate compilation where universal Asio doesn't, and we could make improvements here. More on this later though. Mapping Asio to Capy/Corosio ============================ Let's go over the primitives I've exercised and how well things have gone. * Reading and writing data: I'd say this is Capy's specialty. Primitives map cleanly. Capy has a clean stream model here, with optional type erasure, that makes things simple. Nothing to object. * Establishing TCP connections: most of it maps well. Some considerations here: * You need Corosio to achieve this. With the current design, I think this is reasonable today. * Only IPv4 is currently supported [6]. Socket opening semantics need better definition. * Range connect [7] is missing [8]. This is practical because hostname resolutions yields a range of endpoints, rather than a single one. This is however trivially implementable by users thanks to coroutines, so it isn't critical. * Establishing UNIX domain socket connections: this is not supported at the moment [10]. * TLS. I'm particularly happy here. Corosio defines a tls_stream base class, with concrete implementations, like openssl_stream or wolfssl_stream. This traditional OOP approach is possible because of coroutines. Many of our users run Redis in trusted networks, inside Docker containers, over plain TCP. They shouldn't have to link OpenSSL if they don't use it. In the current Asio-based version, this is not possible without heavy templating or config macros. We've been requested to implement this a number of times, but it's ugly. With Corosio we could do it. * Cancellation. Capy's model here is simpler than Asio's: * Asio has three cancellation types with potentially different semantics: terminal, partial and total. Capy has just one. I think this is the right choice. None of the libraries I work on really require more than this. And uncommon cases can be modeled as a combination of when_all, when_any, and async_event primitives. * Asio's cancellation handlers are stateless. Cancellation state is held by async_compose. Cancellation state is required because a cancellation might arrive after an operation finishes, but before its completion handler runs. The consequence is that you need to check your operation's cancellation state manually after every async primitive. If you forget one, you get an insidious bug [11]. Capy cancellation uses std::stop_token, which is stateful. This mostly removes this problem, which is good. * Asio's cancellation handlers are not thread-safe by default. This leads to insidious surprises. Capy cancellation is thread-safe by default. I don't know if there is any performance penalty here, but it's probably the best choice. * Note: correct and universal cancellation semantics are mandatory to get the next point right. Primitives like when_any don't make sense if one of the operations can't be reliably cancelled. * Running tasks in parallel. Also happy here. Capy has when_any and when_all, similar to Asio's parallel groups. Parallel groups in Asio are still experimental and may create problems with certain config macros, so it's a win here, too. * Note: when_any and when_all are actually a subset of what can be achieved with Asio's parallel group. I don't think this is a problem though. It is the most useful subset. Anything else can be expressed in terms of them + async_event. * Synchronization primitives (i.e. "waiting for events to happen"). Capy has async_mutex [12] and async_event [13]. Asio has none of these, and you need to either implement them using channels (experimental), or timers (you set the timer expiration to infinity, then cancel the timer to signal the event). These are both workarounds and don't capture user intention. I can't stress enough the importance of having a working async_event, especially for higher-level libraries like Redis. It's a fundamental building block. * Waiting periods of time (timers). These are similar to Asio's steady_timer. Other timer types are not supported. None of the libraries I work on need anything else, so I'm satisfied. * Something I'd explore is a standalone sleep(steady_clock::duration) function. It might be ergonomic in some cases. * Setting timeouts to operations. Asio implements this with the cancel_after [14] and cancel_at [15] completion tokens, which we use in Redis. These are absent from Corosio [16]. I've done a quick-and-dirty implementation [17], but this should be extended by the library to support custom awaitables (and not only capy::task). Separate compilation ==================== One of the key benefits of the proposed model is separate compilation (note how the port's connection implementation lives in an .ipp file, which ends up in a single TU). The libraries have no config macros, which I like. Having them creates a lot of problems for separate compilation (this is why we have .ipp files instead of regular TUs in Redis today). Type erasure has probably some performance implications, which I haven't evaluated. A database library like Boost.Redis is probably not going to see any significant impact here. We get performance from reducing round-trips to the server. This kind of performance impact is probably more relevant to domains like high-frequency trading, but I can't add anything here. Error handling ============== Asio has a built-in error_code to exception transformation. If you have an async_write operation accepting a completion handler of void(error_code, std::size_t), when using coroutines, you get: // error_code is swallowed. This throws if the error_code indicates failure std::size_t bytes = co_await async_write(...); This is good for tutorials but probably not what you want for production, since I/O errors are not exceptional. So you end up writing: // doesn't throw, check ec manually auto [ec, bytes ] = co_await async_write(..., asio::as_tuple); Capy doesn't support this. I think this is the right choice, because it's simpler and leads to code following best practice. Executors and associated properties =================================== In Asio, every completion token has a set of associated properties: executor, immediate executor, allocator and cancellation slot. When writing composed operations, you need to make sure to propagate this. This is not trivial with callbacks, since passing a lambda by default doesn't achieve it. Capy stores most of this in a an io_env structure. Task frames hold a pointer to such structure. The result is that propagation happens by default. I haven't had to think much about this, which is a good sign. Capy has functions to launch coroutines with a different environment. I haven't had to use these yet, but I will likely need them when writing multi-threaded examples for Redis. Having them is required. Windows-specific I/O ==================== While Redis doesn't, MySQL supports communication over Windows named pipes. We don't have this working in Boost.MySQL yet, but Asio's windows::stream_handle [18] probably helps here. It's not a high-priority thing, but it would be nice having it on the horizon. Buffers ======= Capy provides many utilities to work with buffers. I think the most useful utilities here are the concrete buffer types, like beyond my needs, but I want to highlight the concrete buffer types, like circular_dynamic_buffer [19]. I miss here an equivalent to Beast's flat_buffer [20] [23]. At the moment, concrete buffer types are: * circular_dynamic_buffer. As I said, very useful. * flat_dynamic_buffer. This is non-allocating, and never frees space with memmove. This is a problem if the server sends a stream of small messages, since there is no guarantee of message boundaries. * dynamic_string_buffer and dynamic_vector_buffer. These are similar to Asio's. Protocols handling many small messages can't use these because they cause data to move with every consumed message. Buffer sequence type erasure is split between Corosio and Capy. There are two classes doing essentially the same job, and when I tried to write a generator that returns a buffer sequence as a concrete type, I found the story fragmented. A single unified type would simplify things. I don't have a strong opinion on where it should live, but having one answer instead of two would help. Asio interoperability ===================== The ASIO interop layer has friction. The executor adapter translates a dispatch call into an `async_post` internally [22], which isn't correct. When you dispatch in ASIO, the expectation is that if you're already on the right executor, the function runs inline. Turning that into a post adds unnecessary overhead and breaks the expected semantics. The boundary between ASIO and Corosio needs to be smoother if we want incremental adoption, and we do want incremental adoption because no one is going to rewrite their entire stack at once. Final thoughts ============== The port succeeded, and this is enough to earn my endorsement. Most coroutine code is cleaner than the one written for universal Asio, which is good. I've found bugs, but Vinnie's team has addressed them already. I intend to port the rest of the tests and likely Boost.MySQL at some point, which will exercise more parts of the API. I hope to see these libraries in Boost in the future. Congratulations reading (or skipping) until here, you're a really tenacious reader. Regards, Ruben. [1] https://lists.boost.org/archives/list/boost@lists.boost.org/thread/DNTZBH7O… [2] https://github.com/anarthal/boost-redis/tree/feature/corosio [3] https://github.com/boostorg/redis/blob/b7b93c96dae038f7817d653a35e7225b83d3… [4] https://github.com/boostorg/redis/blob/b7b93c96dae038f7817d653a35e7225b83d3… [5] https://github.com/anarthal/boost-redis/blob/16464517dc1b47107504b0d9480548… [6] https://github.com/cppalliance/corosio/issues/128 [7] https://www.boost.org/doc/libs/latest/doc/html/boost_asio/reference/async_c… [8] https://github.com/cppalliance/corosio/issues/124 [9] https://github.com/anarthal/boost-redis/blob/16464517dc1b47107504b0d9480548… [10] https://github.com/cppalliance/corosio/issues/122 [11] https://github.com/boostorg/mysql/issues/454 [12] https://github.com/cppalliance/capy/blob/8bcc0fa3753d7ebf80f28379865d987e8d… [13] https://github.com/cppalliance/capy/blob/8bcc0fa3753d7ebf80f28379865d987e8d… [14] https://www.boost.org/doc/libs/latest/doc/html/boost_asio/reference/cancel_… [15] https://www.boost.org/doc/libs/latest/doc/html/boost_asio/reference/cancel_… [16] https://github.com/cppalliance/corosio/issues/141 [17] https://github.com/anarthal/boost-redis/blob/16464517dc1b47107504b0d9480548… [18] https://www.boost.org/doc/libs/latest/doc/html/boost_asio/reference/windows… [19] https://github.com/cppalliance/capy/blob/8bcc0fa3753d7ebf80f28379865d987e8d… [20] https://github.com/boostorg/beast/blob/develop/include/boost/beast/core/fla… [21] https://github.com/cppalliance/capy/blob/8bcc0fa3753d7ebf80f28379865d987e8d… [22] https://github.com/cppalliance/capy/blob/8bcc0fa3753d7ebf80f28379865d987e8d… [23] https://github.com/cppalliance/capy/issues/168

3 2

Code coverage reports
by Sam Darwin 16 Feb '26

16 Feb '26

Still in development, but actually the first iteration is functional. Run coverage reports using gcovr + github pages. No Codecov. To explain more: imagine Codecov-like coverage reports, except they are built with an open source software tool "gcovr". Hosted on Github Pages, and you have potentially more control over the output, the steps, the appearance, etc. since the script is customizable. Instructions: https://github.com/boostorg/boost-ci/blob/master/docs/code-coverage.md

4 4

Capy and Corosio: my endorsement
by Ruben Perez 14 Feb '26

14 Feb '26

Hi all, I've recently been playing with the "Asio 2" libraries that Vinnie has proposed (Capy and Corosio). I've managed to port Boost.Redis to Corosio, with pretty good results. You can find my port here: https://github.com/anarthal/boost-redis/tree/feature/corosio Some particularly interesting files here: * Connection: much cleaner and no longer templated: https://github.com/anarthal/boost-redis/blob/feature/corosio/include/boost/… * Connection implementation: https://github.com/anarthal/boost-redis/blob/feature/corosio/include/boost/… * Usage example: https://github.com/anarthal/boost-redis/blob/feature/corosio/example/cpp20_… The port is functional (although still a prototype), and this alone makes me endorse the proposed libraries. If the libraries get to Boost, I will consider either offering a Capy/Corosio interface for Boost.Redis, or proposing the port as a new library (if Boost.Redis' author agrees). Disclaimer: I'm affiliated with the C++ Alliance. I'm trying to speak here as one of the maintainers of Boost.Redis and a potential user, rather than an employee. I intend to submit a more detailed report on my experience with the port next week, in case someone's interested. Thanks Vinnie for proposing the libraries. Regards, Ruben.

3 2

Re: Capy: Request for endorsements
by Richard 13 Feb '26

13 Feb '26

In article < <CA+EzHGceSqA12Ar_LAkx2VWH9=j522Dix1dCByDj1qHJEBvpvQ(a)mail.gmail.com>> you write: >I'm updating the endorsement request accordingly. If you believe Boost >should provide a coroutine-based I/O foundation and a networking library >built on top of it, your endorsement for a joint Capy + Corosio review >would be welcome. I would like to see such a review take place! -- "The Direct3D Graphics Pipeline" free book <http://tinyurl.com/d3d-pipeline> The Terminals Wiki <http://terminals-wiki.org> The Computer Graphics Museum <http://computergraphicsmuseum.org> Legalize Adulthood! (my blog) <http://legalizeadulthood.wordpress.com>

1 0

[container] New segmented_vector container
by Ion Gaztañaga 09 Feb '26

09 Feb '26

Hi, I'd like to share the addition of a new (mostly refactored) sequence container to Boost.Container: segmented_vector. https://www.boost.org/doc/libs/develop/doc/html/doxygen/boost_container_hea… What it is --------- segmented_vector is the single-ended counterpart of boost::container::deque, a sequence container that supports random access to elements, constant-time insertion and removal at the end, and linear-time insertion and removal in the middle. It uses the same segmented (block-based) storage as deque but only allows growth at the back: it provides push_back, pop_back, emplace_back, and the like, but does not provide push_front, pop_front, or emplace_front. "seque" was not an appropriate name as this container is not a "queue" (tipically a FIFO queue), but I'm open to renaming the container if a better name is proposed ;-) The initial idea was to add a "single_ended" option to "deque" but that would be too confusing. Implementation notes ------------------- segmented_vector is implemented on top of the same internal machinery as deque (with a single-ended policy optimization), so it shares the same allocation and indexing logic. sizeof(segmented_vector) is 3 words, reduced to 2 words in 64 bit machines if stored_size<uint32_t> option is used. Features ------- - Random-access iterators and the usual sequence interface (size, operator[], at, iterators, etc.). - Amortized O(1) push_back, pop_back, emplace_back; O(n) insert/erase in the middle. - Segmented storage: elements live in fixed-size segments (blocks) instead of one contiguous buffer. New segments are allocated as needed when the container grows, so there is no single large reallocation or bulk move of elements as with std::vector. This can reduce peak memory and improve performance when elements are expensive to move or when growth is large. - Iterator and reference stability: inserting or erasing at the end does *not* invalidate iterators or references/pointers to existing elements. Insertions and erasures in the middle invalidate iterators and references in the same way as for deque. Options ------------------- It supports the same options as deque (stored_size, block-size), I'm experimenting with a "reservable" option that allows "capacity/reserve" support both for segmented_vector and deque. Best, Ion

6 14

[spirit] Stepping down as Spirit maintainer
by Nana Sakisaka 06 Feb '26

06 Feb '26

Dear Boost Community, Today I am writing to inform you that I am resigning as the maintainer of Boost.Spirit, effective immediately. In autumn 2024, I began C++23 modernization work on Spirit, planned as a gradual improvement over the existing C++17-based code. However, this effort was strongly discouraged within the Boost community, which resulted in the repository being split into a separate project: `boostorg/spirit_x4` (*). (*) https://lists.boost.org/archives/list/boost@lists.boost.org/thread/K3EQLEQJ… Due to the accusations and personal attacks I received, primarily on the mailing list and also in some GitHub issues, I have been experiencing panic attacks for the past three months. I am unable to open GitHub notifications because they trigger flashbacks. I have not been able to write a single line of code since October. I am on medication, and my doctor says the only practical solution is for me to step away from what is causing the stress. I have to admit that splitting the repository was the worst decision which I was effectively forced to make, and it has done little more than fragment the community. But that has already happened. The existing `boostorg/spirit_x4` repository is, in effect, already a fork. Given that, I do not see why I should continue developing it within this organization. I would prefer to simplify the governance by moving the project under my own organization, rather than continuing to deal with conflicts of interest in a larger community. I have already shared my current status with Joel de Guzman, the original author of the library, and he is aware that I plan to fork. Thanks, Nana Sakisaka

6 5

Re: The C++ Alliance Monthly Newsletter – January 2026
by Mateusz Loskot 06 Feb '26

06 Feb '26

> Boost.GIL Maintenance Restarted > Maintainers: Stefan Seefeld & Mateusz Łoskot Here, I'd like to give a huge shout out to Samuel Debionne (https://github.com/sdebionne) who deserves to be named an active maintainer of GIL more than anyone else recently. Thank you Samuel! Regards, Matt Loskot On Wed, 4 Feb 2026 at 17:41, Mark Cooper via Boost <boost(a)lists.boost.org> wrote: > > Hello everyone, > > Attached is our first C++ Alliance newsletter. There's a lot happening at > the Alliance, and we want to keep the Boost community in the loop. A few > highlights: > > - We're investing in Clang's future > - We're rethinking C++ networking from the ground up > - And we're bringing something special to CppCon 2026 > > Take a look! > > Mark > _______________________________________________ > Boost mailing list -- boost(a)lists.boost.org > To unsubscribe send an email to boost-leave(a)lists.boost.org > https://lists.boost.org/mailman3/lists/boost.lists.boost.org/ > Archived at: https://lists.boost.org/archives/list/boost@lists.boost.org/message/NV457GW… -- Mateusz Loskot, http://mateusz.loskot.net

3 3

Re: The C++ Alliance Monthly Newsletter – January 2026
by Dominique Devienne 05 Feb '26

05 Feb '26

On Wed, Feb 4, 2026 at 5:43 PM Mark Cooper via Boost <boost(a)lists.boost.org> wrote: > Attached is our first C++ Alliance newsletter. Thanks. I suggest that in the future you host it on your web-site, and offer pure-web alternatives instead of PDF only. I'm surprised the ML even allows 2MB attachments, to be honest. Announcing it here is more than fine. Embedding it into an email distributed to hundreds, not so much. My $0.02. --DD

3 3

Re: The C++ Alliance Monthly Newsletter – January 2026
by Peter Dimov 04 Feb '26

04 Feb '26

Mark Cooper wrote: > Hello everyone, > > Attached is our first C++ Alliance newsletter. There's a lot happening at the > Alliance, and we want to keep the Boost community in the loop. A few > highlights: > > - We're investing in Clang's future > - We're rethinking C++ networking from the ground up > - And we're bringing something special to CppCon 2026 > > Take a look! Very nice work. Since the newsletter mentions upcoming 1.91 things, let me add that for Boost 1.91, Boost.UUID has obtained SIMD implementations of its from_chars and to_chars functions, written by Andrey Semashev, that improve performance substantially (up to 13 times) compared to the scalar versions. So if you like converting UUIDs from/to their string representations in tight loops, this would be the Boost release for you. :-)

2 1

Re: Capy: Request for endorsements
by Richard 03 Feb '26

03 Feb '26

In article < <CAHf7xWteO7nQazqXoXBXD24ytSjNAuyVcaC=gDjWYde7X2bdtw(a)mail.gmail.com>> you write: >It's also worth asking, was any of this largely coded by something such as >an LLM? ...and if any library, not just this one, had such content, what then? Crappy code written by humans has been around as long as humans have been writing code. So has good code written by humans. LLM coding agents are with us to stay. Code should be judged on it's intrinsic quality and not whether or not an LLM was used to create it. My IDE has coding agents built into it and they constantly make suggestions for completing code, writing code, etc. I judge these contributions myself and decide whether or not to accept them. In the end, you can't really tell how much of my code is written as suggested completions or as characters I typed myself. -- Richard -- "The Direct3D Graphics Pipeline" free book <http://tinyurl.com/d3d-pipeline> The Terminals Wiki <http://terminals-wiki.org> The Computer Graphics Museum <http://computergraphicsmuseum.org> Legalize Adulthood! (my blog) <http://legalizeadulthood.wordpress.com>

7 16

[container] New container proposal: boost::container::hub, request for endorsement
by Joaquin M López Muñoz 03 Feb '26

03 Feb '26

Hi, I've been writing and benchmarking (candidate) boost::container::hub, a nearly drop-in replacement of C++26 std::hive that has excellent performance: https://github.com/joaquintides/hub/blob/develop/README.md#performance (The reason I didn't name it "hive" is because hub is not 100% conformant to std::hive spec, details at the repo linked above.) Is there interest in having this in Boost? If so, please endorse the submission! As the codebase is fairly small (single 1800-LOC header), and due to the subject matter, my inclination is to propose it as part of Boost.Container rather than as a separate library. Happy to discuss this proposal and its technical details. Looking forward to your feedback. Best, Joaquín M López Muñoz

7 9

How to Understand C++ Coroutines from the Ground Up
by Vinnie Falco 02 Feb '26

02 Feb '26

I've been working on a family of libraries which are based on C++ 20 coroutines. I realize, that a lot of folks may not be familiar with this language feature as it is relatively new and the standard library also did not ship with the components needed to make use of the feature without additional third party libraries. I have worked up a tutorial to teach how to use coroutines. I hope someone finds this valuable. How To Understand C++20 Coroutines from the Ground Up <https://gist.github.com/vinniefalco/bbf1d9d3a720e8ad2ef8fe2e837cdfc9#how-to…> Introduction <https://gist.github.com/vinniefalco/bbf1d9d3a720e8ad2ef8fe2e837cdfc9#introd…> For over two decades, C++ programmers have wrestled with a fundamental challenge: how to write code that waits for things to happen without blocking everything else. Network requests need to complete. Files need to be read. User input must arrive. The traditional solutions—threads, callbacks, and state machines—each carry their own burden of complexity. Threads consume system resources and require careful synchronization. Callbacks scatter your logic across multiple functions. State machines bury simple ideas beneath layers of bookkeeping. C++20 introduces *coroutines*, a language feature that addresses this challenge directly. A coroutine is a function that can suspend its execution midway through, preserve its state, and resume later from exactly where it left off. This capability transforms the way you write asynchronous code, allowing you to express complex sequences of operations as straightforward, linear logic. In this tutorial, you will explore C++20 coroutines from the most basic concepts to practical implementations. You will begin by understanding the problem coroutines solve, then build your first coroutine step by step. By the end, you will have constructed a working generator type and understand the machinery that makes coroutines possible. Prerequisites <https://gist.github.com/vinniefalco/bbf1d9d3a720e8ad2ef8fe2e837cdfc9#prereq…> Before beginning this tutorial, you should have the following: - A C++ compiler with C++20 support (GCC 10+, Clang 14+, or MSVC 2019 16.8+) - Familiarity with basic C++ concepts: functions, classes, templates, and lambdas - Understanding of how function calls work: the call stack, local variables, and return values - A text editor or IDE configured for C++ development The examples in this tutorial use standard C++20 features. If using GCC, compile with: g++ -std=c++20 -fcoroutines your_file.cpp If using Clang, compile with: clang++ -std=c++20 your_file.cpp If using MSVC, enable C++20 in your project settings or compile with: cl /std:c++20 your_file.cpp Step 1 — Understanding the Problem Coroutines Solve <https://gist.github.com/vinniefalco/bbf1d9d3a720e8ad2ef8fe2e837cdfc9#step-1…> Before diving into coroutines, you must understand why they exist. Consider a server application that needs to handle an incoming network request. The server must read the request from the network, parse it, possibly read from a database, compute a response, and send that response back. Each of these steps might take time to complete. In traditional synchronous code, you might write something like this: void handle_request(connection& conn) { std::string request = conn.read(); // blocks until data arrives auto parsed = parse_request(request); auto data = database.query(parsed.id); // blocks until database responds auto response = compute_response(data); conn.write(response); // blocks until write completes } This code reads naturally from top to bottom. The logic flows in a straight line. But there is a problem: while waiting for the network or database, this function blocks the entire thread. If you have thousands of concurrent connections, you would need thousands of threads, each consuming memory and requiring the operating system to schedule them. The traditional alternative uses callbacks: void handle_request(connection& conn) { conn.async_read([&conn](std::string request) { auto parsed = parse_request(request); database.async_query(parsed.id, [&conn](auto data) { auto response = compute_response(data); conn.async_write(response, [&conn]() { // request complete }); }); }); } This code does not block. Each operation starts, registers a callback, and returns immediately. When the operation completes, the callback runs. But look what has happened to the code: three levels of nesting, logic scattered across multiple lambda functions, and local variables that cannot be shared between callbacks without careful lifetime management. David Mazières, in his exploration of C++ coroutines, described the pain of this approach vividly. In his SMTP server code, a single logical operation named cmd_rcpt had to be split across seven separate functions: cmd_rcpt, cmd_rcpt_0, cmd_rcpt_2, cmd_rcpt_3, cmd_rcpt_4, cmd_rcpt_5, and cmd_rcpt_6. Each function represented a different return point from an asynchronous operation. The logic of a single command was scattered across the codebase. Coroutines solve this problem by allowing you to write code that looks synchronous but behaves asynchronously: task<void> handle_request(connection& conn) { std::string request = co_await conn.async_read(); auto parsed = parse_request(request); auto data = co_await database.async_query(parsed.id); auto response = compute_response(data); co_await conn.async_write(response); } This code reads just like the original blocking version. The logic flows from top to bottom. Local variables like request, parsed, and data exist naturally in their scope. Yet the function suspends at each co_await point, allowing other work to proceed while waiting. The variable request maintains its value even though the function may suspend and resume multiple times. This is the fundamental capability that coroutines provide: the preservation of local state across suspension points. You have now seen the problem that coroutines solve. The callback approach fragments your logic. Coroutines restore the natural flow of code while maintaining asynchronous behavior. Step 2 — Recognizing Coroutines by Their Keywords <https://gist.github.com/vinniefalco/bbf1d9d3a720e8ad2ef8fe2e837cdfc9#step-2…> A coroutine in C++20 looks almost like a regular function. The difference lies in what appears inside the function body. A function becomes a coroutine when it contains any of three special keywords: co_await, co_yield, or co_return. The keyword co_await suspends the coroutine and waits for some operation to complete. When you write co_await expr, the coroutine saves its state, pauses execution, and potentially allows other code to run. When the awaited operation completes, the coroutine resumes from exactly where it left off. The keyword co_yield produces a value and suspends the coroutine. This is useful for generators—functions that produce a sequence of values one at a time. After yielding a value, the coroutine pauses until someone asks for the next value. The keyword co_return completes the coroutine and optionally provides a final result. Unlike a regular return statement, co_return interacts with the coroutine machinery to properly finalize the coroutine's state. Here is the simplest possible coroutine: #include <coroutine> struct SimpleCoroutine { struct promise_type { SimpleCoroutine get_return_object() { return {}; } std::suspend_never initial_suspend() { return {}; } std::suspend_never final_suspend() noexcept { return {}; } void return_void() {} void unhandled_exception() {} }; }; SimpleCoroutine my_first_coroutine() { co_return; // This makes it a coroutine } Do not worry about the promise_type structure yet. You will explore it in detail later. For now, observe that the presence of co_return transforms what looks like a regular function into a coroutine. If you try to compile a function with these keywords but without proper infrastructure, the compiler will produce errors. The C++ coroutine mechanism requires certain types and functions to exist. This is why the example includes the promise_type nested structure—it provides the minimum scaffolding the compiler needs. The distinction between regular functions and coroutines matters because they behave fundamentally differently at runtime: - A regular function allocates its local variables on the stack. When it returns, those variables are gone. - A coroutine allocates its local variables in a heap-allocated *coroutine frame*. When it suspends, those variables persist. When it resumes, they are still there. This persistence of state is what allows coroutines to pause and resume while maintaining their local variables. You have now learned to recognize coroutines by their keywords. The presence of co_await, co_yield, or co_return signals that a function is a coroutine with special runtime behavior. Step 3 — Understanding Suspension and Resumption <https://gist.github.com/vinniefalco/bbf1d9d3a720e8ad2ef8fe2e837cdfc9#step-3…> The heart of coroutines is the ability to suspend execution and resume it later. To understand how this works, you must examine what happens when a coroutine suspends. When you call a regular function, the system allocates space on the call stack for the function's local variables and parameters. When the function returns, this stack space is reclaimed. The function's state exists only during the call. When you call a coroutine, something different happens. The system allocates a *coroutine frame* on the heap. This frame holds the coroutine's local variables, parameters, and information about where execution should resume. Because the frame lives on the heap rather than the stack, it persists even when the coroutine is not actively running. Consider this example: #include <coroutine> #include <iostream> struct ReturnObject { struct promise_type { ReturnObject get_return_object() { return {}; } std::suspend_never initial_suspend() { return {}; } std::suspend_never final_suspend() noexcept { return {}; } void return_void() {} void unhandled_exception() {} }; }; struct Awaiter { std::coroutine_handle<>* handle_out; bool await_ready() { return false; } void await_suspend(std::coroutine_handle<> h) { *handle_out = h; } void await_resume() {} }; ReturnObject counter(std::coroutine_handle<>* handle) { Awaiter awaiter{handle}; for (unsigned i = 0; ; ++i) { std::cout << "counter: " << i << std::endl; co_await awaiter; } } int main() { std::coroutine_handle<> h; counter(&h); for (int i = 0; i < 3; ++i) { std::cout << "main: resuming" << std::endl; h(); } h.destroy(); } Output: counter: 0 main: resuming counter: 1 main: resuming counter: 2 main: resuming counter: 3 Study what happens in this example: 1. The main function calls counter, passing the address of a coroutine handle. 2. The counter coroutine begins executing. It prints "counter: 0" and then reaches co_await awaiter. 3. The co_await expression checks if the awaiter is ready by calling await_ready(). It returns false, so suspension proceeds. 4. The coroutine saves its state—including the value of i—to the coroutine frame. 5. The await_suspend method receives a handle to the suspended coroutine and stores it in main's variable h. 6. Control returns to main, which now holds a handle to the suspended coroutine. 7. The main function calls h(), which resumes the coroutine. 8. The coroutine continues from where it left off, increments i, prints its new value, and suspends again. 9. This cycle repeats until main destroys the coroutine. The variable i inside counter maintains its value across all these suspension and resumption cycles. It starts at 0, increments to 1, then 2, then 3. Each time the coroutine resumes, i is exactly where it was when the coroutine suspended. A std::coroutine_handle<> is a lightweight object, similar to a pointer. It references the coroutine frame on the heap. Calling the handle (using h() or h.resume()) resumes the coroutine. The handle does not own the coroutine frame—you must eventually call h.destroy() to free the memory. The Awaiter type in this example demonstrates the three methods that co_await uses: - await_ready(): Returns true if the result is immediately available and no suspension is needed. Returns false to proceed with suspension. - await_suspend(handle): Called when the coroutine suspends. Receives the coroutine handle, allowing external code to later resume the coroutine. - await_resume(): Called when the coroutine resumes. Its return value becomes the value of the co_await expression. The C++ standard library provides two predefined awaiters: std::suspend_always and std::suspend_never. As their names suggest, suspend_always::await_ready() always returns false (always suspend), while suspend_never::await_ready() always returns true (never suspend). You have now seen how suspension and resumption work. The coroutine frame preserves state on the heap, and the coroutine handle provides a way to resume execution. Step 4 — Understanding the Promise Type <https://gist.github.com/vinniefalco/bbf1d9d3a720e8ad2ef8fe2e837cdfc9#step-4…> Every coroutine has an associated *promise type*. This type acts as a controller for the coroutine, defining how it behaves at key points in its lifecycle. The promise type is not something you pass to the coroutine—it is a nested type inside the coroutine's return type that the compiler uses automatically. The compiler expects to find a type named promise_type nested inside your coroutine's return type. If your coroutine returns Generator<int>, the compiler looks for Generator<int>::promise_type. This promise type must provide certain methods that the compiler calls at specific points during the coroutine's execution. Here are the required methods: get_return_object(): Called to create the object that will be returned to the caller of the coroutine. This happens before the coroutine body begins executing. initial_suspend(): Called immediately after get_return_object(). Returns an awaiter that determines whether the coroutine should suspend before running any of its body. Return std::suspend_never{} to start executing immediately, or std::suspend_always{} to suspend before the first statement. final_suspend(): Called when the coroutine completes (either normally or via exception). Returns an awaiter that determines whether to suspend one last time or destroy the coroutine state immediately. This method must be noexcept. return_void() or return_value(v): Called when the coroutine executes co_return or falls off the end of its body. Use return_void() if the coroutine does not return a value; use return_value(v) if it does. You must provide exactly one of these, matching how your coroutine returns. unhandled_exception(): Called if an exception escapes the coroutine body. Typically you either rethrow the exception, store it for later, or terminate the program. The compiler transforms your coroutine body into something resembling this pseudocode: { promise_type promise; auto return_object = promise.get_return_object(); co_await promise.initial_suspend(); try { // your coroutine body goes here } catch (...) { promise.unhandled_exception(); } co_await promise.final_suspend(); }// coroutine frame is destroyed when control flows off the end This transformation reveals important details. The return object is created before initial_suspend() runs, so it is available even if the coroutine suspends immediately. The final_suspend() determines whether the coroutine frame persists after completion—if it returns suspend_always, you must manually destroy the coroutine; if it returns suspend_never, the frame is destroyed automatically. Consider this example that demonstrates promise type behavior: #include <coroutine> #include <iostream> struct TracePromise { struct promise_type { promise_type() { std::cout << "promise constructed" << std::endl; } ~promise_type() { std::cout << "promise destroyed" << std::endl; } TracePromise get_return_object() { std::cout << "get_return_object called" << std::endl; return {}; } std::suspend_never initial_suspend() { std::cout << "initial_suspend called" << std::endl; return {}; } std::suspend_always final_suspend() noexcept { std::cout << "final_suspend called" << std::endl; return {}; } void return_void() { std::cout << "return_void called" << std::endl; } void unhandled_exception() { std::cout << "unhandled_exception called" << std::endl; } }; std::coroutine_handle<promise_type> handle; }; TracePromise trace_coroutine() { std::cout << "coroutine body begins" << std::endl; co_return; } int main() { std::cout << "calling coroutine" << std::endl; auto result = trace_coroutine(); std::cout << "coroutine returned" << std::endl; } Output: calling coroutine promise constructed get_return_object called initial_suspend called coroutine body begins return_void called final_suspend called coroutine returned Notice that the promise is constructed first, then get_return_object() creates the return value, then initial_suspend() runs. Since initial_suspend() returns suspend_never, the coroutine body executes immediately. After co_return, return_void() is called, followed by final_suspend(). Since final_suspend() returns suspend_always, the coroutine suspends one last time, and the promise is not destroyed until the coroutine handle is explicitly destroyed. One important warning: if your coroutine can fall off the end of its body without executing co_return, and your promise type lacks a return_void() method, the behavior is undefined. This is a dangerous pitfall. Always ensure your promise type has return_void() if there is any code path that might reach the end of the coroutine body without an explicit co_return. You have now learned how the promise type controls coroutine behavior. The methods on the promise type let you customize initialization, suspension, value delivery, and cleanup. Step 5 — Building a Generator with co_yield <https://gist.github.com/vinniefalco/bbf1d9d3a720e8ad2ef8fe2e837cdfc9#step-5…> One of the most common uses for coroutines is building *generators*—functions that produce a sequence of values on demand. Instead of computing all values upfront and storing them in a container, a generator computes each value when requested. The co_yield keyword makes this pattern elegant. When a coroutine executes co_yield value, it delivers the value to its caller and suspends. The next time the coroutine resumes, it continues from just after the co_yield. Here is how co_yield works internally. The expression co_yield value is transformed by the compiler into: co_await promise.yield_value(value) The yield_value method is a new method you must add to your promise type. It receives the yielded value, typically stores it somewhere accessible, and returns an awaiter (usually std::suspend_always) to suspend the coroutine. Here is a complete generator example: #include <coroutine> #include <iostream> struct Generator { struct promise_type { int current_value; Generator get_return_object() { return Generator{ std::coroutine_handle<promise_type>::from_promise(*this) }; } std::suspend_always initial_suspend() { return {}; } std::suspend_always final_suspend() noexcept { return {}; } std::suspend_always yield_value(int value) { current_value = value; return {}; } void return_void() {} void unhandled_exception() { std::terminate(); } }; std::coroutine_handle<promise_type> handle; Generator(std::coroutine_handle<promise_type> h) : handle(h) {} ~Generator() { if (handle) handle.destroy(); } // Disable copying Generator(const Generator&) = delete; Generator& operator=(const Generator&) = delete; // Enable moving Generator(Generator&& other) noexcept : handle(other.handle) { other.handle = nullptr; } Generator& operator=(Generator&& other) noexcept { if (this != &other) { if (handle) handle.destroy(); handle = other.handle; other.handle = nullptr; } return *this; } bool next() { if (!handle || handle.done()) return false; handle.resume(); return !handle.done(); } int value() const { return handle.promise().current_value; } }; Generator count_to(int n) { for (int i = 1; i <= n; ++i) { co_yield i; } } int main() { auto gen = count_to(5); while (gen.next()) { std::cout << gen.value() << std::endl; } } Output: 1 2 3 4 5 Study the key parts of this example: The yield_value method stores the yielded value in current_value and returns suspend_always to pause the coroutine after each yield. The initial_suspend returns suspend_always, which means the coroutine suspends before executing any of its body. This is important—it means the first call to next() is what starts the coroutine running. The get_return_object method creates the Generator object and stores a handle to the coroutine. Notice the expression std::coroutine_handle<promise_type>::from_promise(*this). This static method creates a coroutine handle from a reference to the promise object. Since the promise object lives inside the coroutine frame at a known offset, this conversion is possible. The Generator class manages the coroutine handle's lifetime. The destructor calls handle.destroy() to free the coroutine frame. The class disables copying (copying handles would be problematic) but enables moving. The next() method resumes the coroutine and returns true if the coroutine produced a value, or false if the coroutine has completed. The value() method retrieves the most recently yielded value from the promise. Here is a more interesting generator that produces the Fibonacci sequence: Generator fibonacci() { int a = 0, b = 1; while (true) { co_yield a; int next = a + b; a = b; b = next; } } int main() { auto fib = fibonacci(); for (int i = 0; i < 10 && fib.next(); ++i) { std::cout << fib.value() << " "; } std::cout << std::endl; } Output: 0 1 1 2 3 5 8 13 21 34 The Fibonacci generator runs an infinite loop internally. It will produce values forever. But because it yields and suspends after each value, the caller controls when (and whether) to ask for more values. The generator only computes values on demand. This is the power of generators. The variables a and b persist across yields because they live in the coroutine frame on the heap. Each call to next() resumes the coroutine, which computes the next Fibonacci number, yields it, and suspends again. You have now built a working generator using co_yield. The promise type's yield_value method receives yielded values, and the Generator class provides an interface for retrieving them. Step 6 — Understanding Return Objects and Coroutine Handles <https://gist.github.com/vinniefalco/bbf1d9d3a720e8ad2ef8fe2e837cdfc9#step-6…> You have seen coroutine handles and return objects in previous examples. Now you will examine them more closely to understand their relationship and how information flows between them. A *coroutine handle* (std::coroutine_handle<>) is a lightweight object that refers to a suspended coroutine. It is similar to a pointer: it does not own the memory it references, and copying it does not copy the coroutine. You can resume the coroutine by calling the handle (using handle() or handle.resume()), query whether the coroutine has completed with handle.done(), and destroy the coroutine frame with handle.destroy(). The coroutine handle is a template. std::coroutine_handle<> (equivalent to std::coroutine_handle<void>) is the most basic form—it can reference any coroutine but provides no access to the promise object. std::coroutine_handle<PromiseType> is a more specific form that knows about a particular promise type. This typed handle can be converted to the void handle, and it provides a promise() method that returns a reference to the promise object. The *return object* is what the caller receives when calling a coroutine. It is the type that appears in the coroutine's declaration. When you write: Generator my_coroutine() { co_yield 42; } The return type is Generator, and when you call my_coroutine(), you receive a Generator object. The return object is created by calling promise.get_return_object() before the coroutine body begins. This happens early in the coroutine's lifecycle, giving the return object a chance to capture the coroutine handle. Here is the sequence: 1. The coroutine frame is allocated on the heap. 2. The promise object is constructed inside the frame. 3. promise.get_return_object() is called, creating the return object. 4. co_await promise.initial_suspend() executes. 5. The coroutine body begins (if initial_suspend did not suspend). 6. The return object is given to the caller. The key insight is that get_return_object() runs before initial_suspend(). This means: - If initial_suspend() returns suspend_always, the coroutine suspends before any user code runs, but the return object already exists and contains the coroutine handle. - If initial_suspend() returns suspend_never, the coroutine runs immediately, and the return object is still created first. Inside get_return_object(), you can obtain the coroutine handle using the static method coroutine_handle::from_promise(*this). Since get_return_object() is called on the promise object (as this), this method returns a handle to the coroutine containing that promise. Here is an example that demonstrates the relationship: #include <coroutine> #include <iostream> struct Task { struct promise_type { Task get_return_object() { std::cout << "Creating return object" << std::endl; return Task{ std::coroutine_handle<promise_type>::from_promise(*this) }; } std::suspend_always initial_suspend() { std::cout << "Initial suspend" << std::endl; return {}; } std::suspend_always final_suspend() noexcept { std::cout << "Final suspend" << std::endl; return {}; } void return_void() {} void unhandled_exception() {} }; std::coroutine_handle<promise_type> handle; Task(std::coroutine_handle<promise_type> h) : handle(h) {} ~Task() { if (handle) handle.destroy(); } Task(Task&& other) noexcept : handle(other.handle) { other.handle = nullptr; } void resume() { handle.resume(); } bool done() const { return handle.done(); } }; Task example_task() { std::cout << "Task body: part 1" << std::endl; co_await std::suspend_always{}; std::cout << "Task body: part 2" << std::endl; } int main() { std::cout << "Before calling coroutine" << std::endl; Task task = example_task(); std::cout << "After calling coroutine, before first resume" << std::endl; task.resume(); std::cout << "After first resume, before second resume" << std::endl; task.resume(); std::cout << "After second resume" << std::endl; } Output: Before calling coroutine Creating return object Initial suspend After calling coroutine, before first resume Task body: part 1 After first resume, before second resume Task body: part 2 Final suspend After second resume Follow the execution flow: 1. Before example_task() is called, nothing has happened. 2. Calling example_task() creates the coroutine frame, constructs the promise, and calls get_return_object(). 3. The return object (Task) is created with a handle to the coroutine. 4. initial_suspend() runs and returns suspend_always, so the coroutine suspends immediately. 5. Control returns to main, which now holds the Task object. 6. The first resume() runs "Task body: part 1", then hits co_await suspend_always{} and suspends. 7. The second resume() runs "Task body: part 2", then falls off the end, triggering final_suspend(). 8. Since final_suspend() returns suspend_always, the coroutine suspends one final time. 9. When Task's destructor runs (at the end of main), it destroys the coroutine handle. The return object provides an interface to the caller. It hides the details of coroutine handles and promises behind whatever API makes sense for your use case. For a generator, the return object provides methods like next() and value(). For a task, it might provide resume() and done(). The return object owns the coroutine handle and is responsible for destroying it. You have now seen how return objects and coroutine handles work together. The return object is the caller's view of the coroutine, while the handle is the mechanism for resuming and managing the coroutine's lifetime. Step 7 — Completing Coroutines with co_return <https://gist.github.com/vinniefalco/bbf1d9d3a720e8ad2ef8fe2e837cdfc9#step-7…> You have seen coroutines that yield sequences of values and suspend indefinitely. Now you will learn how coroutines complete their execution using co_return. A coroutine completes in one of three ways: 1. It executes co_return; (returning void) 2. It executes co_return expression; (returning a value) 3. Execution falls off the end of the coroutine body For case 1 and 3, the compiler calls promise.return_void(). For case 2, the compiler calls promise.return_value(expression). You must provide exactly one of these methods in your promise type, matching how your coroutine returns. When a coroutine completes (by any of these means), it then executes co_await promise.final_suspend(). The awaiter returned by final_suspend() determines what happens next: - If it suspends (like suspend_always), the coroutine frame remains valid. The caller can still access the promise object and must eventually call handle.destroy() to free the memory. - If it does not suspend (like suspend_never), the coroutine frame is destroyed automatically. Any handles to the coroutine become dangling pointers. The choice between these behaviors matters. If your caller needs to access the result stored in the promise after the coroutine completes, use suspend_always. If the coroutine's completion signals some external mechanism (like releasing a semaphore) and the result is not needed, you might use suspend_never to avoid manual cleanup. Here is an example of a coroutine that returns a value: #include <coroutine> #include <iostream> #include <optional> struct ComputeResult { struct promise_type { std::optional<int> result; ComputeResult get_return_object() { return ComputeResult{ std::coroutine_handle<promise_type>::from_promise(*this) }; } std::suspend_always initial_suspend() { return {}; } std::suspend_always final_suspend() noexcept { return {}; } void return_value(int value) { result = value; } void unhandled_exception() { result = std::nullopt; } }; std::coroutine_handle<promise_type> handle; ComputeResult(std::coroutine_handle<promise_type> h) : handle(h) {} ~ComputeResult() { if (handle) handle.destroy(); } ComputeResult(ComputeResult&& other) noexcept : handle(other.handle) { other.handle = nullptr; } void run() { while (!handle.done()) { handle.resume(); } } std::optional<int> get_result() const { return handle.promise().result; } }; ComputeResult compute_sum(int n) { int sum = 0; for (int i = 1; i <= n; ++i) { sum += i; co_await std::suspend_always{}; // yield control periodically } co_return sum; } int main() { auto computation = compute_sum(5); computation.run(); if (auto result = computation.get_result()) { std::cout << "Result: " << *result << std::endl; } } Output: Result: 15 The compute_sum coroutine adds numbers from 1 to n, periodically yielding control with co_await suspend_always{}. When the loop completes, it executes co_return sum, which calls promise.return_value(sum), storing the result in the promise. Because final_suspend() returns suspend_always, the coroutine frame remains valid after completion. The get_result() method can access handle.promise().result to retrieve the computed value. You can query whether a coroutine has completed using handle.done(). This method returns true after the coroutine has executed co_return (or fallen off the end) and completed the final_suspend awaiter. Do not confuse handle.done() with handle.operator bool(). The boolean conversion only checks if the handle is non-null; it does not indicate completion. A critical warning about undefined behavior: if your coroutine can fall off the end of its body and your promise type does not have a return_void() method, the behavior is undefined. This is dangerous because the compiler may not warn you. Always ensure your promise type has return_void() if any code path might reach the end of the coroutine without an explicit co_return. Here is the same computation rewritten to fall off the end instead of using explicit co_return: struct ComputeResult2 { struct promise_type { int result = 0; ComputeResult2 get_return_object() { return ComputeResult2{ std::coroutine_handle<promise_type>::from_promise(*this) }; } std::suspend_always initial_suspend() { return {}; } std::suspend_always final_suspend() noexcept { return {}; } void return_void() {} // Required because we fall off the end void unhandled_exception() {} }; std::coroutine_handle<promise_type> handle; // ... rest of the class }; ComputeResult2 compute_sum2(int n) { auto& result = co_await GetPromiseAwaiter{}; // hypothetical int sum = 0; for (int i = 1; i <= n; ++i) { sum += i; co_await std::suspend_always{}; } result = sum; // Falls off the end - calls promise.return_void() } In this version, we store the result in the promise before falling off the end. The return_void() method must exist even though it does nothing, because the coroutine reaches the end of its body. You have now learned how coroutines complete execution. The co_return statement (or falling off the end) triggers the promise's return methods, and final_suspend determines whether the coroutine frame persists. Step 8 — Building a Generic Generator <https://gist.github.com/vinniefalco/bbf1d9d3a720e8ad2ef8fe2e837cdfc9#step-8…> You have learned all the pieces needed to build a reusable generator type. In this step, you will assemble them into a template class that works with any value type. A production-quality generator needs to handle several concerns: 1. Store and retrieve yielded values of any type 2. Manage the coroutine handle's lifetime correctly 3. Propagate exceptions from the coroutine to the caller 4. Provide a clean iteration interface Here is a complete generic generator: #include <coroutine> #include <exception> #include <utility> template<typename T>class Generator {public: struct promise_type { T value; std::exception_ptr exception; Generator get_return_object() { return Generator{Handle::from_promise(*this)}; } std::suspend_always initial_suspend() noexcept { return {}; } std::suspend_always final_suspend() noexcept { return {}; } std::suspend_always yield_value(T v) { value = std::move(v); return {}; } void return_void() noexcept {} void unhandled_exception() { exception = std::current_exception(); } template<typename U> std::suspend_never await_transform(U&&) = delete; }; using Handle = std::coroutine_handle<promise_type>; private: Handle handle_; public: explicit Generator(Handle h) : handle_(h) {} ~Generator() { if (handle_) { handle_.destroy(); } } Generator(const Generator&) = delete; Generator& operator=(const Generator&) = delete; Generator(Generator&& other) noexcept : handle_(std::exchange(other.handle_, nullptr)) {} Generator& operator=(Generator&& other) noexcept { if (this != &other) { if (handle_) { handle_.destroy(); } handle_ = std::exchange(other.handle_, nullptr); } return *this; } class iterator { Handle handle_; public: using iterator_category = std::input_iterator_tag; using value_type = T; using difference_type = std::ptrdiff_t; using pointer = T*; using reference = T&; iterator() : handle_(nullptr) {} explicit iterator(Handle h) : handle_(h) {} iterator& operator++() { handle_.resume(); if (handle_.done()) { auto& promise = handle_.promise(); handle_ = nullptr; if (promise.exception) { std::rethrow_exception(promise.exception); } } return *this; } iterator operator++(int) { iterator temp = *this; ++(*this); return temp; } T& operator*() const { return handle_.promise().value; } T* operator->() const { return &handle_.promise().value; } bool operator==(const iterator& other) const { return handle_ == other.handle_; } bool operator!=(const iterator& other) const { return !(*this == other); } }; iterator begin() { if (handle_) { handle_.resume(); if (handle_.done()) { auto& promise = handle_.promise(); if (promise.exception) { std::rethrow_exception(promise.exception); } return iterator{}; } } return iterator{handle_}; } iterator end() { return iterator{}; } }; This generator provides a standard iterator interface, allowing use in range-based for loops: Generator<int> range(int start, int end) { for (int i = start; i < end; ++i) { co_yield i; } } Generator<int> squares(int n) { for (int i = 0; i < n; ++i) { co_yield i * i; } } int main() { std::cout << "Range 1 to 5:" << std::endl; for (int x : range(1, 6)) { std::cout << x << " "; } std::cout << std::endl; std::cout << "First 5 squares:" << std::endl; for (int x : squares(5)) { std::cout << x << " "; } std::cout << std::endl; } Output: Range 1 to 5: 1 2 3 4 5 First 5 squares: 0 1 4 9 16 Several design choices in this generator deserve explanation: initial_suspend() returns suspend_always: The coroutine suspends before running any user code. This means begin() must resume the coroutine to get the first value. This design prevents work from being done if the generator is never iterated. final_suspend() returns suspend_always: The coroutine frame persists after completion. This is necessary because the iterator needs to check handle_.done() and potentially access the exception stored in the promise. If final_suspend() returned suspend_never, the handle would become invalid before these checks could occur. Exception handling: The unhandled_exception() method stores the current exception in the promise using std::current_exception(). The iterator's operator++ and begin() check for this exception and rethrow it using std::rethrow_exception(). This propagates exceptions from the coroutine to the calling code. await_transform is deleted: This prevents using co_await inside the generator. A generator should only yield values, not await other operations. Deleting await_transform makes any use of co_await inside a Generator<T> coroutine a compile error. Move semantics: The generator is movable but not copyable. Copying a coroutine handle would create aliasing problems—both copies would refer to the same coroutine frame, and destroying one would invalidate the other. Moving transfers ownership cleanly. Here is an example demonstrating exception propagation: Generator<int> may_throw(bool should_throw) { co_yield 1; co_yield 2; if (should_throw) { throw std::runtime_error("Generator error"); } co_yield 3; } int main() { try { for (int x : may_throw(true)) { std::cout << x << std::endl; } } catch (const std::exception& e) { std::cout << "Caught: " << e.what() << std::endl; } } Output: 1 2 Caught: Generator error The exception thrown inside the generator propagates to the calling code and can be caught normally. You have now built a production-quality generic generator. It handles value types, manages coroutine lifetime, propagates exceptions, and provides a standard iterator interface. Step 9 — Handling Exceptions in Coroutines <https://gist.github.com/vinniefalco/bbf1d9d3a720e8ad2ef8fe2e837cdfc9#step-9…> Exceptions in coroutines require special attention. Because a coroutine can suspend and resume across different call stacks, the normal exception propagation mechanism does not work directly. The promise type's unhandled_exception() method provides the hook for handling exceptions that escape the coroutine body. When an exception is thrown inside a coroutine and not caught within the coroutine, the following happens: 1. The exception is caught by the implicit try-catch block surrounding the coroutine body. 2. promise.unhandled_exception() is called while the exception is still active. 3. After unhandled_exception() returns, co_await promise.final_suspend() executes. 4. The coroutine completes (either suspended or destroyed, depending on final_suspend). Inside unhandled_exception(), you have several options: Terminate the program: Call std::terminate(). This is the safest option if you cannot handle exceptions. void unhandled_exception() { std::terminate(); } Store the exception for later: Use std::current_exception() to capture the exception and store it in the promise. The caller can later check for the exception and rethrow it. void unhandled_exception() { exception_ = std::current_exception(); } Rethrow the exception: Call throw; to rethrow the exception. This propagates the exception to whoever is currently running the coroutine, but be careful—this may not be the original caller if the coroutine has been resumed from a different context. void unhandled_exception() { throw; } Swallow the exception: Do nothing. This silences the exception, which is almost always a mistake but might be appropriate in specific circumstances. void unhandled_exception() { // Exception is silently ignored } The stored exception pattern is most useful for generators and tasks where the caller expects to receive results: #include <coroutine> #include <exception> #include <iostream> #include <stdexcept> struct Task { struct promise_type { std::exception_ptr exception; Task get_return_object() { return Task{std::coroutine_handle<promise_type>::from_promise(*this)}; } std::suspend_always initial_suspend() { return {}; } std::suspend_always final_suspend() noexcept { return {}; } void return_void() {} void unhandled_exception() { exception = std::current_exception(); } }; std::coroutine_handle<promise_type> handle; Task(std::coroutine_handle<promise_type> h) : handle(h) {} ~Task() { if (handle) handle.destroy(); } void run() { handle.resume(); } void check_exception() { if (handle.promise().exception) { std::rethrow_exception(handle.promise().exception); } } }; Task risky_operation() { std::cout << "Starting risky operation" << std::endl; throw std::runtime_error("Something went wrong"); co_return; // Never reached } int main() { Task task = risky_operation(); try { task.run(); task.check_exception(); std::cout << "Operation completed successfully" << std::endl; } catch (const std::exception& e) { std::cout << "Operation failed: " << e.what() << std::endl; } } Output: Starting risky operation Operation failed: Something went wrong The timing of when to check for exceptions matters. In this example, check_exception() is called after run() completes. If the coroutine suspended multiple times, you might want to check for exceptions after each resumption. For generators with iterators, exceptions are typically checked during iteration: iterator& operator++() { handle_.resume(); if (handle_.done()) { auto& promise = handle_.promise(); if (promise.exception) { std::rethrow_exception(promise.exception); } } return *this; } This ensures that exceptions are propagated to the code iterating over the generator. Be aware of exception safety during coroutine initialization. If an exception is thrown before the first suspension point (and before initial_suspend completes), the exception propagates directly to the caller without going through unhandled_exception(). If initial_suspend() returns suspend_always, the coroutine suspends before any user code runs, avoiding this issue. You have now learned how to handle exceptions in coroutines. The unhandled_exception() method provides a hook for capturing or propagating exceptions, and the stored exception pattern allows callers to receive exceptions even when the coroutine has suspended and resumed. Step 10 — Practical Patterns and Applications <https://gist.github.com/vinniefalco/bbf1d9d3a720e8ad2ef8fe2e837cdfc9#step-1…> You have learned the mechanics of C++20 coroutines. Now you will explore practical patterns that demonstrate their power. Lazy Sequences <https://gist.github.com/vinniefalco/bbf1d9d3a720e8ad2ef8fe2e837cdfc9#lazy-s…> Generators excel at producing lazy sequences—sequences where values are computed only when needed. This pattern is useful when working with infinite sequences or when computing values is expensive. Generator<int> infinite_counter() { int i = 0; while (true) { co_yield i++; } } Generator<int> primes() { auto is_prime = [](int n) { if (n < 2) return false; if (n == 2) return true; if (n % 2 == 0) return false; for (int i = 3; i * i <= n; i += 2) { if (n % i == 0) return false; } return true; }; int n = 2; while (true) { if (is_prime(n)) { co_yield n; } ++n; } } int main() { int count = 0; for (int p : primes()) { std::cout << p << " "; if (++count >= 10) break; } std::cout << std::endl; } Output: 2 3 5 7 11 13 17 19 23 29 The prime generator tests each number for primality but only computes values as they are requested. An infinite number of primes exist, but the program only computes the first ten. Transforming Sequences <https://gist.github.com/vinniefalco/bbf1d9d3a720e8ad2ef8fe2e837cdfc9#transf…> Generators can transform sequences from other generators, creating a pipeline of operations: Generator<int> take(Generator<int> source, int n) { int count = 0; for (int value : source) { if (count++ >= n) break; co_yield value; } } Generator<int> filter(Generator<int> source, bool (*predicate)(int)) { for (int value : source) { if (predicate(value)) { co_yield value; } } } Generator<int> transform(Generator<int> source, int (*func)(int)) { for (int value : source) { co_yield func(value); } } bool is_even(int n) { return n % 2 == 0; }int square(int n) { return n * n; } int main() { // Take first 5 even numbers from range, then square them auto pipeline = transform( filter( take(range(1, 100), 10), is_even ), square ); for (int x : pipeline) { std::cout << x << " "; } std::cout << std::endl; } Output: 4 16 36 64 100 Each generator in the pipeline produces values on demand. The filter generator only requests the next value from its source when it needs to produce an output. The transform generator only transforms values as they pass through. Tree Traversal <https://gist.github.com/vinniefalco/bbf1d9d3a720e8ad2ef8fe2e837cdfc9#tree-t…> Ana Lúcia de Moura and Roberto Ierusalimschy, in their influential paper on coroutines, demonstrated tree traversal as a classic use case. With generators, you can traverse a tree structure while maintaining the simple recursive algorithm: struct TreeNode { int value; TreeNode* left; TreeNode* right; TreeNode(int v, TreeNode* l = nullptr, TreeNode* r = nullptr) : value(v), left(l), right(r) {} }; Generator<int> inorder(TreeNode* node) { if (node == nullptr) { co_return; } for (int v : inorder(node->left)) { co_yield v; } co_yield node->value; for (int v : inorder(node->right)) { co_yield v; } } int main() { // 4 // / \ // 2 6 // / \ / \ // 1 3 5 7 TreeNode n1(1), n3(3), n5(5), n7(7); TreeNode n2(2, &n1, &n3), n6(6, &n5, &n7); TreeNode root(4, &n2, &n6); for (int v : inorder(&root)) { std::cout << v << " "; } std::cout << std::endl; } Output: 1 2 3 4 5 6 7 The recursive structure of the tree traversal matches the recursive structure of the code. Each call to inorder creates a new generator that yields values from its subtree. The co_yield in the loop forwards those values upward. Cooperative Multitasking <https://gist.github.com/vinniefalco/bbf1d9d3a720e8ad2ef8fe2e837cdfc9#cooper…> Coroutines enable cooperative multitasking without threads. Multiple tasks can make progress by voluntarily yielding control: #include <vector> #include <string> struct Task { struct promise_type { Task get_return_object() { return Task{std::coroutine_handle<promise_type>::from_promise(*this)}; } std::suspend_always initial_suspend() { return {}; } std::suspend_always final_suspend() noexcept { return {}; } void return_void() {} void unhandled_exception() { std::terminate(); } }; std::coroutine_handle<promise_type> handle; Task(std::coroutine_handle<promise_type> h) : handle(h) {} ~Task() { if (handle) handle.destroy(); } Task(Task&& other) noexcept : handle(other.handle) { other.handle = nullptr; } bool done() const { return handle.done(); } void resume() { handle.resume(); } }; struct Scheduler { std::vector<Task> tasks; void add(Task task) { tasks.push_back(std::move(task)); } void run() { while (!tasks.empty()) { for (size_t i = 0; i < tasks.size(); ) { tasks[i].resume(); if (tasks[i].done()) { tasks.erase(tasks.begin() + i); } else { ++i; } } } } }; Task worker(std::string name, int iterations) { for (int i = 0; i < iterations; ++i) { std::cout << name << " iteration " << i << std::endl; co_await std::suspend_always{}; } } int main() { Scheduler scheduler; scheduler.add(worker("Alice", 3)); scheduler.add(worker("Bob", 2)); scheduler.run(); } Output: Alice iteration 0 Bob iteration 0 Alice iteration 1 Bob iteration 1 Alice iteration 2 The scheduler interleaves the execution of Alice and Bob. Each task runs until it hits co_await suspend_always{}, then yields control. The scheduler resumes the next task, achieving cooperative multitasking. This pattern can be extended with I/O operations. Instead of suspend_always, tasks would await I/O completions. A real scheduler would integrate with an event loop, resuming tasks when their I/O operations complete. You have now seen practical applications of C++20 coroutines. Lazy sequences, sequence transformations, tree traversal, and cooperative multitasking all benefit from coroutines' ability to suspend and resume execution while preserving local state. Conclusion <https://gist.github.com/vinniefalco/bbf1d9d3a720e8ad2ef8fe2e837cdfc9#conclu…> In this tutorial, you explored C++20 coroutines from fundamental concepts to practical implementations. You began by understanding the problem coroutines solve: the fragmentation of logic that occurs when writing asynchronous code with callbacks. Coroutines restore the natural flow of sequential code while maintaining asynchronous behavior. You learned to recognize coroutines by their keywords: co_await for suspension, co_yield for producing values, and co_return for completion. You discovered that the presence of any of these keywords transforms a function into a coroutine with special runtime behavior. You examined the mechanics of suspension and resumption, understanding how the coroutine frame preserves local variables on the heap while the coroutine is suspended. The std::coroutine_handle provides the mechanism for resuming a suspended coroutine. You studied the promise type, the controller class that customizes coroutine behavior. Its methods—get_return_object, initial_suspend, final_suspend, yield_value, return_void, return_value, and unhandled_exception—define how the coroutine initializes, suspends, produces values, completes, and handles errors. You built a complete generator type that produces sequences of values on demand. The generator manages coroutine lifetime, provides an iterator interface, and propagates exceptions from the coroutine to calling code. You explored practical patterns: lazy sequences that compute values only when needed, pipelines that transform sequences, tree traversals that maintain recursive structure, and cooperative multitasking that interleaves multiple tasks. C++20 coroutines provide a foundation for building sophisticated asynchronous systems. The standard library in C++23 and beyond will provide higher-level abstractions built on this foundation. Understanding the mechanisms described in this tutorial will help you use those abstractions effectively and build your own when needed. For further exploration, consider studying: - The std::generator type introduced in C++23 - Asynchronous I/O frameworks that use coroutines - The senders and receivers model being developed for C++26 - Real-world applications of coroutines in networking, databases, and user interfaces Coroutines represent a significant evolution in how C++ programmers can express complex control flow. The ability to write asynchronous code that reads like synchronous code, while maintaining full control over memory and performance, embodies the spirit of C++: abstraction without hidden costs.

4 4