asio: Boost.Asio for native C++ and WebAssembly

Open libs/asio/example/asio_quick_start.cpp. This is the complete program we will compile, including its headers:

The context owns the event loop. The timer belongs to that context and stays alive until main ends. post schedules the first handler; it does not call it immediately. That handler prints posted, arms the timer and registers its completion handler. This sequence keeps the output order the same even if the machine pauses before entering run.

The build compiles and executes the program, then compares its output with the file beside it, asio_quick_start.expected. On success, b2 saves the captured output in asio_quick_start.output at the build path printed by its run-and-compare action. Open that file; its contents should be:

The last line uses webcpp’s example-test helper to report completion, including after an Asyncify suspension. It leaves page modules without the Node harness unchanged.

Notice that run returns after both handlers have run. The timer’s 50 ms is a requested delay, not a promise about exact wall-clock execution time. The output deliberately shows no measured duration.

Node executes the generated WebAssembly using JSPI. Its .output file contains exactly the same three lines. Next, run it with Asyncify:

Again the output is unchanged. These runs exercise the source and its suspension under Node; loading a page in a browser is a separate step in Loading the variant a browser runs. If b2 cannot find a compiler or Node, check Building before changing the program. If the output differs, the example runner prints the difference and fails the build.

You have now run the same event loop natively and with both WebAssembly suspension variants. Follow How to schedule deadlines and cancel a wait to schedule several deadlines and cancel a wait, or How to configure the turn limit to configure a finite chain of posted work. For the reason the browser needs a turn limit, read A turn at a time. Exact contracts are in Guarantees and the generated API reference.

variant=debug and variant=release select build optimization, not different APIs. The new WASIp3 runtime verification uses Release builds. JSPI and Asyncify are browser suspension variants; they are not WASIp3 variants. The WASIp3 thread setting and exception setting are independent choices, subject to the SDK runtime availability above. Cooperative threads suspend at blocking WASI operations; this does not provide simultaneous CPU execution on multiple cores.

This is a historical baseline for the WebCPP integration and capability-completion work verified on 2026-11-03, using Boost 1.92.0, Emscripten 6.0.11 and wasi-sdk 34.0. The project now selects Wasmtime 50.0.1 for its regression suites; the original isolated probes used Wasmtime 49.0.3. It is not a list of everything those upstream projects might support in other builds. The 2026-11-06 distribution migration changes type selection and source ownership. The cells below retain their original evidence date; they do not certify the current unsubmitted candidate. Use How-to: consume the shipped implementation for current build rules and Cobalt’s current validation status. The old /webcpp/asio//cobalt target is now a compatibility alias for /webcpp/cobalt//cobalt. Portable consumers use webcpp::cobalt names. Do not infer that an Asio feature has also been tested through a Cobalt wrapper or completion token.

Each cell describes the named feature, not every overload or possible input. Read the profile availability table first: an unavailable profile makes all of its public features unavailable, even if an isolated source file compiles.

<webcpp/asio/config.hpp> defines the following read-only macros as 0 or 1. Use #if, not #ifdef, to inspect them. Do not define these capabilities on the command line: the header rejects attempts to override them.

WEBCPP_ASIO_HAS_OPENSSL=1 is different: it declares that the optional compiled dependency was selected. /webcpp/asio//openssl and //tls supply it together with the matching provider. Outside B2, the application must also supply the matching OpenSSL headers and libraries. Merely defining it cannot satisfy the linker. ssl.hpp rejects native/WASI use without that dependency; Emscripten keeps its portable TLS settings record.

Define a WEBCPP_ASIO_REQUIRE_* switch to a nonzero integer before the first WebCPP include, or on the compiler command line, to require SOCKET_BACKEND, OPENSSL, THREADS, LOCAL_SOCKETS, SIGNALS, SERIAL_PORT or REVERSE_DNS. An absent switch or a value of zero imposes no requirement. The default permits portable applications to select runtime alternatives, including browser transports. Apply configuration consistently to every translation unit.

This compiled example requires a real socket backend and still handles a runtime refusal from the host:

The browser-specific headers diagnose a non-Emscripten target before including Emscripten headers. wasi/stdio_stream.hpp diagnoses targets without the P2 CLI adapter. B2 rejects unsupported SDK/thread/EH combinations and checks the private WASI descriptor ABI. A compiler cannot determine network grants, available peers, trust roots, a page’s isolation headers or whether a host import will block. Those conditions retain runtime errors or the documented host behavior.

In the following tables, browser covers both JSPI and Asyncify. Their API capabilities are the same; their suspension and exception implementations differ. The separate Asio on WASIp2 table records the P2 profile.

WASIp3 keeps Boost.Asio’s scheduler and select reactor. It does not use the JavaScript event bridge or the browser’s handler-count limit. Its syscalls suspend through wasi-libc and the host’s Component Model implementation.

The public Cobalt target builds its static archive with checked compatibility headers and sources on WASIp3. Timers, TCP/UDP and cancellation are exercised through both Asio completion tokens and Cobalt’s own wrappers. The optional /webcpp/asio//cobalt_ssl target adds Cobalt’s SSL wrapper with verified TLS and handshake/transfer cancellation, including partial composed operations. Truncated and cancelled shutdown are also tested; see Use the corrected SSL stream. See Historical Cobalt source integration for integration details and Validation still required for the historical gap inventory. The current Cobalt guide records the subsequent coroutine and application tests. It has no automatic SIGINT/SIGTERM shutdown bridge on WASIp3; internal coroutine cancellation is a separate mechanism. See Why the Wasm runner changes.

OpenSSL local coverage includes native macOS arm64 single/multi with exceptions on/off using Clang, WASIp2 and WASIp3 single with exceptions on/off, and WASIp3 cooperative with exceptions off. A GCC 15 native multi-threaded build with exceptions also passed the TLS tests. Linux Clang/GCC mappings are implemented but not runtime-tested on this macOS host. The native MSVC recipe is implemented; this local macOS matrix does not establish Windows runtime coverage. The source library uses OS threads natively and cooperative threads on WASIp3; it does not make cooperative execution CPU-parallel. TLS tests cover verified handshakes, asynchronous application data, clean shutdown and rejected peer identities. The embedded CA factory’s trust policy, update procedure and local checks are documented in How-to: configure trusted certificate authorities.

The browser’s default socket transport reports operation_not_supported for network operations. The browser resolver does not perform DNS; see Sockets and transports. A TLS settings record is not a TLS implementation.

These are current port boundaries, not claims that WASIp3 itself can never support the missing operations. The compatibility patch belongs to Boost.Asio’s platform layer; implementing the missing POSIX entry points such as sendmsg/recvmsg belongs in wasi-libc. The current port avoids pretending those entry points or process signals exist.

Select threading=multi together with either suspension variant and exception setting. The public target supplies -pthread through the toolset and the threaded main-poll adapter. It does not move main to a worker automatically. The M-only -Wl,--wrap=__syscall_poll adapter uses the pinned SDK’s async poll on the actual browser main thread; worker waits retain the SDK proxy route. This private SDK boundary must be rechecked when Emscripten is upgraded.

A browser io_context must run on the thread that constructed it. Other threads may post ordinary C++ work to its executor. One context does not support simultaneous runners; keep separate contexts per worker. Running it from a different thread triggers a checked-build assertion and returns zero when assertions are disabled, before accessing thread-local JavaScript values.

browser::main_thread_context supplies an Asio executor for DOM callbacks. Construct and destroy that context on the actual browser main thread; copy its executor to workers and use webcpp::asio::post or bind_executor. Obtain JavaScript objects inside the main callback and send ordinary C++ data back to the worker. Do not move emscripten::val handles between threads. The context must outlive calls using its executors, and destruction must not overlap such calls. If a callback destroys its context, an external allocator resource must outlive the callback because queue control survives until it returns. Queued handlers are discarded during shutdown. Handler storage follows its associated allocator; the SDK owns its separate queue/notification storage.

A main-executor callback runs on an ordinary browser callback stack. It must not call a JSPI/Asyncify suspending import or drive the context’s run family. Normal C++ coroutine suspension that returns to its caller is a different mechanism. If moving or invoking a handler throws, queued handlers are discarded and further queued submissions are discarded. Inline main-thread dispatch retains its ordinary direct-call behavior. The exception propagates to the browser callback boundary; recovery after that failure is not promised. Cancellation still belongs to the originating operation; posting a callable does not add a new cancellation protocol.

The host needs a secure context, workers and shared memory. Serve the page with Cross-Origin-Opener-Policy: same-origin and Cross-Origin-Embedder-Policy: require-corp, and check crossOriginIsolated. These deployment requirements cannot be diagnosed in config.hpp. Applications choose their worker-pool size and must retain the runtime while work is pending. Never block the browser main thread waiting for a live worker.

The local lane covers JSPI/Asyncify with EH on/off in an isolated Chrome page:

Repeat with webcpp-suspend=asyncify and exception-handling=off for the other profiles. The driver tests actual main/worker wakeup, DOM handoff, cancellation, allocator routing, queued shutdown and Cobalt thread completion. The exact coverage appears in Browser pthread profiles.

On emscripten, run suspends main into the browser’s event loop in one of two ways, each a variant of the program built from the same sources:

A build asks for a variant with the feature webcpp-suspend, on b2’s command line, b2 toolset=emscripten webcpp-suspend=asyncify, or in a program’s requirements, <webcpp-suspend>asyncify. The feature is propagated, so that every library a program uses is built for its variant, and composite, since Asyncify does not work with WebAssembly exceptions: emcc only warns, and the program traps at run time with RuntimeError: unreachable when it suspends inside a catch block. So asyncify asks for JavaScript-based exceptions itself, and jspi keeps b2’s WebAssembly ones; a build with exception-handling=off compiles with -fno-exceptions in either:

Emscripten finds the suspending imports itself, so no list of them is given. ASYNCIFY_IGNORE_INDIRECT is not set, since the path from main to the reactor’s select passes a virtual call, Asio’s scheduler_task::run. Asyncify adds instrumentation and increases the program size. With -O3 and exceptions enabled, the release examples measured 1.88 to 1.91 times the JSPI WebAssembly size. The ratio depends on the optimization profile and exception setting; see How to compare release sizes and timings for the six-profile matrix with exceptions on and off, separate JavaScript byte counts, build and execution timings, and reproduction commands.

Build a page program and its two variants with webcpp.variants:

The build writes page_program.variants.json beside the JSPI artifact. Its jspi and asyncify objects each contain a script path relative to the manifest and the WebAssembly size in bytes. Serve the manifest, both scripts and their WebAssembly files with their relative layout intact.

The loader is include/webcpp/asio/webcpp-asio-loader.mjs, shipped with the headers. A page imports its load function and calls load('page_program.variants.json'). It detects JSPI by checking whether WebAssembly.Suspending is a function, chooses jspi when it is and asyncify otherwise, and reads the artifact path from the manifest. It resolves that path relative to the final manifest URL after any HTTP redirects, imports the script and awaits its default factory. A custom fetch that supplies no response URL uses the requested manifest URL. The result is {variant, module}.

supportsJspi(scope) permits detection in a supplied scope. pick(manifest, jspi) returns {variant, script} and rejects a missing script for the selected variant. load(manifestUrl, options) accepts an explicit jspi choice, module options passed to the factory, and replacements for fetch and importModule. Failed manifest requests report their URL and HTTP status; fetch, JSON, import and initialization failures propagate to the caller. A failed JSPI load does not silently retry Asyncify.

A relative manifest URL is resolved against the page URL, or against the loader module URL where no page location exists. Factory completion is variant-dependent: the current JSPI factory awaits main, while Asyncify can resolve before a suspended main finishes. An indefinitely running JSPI program therefore reports readiness through its module callbacks; an application observes its own completion signal. The loader test waits for the program’s output, within the driver’s timeout, rather than sleeping for an assumed duration.

The browser lane loads both variants under Node using a file reader for the manifest, and in headless Chrome over loopback HTTP. It exercises this actual page program:

The same lane checks idle waits and animation callbacks under continuous ready work in Chrome. See Browser observations for its measurements and failure criteria.

After a suspension, Asyncify loses the value main returns: a program whose exit status matters, under node, ends with std::exit; webcpp’s own tests end through webcpp::test::exit_status, and a test that does not fails (AGENTS.md chapter 9). asio’s tests pin both cases where node would read a failure as a pass, in each variant: a main that never finishes, and a main that suspended and then returns 1 without the helper.

For a program including <webcpp/asio/ssl.hpp>, add /webcpp/asio//openssl beside /webcpp/asio//asio in its target sources: exe app : app.cpp /webcpp/asio//asio /webcpp/asio//openssl ;. This forwards /webcpp/third_party//openssl, which builds OpenSSL 3.5.9 (commit 45e844fa2a14ec92d146bd8f5778ac130b6625fb) from the unmodified upstream submodule. No installed OpenSSL or OPENSSL_ROOT is used by this target.

In a Git checkout, initialize the source with git submodule update --init third_party/libs/openssl. A WebCPP source distribution already contains the required OpenSSL files and does not need Git. The build needs Python 3, Perl, Make, and the selected compiler toolchain; Git is also used to verify a source checkout. B2 invokes upstream Configure/Make and exports static libssl.a, libcrypto.a and their matching generated headers. Before Configure, it stages the distributable source files in a temporary directory and verifies their paths, file modes and content hashes against the pin. Missing, additional or altered files fail the build. Dot paths and pinned optional upstream repositories are omitted, just as in the source distribution. The temporary source directory also avoids upstream Makefiles’ restriction on source paths containing spaces. Different toolsets, optimization flags, exception settings and thread profiles use separate build directories. Effective C flags and compiler commands also identify separate archive/header directories. Flags retain normal B2 scope: dependency-specific cflags belong on the OpenSSL target, not only on its consumer. Independent concurrent B2 processes should use separate --build-dir directories. threading=single builds OpenSSL with no-threads; threading=multi enables its platform threading implementation. Native recipes support Clang/GCC on macOS/Linux and MSVC on Windows. MSVC uses upstream Configure and nmake, static archives and the B2 runtime/debug settings; the initial Windows recipe uses portable C without requiring NASM.

For a program built both natively and for the browser, use the condition below. It also selects OpenSSL for WASIp2/P3; browser builds retain the settings adapter:

Do not use <toolset>!emscripten:<library>/webcpp/asio//openssl: that spelling silently fails to link OpenSSL in the tested B2 configuration.

Correct configuration errors as follows:

The built-in default and base providers are linked statically. Loading provider modules is disabled; this configuration is not a FIPS build. Both WASI profiles disable assembly, dynamic loading, QUIC, Unix-domain sockets and the OpenSSL thread pool. Native Clang/GCC builds retain upstream assembly optimizations; the initial MSVC recipe uses portable C. The recipe uses function and data sections plus platform dead stripping. A program has one OpenSSL provider. Native Trystero’s /webcpp/trystero//native target builds pinned static libdatachannel and its required nested sources against this same provider, so it can coexist with Asio and Beast. Such a program selects threading=multi and exceptions for Trystero’s worker-thread backend. Libsecp256k1 remains externally provisioned; OPENSSL_ROOT and LIBDATACHANNEL_ROOT do not select alternate providers.

The configured certificate directory is /etc/ssl. A source-built library does not install a system trust store or import the macOS keychain. Use the embedded factory in How-to: configure trusted certificate authorities for portable defaults, or explicitly load the intended CA file, set verify_peer, and verify the peer’s hostname on a raw context. WASI applications using a file must preopen its directory. Embedded authorities need no certificate filesystem access. Both require the needed TCP network capability; linking the library grants no runtime permission.

WASI seeding explicitly selects OpenSSL’s getrandom configuration, whose WASI implementation calls getentropy, then wasi-libc’s secure wasi:random/random.get-random-bytes host import. With Wasmtime’s default host configuration, the generator is seeded from the operating system. The host remains trusted: an embedder can replace its randomness provider. The tests verify that host entropy is requested and a reported entropy failure prevents random output and key generation; they do not prove cryptographic entropy quality or snapshot/restore safety. Reseed policy after restoring a seeded instance requires separate validation.

The reproducible native/WASIp3 test driver is python3 tools/openssl/test/run.py --fresh from the superproject. It needs Python with TLS 1.3 and an OpenSSL 3 command-line program only to create short-lived server fixtures. The client links the source-built library. WASMTIME selects the runtime executable; the recorded WASIp2/P3 checks use wasi-sdk 34.0 and Wasmtime 50.0.1. See Networking features for the target/variant matrix.

The recurring own lane b2 libs/asio/test/tls//tls-integration drives those TLS, embedded-CA and entropy fixtures on native and WASIp3 profiles. The Cobalt-owned libs/cobalt/test/tls//tls-integration lane checks SSL state and cancellation across the same profiles. The separate libs/cobalt/test/tls//tls lane drives the Cobalt fixtures on WASIp2 with each requested exception mode; see Build for WASIp2 for the complete command, including the ordinary Cobalt consumers. b2 libs/asio/test/tls//openssl-upstream is native only: it requests webcpp-openssl-tests=on, builds and runs upstream’s full alltests suite, then links a TLS consumer against those exact archives. The openssl-upstream-msvc-14.3 and openssl-upstream-msvc-14.5 aliases exercise that suite with the corresponding Windows CI toolsets. Ordinary consumers do not run that suite. The upstream harness is unavailable on WASI; the separate integration tests give narrower evidence and do not claim upstream-suite parity. A lane declaration is not evidence that the current candidate passed CI.

The library’s targets implement that distinction:

For a native or WASI client with portable trust defaults, include <webcpp/asio/tls_client_context.hpp> and link /webcpp/asio//tls. The target includes Asio, source-built OpenSSL and /webcpp/third_party//ca_certificates. No certificate file, environment setting, system trust store or network download is read by the factory. WASI needs no certificate directory preopen; a network connection still needs host permission.

This program prepares the context and checks errors without exceptions. With no arguments it uses the embedded roots. An optional argument supplies replacement PEM bytes, not a file path:

The default invocation prints:

Use the resulting context when constructing TLS streams and keep it alive while they exist. The factory enables verify_peer and requires TLS 1.2 or newer. Configure ssl::host_name_verification for the expected hostname and set SNI on each connection. A trusted issuer alone does not establish the intended hostname.

The overload taking std::string_view replaces the complete trust set. It does not append private authorities to public roots. Supply one or more PEM CA certificates separated by whitespace. Empty input, malformed certificates, non-CA certificates, and trailing non-whitespace data return an error without a usable context. The certificates are copied into the context; the input may then be released. Initialization failures are errors as values too, with or without exceptions. OpenSSL owns its allocations and does not use an Asio allocator. On Emscripten the helper returns unsupported_target: browser TLS and its trust policy remain under the browser’s control.

Write qualified specializations at global scope, using the public webcpp::asio::async_result or webcpp::asio::associated_executor name. These resolve to the template of the selected backend, including native Boost. Do not open a separate namespace containing a new template with the same name. The completion-handler macro is WEBCPP_ASIO_HANDLER_TYPE, from config.hpp; include async_result.hpp before expanding it.

test/distribution/customizations.hpp supplies a complete token and associated executor specialization. Its consumer registers a timer in one translation unit and cancels it from another that also includes Beast and Cobalt. The direct compiler and CMake recipes build those same files with uniform configuration.

WASIp2 provides TCP, UDP, name-resolution streams, monotonic clocks and resources that expose readiness through wasi:io/poll. The port retains Boost.Asio’s select reactor. wasi-libc gathers socket pollables and timer deadlines into one host wait. No worker thread, fixed-interval DNS scan or browser turn budget is introduced. The P2 single-thread profile omits Asio’s pipe-based cross-thread interrupter: this libc has no P2 pipe implementation, and the profile cannot receive work from another application thread. An idle scheduler without a reactor waits on a maximum-instant monotonic-clock pollable. It does not submit an empty poll list, which WASIp2 rejects, or spin.

A DNS address stream is not a POSIX descriptor. A small compiled bridge registers its borrowed pollable with wasi-libc’s descriptor table so the same reactor can wait for sockets, DNS and timers together. That registration API is private to wasi-libc. The build verifies SDK 34.0, libc revision 2e6fb9d8ee0c and the exact copied declaration hashes. Changing the SDK requires revalidating this bridge; the build must not silently use an unknown ABI. The upstream installation is never modified.

async_resolve starts the native lookup through the executor. A deferred token does not start DNS until initiated. The handler never runs inside initiation, uses its associated executor, and receives an error value on failure. Resolver cancellation and per-operation cancellation work before and after registration. Destroying a resolver cancels pending lookups; destroying its context abandons handlers and releases the owned resources.

Numeric host parsing and the libc service-name table require no host DNS wait. The host supplies forward lookup addresses; host capabilities govern access. canonical_name, v4_mapped and all_matching are explicitly unsupported by this adapter and complete with operation_not_supported. Asynchronous reverse lookup also remains unsupported. address_configured uses libc’s numeric family checks. Loopback tests establish local resolution, not access to every external DNS server.

Operation storage and copied input/endpoint scratch storage use the associated handler allocator. Resolver ownership uses the context allocator. The public Boost result container, libc address parsing and descriptor-table storage retain their upstream allocation behavior; this is not a zero-global-allocation promise.

webcpp::asio::wasi::stdio_stream implements partial synchronous and asynchronous reads/writes over WASIp2 CLI resources. Its asynchronous waits use the same reactor, preserve completion-token associations and support cancellation. Only one read and one write may be pending per stream. Keep buffer storage alive until completion. The stream owns resource handles but does not close libc’s descriptors 0 and 1. Cancellation aborts pending operations; subsequent operations remain usable. Closing or destroying the stream cancels pending operations and prevents new I/O.

The Beast supplied-channel client and server run real WebSocket upgrade, text, fragmented binary transfer, ping/pong and close over this adapter, in both exception modes. They need no TCP socket grant. These channels do not provide Unix socket names, descriptor passing, peer credentials or wasi:http WebSocket upgrades.

Writes request a WASI flush before the protocol switches to reading. Readiness cannot preempt an import that the host itself implements with blocking I/O. In particular, Wasmtime CLI stdout can block when its OS pipe fills. A paused consumer must resume draining before the component can observe cancellation. A strict cancellation deadline requires a host/channel whose write imports remain nonblocking.

threading=multi is rejected: SDK 34.0 has no supported P2 pthread runtime profile. POSIX signals, Unix-domain sockets and serial ports are absent from the host interfaces used here. Use the capability guards in Require a capability at compile time for compiler-visible requirements. Cobalt’s known no-EH pending-task move issue remains an upstream limitation, as on native and P3; see Exceptions and error handling.

Unsupported socket operations retain error-code overloads. Tested examples include linger and at_mark, which return operation_not_supported. UDP send_to and connected send gather multiple buffers into one datagram; receive scatters one datagram across the destination buffers. Asynchronous forms retain handler allocation and cancellation. TCP retains partial I/O semantics. Numeric IPv6 scope identifiers work; named interfaces are rejected with invalid_argument. Host permission denial is a runtime error, distinct from an unsupported build profile. Prefer error-code/completion-handler paths for recovery, especially when exception handling is disabled.

Use Boost 1.92.0, wasi-sdk 34.0 and Wasmtime 50.0.1 for the configuration verified here. The distributed Wasm backend records exact upstream inputs and corrections. Updating it requires rerunning the maintainer importer and regression tests; an application build uses the sources already shipped in the library. WASIp3 and cooperative threads require runtime support; the previously installed Wasmtime 47.0.3 could not load the SDK’s cooperative-thread component.

Register clang-wasip3 in user-config.jam as shown by the superproject’s WASI setup. Put the SDK in .local/wasi-sdk, or supply -sWASI_SDK=/path/to/wasi-sdk when choosing the cooperative profile. It must be the same SDK as the compiler registered for this toolset. Put the tested Wasmtime binary on PATH.

/webcpp/asio//asio selects the shipped WebCPP headers and compiles src/wasip3/waitable.cpp. It validates the SDK’s private descriptor ABI before building that bridge. Neither B2 nor another consumer build patches Boost or inserts a replacement Boost include tree. See How-to: consume the shipped implementation for the equivalent source contract outside B2.

From the superproject root, build and check the existing timer example:

The example’s source is in Tutorial: your first asynchronous program. Expected output:

Repeat with exception-handling=off to use the single-thread runtime without C++ exceptions. The library keeps Boost’s callback and error-code interfaces. No JSPI or Asyncify flags are needed.

The build selects experimental-coop-threads as its sysroot and adds -pthread consistently to compilation and linking. It uses that sysroot’s C++ configuration and the matching SDK’s common libc++ headers. This is an experimental SDK profile, not a promise of CPU parallelism. In the tested SDK, requesting exceptions in this profile fails at configuration with a message naming the missing runtime.

The test launcher is for local and CI verification: it enables WASIp3 asynchronous components and cooperative-thread support, grants host network and name-lookup access for the loopback tests, and bounds each guest’s execution to 600 seconds. The global lane also runs large finite document and Unicode workloads. Set WEBCPP_WASIP3_TEST_TIMEOUT to a positive integer number of seconds to choose another bound, for example WEBCPP_WASIP3_TEST_TIMEOUT=15 for focused loopback tests. Invalid or zero bounds fail before launch. Enabling a runtime feature does not create threads in a single-thread binary. Production applications should choose their own timeout and network capabilities.

Run the declared WASIp3 tests and examples with -a, then repeat for each supported profile from Build configurations:

wasi_core exchanges real TCP and UDP traffic over ephemeral IPv4 loopback ports, tests timer and socket cancellation, scatter/gather TCP, and TCP EOF. wasi_core_threads adds a cross-thread post into a reactor with a pending timer and two runners sharing a context. wasi_contract checks empty datagrams, vectored UDP receive with datagram truncation, IPv6 numeric scopes, socket option errors and resolver behavior. wasi_coroutine waits for a timer using Boost.Asio’s co_spawn and awaitable with result-based error handling. The existing run-family and timer tests also run on WASIp3. wasi_udp_gather and capability_wasi/datagrams check synchronous and asynchronous multi-buffer sends and receives, including complete sequences beyond 64 buffers, allocation routing, empty datagrams, oversized input and release of storage before completion.

The SDK verifier checks the private ABI snapshot. The maintainer importers check source hashes, and external consumers use a source snapshot with spaces in its path and no cached replacement Boost headers. Unsupported SDK profiles fail with diagnostics. Native controls use the same runtime test sources. These are local commands; none starts a CI job.

Use <library>/webcpp/cobalt//cobalt in the application’s B2 requirements, webcpp/cobalt/ headers and webcpp::cobalt names. The application supplies co_main; the separately compiled runner omits unsupported process signals. Cobalt’s explicit source inventory also supports other build systems. The old Asio target is a forwarding alias, not a second implementation.

Run the existing Cobalt timer example:

The expected output and complete source are in the Cobalt tutorial.

Repeat with exception-handling=off, or with threading=multi and exception-handling=off for the cooperative runtime. The latter can also run the explicit libs/cobalt/test//cobalt_thread test. The ordinary test target includes cobalt_wasi, cobalt_network_exceptions_on/off and cobalt_io; they cover the runner, both timer APIs, Asio TCP/UDP through use_op, Cobalt’s own IP socket wrappers, refused TCP connections, TCP/UDP cancellation, EOF and result-based resolver behavior.

The libs/cobalt/test//cobalt_wasip3 lane checks successful and unsuccessful command completion with an exact-status driver. Put Wasmtime 50.0.1 on PATH, or set WASMTIME to its executable for that driver. The SDK maps nonzero coroutine returns to host status 1.

For TLS, add /webcpp/asio//tls and await Asio SSL operations with webcpp::cobalt::use_op. The following public-target drivers check TLS 1.2/1.3, trusted and rejected identities, malformed CA data, transfer cancellation and clean, failed and cancelled shutdown:

The WASI client needs network capabilities but no CA filesystem preopen. To use Cobalt’s own io::ssl::stream, link the optional /webcpp/cobalt//cobalt_ssl target. Its shipped implementation, trust configuration and local test commands are described in Use the corrected SSL stream.

The underlying platform contracts are documented by wasi-sdk’s cooperative-thread guide and the Wasmtime release used here.

Boost’s run runs handlers until none is ready, those posted meanwhile included, and a select whose timeout is zero suspends only to a microtask, which never lets the page render. Measured with Emscripten 6.0.11, a handler that posts itself ran 300,000 times under Boost’s run before a JavaScript setTimeout(0) ran, in either suspension variant. Boost’s run is not virtual and cannot be told to yield, hence the composition.

The yield is a suspension, an EM_ASYNC_JS import whose promise a MessageChannel message resolves: a macrotask rather than only a microtask, giving the browser an opportunity to render, run timers and deliver events. It does not guarantee that any particular work happens before the next turn. MessageChannel exists in every browser and in node.

A turn runs at most max_handlers_per_turn handlers, and the run family yields to the browser after each turn that reaches it. Both ready handlers and step 4’s handler consume the same turn budget. A wait does not reset it: a short timer can make the reactor suspend only to microtasks, which cannot deliver browser events or worker proxy messages. The budget resets after the explicit macrotask yield, even when an earlier wait happened to let browser work run. The option is 100 by default. Historically, with a limit of 1000 and Emscripten 6.0.11, the setTimeout(0) above ran after 1,000 handlers under JSPI and 999 under Asyncify, against 300,000 without the limit, and run still ran every handler. It is given at construction, io_context io(io_context_options{.max_handlers_per_turn = 250}), or later with io.max_handlers_per_turn(250); 0 is taken as 1. A stop made by the handler that reaches the limit returns at once, without a yield first. Held by turn_limit, which counts the yields of a handler that posts itself and of a chain of timer completions: one after every max_handlers_per_turn handlers under run and run_for, never more handlers between two, and none under the backend’s base run; and a JavaScript setTimeout(0) runs at a yield, seen by the first handler of a turn. And by run_family, in each variant.

WEBCPP_ASIO_DEFAULT_MAX_HANDLERS_PER_TURN in config.hpp supplies the initial value of io_context_options::max_handlers_per_turn. It defaults to 100 and can be replaced by a compiler definition, for example to use 1000:

For b2, pass the definition on the command line for the complete build:

Use the same value in every translation unit that uses asio and rebuild all of them when changing it. In particular, Cobalt’s runner is compiled separately: a definition in an application source file alone cannot configure an existing runner archive. A separate build directory avoids reusing outputs built with another definition. Do not mix differently configured objects in one program.

An explicit option at construction or a later max_handlers_per_turn(n) call overrides this build default for that context. Zero is normalized to one; negative build defaults are rejected. Native scheduling is unchanged.

The value 100 is a configurable scheduling policy, not a measured optimum or a time budget. Smaller values offer more frequent yields under continuous ready work, with more suspension and scheduling overhead. A single expensive handler can still block the thread. The original browser measurements used small self-posting handlers and checked turn duration, not isolated yield cost. The later Release benchmark measures yield latency separately. See From the original 1,000 default to 100 for the default’s origin and validation, and Relating the limit to an application’s cost budget for the cost model and its limits.

The run family is called on the stack of main, or on the stack of another export the program lists for suspension: in -sJSPI_EXPORTS under JSPI, whose call then returns a promise, and called with ccall(..., {async: true}) under Asyncify. Anywhere else its first suspension fails: under JSPI it throws a SuspendError, and under Asyncify it starts an unwind that corrupts a suspended main. Nothing calls run, poll or dispatch from a JavaScript event: while run is suspended, an event sees running_in_this_thread() true, because the frame run pushed stays on the stack, and a dispatch there runs its handler inside the event, on the wrong stack. asio’s bridge only posts. Nor does a program block the page’s thread without suspending, in a busy loop or a blocking system call.

On emscripten, a run family call made while another runs, or while the bridge delivers a browser event, asserts and returns 0 having run nothing. The io_context keeps a flag while one of its six members runs, and the bridge counts the deliveries in progress. A call while either is set (a nested call from a handler, a run from a JavaScript event while run waits, a run from a registration’s deliver) is a precondition violation, reported by BOOST_ASSERT_MSG, and with assertions off it is still refused. The run around a refused call goes on, still flagged. A handler’s C++ exception that leaves run clears the flag on its way, so that the program’s restart(); run(); after its catch is no nested call. A JavaScript error is another matter (see a JavaScript error out of a handler): where it skips destructors it leaves the flag set, as it leaves Boost’s own state broken, and the context refuses every later call. Each member admits its call once, before any work, and then runs only private code or Boost’s, never another member of the family, whose admission would refuse the call its caller flagged.

Detection is of a call of this run family on the context whose flag or bridge is set. Four calls go undetected: a call from an export of the program’s own that is not listed for suspension, which nothing tells from main until its first suspension fails; a call through a reference to the shipped backend’s base context, which reaches Boost’s own run; poll, poll_one and dispatch, which are Boost’s and no member of the run family, called from a JavaScript event; and a call on another io_context, whose flag and bridge are its own, from a handler or a delivery of this one.

Held by detection, in each variant, with and without exceptions, with an assertion handler counting the assertions and with assertions off: a nested run_for, run_one and the other timed forms nested one after another in a single run, a run from a JavaScript setTimeout while run waits, a run from a delivery while no run is active and a handler is ready, which it leaves for the next run, run again after a C++ exception left it, every timed form over several turns and on a timer alone with no assertion, and the poll of a context with no reactor from a handler. And by flag_scope, the flag’s scope, which puts back the value it found.

A library never calls the run family: it is given an executor. webcpp’s lint refuses a call of run, run_one or run_for on an io_context whose line does not say why after lint-run:, and a program’s own says it, as io.run(); // lint-run: the program's event loop, suspended into the browser's.

xactor’s asio_driver drains an io_context of its own with poll. That context makes no timer and no socket, so it has no reactor: its poll never reaches select and never suspends, and calling it from a handler of the program’s io_context is safe in either variant.

A handler’s exception propagates out of run, as Boost’s, on both variants. Handlers run on the stack of main, inside the run family call, so that a C++ exception a handler throws leaves run, clearing the run family’s flag on its way, and reaches the program’s catch, after any number of suspensions and yields. A suspension keeps what encloses it: a try around run catches what a handler throws after run suspended, and a run called inside a catch block suspends and resumes there. Each variant compiles with the exception model it can suspend through (see the two suspension variants): WebAssembly exceptions under JSPI, and JavaScript-based exceptions under Asyncify, which traps when it suspends inside a catch block of WebAssembly exceptions. A JavaScript error out of a handler is caught by no C++ catch, and what it leaves depends on the build (see a JavaScript error out of a handler).

Held by exceptions, natively and in each variant, built with exceptions whatever the build asks: a try that encloses a run which suspends in the reactor’s wait catches nothing, a run suspends inside a catch block and resumes there, a handler’s exception thrown after run suspended reaches a catch in main, and the next run after it runs its handler, no nested call, and so does one thrown after run yielded twice to the browser, 2,000 handlers having filled two turns of the default limit.

On emscripten, handlers run only on the stack of a run family call, as natively: work posted before run is called waits for it, and a browser event that arrives while no run is active is posted and waits for the next one. Held by reactor, where work posted before run runs only inside it, and a post made from a JavaScript setTimeout wakes a suspended run.

As natively, run returns when no operation is pending, even with a connection open: a WebSocket with no pending read does not keep run alive, and its messages queue. After main returns, the runtime stays alive, since Emscripten keeps it by default, events keep being posted, and nothing runs them unless an export listed for suspension calls the run family again.

When ready work repeatedly posts more work, set the limit on the context that runs it. This program requests turns of 250 handlers and posts a finite chain of 5,000 pieces of work:

Run it from the superproject root:

Keep the state alive until run returns. Each handler posts the next one instead of calling it inline, so the context can yield between turns. Natively the same program prints the same output, but the option does not change Boost’s scheduling. Change the limit to trade handler throughput against opportunities for the browser to process other work. A handler that itself blocks for a long time still blocks the page; the option does not impose a time budget on individual handlers. The measured browser checks are described in Browser observations.