The C++ Alliance

On Triremes, Aircraft, and Molecular Modelling Simulations

2026-04-10T00:00:00+00:00

First some personal news. To keep my coding skills sharp(ish), I updated my simulation of Greek and Persian triremes (rowed war-galleys with big bronze rams) with better graphics (splashy bows, greying sea and skies in strong wind, fire pots to illuminate courses) and some better AI. Originally the code was in C++, but changed to C# to work well with XNA graphics. I was unaware of the Ogre graphics library at the time, nor the Boost libraries - which might have given the performance to extend the AI look-ahead from a paltry six seconds to perhaps ten seconds or more (look-ahead is a combinatorial explosion and performance-critical). Called the updated game Trireme Commander 2, and put it up on itch.io. So far, sold one copy - only 999,999 to go and I will have sold a million! One step at a time I guess.

From discussions with new Cpp Alliance staff, I added two scenarios to the User Guide - aeronautical engineering and bio-tech. I do know something about aeronautical stuff - having worked on the awesome Microsoft Flight Simulator for four years (one of the best jobs I had in about 18 years at Microsoft). Modern aircraft should be considered as flying computers - so many systems working on our behalf and most of those systems (airspace, instrument landing, beacons, runways) well thought out with safety in mind. Writing real-time software for an aircraft though requires following a strict discipline and procedures that most of us are never aware of. If you have four airspeed sensors and two give one number, and two another, what do you do? Terrible things have happened if coders do things like just take the average. I added the scenario to the User Guide with some examples of the procedures and errors that come up with flight software, such as range failure, underflow, and order-dependent drift.

Whereas I know something about airplanes, I know little about bio-tech software - molecular modelling and stuff like that. However, my son works at Carnegie Mellon as a PhD and bio-tech assistant, and I was able to get a meaningful discussion going on phylogenetic trees - modelling evolution, species, and all those things that follow a biological tree structure. Fascinating, and I added the topic again to the User Guide advanced scenarios. Talk about airplanes being flying computers, carbon-based lifeforms are computers too only many times more involved and connected.

Documentation needs to feel alive too - it needs updated and new stuff added on a regular basis just to show it is active and evolving. Adding topics to the FAQs (User and Contributor) is something I do frequently - often looking at the discussions on #boost slack channels to pick up on current thinking and areas of difficulty or concern, such as compatibility issues, CMake, and conference attendance. Or, for contributors, topics such as documentation, navigation, and useful macros.

Reading proposed library documentation is always interesting. Always try to get the authors to focus on, or at least mention, use cases. It is use cases that pull in developers - saying what something “does” is so much more important than saying what something “is”. Developers, understandably, are so close to the metal that it can be difficult for them to step back and focus on use over internals. There are many perspectives in looking at the same thing.

Joining Community, Detecting Communities, Making Community.

2026-04-08T00:00:00+00:00

Joining Community

Early in Q1 2026, I joined the C++ Alliance. A very exciting moment.

So I began to work early January under Joaquin’s mentorship, with the idea of having a clear contribution to Boost Graph by the end of Q1. After a few days of auditing the current state of the library versus the literature, it became clear that community detection methods (aka graph clustering algorithms) were sorely lacking for Boost.Graph, and that implementing one would be a great start to revitalizing the library and fill up maybe the largest methodological gap in its current algorithmic coverage.

Detecting Communities

The vision was (and still is) simple: i) begin to implement Louvain algorithm, ii) build upon it to extend to the more complex Leiden algorithm, iii) finally get started with the Stochastic Block Model.

If the plan is straightforward, the Louvain literature is not, and the BGL abstractions even less. But under the review and guidance from Joaquin and Jeremy Murphy (maintainer of the BGL), I was able to put up a satisfying implementation:

Using the Newman-Girvan Modularity as the quality function to optimize, one can simply call:

double Q = boost::louvain_clustering(
    g, cluster_map, weight_map, gen,
    boost::newman_and_girvan{},  // quality function (default)
    1e-7,                        // min_improvement_inner (per-pass convergence)
    0.0                          // min_improvement_outer (cross-level convergence)
);
// Q = 0.42, cluster_map = {0,0,0, 1,1,1}

As it happens often with heuristics, there is a large number of quality functions out there, and this is not because of a lack of consensus: in a 2002 paper, computer scientist Jon Kleinberg proved that no clustering quality function (Modularity, Goldberg density, Surprise…) can simultaneously be:

scale-invariant (doubling all edges should not change the clusters),
rich (all partitions should be achievable),
consistent (shortening distances inside a cluster and expanding distances between clusters should lead to similar results).

In other words, there is no way to implement a single function hoping it would exhibit three basic properties we would genuinely expect. All we can do is to explore different trade-offs using different quality functions.

So I left some doors open to be able to inject an arbitrary quality function. If this function exposes a minimal, “naive” interface, the algorithm will statically use a slow but generic path, and iterate across all the edges of the graph to compute the quality. It is slow, yes, but it makes the study of qualities easier, as one does not have to figure out the local mathematical decomposition of the function to get started with coding:

struct my_quality {
    template <typename G, typename CMap, typename WMap>
    typename boost::property_traits<WMap>::value_type
    quality(const G& g, const CMap& c, const WMap& w) {
        // your custom partition quality function
    }
};

double Q = boost::louvain_clustering(g, cluster_map, weight_map, gen, my_quality{});

However, the Louvain algorithm is extremely popular because it is fast, as it is able to update the quality computational state for each vertex it tries to “insert” or “remove” from a neighboring putative community. This locality decomposition has to be figured out mathematically for each quality function, so it’s not trivial.

I defined a GraphPartitionQualityFunctionIncrementalConcept that refines the GraphPartitionQualityFunctionConcept : if the algorithm detects that the injected quality function exposes an interface for this incremental update, the fast path is taken. One thing I figured out is that the GraphPartitionQualityFunctionIncrementalConcept is for now too specific to the Modularity family. I am currently working on a proposal to increase its scope in future work.

The current PR has been carefully tested and benchmarked for correctness and performance, and validated by Jeremy to be merged on develop branch.

I wrote a paper to be submitted to the Journal of Open Source Software to publish the current results and benchmarks, as we are at least as fast as our competitors, and more generic. There is no equivalent I am aware of.

Making Community

Concurrently, I worked on summoning the Boost.Graph user base, and it quickly became clear a small local workshop would be a tremendous start: the Louvain algorithm community is based in Louvain (Belgium), its extension was formulated in Leiden (Netherlands) and my PhD graphs network is based in Paris (France) in what has been presented to me as “the Temple of the Stochastic Block Model” ! Quite a sign: life finds ways to run in (tight) circles.

So the goal of this workshop is to bring together a small group (10-15 people) of researchers, open-source implementers, and industrial users for a day of honest conversation on May 6th 2026. Three questions will anchor the discussions:

What types of graphs and data structures do you use in practice?
What performance, scalability, and interpretability requirements matter most to you?
What algorithms are missing today that Boost.Graph could offer?

Ray and Collier from the C++ Alliance will also be there to record the lightning talks and document the process. It would also be the occasion to show off the python-based animations I put together for the French C++ User Group presentation on March 24th. Those had a nice success and received many compliments, as it pairs well with the visual and dynamic nature of graphs and their algorithms, and I hope it will contribute to the repopularization of Boost.Graph.

Graphliiings asseeeeemble !

Mr.Docs: Niebloids, Reflection, Code Removal, New XML Generator

2026-04-06T00:00:00+00:00

This quarter, I focused on two areas of Mr.Docs: adding first-class support for function objects, the pattern behind C++20 Niebloids and Ranges CPOs, and overhauling how the tool turns C++ metadata into documentation output (the reflection layer).

Function objects: documenting what users actually call

In modern C++ libraries, many “functions” are actually global objects whose type has operator() overloads. The Ranges library, for instance, defines std::ranges::sort() not as a function template but as a variable of some unspecified callable type. Users call it like a function and expect it to be documented like one. Before this quarter, Mr.Docs didn’t know the difference: it would document the variable and its cryptic implementation type.

The new function-object support (roughly 4,600 lines across 38 files) bridges this gap. When Mr.Docs encounters a variable whose type is a record with no public members but operator() overloads and special member functions, it now synthesizes free-function documentation entries named after the variable. The underlying type is marked implementation-defined and hidden from the output. Multi-overload function objects are naturally grouped by the existing overload machinery. So, given:

struct abs_fn {
    double operator()(double x) const noexcept;
};
inline constexpr abs_fn abs = {};

Mr.Docs documents it as simply:

double abs(double x) noexcept;

For cases where auto-detection isn’t quite right — for example, when the type has extra public members — library authors can use the new @functionobject or @functor doc commands. There is also an auto-function-objects config option to control the behavior globally. The feature comes with a comprehensive test fixture covering single and multi-overload function objects, templated types, and types that live in nested detail namespaces.

Reflection: from boilerplate to a single generic template

The bigger effort — and the one that kept surprising me with its scope — was the reflection refactoring. Mr.Docs converts its internal C++ metadata into a DOM (a tree of lazy objects) that drives the Handlebars template engine. Before this quarter, every type in the system required a hand-written tag_invoke() overload: one function to map the type’s fields to DOM properties, another to convert it to a dom::Value. Adding a new symbol kind meant touching half a dozen files and following a pattern that was easy to get wrong.

The goal was simple to state: replace all of that with a single generic template that works for any type carrying a describe macro.

Phase 1: Boost.Describe

The first attempt used Boost.Describe. I added BOOST_DESCRIBE_STRUCT() annotations to every metadata type and wrote generic merge() and mapReflectedType() templates that iterated over the described members. This proved the concept and eliminated a great deal of boilerplate. However, we didn’t want a public dependency on Boost.Describe, which meant the dependency was hidden in .cpp files and couldn’t be used in templates living in public heades,

Phase 2: custom reflection macros

So I wrote our own. MRDOCS_DESCRIBE_STRUCT() and MRDOCS_DESCRIBE_CLASS() provide the same compile-time member and base-class iteration as Boost.Describe, but with no external dependency. The macros live in Describe.hpp and produce constexpr descriptor lists that the rest of the system iterates with describe::for_each().

Phase 3: removing the overloads

With the describe macros in place, I could write generic implementations of tag_invoke() for both LazyObjectMapTag (DOM mapping) and ValueFromTag (value conversion), plus a generic merge(). Each one replaces dozens of per-type overloads with a single constrained template. The mapMember() function handles the dispatch: optionals are unwrapped, vectors become lazy arrays, described enums become kebab-case strings, and compound described types become lazy objects — all automatically.

Removing the overloads was not as straightforward as I had hoped. The old overloads were entangled with:

The Handlebars templates, which assumed specific DOM property names. Renaming symbol to id, type to underlyingType, and description to document required updating templates and golden tests in lockstep.
The XML generator, which silently skipped types that weren’t described. Adding MRDOCS_DESCRIBE_STRUCT() to TemplateInfo and MemberPointerType made the XML output more complete, requiring schema updates and golden-test regeneration.

The result

Out of the original 39 custom tag_invoke(LazyObjectMapTag) overloads, only 7 remain — each with genuinely non-reflectable logic (computed properties, polymorphic dispatch, or member decomposition). Roughly 60 tag_invoke(ValueFromTag) boilerplate overloads were also removed. Adding a new metadata type to Mr.Docs now requires nothing beyond MRDOCS_DESCRIBE_STRUCT() at the point of definition.

The XML Generator: a full rewrite in 350 lines

The XML generator was the first major payoff of the reflection work (although it was initially done when we were using Boost.Describe). The old generator had its own hand-written serialization for every metadata type, completely independent of the DOM layer. It was a parallel set of per-type functions that had to be kept in sync with every schema change.

I replaced it with a generic implementation built entirely on the describe macros. The core is about 350 lines: writeMembers() walks describe_bases and describe_members, writeElement() dispatches on type traits for primitives, optionals, vectors, and enums, and writePolymorphic() handles the handful of type hierarchies (Type, TParam, TArg, Block, Inline) via .inc-generated switches. The old generator needed a new function for every type; the new one handles them all, and the 241 files changed in that commit were almost entirely golden-test updates reflecting the now-more-complete and totally changed output.

Smaller fixes

Alongside the two main efforts, I fixed several bugs that came up during development or were reported by users:

Markdown inline formatting (bold, italic, code) and bullet lists were not rendering correctly in certain combinations.
<pre> tags were missing around HTML code blocks.
bottomUpTraverse() was silently skipping ListBlock items, causing doc-comment content to be lost.
Several CI improvements: faster PR demos, better failure detection, increased test coverage for the XML generator.

Looking ahead

The reflection infrastructure is now in good shape, and most of the mechanical boilerplate is gone. The remaining tag_invoke() overloads are genuinely custom — they compute properties that don’t exist as C++ members, or they dispatch polymorphically across type hierarchies. Those are worth keeping. Going forward, I’d like to explore whether the describe macros can replace more of the manual visitor code throughout the codebase.

As always, feedback and suggestions are welcome — feel free to open an issue or reach out on Slack.

Speed and Safety

2026-04-06T00:00:00+00:00

In my last post I mentioned that int128 library would be getting CUDA support in the future. The good news is that the future is now! Nearly all the functions in the library are available on both host and device. Any function that has BOOST_INT128_HOST_DEVICE in its signature in the documentation is available for usage. An example of how to use the types in the CUDA kernels has been added as well. These can be as simple as:

using test_type = boost::int128::uint128_t;

__global__ void cuda_mul(const test_type* in1, const test_type* in2, test_type* out, int num_elements)
{
    int i = blockDim.x * blockIdx.x + threadIdx.x;

    if (i < num_elements)
    {
        out[i] = in1[i] * in2[i];
    }
}

Other Boost libraries are or will be beneficiaries of this effort as well. First, Boost.Charconv now supports boost::charconv::from_chars and boost::charconv::to_chars for integers being run on device. This can give you up to an order of magnitude improvement in performance. These results and benchmarks are available in the Boost.Charconv documentation. Next, in the coming months Boost.Decimal will gain CUDA support as part of this effort. We think users will benefit greatly from being able to perform massively parallel parsing, serialization, and calculations on decimal numbers. Stay tuned for this likely in Boost 1.92. In the meantime, enjoy the initial release of Decimal coming in Boost 1.91!

On the other side of the performance that we’re looking to deliver in coming versions of Boost, we must not forget the importance of safety. There exist plenty of examples of damage and death caused by arithmetic errors in computer programs. Can we create a library that provides guaranteed safety in arithmetic while minimizing performance losses and integration friction? How does one guarantee the behavior of their types? In our implementation, Boost.Safe_Numbers, we are investigating the usage of the Why3 platform for deductive program verification. By pursuing these formal methods, safety can have real meaning. We will continue to provide additional details as part of the formal verification page of our documentation. Since inevitably the library will cause an increase in the number of errors (which is a good thing), we aim to fail as early as possible, and when we do provide the most helpful error message that we can. For example, we have some static arithmetic errors reported in as few as three lines:

clang-darwin.compile.c++ ../../../bin.v2/libs/safe_numbers/test/compile_fail_basic_usage_constexpr.test/clang-darwin-21/debug/arm_64/cxxstd-20-iso/threading-multi/visibility-hidden/compile_fail_basic_usage_constexpr.o
../examples/compile_fail_basic_usage_constexpr.cpp:18:22: error: constexpr variable 'z' must be initialized by a constant expression
   18 |         constexpr u8 z {x + y};
      |                      ^ ~~~~~~~
../../../boost/safe_numbers/detail/unsigned_integer_basis.hpp:397:17: note: subexpression not valid in a constant expression
  397 |                 throw std::overflow_error("Overflow detected in u8 addition");
      |                 ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
../examples/compile_fail_basic_usage_constexpr.cpp:18:25: note: in call to 'operator+<unsigned char>({255}, {2})'
   18 |         constexpr u8 z {x + y};
      |                         ^~~~~
1 error generated.

Our runtime error reporting system fundamentally uses Boost.Throw_Exception so it can report not only the type, operation, file and line, but also up to an entire stack trace when leveraging the optional linking with Boost.Stacktrace. Not to forget our discussion of CUDA so quickly, the Safe_Numbers library will have CUDA support. One thing that we will continue to refine is synchronizing error reporting on device as one cannot throw an exception on device.

We are always looking for users of all the libraries discussed. If you are a current or prospective user, feel free to reach out and let us know what you’re using it for, or any issues that you find.

The road to C++20 modules, Capy and Redis

2026-04-06T00:00:00+00:00

Modules in using std::cpp 2026

C++20 modules have been in the standard for 6 years already, but we’re not seeing widespread adoption. The ecosystem is still getting ready. As a quick example, import std, an absolute blessing for compile times, requires build system support, and this is still experimental as of CMake 4.3.1.

And yet, I’ve realized that writing module-native applications is really enjoyable. The system is well-thought and allows for better encapsulation, just as you’d write in a modern programming language. I’ve been using my Servertech Chat project (a webserver that uses Boost.Asio and companion libraries) to get a taste of what modules really look like in real code.

When writing this, I saw clearly that having big dependencies that can’t be consumed via import is a big problem. With the scheme I used, compile times got 66% worse instead of improving. This is because when writing modules, you tend to have a bigger number of translation units. These are supposed to be much more lightweight, but if you’re relying on #include for third-party libraries, they’re not.

For example:

//
// File: redis_client.cppm. Contains only the interface declaration (somehow like headers do)
//
module;

// No import boost yet - must be in the global module fragment
#include <boost/asio/awaitable.hpp>
#include <boost/system/result.hpp>

module servertech_chat:redis_client;
import std;

namespace chat {

class redis_client
{
public:
    virtual ~redis_client() {}
    virtual boost::asio::awaitable<boost::system::result<std::int64_t>> get_int_key(std::string_view key) = 0;
    // ...
};

}

//
// File: redis_client.cpp. Contains the implementation
//
module;

#include <boost/redis/connection.hpp>

module servertech_chat;
import :redis_client;
import std;

namespace {

class redis_client_impl final : public redis_client { /* ... */ };

}

I analyze this in much more depth in the talk I’ve had the pleasure to give at using std::cpp this March in Madrid. The TL;DR is that supporting import boost natively is very important for any serious usage of Boost in the modules world.

`import boost` is upon us

As you may know, I prefer doing to saying, and I’ve been writing a prototype to support import boost natively while keeping today’s header code as is. This prototype has seen substantial advancements during these months.

I’ve developed a systematic approach for modularization, and we’ve settled for the ABI-breaking style, with compatibility headers. I’ve added support for GCC (the remaining compiler) to the core libraries that we already supported (Config, Mp11, Core, Assert, ThrowException, Charconv), and I’ve added modular bindings for Variant2, Compat, Endian, System, TypeTraits, Optional, ContainerHash, IO and Asio. These are only tested under Clang yet - it’s part of a discovery process. The idea is modularizing the flagship libraries to verify that the approach works, and to measure compile time improvements.

There is still a lot to do before things become functional. I’ve received helpful feedback from many community members, which has been invaluable.

Redis meets Capy

If you’re a user of Boost.Asio and coroutines, you probably know that there’s a new player in town - Capy and Corosio. They’re a coroutines-native Asio replacement which promise a range of benefits, from improved expressiveness to saner compile times, without performance loss.

Since I maintain Boost.MySQL and co-maintain Boost.Redis, I know the pain of writing operations using the universal Asio model. Lifetime management is difficult to follow, testing is complex, and things must remain header-only (and usually heavily templatized). Coroutine code is much simpler to write and understand, and it’s what I use whenever I can. So obviously I’m interested in this project.

My long-term idea is creating a v2 version of MySQL and Redis that exposes a Capy/Corosio interface. As a proof-of-concept, I migrated Boost.Redis and some of its tests. Still some polishing needed, but - it works! You can read the full report on the Boost mailing list.

Some sample code as an appetizer:


capy::task<void> run_request(connection& conn)
{
    // A request containing only a ping command.
    request req;
    req.push("PING", "Hello world");

    // Response where the PONG response will be stored.
    response<std::string> resp;

    // Executes the request.
    auto [ec] = co_await conn.exec(req, resp);
    if (ec)
        co_return;
    std::cout << "PING value: " << std::get<0>(resp).value() << std::endl;
}

capy::task<void> co_main()
{
    connection conn{(co_await capy::this_coro::executor).context()};
    co_await capy::when_any(
        // Sends the request
        run_request(conn),

        // Performs connection establishment, re-connection, pings...
        conn.run(config{})
    );
}

Redis PubSub improvements

Working with PubSub messages in Boost.Redis has always been more involved than in other libraries. For example, we support transparent reconnection, but (before 1.91), the user had to explicitly re-establish subscriptions:

request req;
req.push("SUBSCRIBE", "channel");
while (conn->will_reconnect()) {
    // Reconnect to the channels.
    co_await conn->async_exec(req, ignore);

    // ...
}

Boost 1.91 has added PubSub state restoration. A fancy name but an easy feature: established subscriptions are recorded, and when a reconnection happens, the subscription is re-established automatically:

// Subscribe to the channel 'mychannel'. If a re-connection happens,
// an appropriate SUBSCRIBE command is issued to re-establish the subscription.
request req;
req.subscribe({"mychannel"});
co_await conn->async_exec(req);

Boost 1.91 also adds flat_tree, a specialized container for Redis messages with an emphasis on memory-reuse, performance and usability. This container is especially appropriate when dealing with PubSub. We’ve also added connection::async_receive2(), a higher-performance replacement for connection::async_receive() that consumes messages in batches, rather than one-by-one, eliminating re-scheduling overhead. And push_parser, a view to transform raw RESP3 nodes into user-friendly structures.

With these improvements, code goes from:

// Loop while reconnection is enabled
while (conn->will_reconnect()) {

    // Reconnect to channels.
    co_await conn->async_exec(req, ignore);

    // Loop reading Redis pushs messages.
    for (error_code ec;;) {
        // First try to read any buffered pushes.
        conn->receive(ec);
        if (ec == error::sync_receive_push_failed) {
            ec = {};

            // Wait for pushes
            co_await conn->async_receive(asio::redirect_error(asio::use_awaitable, ec));
        }

        if (ec)
            break;  // Connection lost, break so we can reconnect to channels.

        // Left to the user: resp contains raw RESP3 nodes, which need to be parsed manually!

        // Remove the nodes corresponding to one message
        consume_one(resp);
    }
}

To:

// Loop to read Redis push messages.
while (conn->will_reconnect()) {
    // No need to reconnect, we now have PubSub state restoration
    // Wait for pushes
    auto [ec] = co_await conn->async_receive2(asio::as_tuple);
    if (ec)
        break; // Cancelled

    // Consume the messages
    for (push_view elem : push_parser(resp.value()))
        std::cout << "Received message from channel " << elem.channel << ": " << elem.payload << "\n";

    // Clear all the batch
    resp.value().clear();
}

Hubs, intervals and math

2026-04-02T00:00:00+00:00

During Q1 2026, I’ve been working in the following areas:

`boost::container::hub`

boost::container::hub is a nearly drop-in replacement of C++26 std::hive sporting a simpler data structure and providing competitive performance with respect to the de facto reference implementation plf::hive. When I first read about std::hive, I couldn’t help thinking how complex the internal design of the container is, and wondered if something leaner could in fact be more effective. boost::container::hub critically relies on two realizations:

Identification of empty slots by way of std::countr_zero operations on a bitmask is extremely fast.
Modern allocators are very fast, too: boost::container::hub does many more allocations than plf::hive, but this doesn’t degrade its performance significantly (although it affects cache locality).

boost::container::hub is formally proposed for inclusion in Boost.Container and will be officially reviewed April 16-26. Ion Gaztañaga serves as the review manager.

using std::cpp 2026

I gave my talk “The Mathematical Mind of a C++ Programmer” at the using std::cpp 2026 conference taking place in Madrid during March 16-19. I had a lot of fun preparing the presentation and delivering the actual talk, and some interesting discussions were had around it. This is a subject I’ve been wanting to talk about for decades, so I’m somewhat relieved I finally got it over with this year. Always happy to discuss C++ and math, so if you have feedback or want to continue the conversation, please reach out to me.

Boost.Unordered

Written maintenance fixes PR#328, PR#335, PR#336, PR#337, PR#339, PR#344, PR#345. Some of these fixes are related to Node.js vulnerabilities in the Antora setup used for doc building: as the number of Boost libraries using Antora is bound to grow, maybe we should think of an automated way to get these vulnerabilities automatically fixed for the whole project.
Reviewed and merged PR#317, PR#332, PR#334, PR#341, PR#342. Many thanks to Sam Darwin, Braden Ganetsky and Andrey Semashev for their contributions.

Boost.Bimap

Merged PR#31 (std::initializer_list constructor) and provided testing and documentation for this new feature (PR#54). The original PR was silently sitting on the queue for more than four years and it was only when it was brought to my attention in a Reddit conversation that I got to take a look at it. Boost.Bimap needs an active mantainer, I guess I could become this person.

Boost.ICL

Recent changes in libc++ v22 code for associative container lookup have resulted in the breakage of Boost.ICL. My understanding is that the changes in libc++ are not standards conformant, and there’s an ongoing discussion on that; in the meantime, I wrote and proposed a PR to Boost.ICL that fixes the problem (pending acceptance).

Support to the community

I’ve been helping a bit with Mark Cooper’s very successful Boost Blueprint series on X.
Supporting the community as a member of the Fiscal Sponsorship Committee (FSC).

Systems, CI Updates Q1 2026

2026-03-31T00:00:00+00:00

Code Coverage Reports - designing new GCOVR templates

A major effort this quarter and continuing on since it was mentioned in the last newsletter is the development of codecov-like coverage reports that run in GitHub Actions and are hosted on GitHub Pages. Instructions: Code Coverage with Github Actions and Github Pages. The process has really highlighted a phenomenon in open-source software where by publishing something to the whole community, end-users respond back with their own suggestions and fixes, and everything improves iteratively. It would not have happened otherwise. The upstream GCOVR project has taken an interest in the templates and we are working on merging them into the main repository for all gcovr users. Boost contributors and gcovr maintainers have suggested numerous modifications for the templates. Great work by Julio Estrada on the template development.

Better full page scrolling of C++ source code files
Include ‘functions’ listings on every page
Optionally disable branch coverage
Purposely restrict coverage directories to src/ and include/
Another scrolling bug fixed
Both blue and green colored themes
Codacy linting
New forward and back buttons. Allows navigation to each “miss” and subsequent pages

Server Hosting

This quarter we decommissioned the Rackspace servers which had been in service 10-15 years. Rene provided a nice announcement:

Farewell to Wowbagger - End of an Era for boost.org

There was more to do then just delete servers, I built a new results.boost.org FTP server replacing the preexisting FTP server used by regression.boost.org. Configured and tested it. Inventoried the old machines, including a monitoring server. Built a replacement wowbagger called wowbagger2 to host a copy of the website - original.boost.org. The monthly cost of a small GCP Compute instance seems to be around 5% of the Rackspace legacy cloud server. Components: Ubuntu 24.04. Apache. PHP 5 PPA. “original.boost.org” continues to host a copy of the earlier boost.org website for comparison and development purposes which is interesting to check.

Launched server instances for corosio.org and paperflow.

Fil-C

Working with Tom Kent to add Fil-C https://github.com/pizlonator/fil-c test into the regression matrix https://regression.boost.org/ . Built a Fil-C container image based on Drone images. Debugging the build process. After a few roadblocks, the latest news is that Fil-C seems to be successfully building. This is not quite finished but should be online soon.

Boost release process boostorg/release-tools

The boostorg/boost CircleCI jobs often threaten to cross the 1-hour time limit. Increased parallel processes from 4 to 8. Increased instance size from medium to large. And yet another adjustment: there are 4 compression algorithms used by the releases (gz, bz2, 7z, zip) and it is possible to find drop-in replacement programs that go much faster than the standard ones by utilizing parallelization. lbzip2 pigz. The substitute binaries were applied to publish-releases.py recently. Now the same idea in ci_boost_release.py. All of this reduced the CircleCI job time by many minutes.

Certain boost library pull requests were finally merged after a long delay allowing an upgrade of the Sphinx pip package. Tested a superproject container image for the CircleCI jobs with updated pip packages. Boost is currently in a code freeze so this will not go live until after 1.91.0. Sphinx docs continue to deal with upgrade incompatibilities. I prepared another set of pull requests to send to boost libraries using Sphinx.

Doc Previews and Doc Builds

Antora docs usually show an “Edit this Page” link. Recently a couple of Alliance developers happened to comment the link didn’t quite work in some of the doc previews, and so that opened a topic to research solutions and make the Antora edit-this-page feature more robust if possible. The issue is that Boost libraries are git submodules. When working as expected submodules are checked out as “HEAD detached at a74967f0” rather than “develop”. If Antora’s edit-this-page code sees “HEAD detached at a74967f0” it will default to the path HEAD. That’s wrong on the GitHub side. A solution we found (credit to Ruben Perez) is to set the antora config to edit_url: ‘{web_url}/edit/develop/{path}’. Don’t leave a {ref} type of variable in the path.

Rolling out the antora-downloads-extension to numerous boost and alliance repositories. It will retry the ui-bundle download.

Refactored the release-tools build_docs scripts so that the gems and pip packages are organized into a format that matches Gemfile and requirement.txt files, instead of what the script was doing before “gem install package”. By using a Gemfile, the script becomes compatible with other build systems so content can be copy-pasted easily.

CircleCI superproject builds use docbook-xml.zip, where the download url broke. Switched the link address. Also hosting a copy of the file at https://dl.cpp.al/misc/docbook-xml.zip

Boost website boostorg/website-v2

Collaborated in the process of on-boarding the consulting company Metalab who are working on V3, the next iteration of the boost.org website.

Disable Fastly caching to assist metalab developers.

Gitflow workflow planning meetings.

Discussions about how Tools should be present on the libraries pages.

On the DB servers, adjusted postgresql authentication configurations from md5 to scram-sha-256 on all databases and multiple ansible roles. Actually this turns out to be a superficial change even though it should be done. The reason is that newer postgres will use scram-sha-256 behind-the-scenes regardless.

Wrote deploy-qa.sh, a script to enable metalab QA engineers to deploy a pull request onto a test server. The precise git SHA commit of any open pull request can be tested.

Wrote upload-images.sh, a script to store Bob Ostrom’s boost cartoons in S3 instead of the github repo.

Mailman3

Synced production lists to the staging server. Wrote a document in the cppalliance/boost-mailman repo explaining how the multi-step process of syncing can be done.

boostorg

Migrated cppalliance/decimal to boostorg/decimal.

Jenkins

The Jenkins server is building documentation previews for dozens of boostorg and cppalliance repositories where each job is assigned its own “workspace” directory and then proceeds to install 1GB of node_modules. That was happening for every build and every pull request. The disk space on the server was filling up, every few weeks yet another 100GB. Rather than continue to resize the disk, or delete all jobs too quickly, was there the opportunity for optimization? Yes. In the superproject container image relocate the nodejs installation to /opt/nvm instead of root’s home directory. The /opt/nvm installation can now be “shared” by other jobs which reduces space. Conditionally check if mermaid is needed and/or if mermaid is already available in /opt/nvm. With these modifications, since each job doesn’t need to install a large amount of npm packages the job size is drastically reduced.

Upgraded server and all plugins. Necessary to fix spurious bugs in certain Jenkins jobs.

Debugging Jenkins runners, set subnet and zone on the cloud server configurations.

Fixed lcov jobs, that need cxxstd=20

Migrated many administrative scripts from a local directory on the server to the jenkins-ci repository. Revise, clean, discard certain scripts.

Dmitry contributed diff-reports that should now appear in every pull request which has been configured for LCOV previews.

Implemented –flags in lcov build scripts [–skip-gcovr] [–skip-genhtml] [–skip-diff-report] [–only-gcovr]

Ansible role task: install check_jenkins_queue nagios plugin automatically from Ansible.

GHA

Completed a major upgrade of the Terraform installation which had lagged upstream code by nearly two years.

Deployed a series of GitHub Actions runners for Joaquin’s latest benchmarks at https://github.com/boostorg/boost_hub_benchmarks. Installed latest VS2026. MacOS upgrade to 26.3.

Drone

Launched new MacOS 26 drone runners, and FreeBSD 15.0 drone runners.

Statement from the C++ Alliance on WG21 Committee Meeting Support

2026-03-27T00:00:00+00:00

The C++ Alliance is proud to support attendance at WG21 committee meetings. We believe that facilitating the attendance of domain experts produces better outcomes for C++ and for the broader ecosystem, and we are committed to making participation more accessible.

We want to be unequivocally clear: the C++ Alliance does not, and will never, direct or compel attendees to vote in any particular way. Our support comes with no strings attached. Those who attend are free and encouraged to exercise their independent judgment on every proposal before the committee.

The integrity of the WG21 standards process depends on the independence of its participants. We respect that process deeply, and any suggestion to the contrary does not reflect our values or our program.

If you are interested in learning more about our attendance program, please reach out to us at info@cppalliance.org.

Corosio Beta: Coroutine-Native Networking for C++20

2026-03-11T00:00:00+00:00

Corosio Beta: Coroutine-Native Networking for C++20

The C++ Alliance is releasing the Corosio beta, a networking library designed from the ground up for C++20 coroutines. We are inviting serious C++ developers to use it, break it, and tell us what needs to change before it goes to Boost formal review.

The Gap C++20 Left Open

C++20 gave us coroutines. It did not give us networking to go with them. Boost.Asio has added coroutine support over the years, but its foundations were laid for a world of callbacks and completion handlers. Retrofitting coroutines onto that model produces code that works, but never quite feels like the language you are writing in. We decided to find out what networking looks like when you start over.

What Corosio Is

Corosio is a coroutine-only networking library for C++20. It provides TCP sockets, acceptors, TLS streams, timers, and DNS resolution. Every operation is an awaitable. You write co_await and the library handles executor affinity, cancellation, and frame allocation. No callbacks. No futures. No sender/receiver.

auto [socket] = co_await acceptor.async_accept();
auto n = co_await socket.async_read_some(buffer);
co_await socket.async_write(response);

Corosio runs on Windows (IOCP), Linux (epoll), and macOS (kqueue). It targets GCC 12+, Clang 17+, and MSVC 14.34+, with no dependencies outside the standard library. Capy, its I/O foundation, is fetched automatically by CMake.

Built on Capy

Corosio is built on Capy, a coroutine I/O foundation library that ships alongside it. The core insight driving Capy’s design comes 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’s IoAwaitable protocol ensures coroutines resume on the correct executor after I/O completes, without thread-local globals, implicit context, or manual dispatch. Cancellation follows the same forward-propagation model: stop tokens flow from the top of a coroutine chain to the platform API boundary, giving you uniform cancellation across all operations. Frame allocation uses thread-local recycling pools to achieve zero steady-state heap allocations after warmup.

What We Are Asking For

We are looking for feedback on correctness, ergonomics, platform behavior, documentation, and performance under real workloads. Specifically:

Does the executor affinity model hold up under production conditions?
Does cancellation behave correctly across complex coroutine chains?
Are there platform-specific edge cases in the IOCP, epoll, or kqueue backends?
Does the zero-allocation model hold in your deployment scenarios?

We are inviting serious C++ developers, especially if you have shipped networking code, to use it, break it, and tell us what your experience was. The Boost review process rewards libraries that arrive having already faced serious scrutiny.

Get It

git clone https://github.com/cppalliance/corosio.git
cd corosio
cmake -S . -B build -G Ninja
cmake --build build

Or with CMake FetchContent:

include(FetchContent)
FetchContent_Declare(corosio
  GIT_REPOSITORY https://github.com/cppalliance/corosio.git
  GIT_TAG        develop
  GIT_SHALLOW    TRUE)
FetchContent_MakeAvailable(corosio)
target_link_libraries(my_app Boost::corosio)

Requires: CMake 3.25+, GCC 12+ / Clang 17+ / MSVC 14.34+

Resources

Corosio on GitHub – https://github.com/cppalliance/corosio

Corosio Docs – https://develop.corosio.cpp.al/

Capy on GitHub – https://github.com/cppalliance/capy

Capy Docs – https://develop.capy.cpp.al/

File an Issue – https://github.com/cppalliance/corosio/issues

A postgres library for Boost

2026-01-23T00:00:00+00:00

Do you know Boost.MySQL? If you’ve been reading my posts, you probably do. Many people have wondered ‘why not Postgres?’. Well, the time is now. TL;DR: I’m writing the equivalent of Boost.MySQL, but for PostgreSQL. You can find the code here.

Since libPQ is already a good library, the NativePG project intends to be more ambitious than Boost.MySQL. In addition to the expected Asio interface, I intend to provide a sans-io API that exposes primitives like message serialization.

Throughout this post, I will go into the intended library design and the rationales behind its design.

The lowest level: message serialization

PostgreSQL clients communicate with the server using a binary protocol on top of TCP, termed the frontend/backend protocol. The protocol defines a set of messages used for interactions. For example, when running a query, the following happens:

┌────────┐                                    ┌────────┐
│ Client │                                    │ Server │
└───┬────┘                                    └───┬────┘
    │                                             │
    │  Query                                      │
    │ ──────────────────────────────────────────> │
    │                                             │
    │                        RowDescription       │
    │ <────────────────────────────────────────── │
    │                                             │
    │                              DataRow        │
    │ <────────────────────────────────────────── │
    │                                             │
    │                        CommandComplete      │
    │ <────────────────────────────────────────── │
    │                                             │
    │                        ReadyForQuery        │
    │ <────────────────────────────────────────── │
    │                                             │

In the lowest layer, this library provides functions to serialize and parse such messages. The goal here is being as efficient as possible. Parsing functions are non-allocating, and use an approach inspired by Boost.Url collections:

Parsing database types

The PostgreSQL type system is quite rich. In addition to the usual SQL built-in types, it supports advanced scalars like UUIDs, arrays and user-defined aggregates.

When running a query, libPQ exposes retrieved data as either raw text or bytes. This is what the server sends in the DataRow packets shown above. To do something useful with the data, users likely need parsing and serializing such types.

The next layer of NativePG is in charge of providing such functions. This will likely contain some extension points for users to plug in their types. This is the general form of such functions:

system::error_code parse(span<const std::byte> from, T& to, const connection_state&);
void serialize(const T& from, dynamic_buffer& to, const connection_state&);

Note that some types might require access to session configuration. For instance, dates may be expressed using different wire formats depending on the connection’s runtime settings.

At the time of writing, only ints and strings are supported, but this will be extended soon.

Composing requests

Efficiency in database communication is achieved with pipelining. A network round-trip with the server is worth a thousand allocations in the client. It is thus critical that:

The protocol properly supports pipelining. This is the case with PostgreSQL.
The client should expose an interface to it, and make it very easy to use. libPQ does the first, and NativePG intends to achieve the second.

NativePG pipelines by default. In NativePG, a request object is always a pipeline:

// Create a request
request req;

// These two queries will be executed as part of a pipeline
req.add_query("SELECT * FROM libs WHERE author = $1", {"Ruben"});
req.add_query("DELETE FROM libs WHERE author <> $1", {"Ruben"});

Everything you may ask the server can be added to request. This includes preparing and executing statements, establishing pipeline synchronization points, and so on. It aims to be close enough to the protocol to be powerful, while also exposing high-level functions to make things easier.

Reading responses

Like request, the core response mechanism aims to be as close to the protocol as possible. Since use cases here are much more varied, there is no single response class, but a concept, instead. This is what a response_handler looks like:


struct my_handler {
    // Check that the handler is compatible with the request,
    // and prepare any required data structures. Called once at the beginning
    handler_setup_result setup(const request& req, std::size_t pipeline_offset);

    // Called once for every message received from the server
    // (e.g. `RowDescription`, `DataRow`, `CommandComplete`)
    void on_message(const any_request_message& msg);

    // The overall result of the operation (error_code + diagnostic string).
    // Called after the operation has finished.
    const extended_error& result() const;
};

Note that on_message is not allowed to report errors. Even if a handler encounters a problem with a message (imagine finding a NULL for a field where the user isn’t expecting one), this is a user error, rather than a protocol error. Subsequent steps in the pipeline must not be affected by this.

This is powerful but very low-level. Using this mechanism, the library exposes an interface to parse the result of a query into a user-supplied struct, using Boost.Describe:

struct library
{
    std::int32_t id;
    std::string name;
    std::string cpp_version;
};
BOOST_DESCRIBE_STRUCT(library, (), (id, name, cpp_version))

// ...
std::vector<library> libs;
auto handler = nativepg::into(libs); // this is a valid response_handler

Network algorithms

Given a user request and response handler, how do we send these to the server? We need a set of network algorithms to achieve this. Some of these are trivial: sending a request to the server is an asio::write on the request’s buffer. Others, however, are more involved:

Reading a pipeline response needs to verify that the message sequence is what we expected, for security, and handle errors gracefully.
The handshake algorithm, in charge of authentication when we connect to the server, needs to respond to server authentication challenges, which may come in different forms.

Writing these using asio::async_compose is problematic because:

They become tied to Boost.Asio.
They are difficult to test.
They result in long compile times and code bloat due to templating.

At the moment, these are written as finite state machines, similar to how OpenSSL behaves in non-blocking mode:

// Reads the response of a pipeline (simplified).
// This is a hand-wired generator.
class read_response_fsm {
public:
    // User-supplied arguments: request and response
    read_response_fsm(const request& req, response_handler_ref handler);

    // Yielded to signal that we should read from the server
    struct read_args { span<std::byte> buffer; };

    // Yielded to signal that we're done
    struct done_args { system::error_code result; };

    variant<read_args, done_args>
    resume(connection_state&, system::error_code io_result, std::size_t bytes_transferred);
};

The idea is that higher-level code should call resume until it returns a done_args value. This allows de-coupling from the underlying I/O runtime.

Since NativePG targets C++20, I’m considering rewriting this as a coroutine. Boost.Capy (currently under development - hopefully part of Boost soon) could be a good candidate for this.

Putting everything together: the Asio interface

At the end of the day, most users just want a connection object they can easily use. Once all the sans-io parts are working, writing it is pretty straight-forward. This is what end user code looks like:

// Create a connection
connection conn{co_await asio::this_coro::executor};

// Connect
co_await conn.async_connect(
    {.hostname = "localhost", .username = "postgres", .password = "", .database = "postgres"}
);
std::cout << "Startup complete\n";

// Compose our request and response
request req;
req.add_query("SELECT * FROM libs WHERE author = $1", {"Ruben"});
std::vector<library> libs;

// Run the request
co_await conn.async_exec(req, into(libs));

Auto-batch connections

While connection is good, experience has shown me that it’s still too low-level for most users:

Connection establishment is manual with async_connect.
No built-in reconnection or health checks.
No built-in concurrent execution of requests. That is, async_exec first writes the request, then reads the response. Other requests may not be executed during this period. This limits the connection’s throughput.

For this reason, NativePG will provide some higher-level interfaces that will make server communication easier and more efficient. To get a feel of what we need, we should first understand the two main usage patterns that we expect.

Most of the time, connections are used in a stateless way. For example, consider querying data from the server:

request req;
req.add_query("SELECT * FROM libs WHERE author = $1", {"Ruben"});
co_await conn.async_exec(req, res);

This query is not mutating connection state in any way. Other queries could be inserted before and after it without making any difference.

I plan to add a higher-level connection type, similar to redis::connection in Boost.Redis, that automatically batches concurrent requests and handles reconnection. The key differences with connection would be:

Several independent tasks can share an auto-batch connection. This is an error for connection.
If several requests are queued at the same time, the connection may send them together to the server using a single system call.
There is no async_connect in an auto-batch connection. Reconnection is handled automatically.

Note that this pattern is not exclusive to read-only or individual queries. Transactions can work by using protocol features:

request req;
req.set_autosync(false); // All subsequent queries are part of the same transaction
req.add_query("UPDATE table1 SET x = $1 WHERE y = 2", {42});
req.add_query("UPDATE table2 SET x = $1 WHERE y = 42", {2});
req.add_sync(); // The two updates run atomically
co_await conn.async_exec(req, res);

Connection pools

I mentioned there were two main usage scenarios in the library. Sometimes, it is required to use connections in a stateful way:

request req;
req.add_simple_query("BEGIN"); // start a transaction manually
req.add_query("SELECT * FROM library WHERE author = $1 FOR UPDATE", {"Ruben"}); // lock rows
co_await conn.async_exec(req, lib);

// Do something in the client that depends on lib
if (lib.id == "Boost.MySQL")
    co_return; // don't

// Now compose another request that depends on what we read from lib
req.clear();
req.add_query("UPDATE library SET status = 'deprecated' WHERE id = $1", {lib.id});
req.add_simple_query("COMMIT");
co_await conn.async_exec(req, ignore);

The key point here is that this pattern requires exclusive access to conn. No other requests should be interleaved between the first and the second async_exec invocations.

The best way to solve this is by using a connection pool. This is what client code could look like:

co_await pool.async_exec([&] (connection& conn) -> asio::awaitable<system::error_code> {
    request req;
    req.add_simple_query("BEGIN");
    req.add_query("SELECT balance, status FROM accounts WHERE user_id = $1 FOR UPDATE", {user_id});

    account_info acc;
    co_await conn.async_exec(req, into(acc));

    // Check if account has sufficient funds and is active
    if (acc.balance < payment_amount || acc.status != "active")
        co_return error::insufficient_funds;

    // Call external payment gateway API - this CANNOT be done in SQL
    auto result = co_await payment_gateway.process_charge(user_id, payment_amount);

    // Compose next request based on the external API response
    req.clear();
    if (result.success) {
        req.add_query(
            "UPDATE accounts SET balance = balance - $1 WHERE user_id = $2",
            {payment_amount, user_id}
        );
        req.add_simple_query("COMMIT");
    }
    co_await conn.async_exec(req, ignore);

    // The connection is automatically returned to the pool when this coroutine completes
    co_return result.success ? error_code{} : error::payment_failed;
});

I explicitly want to avoid having a connection_pool::async_get_connection() function, like in Boost.MySQL. This function returns a proxy object that grants access to a free connection. When destroyed, the connection is returned to the pool. This pattern looks great on paper, but runs into severe complications in multi-threaded code. The proxy object’s destructor needs to mutate the pool’s state, thus needing at least an asio::dispatch to the pool’s executor, which may or may not be a strand. It is so easy to get wrong that Boost.MySQL added a pool_params::thread_safe boolean option to take care of this automatically, adding extra complexity. Definitely something to avoid.

SQL formatting

As we’ve seen, the protocol has built-in support for adding parameters to queries (see placeholders like $1). These placeholders are expanded in the server securely.

While this covers most cases, sometimes we need to generate SQL that is too dynamic to be handled by the server. For instance, a website might allow multiple optional filters, translating into WHERE clauses that might or might not be present.

These use cases require SQL generated in the client. To do so, we need a way of formatting user-supplied values without running into SQL injection vulnerabilities. The final piece of the library becomes a format_sql function akin to the one in Boost.MySQL.

Final thoughts

While the plan is clear, there is still much to be done here. There are dedicated APIs for high-throughput data copying and push notifications that need to be implemented. Some of the described APIs have a solid working implementation, while others still need some work. All in all, I hope that this library can soon reach a state where it can be useful to people.

Systems, CI Updates Q4 2025

2026-01-22T00:00:00+00:00

Doc Previews and Doc Builds

The pull request to isomorphic-git “Support git commands run in submodules” was merged, and released in the latest version. (See previous post for an explanation). The commit modified 153 files, all the git api commands, and tests applying to each one. The next step is for upstream Antora to adjust package.json and refer to the newer isomorphic-git so it will be distributed along with Antora. Since isomorphic-git is more widely used than just Antora, their userbase is already field testing the new version.

Created an antora extension https://github.com/cppalliance/antora-downloads-extension that will retry ui-bundle downloads. The Boost Superproject builds sometimes fail because of Antora download failures. I am now in the process of rolling out this extension to all affected repositories. It must be included in each playbook if that playbook downloads the bundle as part of the build process.

Adjusted doc previews to update the existing PR comments instead of posting many new ones, to reduce the email spam effect. The job will modify a timestamp in the PR comment which allows developers to see the most recent build time and if the pages rebuilt successfully. I needed to solve some puzzles to implement this, since usually Jenkins jobs are stateless and don’t know if they previously posted a comment, or which comment it was that should be modified across subsequent jobs runs. It turns out there is a feature “Build with Parameters”, and properties/parameters can be saved in the job.

Boost website boostorg/website-v2

Lowered the CPU threshold on the horizontal pod autoscaler to scale pods more rapidly when there is increased traffic.

When web visitors go to the wrong domain or URL, set the redirects to 301 “moved permanently”. Reduced the number of redirect hops by sending visitors directly to the final URL www.boost.org.

Investigated a bug where PDF files were timing out and crashing the server. Those should not be parsed by beautiful soup or lxml.

During this quarter we published boost 1.90.0. Worked closely with the release managers to resolve problems during the release. The boost.org website was not fully updating after importing the new version.

Meetings about CMS feature, other topics. Many general discussions about website issues.

Mailman3

When unmoderating a new user on mailman3 an administrator must click a drop-down and select “Default Processing” so this subscriber may send emails directly to the list and not continue to be moderated. I have started developing an enhancement in Postorius whereby there is one simple button “Accept and Unmoderate” thus streamlining the process. However as often happens with new and radical ideas sent to the Mailman maintainers, they put up roadblocks. While I believe the new feature is promising, and it is helpful to quickly unmoderate users, without skipping that step, the future of the pull request is uncertain.

boost-ci

Created a Fastly CDN mirror of keyserver.ubuntu.com at keyserver.boost.org. If keyserver.ubuntu.com experiences occasional outages but keys are cached on the CDN mirror, then CI jobs will be able to proceed without difficulty. Configured both Drone and boost-ci to use the CDN at keyserver.boost.org.

Jenkins

Beast2 doc previews. Capy previews. JSON lcov jobs. Openmethod doc previews.

Modified email notifications to send ‘recovery’ type messages after failed jobs. Other enhancements to Jenkins jobs.

Boost release process boostorg/release-tools

When building releases with publish-release.py, generate “nodocs” copies of the Boost releases and upload them to archives.boost.io. The “nodocs” versions are now functional. If anyone would like to accelerate their CI build process, set the target URL to nodocs such as: https://archives.boost.io/release/1.90.0/source-nodocs/boost_1_90_0.tar.gz .

Migrated the release workstation instance from GCP to AWS so that during the next Boost release 1.91.0 the server will be closer to AWS S3, allowing file uploads to transfer faster. Designed a mechanism that resizes the server instance on a cron schedule via GHA. Most of the time it’s quite small, but during releases the server is allocated more CPU.

Drone

Microsoft Windows - VS2026 container image.
Ubuntu 25.10 container image.

GHA

Added CI jobs to build “documentation” in the boostorg/container repository. GHA will test doc builds, which helps when debugging modifications to documentation.

Fil-C is a “fanatically compatible memory-safe implementation of C and C++.” https://github.com/pizlonator/fil-c Upon request, I composed an example Fil-C GitHub Actions job at https://github.com/sdarwin/fil-c-demo which was then applied by developers in other Boost repositories.

Containers galore

2026-01-18T00:00:00+00:00

During Q4 2025, I’ve been working in the following areas:

Boost.Bloom

Written an article explaining the usage and implementation of the recently introduced bulk operations.

Boost.Unordered

Written maintenance fixes PR#320, PR#321, PR#326, PR#327, PR#328, PR#335.

Boost.MultiIndex

Refactored the library to use Boost.Mp11 instead of Boost.MPL (PR#87), remove pre-C++11 variadic argument emulation (PR#88) and remove all sorts of pre-C++11 polyfills (PR#90). These changes are explained in an article and will be shipped in Boost 1.91. Transition is expected to be mostly backwards compatible, though two Boost libraries needed adjustments as they use MultiIndex in rather advanced ways (see below).

Boost.Flyweight

Adapted the library to work with Boost.MultiIndex 1.91 (PR#25).

Boost.Bimap

Adapted the library to work with Boost.MultiIndex 1.91 (PR#50).

Other Boost libraries

Helped set up the Antora-based doc build chain for DynamicBitset (PR#96, PR#97, PR#98).
Same with OpenMethod (PR#40).
Fixed concept compliance of iterators provided by Spirit (PR#840, PR#841).

Experiments with Fil-C

Fil-C is a C and C++ compiler built on top of LLVM that adds run-time memory-safety mechanisms preventing out-of-bounds and use-after-free accesses. I’ve been experimenting with compiling Boost.Unordered test suite with Fil-C and running some benchmarks to measure the resulting degradation in execution times and memory usage. Results follow:

Proof of concept of a semistable vector

By “semistable vector” I mean that pointers to the elements may be invalidated upon insertion and erasure (just like a regular std::vector) but iterators to non-erased elements remain valid throughout. I’ve written a small proof of concept of this idea and measured its performance against non-stable std::vector and fully stable std::list. It is dubious that such container could be of interest for production use, but the techniques explored are mildly interesting and could be adapted, for instance, to write powerful safe iterator facilities.

Teaser: exploring the `std::hive` space

In short, std::hive (coming in C++26) is a container with stable references/iterators and fast insertion and erasure. The reference implementation for this container relies on a rather convoluted data structure, and I started to wonder if something simpler could deliver superior performance. Expect to see the results of my experiments in Q1 2026.

Website

Filed issues #1936, #1937, #1984.

Support to the community

I’ve been part of a task force with the C++ Alliance to review the entire catalog of Boost libraries (170+) and categorize them according to their maintainance status and relevance in light of additions to the C++ standard library over the years.
Supporting the community as a member of the Fiscal Sponsorship Committee (FSC).

Decimal is Accepted and Next Steps

2026-01-15T00:00:00+00:00

After two reviews the Decimal (https://github.com/cppalliance/decimal) library has been accepted into Boost. Look for it to ship for the first time with Boost 1.91 in the Spring. For current and prospective users, a new release series (v6) is available on the releases page of the library. This major version change contains all of the bug fixes and addresses comments from the second review. We have once again overhauled the documentation based on the review to include a significant increase in the number of examples. Between the Basic Usage and Examples tabs on the website we believe there’s now enough information to quickly make good use of the library. One big quality of life worth highlighting for this version is that it ships with pretty printers for both GDB and LLDB. It is a huge release (1108 commits with a diff stat of >50k LOC), but is be better than ever. I expect that this is the last major version that will be released prior to moving to the Boost release cycle.

Where to go from here?

As I have mentioned in previous posts, the int128 (https://github.com/cppalliance/int128) library started life as the backend for portable arithmetic and representation in the Decimal library. It has since been expanded to include more of the standard library features that are unnecessary as a back-end, but useful to many people like <format> support. The last major update that I intend to make to the library prior to proposal for Boost is to add CUDA support. This would not only add portability to another platform for many users, it would open the door for Decimal to also have CUDA support. I will also be looking at a few of our performance measures as I think there are still places for improvement (such as signed 128-bit division).

Lastly, towards the end of this quarter (March 5 - March 15), I will be serving as the review manager for Alfredo Correa’s Multi (https://github.com/correaa/boost-multi) library. Multi is a modern C++ library that provides manipulation and access of data in multidimensional arrays for both CPU and GPU memory. Feel free to give the library a go now and comment on what you find. This is a very high quality library which should have an exciting review.

From Prototype to Product: MrDocs in 2025

2025-10-28T00:00:00+00:00

In 2024, the MrDocs project was a fragile prototype. It documented Boost.URL, but the CLI, configuration, and build process were unstable. Most users could not run it without direct help from the core group. That unstable baseline is the starting point for this report.

In 2025, we moved the codebase to minimum-viable-product shape. I led the releases that stabilized the pipeline, aligned the configuration model, and documented the work in this report to support a smooth leadership transition. This post summarizes the 2024 gaps, the 2025 fixes, and the recommended directions for the next phase.

System Overview
2024: Lessons from a Fragile Prototype
2025: From Prototype to MVP
2026: Beyond the MVP
Acknowledgments
Conclusion

System Overview

MrDocs is a C++ documentation generator built on Clang. It parses source with full language fidelity, links declarations to their comments, and produces reference documentation that reflects real program structure—templates, constraints, and overloads included.

Traditional tools often approximate the AST. MrDocs uses the AST directly, so documentation matches the code and modern C++ features render correctly.

Unlike single-purpose generators, MrDocs separates the corpus (semantic data) from the presentation layer. Projects can choose among multiple output formats or extend the system entirely: supply custom Handlebars templates or script new generators using the plugin system. The corpus is represented in the generators as a rich JSON-like DOM. With schema files, MrDocs enables integration with build systems, documentation frameworks, or IDEs.

From the user’s perspective, MrDocs behaves like a well-engineered CLI utility. It accepts configuration files, supports relative paths, accepts custom build options, and reports warnings in a controlled, compiler-like fashion. For C++ teams transitioning from Doxygen, the command structure is somewhat familiar, but the internal model is designed for reproducibility and correctness. Our goal is not just to render reference pages but to provide a reliable pipeline that any C++ project seeking modern documentation infrastructure can adopt.

graph LR A[Source] --> B[Clang] B --> C[Corpus] C --> D{Plugin Layer} subgraph Generator E[HTML] F[AsciiDoc] G[XML] G2[...] end D --> E D --> F D --> G D --> G2 E --> H{Plugin Layer} H --> H2[Published Docs] F --> H G --> H G2 --> H C --> I[Schema Export] I --> J[Integrations
IDEs & Build Systems]

2024: Lessons from a Fragile Prototype

MrDocs entered 2024 as a proof-of-concept built for Boost.URL. It could document one or two curated codebases and produce asciidoc pages for Antora, but the workflow stopped there. The CLI exposed only the scenarios we needed. Configuration options lived in internal notes. The only dependable build path was the script sequence we used inside the Alliance. External users hit errors and missing options almost immediately.

Stability was just as fragile: We had no sanitizers, no warnings-as-errors, and inconsistent CI hardware. The binaries crashed as soon as they saw unfamiliar code. The pipeline worked only when the input looked like Boost.URL. Point it at slightly different code patterns and it would segfault. Each feature landed as a custom patch, so logic duplicated across generators, and fixing one path broke another.

Early releases: Release v0.0.1 captured that prototype: the early Handlebars engine, the HTML generator, the DOM refactor, and a list of APIs that only the core team could drive. v0.0.2 added structured configuration, automatic compile_commands.json, and better SFINAE handling, but the tool was still insider-only.

Leadership transition: Late in 2024 I became project lead with two initial priorities: document the gaps and describe the true limits of the system. That set the 2025 baseline—a functional prototype that needed coherence, reproducibility, and trust before it could call itself a product.

What 2025 later fixed were the weaknesses we saw here: configuration coherence, generator unification, schema validation, and basic options were all missing. The CLI, configuration files, and code drifted apart. Generators evolved independently with duplicated code and inconsistent naming. Editors had no schema to lean on. Extraction rules were ad hoc, which made the output incomplete. CI ran on an improvised matrix with no caching, sanitizers, or coverage, so regressions slipped through. That was the starting point.

Summary: 2024 produced a working demo, not a reproducible system. Each success exposed another weak link and clarified what had to change in 2025.

In short:

2024 left us with a working prototype but no coherent architecture.
The system could demonstrate the concept, but not sustain or reproduce it.
Every improvement exposed another weak link, and every success demanded more structure than the system was built to handle.
It was a year of learning by exhaustion—and setting the stage for everything that came next.

Key 2024 checkpoints align with the timeline below:

%%{init: {"theme": "base", "themeVariables": {"primaryColor": "#f7f9ff", "primaryBorderColor": "#9aa7e8", "primaryTextColor": "#1f2a44", "lineColor": "#b4bef2", "secondaryColor": "#fbf8ff", "tertiaryColor": "#ffffff", "fontSize": "14px"}}}%% timeline title Prototypes 2024 Q1 : Boost.URL showcase 2024 Q2 : CLI gaps 2024 Q3 : Config + SFINAE fixes 2024 Q4 : Leadership transition

2025: From Prototype to MVP

I started the year with a gap analysis that compared MrDocs to other C++ documentation pipelines. From that review I defined the minimum viable product and three priority tracks. Usability covered workflows and surface area that make adoption simple. Stability covered deterministic behavior, proper data structures, and CI discipline. Foundation covered configuration and data models that keep code, flags, and documentation aligned. The 2025 releases followed those tracks and turned MrDocs from a proof of concept into a tool that other teams can adopt.

v0.0.3 — Consistency. We replaced ad-hoc behavior with a coherent system: a single source of truth for configuration kept CLI, config files, and docs in sync; generators and templates were unified so changes propagate by design; core semantic extraction (e.g., concepts, constraints, SFINAE) became reliable; and CI hardened around reproducible, tested outputs across HTML and Antora.
v0.0.4 — Foundation. We introduced precise warning controls and a family of extract-* options to match established tooling, added a JSON Schema for configuration (enabling editor validation/autocomplete), delivered a robust reference system for documentation comments, brought initial inline formatting to generators, and simplified onboarding with a cross-platform bootstrap script. CI gained sanitizers, coverage checks, and modern compilers.
v0.0.5 — Stabilization. We redesigned documentation metadata to support recursive inline elements, enforced safer polymorphic types with optional references and non-nullable patterns, and added user-facing improvements (sorting, automatic compilation database detection, quick reference indices, improved namespace/overload grouping, LLDB formatters). The website and documentation UI were refreshed for accessibility and responsiveness, new demos (including self-documentation) were published, and CI was further tightened with stricter policies and cross-platform bootstrap enhancements.

Together, these releases executed the roadmap derived from the initial gap analysis: they aligned the moving parts, closed the most important capability gaps, and delivered a stable foundation that future work can extend without re-litigating fundamentals.

%%{init: {"theme": "base", "themeVariables": { "primaryColor": "#e4eee8", "primaryBorderColor": "#affbd6", "primaryTextColor": "#000000", "lineColor": "#baf9d9", "secondaryColor": "#f0eae4", "tertiaryColor": "#ebeaf4", "fontSize": "14px" }}}%% mindmap root((MVP Evolution)) v0.0.3 Config sync Shared templates CI discipline v0.0.4 Warning controls Schema Bootstrap v0.0.5 Recursive docs Nav refresh Tooling polish

v0.0.3: Enforcing Consistency

v0.0.3 is where MrDocs stopped being a collection of one-off special cases and became a coherent system. Before this release, features landed in a single generator and drifted from the others; extraction handled only the narrowly requested pattern and crashed on nearby ones; and options were inconsistent—some hard-coded, some missing from CLI/config, with no mechanism to keep code, docs, and flags aligned.

What changed: The v0.0.3 release fixes this foundation. We introduced a single source of truth for configuration options with TableGen-style metadata: docs, the config file, and the CLI always stay in sync. We added essential Doxygen-like options to make basic projects immediately usable and filled obvious gaps in symbols and doc comments.

We implemented metadata extraction for core symbol types and their information—such as template constraints, concepts, and automatic SFINAE detection. We unified generators and templates so changes propagate by design, added tagfile support and “lightweight reflection” to documentation comments as lazy DOM objects and arrays, and extended Handlebars to power the new generators. These features allowed us to create the initial version of the website and ensure the documentation is always in sync.

Build and testing discipline: CI, builds, and tests were hardened. All generators were now tested, LLVM caching systems improved, and we launched our first macOS release (important for teams working on Antora UI bundles). All of this long tail of performance, correctness, and safety work turned “works on my machine” into repeatable, adoptable output across HTML and Antora.

v0.0.3 was the inflection point. For the first time, developers could depend on consistent configuration, shared templates, and predictable behavior across generators. It aligned internal tools, eliminated duplicated effort, and replaced trial-and-error debugging with reproducible builds. Every improvement in later versions built on this foundation.

Categorized improvements for v0.0.3

Configuration Options: enforcing consistency, reproducible builds, and transparent reporting
- Enforce configuration options are in sync with the JSON source of truth (a1fb8ec6, 9daf71fe)
- File and symbol filters (1b67a847, b352ba22)
- Reference and symbol configuration (a3e4477f, 30eaabc9)
- Extraction options (41411db2, 1214d94b)
- Reporting options (f994e47e, 0dd9cb45)
- Configuration structure (c8662b35, dcf5beef, 4bd3ea42)
- CLI workflows (a2dc4c78, 3c0f90df)
- Warnings (4eab1933, 5e586f2b, 0e2dd713)
- SettingsDB (225b2d50, 51639e77)
- Deterministic configuration (b5449741)
- Global configuration documentation (ec3dbf5c)
Generators: unification, new features, and early refactoring
- Antora/HTML generator consistency (e674182f, 82e86a6c, 9154b9c5)
- HTML generator improvements (a28cb2f7, 064ce55a, 5f6665d8)
- Documentation for generators (2382e8cf, 646a1e5b)
- Supporting new output formats (58a79f74, 271dde57, 9d9f6652)
- Handlebars improvements (ebf4dbeb, be76fc07)
- Generator tooling (00fc84cf, 6a69747d)
- Navigation helpers (fdccad42)
- DOM optimizations (9b41d2e4)
Libraries and metadata: unification, fixes, and extraction enhancements
- Info node visitor and traversal improvements (be86a08d, 58ab5a5e)
- Metadata consistency (544ee37d, 62f8a2bd, bd9c704f)
- Template and concept support (4b0b4a71, 57cf74de, 92aa76a4)
- Symbol resolution and references (f64d4a06, aa9333d4)
- Documentation improvements (5d3f21c8)
Website and Documentation: turning features into a showcase and simplifying workflows
- Create website (05400c3c, 8fba2020)
- Use the new features to create an HTML panel demos workflow (12ceadee, d38d3e1a, c46c4a91)
- Unify Antora author mode playbook (999ea4f3)
- Generator use cases and trade-offs (2307ca6a)
- Correctness and simplification (4d884f43, 55214d72, b078bead, d8b7fcf4, 96484836, 62f361fb)
Build, Testing, and Releases: strengthening CI, improving LLVM caching workflow, and stabilizing releases
- Templates are tested with golden tests (2bc09e65, 9eece731)
- LLVM caches and runners improvements (4c14e875, bd54dc7c, 3d92071a, 8537d3db, f3b33a47, 5982cc7e, 93487669)
- Enable macOS workflow (390159e3)
- Stabilize artifacts (5e0f628e, d1c3566e, 62736e45)
- Tests support individual file inputs, which improved local tests considerably (75b1bc52)
- Performance, correctness, and safety (a820ad79, 43e5f252, a382820f, fbcb5b2d, 6a2290cb, 49f4125f)

v0.0.4: Establishing the Foundation

v0.0.4 completed the core capabilities we need for production. With the moving parts aligned in v0.0.3, this release focused on the fundamentals. It added consistent warning options, extraction controls that match established tools, schema support for IDE auto-completion, a complete reference system for doc comments, and initial inline formatting in the generators. The bootstrap script became a one-step path to a working build. We also hardened the pipeline with modern CI practices—sanitizers, coverage integration, and standardized presets.

Categorized improvements for v0.0.4

Configuration and Extraction: structured configuration, extraction controls, and schema validation
- Configuration schema (d9517e1d, 5f846c1c, ffa0d1a6)
- Extraction filters (0a60bb98, a7d7714d)
- Reference configuration (d18a8ab3)
- Documentation metadata (6676c1e8)
Warnings and Reporting: consistent governance with CLI parity
- Warning controls (2a29f0a0, 6d3c1f47)
- Extract options (extract-{public,protected,private,inline}) (aa5a6be3)
- CLI defaults (d85439c3)
Generators: Javadoc, inline formatting, and reference improvements
- Documentation reference system (4b430f9b, 73489e2b)
- Javadoc metadata (8dd3af67, f7e59d4c)
- Inline formatting (5c7490a3, d1d80745)
- XML generator alignment (9867e0d2, 0f890f2c)
Build and CI: sanitizers, coverage, and reproducible builds
- Sanitizer integration (6257c747, 88954d7f)
- Coverage reporting (bf195759)
- Relocatable build (std::format) (7b871032)
- Bootstrap modernization (3eec9a48, 71afb87b, 524e7923)

v0.0.5: Stabilization and Public Readiness

v0.0.5 marked the transition toward a sustained development model and prepared the project for handoff. This release focused on presentation, polish, and reliability—ensuring that MrDocs was ready not only for internal use but for public visibility. During this period, we expanded the set of public demos, refined the website and documentation, and stabilized the infrastructure to support a growing user base. The goal was to leave the project in a state where it could continue evolving smoothly, with a stable core, clear development practices, and a professional public face.

Community and visibility: Beyond the commits, this release reflected broader activity around the project. We generated and published several new demos, many of which revealed integration issues that were subsequently fixed. As more external users began adopting MrDocs, the feedback loop accelerated: bug reports, feature requests, and real-world edge cases guided much of the work. New contributors joined the team, collaboration became more distributed, and visibility increased. Around the same time, I introduced MrDocs to developers at CppCon 2025, where it received strong feedback from library authors testing it on their own projects. The tool was beginning to gain recognition as a viable, modern alternative to Doxygen.

Technical progress: This release focused on correctness. We redesigned the documentation comment data structures to support recursive inline elements and render Markdown and HTML-style formatting correctly. We moved to non-nullable polymorphic types and optional references so that invariants fail at compile time rather than at runtime. User-facing updates included new sorting options, automatic compilation database detection, a quick reference index, broader namespace and overload grouping, and LLDB formatters for Clang and MrDocs symbols. We refreshed the website and documentation UI for accessibility and responsiveness, added new demos (including the MrDocs self-reference), and tightened CI with more sanitizers, stricter warning policies, and cross-platform bootstrap improvements.

Together, these improvements completed the transition from a developing prototype to a dependable product. v0.0.5 established a stable foundation for others to build on—polished, documented, and resilient—so future releases could focus on extending capabilities rather than consolidating them. With this release, the project reached a point where the handoff could occur naturally, closing one chapter and opening another.

Categorized improvements for v0.0.5

Metadata: documentation inlines and safety improvements
- Recursive documentation inlines (51e2b655)
- Consistent sorting options for members and namespaces (sort-members-by, sort-namespace-members-by) (f0ba28dd, a0f694dc)
- Non-nullable polymorphic types and optional references (c9f9ba13, 8ef3ffaf, bd3e1217, afa558a6, 6ba8ef6b)
- Consistent metadata class family hierarchy pattern (6d495497)
- MrDocsSettings includes automatic compilation database support (9afededb, a1f289de)
- Quick reference index (68e029c1, 940c33f4)
- Namespace/using/overloads grouping includes using declarations and overloads as shadows (69e1c3bc, d722b7d0, 2b59269c)
- Conditional explicit clauses in templated methods (2bff4e2f)
- Destructor overloads supported in class templates (336ad319)
- Using declarations include all shadow variants (88a1cebf, 9253fd8f, a7d5cf6a)
- show-enum-constants option (07b69e1c)
- Custom LLDB formatters for Clang and MrDocs symbols (069bd8f4, f83eca17, 1b39fdd7, aefc53c7)
- Performance, correctness, and safety (d1788049, 3bd94cff, 8a811560, 3ff37448, ad1e7baa, b10b8aa3, 482c0be8, d66da796, ec8daa11, 5234b67c, 5e879b10, 35e14c93, d5a28a89, 6878c199, 21ce3e74, 2da2081b, b528ae11)
Website and Documentation: new demos and a new website
- New demos (cfa9eb7d, 1b930b86, c18be83e, 177fae4a, 33275050)
- Website and documentation refresh (35e14c93, a6437742)
- Self-documentation (f2a5f77e)
- Antora enhancements (5ed0f48f)
Build, Testing, and Releases: improvements and hardening CI
- Toolchain and CI hardening (6257c747, 88954d7f, bf195759, ba0dcfd3)
- Bootstrap improvements (3eec9a48, 71afb87b, 524e7923, 4b79ef41, 7d27204e, 988e9ebc, 94a5b799, be7332cf, 4d705c96, f48bbd2f, f9363461)
- Performance, correctness, and safety (5aa714b2, 469f41ee, 629f1848, 2f0dd8c1, acf7c107)

2026: Beyond the MVP

MrDocs now ships a working MVP, but significant foundational work remains. The priority framework is the same: start with gap analysis, shape an MVP (or now just a viable product), and rank follow-on work against that baseline. In 2025 we invested in presentation earlier than infrastructure. That inversion still raises costs: each foundational change forces rework across user-facing pieces.

I do not know how the leadership model will evolve in 2026. The team might keep a single coordinator or move to shared stewardship. Regardless, the project only succeeds if we continue investing in foundational capabilities. The steps below outline the recommendations I believe will help keep MrDocs sustainable over the long term.

%%{init: {"theme": "base", "themeVariables": { "primaryColor": "#f2eadf", "primaryBorderColor": "#ffe8c6", "primaryTextColor": "#000000", "lineColor": "#ffe8c8", "secondaryColor": "#e8ebf3", "tertiaryColor": "#eceaf4", "fontSize": "14px" }}}%% mindmap root((2026 Priorities)) Reflection Describe symbols Shared walkers Metadata Recursive docs Stable names Typed expressions Extensions Script helpers Plugin ABI Dependencies Curated toolchain Opt-in stubs Community Integration demos Outreach cadence

Strategic Prioritization

Aligning priorities is itself the highest priority. At the start of my tenure as project lead we followed a strict sequence—gap analysis, then an MVP, then a set of priorities—but that model exposed limitations once work began to land. The issue tracker does not reflect how priorities relate to each other, and as individual tickets close the priority stack does not adjust automatically. The project’s complexity now amplifies the risk: without a clear view of dependencies we can assign a high-value engineer to a task that drags several teammates into the same bottleneck, resulting in net-negative progress. Defining priorities therefore includes understanding the team’s skills, mapping how they collaborate, and making sure no one becomes a sink that blocks everyone else. Alignment across roles remains essential so the plan reflects the people who actually execute it.

The tooling already exists to put this into practice. GitHub now lets us mark issues as blocked by or blocking others and to model parent/child relationships. We can use those relationships to reorganize the priorities programmatically. Once the relationships are encoded, priorities gain semantic meaning because we can explain why a small ticket matters in the larger story. Priorities become the byproduct of higher-level goals— narratives about the product—rather than a short-term static wish list of individual features.

We also need to strengthen the operational tools that keep the team coordinated. Coverage in CI is still far below our other C++ Alliance projects, and the gap shows up as crashes whenever a new library explores an untested path in the codebase. Improving coverage is a priority in its own right. We can pair that effort with automation and analysis tools like ReviewDog to accelerate code-review feedback, Danger.js to enforce pull-request policies, CodeClimate or similar services for static analysis, and clang-tidy checks to catch issues earlier. Finally, we can invite other collaborators to revisit the gap analysis and MVP, including C++Alliance colleagues who specialize in marketing. Their perspective will help us assign priorities that reflect both technical dependencies and the project’s broader positioning.

Reflection

The corpus keeps drifting out of sync because every important path in MrDocs duplicates representation by hand. Almost every subsystem reflects data from one format to another, and almost every internal operation traverses those structures. Each time we adjust a field we have to edit dozens of call sites, and even small mistakes create inconsistent state—different copies of the “truth” that evolve independently. Reflection eliminates this churn. If we can describe the corpus once and let the code iterate over those descriptions, the boilerplate disappears, the traversals remain correct, and we stop fighting the same battle.

A lightweight option would be to enforce the corpus from JSON the way we treat configuration, but the volume of metadata in AST makes that impractical. Instead, we lean on compile-time reflection utilities such as Boost.Describe and Boost.mp11. With those libraries we can convert the corpus to any representation, and each generator—including future binary or JSON targets—sees the same schema automatically. MrDocs can even emit the schema that powers each generator, keeping the schema, DOM, and documentation in sync. This approach also fixes the long-standing lag in the XML generator, where updates have historically been manual and error-prone.

The following sequence diagram illustrates how reflection consolidates data flow without duplicating logic:

sequenceDiagram participant AST as Clang AST participant Corpus as Typed Corpus participant Traits as Reflect Traits participant DOM as Corpus DOM participant Generators as Generators participant Clients as Integrations AST->>Corpus: Extract symbols Corpus->>Traits: Publish descriptors Traits->>DOM: Build type-erased nodes DOM->>Generators: Supply normalized schema Generators->>Clients: Deliver outputs Clients->>Generators: Provide feedback Generators->>Traits: Request updates

Process: We can start by describing the Symbols, Javadoc, and related classes, shipping each refactor as a dedicated PR so reviews stay contained. Each description removes custom specializations, reverts to = default where possible, and replaces old logic with static asserts that enforce invariants. We generalize the main merge logic first, then update callers such as the AST visitor that walks RecordTranche, ensuring the comments data structure matches the new descriptions. A MRDOCS_DESCRIBE_DERIVED helper can enumerate derived classes so every visit routine becomes generic. Once the C++ side is described, we rebuild the lazy DOM objects on top of Describe so their types mirror the DOM layout directly.

Use cases: Redundant non-member functions like tag_invoke, operator⇔, toString, and merge collapse into shared implementations that use traits unless real customization is required. New generators—binary, JSON, or otherwise—drop in with minimal code because the schema and traversal logic already exist. The XML generator stops maintaining a private representation and simply reads the described elements. We can finally standardize naming conventions (kebab-case or camelCase) because the schema enforces them. Generating the Relax NG Compact file becomes just another output produced from the same description. A metadata walker can then discover auxiliary objects and emit DOM documentation automatically. As a side effect of integrating Boost.mp11, we can extend the tag_invoke context protocol with tuple-based helpers for mrdocs::FromValue, further narrowing the gap between concrete and DOM objects.

Metadata

MrDocs still carries metadata gaps that are too large to ignore. The subsections below highlight the three extraction areas that demand sustained effort; each of them blocks the rest of the system from staying consistent.

Recursive blocks and inlines. Release 0.0.5 introduced the data structures for recursive Javadoc elements, but we still do not parse all of those structures. The fix is straightforward in concept—extend the CommonMark-based parser so every block and inline variant becomes a first-class node—but the implementation is long because there are many element types. We can ship this incrementally by opening issues and sub-issues, tackling one structure per PR, and starting with block elements before moving to inlines. The existing post-process documentation finalizer already contains the mechanics; we just need to wire each rule into the new documentation nodes.

Legible names. The current name generator appends hash fragments to differentiate symbols lazily, which makes references unstable and awkward. We need a stable allocator that remembers which symbols claimed which names. The highest-priority symbol should receive the base name, and suffixes should cascade to less critical overloads so the visible entries stay predictable. Moving the generator into the extraction phase and storing the assignments there ensures anchors remain stable, lets us update artifacts such as the Boost.URL tagfile, and produces names that actually read well.

Populate expressions. Whenever the extractor fails to recognize an expression, it falls back to the raw source string. That shortcut prevents us from applying the usual transformations, especially inside requires-expressions where implementation-defined symbols appear. We should introduce typed representations for the constructs we already understand and continue to store strings for the expressions we have not modeled yet. As coverage grows, more expressions flow through the structured pipeline, and the remaining string-based nodes shrink to the truly unknown cases.

Extensions and Plugins

Extensions and plugins aim at the same outcome—letting projects customize MrDocs—but they operate at different layers. Extensions run inside the application, usually through interpreters we bundle. We already ship Lua and Duktape, yet today they only power a handful of Handlebars helpers. The plan is to widen that surface: add more interpreters where it makes sense, extend helper support so extensions can participate in escaping and formatting, and give extensions the ability to consume the entire corpus. With that access, an extension can list every symbol, emit metadata in formats we do not yet support, or transform the corpus before it reaches a native generator. The same mechanism enables quality-of-life utilities, such as a generator extension that checks whether a library’s public API changed according to a policy defined in code.

Plugins, by contrast, are compiled artifacts. They unlock similar customization goals, but their ABI must stay stable, and platform differences mean a plugin built on one system will not run on another. To keep the surface manageable we should expose a narrow wrapper: pass plugins a set of DOM proxies so they never depend on the underlying Info classes, use traits or versioned interfaces to handle incompatibilities, and plan the API carefully before release.

Dependency Resilience

Working with dependent libraries is still the most fragile part of the MrDocs workflow. Environments drift, transitive dependencies change without notice, and heavyweight projects force us to install toolchains we do not actually need. In Boost.URL alone we watch upstream Boost libraries evolve every few weeks; sometimes the code truly breaks, but just as often a new release exercises an untested path in MrDocs and triggers a crash because our coverage is still thin. Other ecosystems push the cost even higher: documenting a library that depends on LLVM can turn a three-second render into an hours-long process because the transitive LLVM headers MrDocs needs are generated at build time, so we must compile and install LLVM merely to obtain include files. CI environments regularly fail for the same reason.

We already experimented with mitigation strategies and should refine them rather than abandon the ideas. Shipping a curated standard library with MrDocs removes one entire category of instability. The option will soon be disabled by default, but users can still enable it or even combine it with the system library when reproducibility matters more than access to system libraries. This mirrors how Clang ships libc++; it does not allow invalid code, it simply guarantees a known baseline.

On top of that, we have preliminary support for user-defined stubs. Configuration files can provide short descriptions of expected symbols from hard-to-build dependencies, and MrDocs can inject those during extraction. For predictable patterns we can auto-generate stubs when the user opts in, synthesizing symbols rather than failing immediately. None of this accepts invalid code—the compiler still diagnoses real errors—but it shields projects from breakage when a transitive dependency tweaks implementation details or when generated headers are unavailable. The features remain optional, so teams can disable synthesis to debug the underlying issue and still benefit from the faster path when schedules are tight. Even if the project moves in another direction we should document the proposal and remove the existing stub hooks deliberately rather than letting them linger undocumented.

The payoffs are clear. Boost libraries could generate documentation without cloning the entire super-project, relying on SettingsDB to produce a compilation database and skipping CMake entirely. MrDocs itself could publish reference docs without building LLVM because the required symbols would come from stubs. Releases would stop breaking every time a transitive dependency changes, and developers would regain hours currently spent firefighting. These are the stability and reproducibility gains we need if we want MrDocs to be the default tooling for large C++ ecosystems.

Follow-up Issues for v0.0.6

To keep this post focused on the big-picture transition, I spun the tactical tasks into GitHub issues for the 0.0.6 milestone. They’re queued up and ready for execution whenever the team circles back to implementation.

List of follow-up issues for v0.0.6

#1081 Support custom stylesheets in the HTML generator
#1082 Format-agnostic Handlebars generator extension
#1083 Allow SettingsDB to describe a single source file
#1084 Guard against invalid source links
#1085 Complete tests for all using declaration forms
#1086 Explore a recursive project layout
#1087 Convert ConfigOptions.json into a schema file
#1088 Separate parent context and parent page
#1089 List deduction guides on the record page
#1090 Expand coverage for Friends
#1091 Remove dependency symbols after finalization
#1092 Review Bash Commands Parser
#1093 Review NameInfoVisitor
#1094 Improve overload-set documentation
#1095 CI uses the bootstrap script
#1096 Connect Antora extensions
#1097 Handlebars: optimize render state
#1098 Handlebars: explore template compilation
#1099 Handlebars: investigate incremental rendering

Acknowledgments

Matheus Izvekov and Krystian Stasiowski kept the Clang integration moving. Their expertise cleared issues that would have stalled us. Gennaro Prota and Fernando Pelliccioni handled the maintenance load that kept the project on schedule. They took on the long tasks and followed them through.

Robert Beeston and Julio Estrada delivered the public face of MrDocs. The site we ship today exists because they turned open-ended goals into a complete experience.

Vinnie Falco, Louis Tatta, and Sam Darwin formed the backbone of my daily support. Vinnie trusted the direction and backed the plan when decisions were difficult. Louis made sure I had space to return after setbacks. Sam kept the Alliance infrastructure running so the team always had what it needed.

Ruben Perez, Klemens Morgenstern, Peter Dimov, and Peter Turcan offered honest feedback whenever we needed another perspective. Their observations sharpened the product and kept collaboration positive.

Joaquín M López Muñoz and Arnaud Bachelier guided me through the people side of leadership. Their advice turned complex situations into workable plans.

Working alongside everyone listed here has been a privilege. Their contributions made this year possible.

Conclusion

The 2025 releases unified the generators, locked the configuration model, added sanitizers and coverage to CI, and introduced features that make the tool usable outside Boost.URL. The project is ready for new contributors because they can extend the code without rebuilding the basics, and downstream teams can run the CLI on large codebases and expect predictable output.

While we delivered those releases, I learned that engineering progress depends on steady communication. Remote discussions often sound negative even when people agree on the goals, so I schedule short check-ins, add light signals like emojis, and keep space for conversations that are not task-driven. I also protect time to listen and ask for help when the workload gets heavy; if I lose that time, every deadline slips anyway.

Final Reflections

Technical conversations start negative by default, so add clear signals when you agree or appreciate the work.
Assume terse feedback comes from the medium, not the person, and respond with patience.
Keep informal connection habits—buddy calls, breaks, or quick chats—to maintain trust.
Look after your own health and use outside support when needed.
Never allow the schedule to block real listening time; reset your calendar when that happens.

Making the Clang AST Leaner and Faster

2025-10-20T00:00:00+00:00

Modern C++ codebases — from browsers to GPU frameworks — rely heavily on templates, and that often means massive abstract syntax trees. Even small inefficiencies in Clang’s AST representation can add up to noticeable compile-time overhead.

This post walks through a set of structural improvements I recently made to Clang’s AST that make type representation smaller, simpler, and faster to create — leading to measurable build-time gains in real-world projects.

A couple of months ago, I landed a large patch in Clang that brought substantial compile-time improvements for heavily templated C++ code.

For example, in stdexec — the reference implementation of the std::execution feature slated for C++26 — the slowest test (test_on2.cpp) saw a 7% reduction in build time.

Also the Chromium build showed a 5% improvement (source).

At a high level, the patch makes the Clang AST leaner: it reduces the memory footprint of type representations and lowers the cost of creating and uniquing them.

These improvements will ship with Clang 22, expected in the next few months.

How elaboration and qualified names used to work

Consider this simple snippet:

namespace NS {
  struct A {};
}
using T = struct NS::A;

The type of T (struct NS::A) carries two pieces of information:

It’s elaborated — the struct keyword appears.
It’s qualified — NS:: acts as a nested-name-specifier.

Here’s how the AST dump looked before this patch:

ElaboratedType 'struct NS::A' sugar
`-RecordType 'test::NS::A'
  `-CXXRecord 'A'

The RecordType represents a direct reference to the previously declared struct A — a kind of canonical view of the type, stripped of syntactic details like struct or namespace qualifiers.

Those syntactic details were stored separately in an ElaboratedType node that wrapped the RecordType.

Interestingly, an ElaboratedType node existed even when no elaboration or qualification appeared in the source (example). This was needed to distinguish between an explicitly unqualified type and one that lost its qualifiers through template substitution.

However, this design was expensive: every ElaboratedType node consumed 48 bytes, and creating one required extra work to uniquify it — an important step for Clang’s fast type comparisons.

A more compact representation

The new approach removes ElaboratedType entirely. Instead, elaboration and qualifiers are now stored directly inside RecordType.

The new AST dump for the same example looks like this:

RecordType 'struct NS::A' struct
|-NestedNameSpecifier Namespace 'NS'
`-CXXRecord 'A'

The struct elaboration now fits into previously unused bits within RecordType, while the qualifier is tail-allocated when present — making the node variably sized.

This change both shrinks the memory footprint and eliminates one level of indirection when traversing the AST.

Representing `NestedNameSpecifier`

NestedNameSpecifier is Clang’s internal representation for name qualifiers.

Before this patch, it was represented by a pointer (NestedNameSpecifier*) to a uniqued structure that could describe:

The global namespace (::)
A named namespace (including aliases)
A type
An identifier naming an unknown entity
A __super reference (Microsoft extension)

For all but cases (1) and (5), each NestedNameSpecifier also held a prefix — the qualifier to its left.

For example:

Namespace::Class::NestedClassTemplate<T>::XX

This would be stored as a linked list:

[id: XX] -> [type: NestedClassTemplate<T>] -> [type: Class] -> [namespace: Namespace]

Internally, that meant seven allocations totaling around 160 bytes:

NestedNameSpecifier (identifier) – 16 bytes
NestedNameSpecifier (type) – 16 bytes
TemplateSpecializationType – 48 bytes
QualifiedTemplateName – 16 bytes
NestedNameSpecifier (type) – 16 bytes
RecordType – 32 bytes
NestedNameSpecifier (namespace) – 16 bytes

The real problem wasn’t just size — it was the uniquing cost. Every prospective node has to be looked up in a hash table for a pre-existing instance.

To make matters worse, ElaboratedType nodes sometimes leaked into these chains, which wasn’t supposed to happen and led to several long-standing bugs.

A new, smarter `NestedNameSpecifier`

After this patch, NestedNameSpecifier becomes a compact, tagged pointer — just one machine word wide.

The pointer uses 8-byte alignment, leaving three spare bits. Two bits are used for kind discrimination, and one remains available for arbitrary use.

When non-null, the tag bits encode:

A type
A declaration (either a __super class or a namespace)
A namespace prefixed by the global scope (::Namespace)
A special object combining a namespace with its prefix

When null, the tag bits instead encode:

An empty nested name (the terminator)
The global name
An invalid/tombstone entry (for hash tables)

Other changes include:

The “unknown identifier” case is now represented by a DependentNameType.
Type prefixes are handled directly in the type hierarchy.

Revisiting the earlier example, after the patch its AST dump becomes:

DependentNameType 'Namespace::Class::NestedClassTemplate<T>::XX' dependent
`-NestedNameSpecifier TemplateSpecializationType 'Namespace::Class::NestedClassTemplate<T>' dependent
  `-name: 'Namespace::Class::NestedClassTemplate' qualified
    |-NestedNameSpecifier RecordType 'Namespace::Class'
    | |-NestedNameSpecifier Namespace 'Namespace'
    | `-CXXRecord 'Class'
    `-ClassTemplate NestedClassTemplate

This representation now requires only four allocations (156 bytes total):

DependentNameType – 48 bytes
TemplateSpecializationType – 48 bytes
QualifiedTemplateName – 16 bytes
RecordType – 40 bytes

That’s almost half the number of nodes.

While DependentNameType is larger than the previous 16-byte “identifier” node, the additional space isn’t wasted — it holds cached answers to common queries such as “does this type reference a template parameter?” or “what is its canonical form?”.

These caches make those operations significantly cheaper, further improving performance.

Wrapping up

There’s more in the patch than what I’ve covered here, including:

RecordType now points directly to the declaration found at creation, enriching the AST without measurable overhead.
RecordType nodes are now created lazily.
The redesigned NestedNameSpecifier simplified several template instantiation transforms.

Each of these could warrant its own write-up, but even this high-level overview shows how careful structural changes in the AST can lead to tangible compile-time wins.

I hope you found this deep dive into Clang’s internals interesting — and that it gives a glimpse of the kind of small, structural optimizations that add up to real performance improvements in large C++ builds.

The C++ Alliance

On Triremes, Aircraft, and Molecular Modelling Simulations

Joining Community, Detecting Communities, Making Community.

Joining Community

Detecting Communities

Making Community

Mr.Docs: Niebloids, Reflection, Code Removal, New XML Generator

Function objects: documenting what users actually call

Reflection: from boilerplate to a single generic template

Phase 1: Boost.Describe

Phase 2: custom reflection macros

Phase 3: removing the overloads

The result

The XML Generator: a full rewrite in 350 lines

Smaller fixes

Looking ahead

Speed and Safety

The road to C++20 modules, Capy and Redis

Modules in using std::cpp 2026

import boost is upon us

Redis meets Capy

Redis PubSub improvements

Hubs, intervals and math

boost::container::hub

using std::cpp 2026

Boost.Unordered

Boost.Bimap

Boost.ICL

Support to the community

Systems, CI Updates Q1 2026

Code Coverage Reports - designing new GCOVR templates

Server Hosting

Fil-C

Boost release process boostorg/release-tools

Doc Previews and Doc Builds

Boost website boostorg/website-v2

Mailman3

boostorg

Jenkins

GHA

Drone

Statement from the C++ Alliance on WG21 Committee Meeting Support

Corosio Beta: Coroutine-Native Networking for C++20

Corosio Beta: Coroutine-Native Networking for C++20

The Gap C++20 Left Open

What Corosio Is

Built on Capy

What We Are Asking For

Get It

Resources

A postgres library for Boost

The lowest level: message serialization

Parsing database types

Composing requests

Reading responses

Network algorithms

Putting everything together: the Asio interface

Auto-batch connections

Connection pools

SQL formatting

Final thoughts

Systems, CI Updates Q4 2025

Doc Previews and Doc Builds

Boost website boostorg/website-v2

Mailman3

boost-ci

Jenkins

Boost release process boostorg/release-tools

Drone

GHA

Containers galore

Boost.Bloom

Boost.Unordered

Boost.MultiIndex

Boost.Flyweight

Boost.Bimap

Other Boost libraries

Experiments with Fil-C

Proof of concept of a semistable vector

Teaser: exploring the std::hive space

`import boost` is upon us

`boost::container::hub`

Teaser: exploring the `std::hive` space

Representing `NestedNameSpecifier`

A new, smarter `NestedNameSpecifier`