stlab-execution

C++17/20 task execution, executors, timers, and process lifecycle, extracted from STLab under the Boost Software License 1.0. Existing stlab:: API names and stlab/concurrency/*.hpp and stlab/pre_exit.hpp include paths are preserved. No futures, channels, serial queues, or STLab utility library are required.

Release: 1.0.0 is the first standalone release of the execution runtime. cpp-library is pinned to its 5.5.0 release. See the release notes for compatibility requirements and release validation.

Queued task requirements

For targets submitted to the default/high/low executors, main executor, or system timer, callable construction (including copy/move construction) and destruction of moved-from callables must not submit additional work. Queues may perform these operations while locked. Submission from task bodies and executed-target cleanup remains supported.

On threaded task systems, default/high/low executor tasks and timer callbacks, including their executed-target cleanup, must not call pre_exit(): shutdown waits for their completion. Main-queue tasks may initiate shutdown. Threadless Emscripten retains asynchronous shutdown behavior.

External dependencies

Search for [DEPENDENCY] in source comments and this README to find dependency declarations and upstream sources. Pinned packages use current releases; system libraries, toolchains, and editor tools are supplied by the client. Minimum supported versions are compatibility requirements, not pins to obsolete releases.

cmake/CPM.cmake is the CPM download bootstrap, pinned to 0.43.2 with a SHA-256 check on the downloaded release. Keep provenance here rather than modifying the externally supplied bootstrap.

cpp-library 5.5.0 provides build, install, documentation, and template generation, pinned to the release's exact commit. Regenerate templates with cmake --preset=init and cmake --build --preset=init. Do not edit generated files; update their owning cpp-library templates or generator instead. The project declares doctest 2.5.3 for tests; the toolkit provides doxygen-awesome-css 2.5.0 for documentation.

The generated CI workflow uses checkout v7, msvc-dev-cmd 1.13.0, doxygen-install 2.0.3, configure-pages v6, upload-pages-artifact v5, and deploy-pages v5. These versions and their source comments are owned by cpp-library's cmake/cpp-library-ci.cmake, not the generated workflow.

Build and analysis tools are client-provided CMake, Ninja, and, for the clang-tidy preset, LLVM's clang-tidy.

Python is used by scripts/flatten_json.py; Git resolves source dependencies and project versions.

The editor extension recommendations are unpinned and managed by VS Code.

Build and test

Use CMake 3.24 or newer and Ninja, with the compiler environment configured:

cmake --preset=test
cmake --build --preset=test
ctest --preset=test

cmake --preset=test -B build\test-cpp17 -DCMAKE_CXX_STANDARD=17
cmake --build build\test-cpp17
ctest --test-dir build\test-cpp17 --output-on-failure

The generated presets are default, test, docs, clang-tidy, init, and install; variant names below are build directories, not additional presets. Configure variants with the test preset and a distinct -B directory, then build and test that directory directly. For example:

cmake --preset=test -B build\test-shared -DBUILD_SHARED_LIBS=ON
cmake --build build\test-shared
ctest --test-dir build\test-shared --output-on-failure

The toolkit dependency is pinned to its exact commit; for local development, pass -DCPM_cpp-library_SOURCE:PATH=<toolkit-checkout> during configuration. Release versions are derived from Git tags; fetch tags when building a release checkout. With no release tag, the toolkit's development version is 0.0.0. -DCPP_LIBRARY_VERSION=1.0.0 may be used for standalone install validation, but is not evidence of a release.

Configure with -DSTLAB_EXECUTION_PACKAGE_TESTS=ON to verify standalone installed C++17/20 consumers. Every test configuration independently compiles each applicable public header. Package checks can be combined with -DBUILD_SHARED_LIBS=ON and -DSTLAB_TASK_SYSTEM=portable. The verifier uses a fresh install-preset child with BUILD_TESTING=OFF and the standalone validation version override above, never an STLab package. Commands and package evidence remain under <build-directory>/package-test/execution-packages; Windows fixtures deploy TARGET_RUNTIME_DLLS before execution. Use the same compiler environment and toolkit :PATH override as other native presets.

Select portable task workers with -DSTLAB_TASK_SYSTEM=portable, portable main execution with -DSTLAB_MAIN_EXECUTOR=portable, and address sanitization with -DSTLAB_SANITIZER=address. Use separate build directories for these variants. On Windows, run all three CMake commands from the same x64 Visual Studio developer environment. Address sanitization instruments both the runtime and its contract/lifecycle executables; allocator interception tests run only in non-ASan static Windows configurations.

With an activated Emscripten SDK and Node 18.3.0 or newer, select the project toolchain and enable pthreads or cooperative event-loop execution explicitly:

cmake --preset=test -B build\test-emscripten "-DCMAKE_TOOLCHAIN_FILE=cmake\Platform\Emscripten-Execution.cmake" -DSTLAB_EMSCRIPTEN_PTHREADS=ON
cmake --build build\test-emscripten
ctest --test-dir build\test-emscripten --output-on-failure

cmake --preset=test -B build\test-emscripten-threadless "-DCMAKE_TOOLCHAIN_FILE=cmake\Platform\Emscripten-Execution.cmake" -DSTLAB_EMSCRIPTEN_PTHREADS=OFF
cmake --build build\test-emscripten-threadless
ctest --test-dir build\test-emscripten-threadless --output-on-failure

The threadless suite uses standalone Node scenarios rather than a blocking doctest/std::future harness. Each process has a timeout. ABI rejection tests require an unresolved task-storage guard diagnostic, not merely a failed link. The deliberately incompatible target is excluded from the default build.

Nested configuration tests preserve the selected NODE_JS_FLAGS list and check the child cache and actual emulator executable/flag order. For a focused regression with two Node options, reconfigure the threadless directory above (repeat with the pthread-enabled directory for pthreads):

cmake --preset=test -B build\test-emscripten-threadless "-DCMAKE_TOOLCHAIN_FILE=cmake\Platform\Emscripten-Execution.cmake" -DSTLAB_EMSCRIPTEN_PTHREADS=OFF "-DNODE_JS_FLAGS:STRING=--no-warnings;--stack-trace-limit=20"
ctest --test-dir build\test-emscripten-threadless --output-on-failure -R "shared_reconfiguration|emscripten_configuration"

Consume

Windows test and package consumers deploy runtime DLLs with an empty-list-safe helper compatible with CMake 3.24. Static consumers require no DLL copy.

Link stlab::execution from add_subdirectory or CPM. Installed consumers use find_package(stlab-execution CONFIG REQUIRED) and the same target name.

Current local source consumption (generic developer paths):

set(CPM_cpp-library_SOURCE "/path/to/cpp-library" CACHE PATH "")
set(CPM_stlab-execution_SOURCE "/path/to/stlab-execution" CACHE PATH "")
CPMAddPackage(
  NAME stlab-execution
  SOURCE_DIR "${CPM_stlab-execution_SOURCE}")
target_link_libraries(app PRIVATE stlab::execution)

From a developer shell, equivalent typed overrides are -DCPM_cpp-library_SOURCE:PATH=<toolkit-checkout> and -DCPM_stlab-execution_SOURCE:PATH=<execution-checkout>. Use them to validate local changes instead of the remote development commits; do not substitute developer paths into production dependency declarations.

Fetch the 1.0.0 release:

CPMAddPackage("gh:stlab/[email protected]")
target_link_libraries(app PRIVATE stlab::execution)

STLab's execution dependency pin and minimum installed-package requirement must be updated together when it adopts this release.

For a locally installed execution package:

find_package(stlab-execution CONFIG REQUIRED)
target_link_libraries(app PRIVATE stlab::execution)

Set CMAKE_PREFIX_PATH to the install prefix. Source and installed consumers include the same canonical headers, for example <stlab/concurrency/default_executor.hpp> and <stlab/pre_exit.hpp>. STLab users keep linking stlab::stlab; its public execution dependency supplies these headers and the single runtime transitively. Execution never requires STLab. The legacy stlab-core / stlab::stlab-core INTERFACE targets belong to STLab, not to the standalone execution package.

Rebuild all consumers. Independent execution inline namespaces and library filenames change the C++ ABI. Existing public stlab:: names, include paths, task-storage guards, and the v2 C scheduling ABI are preserved; this is source compatibility, not compatibility with old prebuilt C++ binaries.

STLAB_EXECUTION_INSTALL defaults to ON for standalone builds and OFF as a subproject. The generated stlab/execution/config.hpp belongs to this library, with execution-specific version macros and an execution_v* inline namespace. STLab's version/namespace and coroutine policy are independent. Its own STLAB_INSTALL controls only STLab-owned artifacts; enabling either package's installation does not silently enable the other. Header file sets do not overlap.

The runtime is statically linked by default. Set BUILD_SHARED_LIBS=ON to build a shared runtime, including on Windows. The parent project's BUILD_SHARED_LIBS is respected and is not changed. The former STLAB_EXECUTION_SHARED and STLAB_CORE_SHARED CMake options are no longer used; migrate those inputs to BUILD_SHARED_LIBS. The public STLAB_EXECUTION_SHARED() macro and its STLAB_CORE_SHARED() compatibility alias reflect the actual execution target type.

Backend options retain STLab's defaults and validation: STLAB_THREAD_SYSTEM, STLAB_TASK_SYSTEM, STLAB_MAIN_EXECUTOR, STLAB_TASK_POOL_MAXIMUM, and STLAB_EMSCRIPTEN_PTHREADS. STLAB_SANITIZER=address retains runtime address-sanitizer instrumentation.

Coroutine configuration (STLAB_NO_STD_COROUTINES and STLAB_STD_COROUTINES()) belongs exclusively to STLab. Execution neither resolves that option nor defines that macro; its C++17 public interface is independent of STLab's coroutine policy and either library's build standard.

Call stlab::pre_exit() exactly once before normal process exit when using runtime services. Scheduling, timer retirement, pre-exit ordering, and versioned C ABI entry points retain their STLab contracts; see adjacent header documentation.

Documentation and platform CI

Header-adjacent contracts are canonical. cmake --preset=docs and cmake --build --preset=docs generate the standalone API reference in build/docs/html; Doxygen is required. There is no published execution documentation site yet. The directory groups and main page are owned here, without importing STLab's higher-level API sources.

The generated CI workflow covers native Linux GCC/Clang, macOS, Windows, and clang-tidy using the generic presets. Shared, C++17, portable, sanitizer, Qt, Emscripten, and installed-package variants require separate runs with the configuration options above; .github/matrix.json is not consumed by this workflow. Job configuration alone is not passing runtime evidence.

Release publication follows dependency order: publish cpp-library first, pin execution to that release's exact commit and verify without local toolkit overrides; publish execution next; then update STLab's pin and matching installed dependency requirement and verify STLab without overrides. No release or minimum version is inferred from local validation's CPP_LIBRARY_VERSION override.