The C++ Alliance

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.

Conan Packages for Boost

2025-10-16T00:00:00+00:00

Back in April my former colleague Christian Mazakas has announced his work on registry of nightly Boost packages for vcpkg. That same month Conan developers have introduced a new feature that significantly simplified providing of an alternative Conan package source. These two events gave me an idea to create an index of nightly Boost packages for Conan.

Conan Remotes

Conan installs packages from a remote, which is usually a web server. When you request a package in a particular version range, the remote determines if it has a version that satisfies that range, and then sends you the package recipe and, if possible, compatible binaries for the package.

Local-recipes-index is a new kind of Conan remote that is not actually a remote server and is just a local directory hierarchy of this kind:

recipes
├── pkg1
│   ├── all
│   │   ├── conandata.yml
│   │   ├── conanfile.py
│   │   └── test_package
│   │       └── ...
│   └── config.yml
└── pkg2
    ├── all
    │   ├── conandata.yml
    │   ├── conanfile.py
    │   └── test_package
    │       └── ...
    └── config.yml

The directory structure is based on the Conan Center’s underlying GitHub project. In actuality only the config.yml and conanfile.py files are necessary. The former tells Conan where to find the package recipes for each version (and hence determines the set of available versions), the latter is the package recipe. In theory there could be many subdirectories for different versions, but in reality most if not all packages simply push all version differences into data files like conandata.yml and select the corresponding data in the recipe script.

My idea in a nutshell was to set up a scheduled CI job that each day would run a script that takes Boost superproject’s latest commits from develop and master branches and generates a local-recipes-index directory hierarchy. Then to have recipes directories coming from different branches merged together, and the result be merged with the results of the previous run. Thus, after a while an index of Boost snapshots from each day would accumulate.

Modular Boost

The project would have been fairly simple if my goal was to just provide nightly packages for Boost. Simply take the recipe from the Conan Center project and replace getting sources from a release archive with getting sources from GitHub. But I also wanted to package every Boost library separately. This is generally known as modular Boost packages (not to be confused with Boost C++ modules). There is an apparent demand for such packages, and in fact this is exactly how vcpkg users consume Boost libraries.

In addition to the direct results—the Conan packages for Boost libraries—such project is a great test of the modularity of Boost. Whether each library properly spells out all of its dependencies, whether there’s enough associated metadata that describes the library, whether the project’s build files are usable without the superproject, and so on. Conan Center (the default Conan remote) does not currently provide modular Boost packages, only packages for monolithic Boost (although it provides options to disable building of specific libraries). Due to that I decided to generate package recipes not only for nightly builds, but for tagged releases too.

Given that, the core element of the project is the script that creates the index from a Boost superproject Git ref (branch name or tag). Each library is a git submodule of the superproject. Every superproject commit contains references to specific commits in submodules’ projects. The script checks out each such commit, determines the library’s dependencies and other properties important for Conan, and outputs config.yml, conanfile.py, conandata.yml, and test_package contents.

Versions

As previously mentioned, config.yml contains a list of supported versions. After one runs the generator script that file will contain exactly one version. You might ask, what exactly is that version? After some research I ended up with the scheme MAJOR.MINOR.0-a.B+YY.MM.DD.HH.mm, where:

MAJOR.MINOR.0 is the next Boost release version;
a implies an alpha-version pre-release;
B is m for the master branch and d for the develop branch;
YY.MM.DD.HH.mm is the authorship date and time of the source commit.

For example, a commit authored at 12:15 on 15th of August 2025 taken from the master branch before Boost 1.90.0 was released would be represented by the version 1.90.0-a.m+25.08.15.12.15. The scheme is an example of semantic versioning. The part between the hyphen and the plus specifies a pre-release, and the part following the plus identifies a specific build. All parts of the version contribute to the versions order after sorting. Importantly, pre-releases are ordered before the release they predate, which makes sense, but isn’t obvious from the first glance.

I originally did not plan to put commit time into the version scheme, as the scheduled CI job only runs once a day. But while working on the project, I also had the package index updated on pushes into the master branch, which overwrote previously indexed versions, and that was never the intention. Also, originally the pre-release part was just the name of the branch, which was good enough to sort master and develop. But with the scope of the project including actual Boost releases and betas, I needed beta versions to sort after master and develop versions, but before releases, hence I made them alpha versions explicitly.

One may ask, why do I even care about betas? By having specific beta versions I want to encourage more people to check out Boost libraries in beta state and find the bugs early on. I hope that if obtaining a beta version is as easy as simply changing one string in a configuration file, more people will check them and that would reduce the amount of bugs shipped in Boost libraries.

Conan Generators

One of the most important Conan features in my opinion is its support for any build system rather than for a limited selection of them. This is done via generators—utilities that Convert platform description and dependency data into configuration files for build systems. In Conan 2.x the regular approach is to have a set of 2 generators for a given build system.

The main one is a dependencies generator, which creates files that tell the build system how to find dependencies. For example, if you are familiar with CMake, the CMakeDependencies generator creates config modules for every dependency.

The other one is a toolchain generator. Those convert platform information into build system configuration files which determine the compiler, computer architecture, OS, and so on. Using CMake as an example again, the CMakeToolchain generator creates a toolchain file.

The reason for the split into 2 generators is that there are cases when you use only one of them. For example, if you don’t have any dependencies, you don’t need a dependencies generator. And when you are working on a project, you might already have the necessary build system configuration files, so you don’t need a toolchain generator.

For my project I needed both for Boost’s main build system, b2. Boost can also be built with CMake, but that’s still not officially supported, and is tested less rigorously. Unfortunately, Conan 2.x doesn’t currently have in-built support for b2. It had it in Conan 1.x, but with the major version increase they’ve removed most of the old generators, and the PR to add it back did not go anywhere. So, I had to implement those 2 generators for b2. Luckily, Conan supports putting such Conan extensions into packages. So, now the package index generation script also creates a package with b2 generators.

The Current State and Lessons Learned

The work is still in its early stage, but the project is in a somewhat usable state already. It is currently located here (I plan to place it under boostorg GitHub organisation with the Boost community’s approval, or, failing that, under cppalliance organisation). You can clone the project and install and use some of the Boost libraries, but not all. I have tested that those libraries build and work on Windows, Linux, and macOS. The b2 generators are almost feature complete at this point.

My future work will be mostly dedicated to discovering special requirements of the remaining libraries and working out ways to handle them. The most interesting problems are handling projects with special “options” (e.g. Boost.Context usually has to be told what the target platform ABI and binary format are), and handling the few external dependencies (e.g. zlib and ICU). Another interesting task is handling library projects with several binaries (e.g. Boost.Log) and dealing with the fact that libraries can change from being compiled to being header-only (yes, this does happen).

There were also several interesting findings. At first I tried determining dependencies from the build scripts. But that turned out to be too brittle, so in the end I decided to use depinst, the tool Boost projects use in CI to install dependencies. This is still a bit too simplistic, as libraries can have optional and platform dependencies. But I will have to address this later.

Switching to depinst uncovered that in Boost 1.89.0 a circular dependency appeared between Boost.Geometry and Boost.Graph. This is actually a big problem for package managers, as they have to build all dependencies for a project before building it, and before that do the same thing for each of the dependencies, and this creates a paradoxical situation where you need to build the project before you build that same project. To make such circular dependencies more apparent in the future, I’ve added a flag to depinst that makes it exit with an error if a cycle is discovered.

Overall, I think Boost modularisation is going fairly well. Every library I’ve tried yet builds correctly without the superproject present. I hope to finish the project soon, preferably before the 1.90.0 release.

After that there’s still an interesting possible addition. Christian’s vcpkg registry mentioned in the very beginning also had a package for a candidate library, so that people could easily install it and try it out during the review period. My package index could in the future also do that. Hopefully that will motivate more people to participate in Boost reviews.

Writing Docs with Visuals and Verve

2025-10-15T00:00:00+00:00

In a past life I worked in the computer journalism business, and learnt over time what attracts people to read a page. Lot’s of things are important, the font used, the spacing between letters and lines and paragraphs, even the width of a column of text is super-important for readability (so the eye does not lose track of the line it is on). Other stuff is important to, readers, especially technical readers, love tables. A table of all the networking libraries available in Boost for example, becomes a reassuring point of reference, as opposed to a bunch of text listing the libraries. Two of the most important factors in drawing readers in are headlines and images. It can take some grey matter and experience and skill to come up with a catchy headline (“Phew - what a scorcher” - is a famous example of a tabloid headline after a super hot day!). The more I worked in journalism the more I appreciated all the skills involved - and those I had and those I had not! When it comes to images, I decided to add at least one image to all the Scenarios in the Boost User Guide (Finance, Networking, Simulation, among others). One of the skills I do not have is that of an artist - so these images mostly had to come from elsewhere. Not all though, for the deformation example in the Simulation scenario, I came up with the following image - which works I guess!

For other images I used AI to come up with some text based diagrams, which do work well as “images” for a technical readership. For example, the following simple flow for a Message Queue shows what is going on, Receiver 3 picking up all the inappropriately addressed messages, as well as its own.

Other images required some research. I must admit I did not know the difference between a petal and a sepal until I did some research on the iris data used in the Machine Learning scenario. The following image is a composite of a picture taken by my wife of an iris in a New Mexico volcanic caldera, and a diagram generated by AI. Now I know, the sepals are the dangly bits I would have called petals before engaging in this research.

Hopefully these images will draw in readers and entice them to try out the scenarios, and then continue their programming journey with the support of Boost libraries.

Another topic I dug into this quarter is to find examples of good and bad practices, and then to tabularize them (remember, tables are trusted references…). I started with error messages. Here is an example of a tedious error message:

error C2679: binary '=': no operator found which takes a right-hand operand of type 'boost::gregorian::date' (or there is no acceptable conversion)

Why is it tedious? Because it is verbose and yet still doesn’t say what the user did wrong, not even the library name is in the message. A shorter, sharper and more helpful message would be:

boost::date_time::invalid_date: "2025-02-30" is not a valid Gregorian date

This message contains the library name (date_time), and the invalid input. Error message content should be a high-priority issue for API developers.

Another topic added to Best Practices is simply API design itself. The Boost filesystem library contains some good examples of clear design, for example - here is a section from the Contributor Guide:

Of course there is an element of style, taste, personal preferences in all these issues. It is totally OK for APIs to reflect those traits of the developers, this guide is there as a check point - a resource to read over and reflect on when evaluating your own work.

Talking of AI - and who isn’t? - I requested the Cpp Alliance give me an image-creating AI API account, so I could add a section to the AI Client scenario on creating images. It is a lot of fun asking an AI to create an image, though you would be correct in thinking you probably could have come up with better yourself! For example, check out this exchange:

Enter your request (ASCII diagram or text) or 'exit': Can you draw an ASCII diagram of a speedboat?

Assistant Response: Sure! Here's a simple ASCII representation of a speedboat:

        __/__
  _____/_____|_____
  \              /
~~~~~~~~~~~~~~~~~~~~~

On a tad more serious note, I added topics on Reflection and Diagnostics to the User Guide. And I scan the Slack conversations for words or phrases that are new to me, and add them to the User Guide Glossary - which is a fun document on its own account. Even a document as potentially dull as a glossary can be fun to create and fun to read. Everybody likes to be entertained when they are reading, it takes the grind out of the experience.

DynamicBitset Reimagined: A Quarter of Flexibility, Cleanup, and Modern C++

2025-10-14T00:00:00+00:00

Over the past three months, I’ve been immersed in a deep and wide-ranging overhaul of the Boost.DynamicBitset library. What started as a few targeted improvements quickly evolved into a full-scale modernization effort—touching everything from the underlying container to iterator concepts, from test coverage to documentation style. More than 170 commits later, the library is leaner, more flexible, and better aligned with modern C++ practices.

Making the core more flexible

The most transformative change this quarter was allowing users to choose the underlying container type for dynamic_bitset. Until now, the implementation assumed std::vector, which limited optimization opportunities and imposed certain behaviors. By lifting that restriction, developers can now use alternatives like boost::container::small_vector, enabling small buffer optimization and more control over memory layout.

This change had ripple effects throughout the codebase. I had to revisit assumptions about contiguous storage, update operators like <<=, >>=, and ensure that reference stability and iterator behavior were correctly handled.

Introducing C++20 iterators

One of the more exciting additions this quarter was support for C++20-style iterators. These new iterators conform to the standard iterator concepts, making dynamic_bitset more interoperable with modern algorithms and range-based utilities.

I added assertions to ensure that both the underlying container and dynamic_bitset itself meet the requirements for bidirectional iteration. These checks are enabled only when compiling with C++20 or later, and they help catch subtle mismatches early—especially when users plug in custom containers.

Saying goodbye to legacy workarounds

With modern compilers and standard libraries, many old workarounds are no longer needed. I removed the max_size_workaround() after confirming that major implementations now correctly account for allocators in max_size(). I also dropped support for obsolete compilers like MSVC 6 and CodeWarrior 8.3, and for pre-standard iostreams, cleaned up outdated macros, and removed compatibility layers for pre-C++11 environments.

These removals weren’t just cosmetic—they simplified the code and made it easier to reason about. In many places, I replaced legacy constructs with standard features like noexcept and std::move().

constexpr support

When it is compiled as C++20 or later, almost all functions in DynamicBitset are now constexpr.

Dropping obsolete dependencies

As part of the cleanup effort, I also removed several outdated dependencies that were no longer justified. These included Boost.Integer (previously used by lowest_bit()), core/allocator_access.hpp, and various compatibility headers tied to pre-C++11 environments. This not only reduces compile-time overhead and cognitive load, but also makes the library easier to audit and maintain.

Strengthening the test suite

A part of this quarter’s work was expanding and refining the test coverage. I added new tests for flip(), resize(), swap(), and operator!=(). I also ensured that input iterators are properly supported in append(), and verified that std::hash behaves correctly even when two bitsets share the same underlying container but differ in size.

Along the way, I cleaned up misleading comments, shortened overly complex conditions, and removed legacy test code that no longer reflected the current behavior of the library. The result is a test suite that’s more robust, more meaningful, and easier to maintain.

Documentation that speaks clearly

I’ve always believed that documentation should be treated as part of the design, not an afterthought. This quarter, I ported the existing documentation to MrDocs and Antora, while fixing and improving a few bits in the process. This uncovered a few MrDocs bugs, some of which remain—but I’m hopeful.

I also spent time harmonizing the style and structure of the library’s comments and docstrings.

I chose to document iterator categories rather than exposing concrete types, which keeps the interface clean and focused on behavior rather than implementation details.

New member functions and smarter implementations

This quarter also introduced several new member functions that expand the expressiveness and utility of dynamic_bitset:

push_front() and pop_front() allow bit-level manipulation at the front of the bitset, complementing the existing back-oriented operations.
find_first_off() and find_next_off() provide symmetric functionality to their find_first() counterparts, making it easier to locate unset bits.
A constructor from basic_string_view was added for C++17 and later, improving interoperability with modern string APIs.

Alongside these additions, I revisited the implementation of several existing members to improve performance and clarity:

push_back() and pop_back() were streamlined for better efficiency.
all() and lowest_bit() were simplified and optimized, with the latter also shedding its dependency on Boost.Integer.
append() was fixed to properly support input iterators and avoid redundant checks.

Minor but impactful cleanups

A large number of small edits improved correctness, readability, and maintainability:

Fixed the stream inserter to set badbit if an exception is thrown during output.
Changed the stream extractor to rethrow any exceptions coming from the underlying container.
Reordered and cleaned up all #include sections to use the "" form for Boost includes where appropriate and to keep include groups sorted.
Removed an example timing benchmark that was misleading and a number of unneeded comments and minor typos across code and docs.

These edits reduce noise and make code reviews and maintenance more pleasant.

Reflections

Looking back, this quarter reminded me of the value of revisiting assumptions. Many of the workarounds and constraints that once made sense are now obsolete. By embracing modern C++ features and simplifying where possible, we can make libraries like dynamic_bitset more powerful and more approachable.

It also reinforced the importance of clarity—both in code and in documentation. Whether it’s a test case, a comment, or a public API, precision and consistency go a long way.

The work continues, but the foundation is stronger than ever. If you’re using dynamic_bitset or thinking about integrating it into your project, I’d love to hear your feedback.

Working on Boost.Bloom roadmap

2025-10-09T00:00:00+00:00

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

Boost.Bloom

Boost.Bloom has been officially released in Boost 1.89. I’ve continued working on a number of roadmap features:

Originally, some subfilters (block, fast_multiblock32 and fast_multiblock64) implemented lookup in a branchful or early-exit way: as soon as a bit checks to zero, lookup terminates (with result false). After extensive benchmarks, I’ve changed these subfilters to branchless execution for somewhat better performance (PR#42). Note that boost::bloom::filter<T, K, ...> is still branchful for K (the number of subfilter operations per element): in this case, branchless execution involves too much extra work and does not compensate for the removed branch speculation. Ivan Matek helped with this investigation.
Added bulk-mode operations following a similar approach to what we did with Boost.Unordered concurrent containers (PR#42).
I’ve been also working on a proof of concept for a dynamic filter where the k and/or k’ values can be specified at run time. As expected, the dynamic filter is slower than its static counterpart, but benchmarks show that execution times can increase by up to 2x for lookup and even more for insertion, which makes me undecided as to whether to launch this feature. An alternative approach is to have a dynamic_filter<T> be a wrapper over a virtual interface whose implementation is selected at run time from a static table of implementations based on static filter<T, K> with K between 1 and some maximum value (this type erasure technique is described, among other places, in slides 157-205 of Sean Parent’s C++ Seasoning talk): performance is much better, but this approach also has drawbacks of its own.
Reviewed a contribution fom Braden Ganetsky to make the project’s CMakeLists.txt more Visual Studio-friendly (PR#33).

Boost.Unordered

Reviewed PR#316.

Boost.MultiIndex

Reviewed PR#83, PR#84.

Boost.Flyweight

Fixed an internal compile error that manifested with newer compilers implementing P0522R0 (PR#23).
Reviewed PR#22.

Boost.PolyCollection

Reviewed PR#32.

Boost website

Filed issues #1845, #1846, #1851, #1858, #1900, #1927, #1936, #1937.
Helped with the transition of the global release notes procedure to one based on the new website repo exclusively (PR#508, PR#510). This procedure is expected to launch in time for the upcoming Boost 1.90 release.

Boost promotion

Prepared and posted around 10 messages on Boost’s X account and Reddit. The activity on social media has grown considerably thanks to the dedication of Rob Beeston and others.

Support to the community

Helped Jean-Louis Leroy get Drone support for the upcoming Boost.OpenMethod library (PR#39).
Supporting the community as a member of the Fiscal Sponsorhip Committee (FSC).

Levelling up Boost.Redis

2025-10-07T00:00:00+00:00

I’ve really come to appreciate Boost.Redis design. With only three asynchronous primitives it exposes all the power of Redis, with features like automatic pipelining that make it pretty unique. Boost.Redis 1.90 will ship with some new exciting features that I’ll cover in this post.

Cancelling requests with asio::cancel_after

Boost.Redis implements a number of reliability measures, including reconnection. Suppose that you attempt to execute a request using async_exec, but the Redis server can’t be contacted (for example, because of a temporary network error). Boost.Redis will try to re-establish the connection to the failed server, and async_exec will suspend until the server is healthy again.

This is a great feature if the outage is transitory. But what would happen if the Redis server is permanently down - for example, because of deployment issue that must be manually solved? The user will see that async_exec never completes. If new requests continue to be issued, the program will end up consuming an unbound amount of resources.

Starting with Boost 1.90, you can use asio::cancel_after to set a timeout to your requests, preventing this from happening:

// Compose your request
redis::request req;
req.push("SET", "my_key", 42);

// If the request doesn't complete within 30s, consider it as failed
co_await conn.async_exec(req, redis::ignore, asio::cancel_after(30s));

For this to work, async_exec must properly support per-operation cancellation. This is tricky because Boost.Redis allows executing several requests concurrently, which are merged into a single pipeline before being sent. For the above to useful, cancelling one request shouldn’t affect other requests. In Asio parlance, async_exec should support partial cancellation, at least.

Cancelling a request that hasn’t been sent yet is trivial - you just remove it from the queue and call it a day. Cancelling requests that are in progress is more involved. We’ve solved this by using “tombstones”. If a response encounters a tombstone, it will get ignored. This way, cancelling async_exec has always an immediate effect, but the connection is kept in a well-defined state.

Custom setup requests

Redis talks the RESP3 protocol. But it’s not the only database system that speaks it. We’ve recently learnt that other systems, like Tarantool DB, are also capable of speaking RESP3. This means that Boost.Redis can be used to interact with these systems.

At least in theory. In Boost 1.89, the library uses the HELLO command to upgrade to RESP3 (Redis’ default is using the less powerful RESP2). The command is issued as part of the reconnection loop, without user intervention. It happens that systems like Tarantool DB don’t support HELLO because they don’t speak RESP2 at all, so there is nothing to upgrade.

This is part of a larger problem: users might want to run arbitrary commands when the connection is established, to perform setup tasks. This might include AUTH to provide credentials or SELECT to choose a database index.

Until now, all you could do is configure the parameters used by the HELLO command. Starting with Boost 1.90, you can run arbitrary commands at connection startup:

// At startup, don't send any HELLO, but set up authentication and select a database
redis::request setup_request;
setup_request.push("AUTH", "my_user", "my_password");
setup_request.push("SELECT", 2);

redis::config cfg {
    .use_setup = true, // use the custom setup request, rather than the default HELLO command
    .setup = std::move(setup_request), // will be run every time a connection is established
};

conn.async_run(cfg, asio::detached);

This opens the door simplifying code using PubSub. At the moment, such code needs to issue a SUBSCRIBE command every time a reconnection happens, which implies some tricks around async_receive. With this feature, you can just add a SUBSCRIBE command to your setup request and forget.

This will be further explored in the next months, since async_receive is currently aware of reconnections, so it might need some extra changes to see real benefits.

Valkey support

Valkey is a fork from Redis v7.3. At the time of writing, both databases are mostly interoperable in terms of protocol features, but they are being developed separately (as happened with MySQL and MariaDB).

In Boost.Redis we’ve committed to supporting both long-term (at the moment, by deploying CI builds to test both).

Race-free cancellation

It is very easy to introduce race conditions in cancellation with Asio. Consider the following code, which is typical in libraries that predate per-operation cancellation:

struct connection
{
    asio::ip::tcp::socket sock;
    std::string buffer;

    struct echo_op
    {
        connection* obj;
        asio::coroutine coro{};

        template <class Self>
        void operator()(Self& self, error_code ec = {}, std::size_t = {})
        {
            BOOST_ASIO_CORO_REENTER(coro)
            {
                while (true)
                {
                    // Read from the socket
                    BOOST_ASIO_CORO_YIELD
                    asio::async_read_until(obj->sock, asio::dynamic_buffer(obj->buffer), "\n", std::move(self));

                    // Check for errors
                    if (ec)
                        self.complete(ec);

                    // Write back
                    BOOST_ASIO_CORO_YIELD
                    asio::async_write(obj->sock, asio::buffer(obj->buffer), std::move(self));

                    // Done
                    self.complete(ec);
                }
            }
        }
    };

    template <class CompletionToken>
    auto async_echo(CompletionToken&& token)
    {
        return asio::async_compose<CompletionToken, void(error_code)>(echo_op{this}, token, sock);
    }

    void cancel() { sock.cancel(); }
};

There is a race condition here. cancel() may actually not cancel a running async_echo. After a read or write completes, the respective handler may not be called immediately, but queued for execution. If cancel() is called within that time frame, the cancellation will be ignored.

The proper way to handle this is using per-operation cancellation, rather than a cancel() method. async_compose knows about this problem and keeps state about received cancellations, so you can write:

// Read from the socket
BOOST_ASIO_CORO_YIELD
asio::async_read_until(obj->sock, asio::dynamic_buffer(obj->buffer), "\n", std::move(self));

// Check for errors
if (ec)
    self.complete(ec);

// Check for cancellations
if (!!(self.get_cancellation_state().cancelled() & asio::cancellation_type_t::terminal))
    self.complete(asio::error::operation_aborted);

In 1.90, the library uses this approach everywhere, so cancellation is reliable. Keeping the cancel() method is a challenge, as it involves re-wiring cancellation slots, so I won’t show it here - but we’ve managed to do it.

Next steps

I’ve got plans to keep working on Boost.Redis for a time. You can expect more features in 1.91, like Sentinel support and more reliable health checks.

Decimal Goes Back to Review

2025-10-06T00:00:00+00:00

We are excited to announce that the Decimal (https://github.com/cppalliance/decimal) library is going back to review for inclusion in Boost from 06 to 15 October. In preparation for this we have made quite a few changes since the indeterminate end of the first review about 9 months ago:

Breaking Changes:

Based on bitwise comparisons with other similar libraries and database software, we have changed the internal encoding of our IEEE 754-compliant types
We spent about 3 months optimizing just back end integer types that are now used throughout the library, and as the internals of decimal128_t
We have changed the type names to better match conventions:
- decimalXX is now decimalXX_t
- decimalXX_fast is now decimal_fastXX_t
The headers have been similarly renamed (e.g. decimal32.hpp -> decimal32_t.hpp), and can now be used independently instead of requiring the monolith based on feedback in Review
Constructors have been simplified to reduce confusion (no more double negative logic)
The default rounding mode has changed to align with IEEE 754, with rounding bugs being squashed across the modes as well

Other Changes:

The documenation content has been overhauled thanks to feedback from Peter Turcan and others during the first review
The docs are no longer a single long page of Asciidoc; we have moved to Antora. Thanks to Joaquín and Christian for making it trivial to copy from Unordered to make that happen.
- https://develop.decimal.cpp.al/
We now support formatting with {fmt}
Benchmarks have been expanded to include GCC _DecimalXX types, and Intel’s libbid. I think people should be pleased with the results now, since that was a huge point of contention at the end of the review
We have added support for CMake pkg config for ease of use
Every post-review issue John was kind enough to consolidate and open have been addressed: https://github.com/cppalliance/decimal/issues?q=is%3Aissue%20state%3Aclosed%20label%3A%22Boost%20Review%22

Continued Developments:

I think the only unaddressed comment from the first review is support for hardware decimal floating point types. There are a few rarer architectures that have native decimal floating point units like POWER10. Is it possible to fully integrate these native types for use in the library? Armed with a compiler farm account I have begun developing a wrapper around the native types that seems to work. Stay tuned.
One item that we have considered, but have not put any effort into yet would be getting the library running on CUDA platforms. If this is a feature that you are interested in, please let us know!
As is always the case with Boost reviews, regardless of the outcome I am sure that we will receive lots of feedback on how to improve the library.

If you are interested, much of the contents of the first review can be found in the original thread on the boost mailing list archive: https://lists.boost.org/archives/list/boost@lists.boost.org/thread/AGFOQZMJ4HKKQ5C5XDDKNJ3VJL72YTWL/

The C++ Alliance

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

Website

Support to the community

Decimal is Accepted and Next Steps

From Prototype to Product: MrDocs in 2025

System Overview

2024: Lessons from a Fragile Prototype

2025: From Prototype to MVP

v0.0.3: Enforcing Consistency

v0.0.4: Establishing the Foundation

v0.0.5: Stabilization and Public Readiness

2026: Beyond the MVP

Strategic Prioritization

Reflection

Metadata

Extensions and Plugins

Dependency Resilience

Follow-up Issues for v0.0.6

Acknowledgments

Conclusion

Making the Clang AST Leaner and Faster

How elaboration and qualified names used to work

A more compact representation

Representing NestedNameSpecifier

A new, smarter NestedNameSpecifier

Wrapping up

Conan Packages for Boost

Conan Remotes

Modular Boost

Teaser: exploring the `std::hive` space

Representing `NestedNameSpecifier`

A new, smarter `NestedNameSpecifier`