patton is a library for hardware-sensitive parallel programming in C++.

• Example usage
• Features
• Alternatives
• Reference documentation
• License
• Dependencies
• Compiler and platform support
• Installation and use
• Version semantics

#include <thread>
#include <iostream>

#include <patton/thread.hpp>

int main()
{
    std::cout << "Number of hardware threads: " << std::thread::hardware_concurrency() << "\n";
    std::cout << "Number of cores: " << patton::physical_concurrency() << "\n";
}

patton provides the following components:

• Allocators with user-defined alignment and element initialization
• Containers with user-defined alignment
• Basic hardware information (page size, cache line size, number of cores)
• A configurable thread pool

For more information, please refer to the reference documentation.

Instead of using a container with a default-initializing allocator, one could allocate the data with std::make_shared_for_overwrite<>(). This may be less safe and less convenient, though, because shared_ptr<T[]> does not expose a container-like interface.

Instead of using a container with user-defined element alignment, one could define a struct aligned to std::hardware_destructive_interference_size with an alignas() specifier. However, std::hardware_destructive_interference_size is a compile-time constant, and the actual cache line size of the architecture may differ. What's worse, for some compilers std::hardware_destructive_interference_size is defined differently depending on compiler flags, and thus using the value for alignment of data structures may lead to ABI incompatibility issues.

For querying information on hardware properties and topology, one may refer to the hwloc library instead.

Instead of managing a configurable thread pool explicitly, one could rely on OpenMP or use the Threading Building Blocks (TBB) library. OpenMP uses a rather different programming model designed for easy adaptation and parallelization of existing sequential code through #pragma annotations. TBB is a task-based parallel programming library which can be configured to respect thread affinity.

patton uses the Boost Software License.

• gsl-lite, an implementation of the C++ Core Guidelines Support Library
• optional (for testing only): Catch2

patton requires a compiler and standard library conforming with the C++20 standard.

patton currently supports Microsoft Windows and Linux and has partial support for MacOS (no thread pinning).

The following compilers are officially supported (that is, part of our CI pipeline):

• Microsoft Visual C++ 19.3 and newer (Visual Studio 2022 and newer)
• GCC 12 and newer with libstdc++ (tested on Linux and MacOS)
• Clang 19 and newer with libc++ (tested on Windows and Linux)
• AppleClang 16.0 and newer with libc++ (Xcode 16.0 and newer)

The recommended way to consume patton in your CMake project is to use find_package() to locate the package patton and target_link_libraries() to link to the imported target patton::patton:

cmake_minimum_required(VERSION 3.20 FATAL_ERROR)

project(my-program LANGUAGES CXX)

find_package(patton 1.0 REQUIRED)

add_executable(my-program main.cpp)
target_compile_features(my-program PRIVATE cxx_std_20)
target_link_libraries(my-program PRIVATE patton::patton)

patton may be obtained with CPM:

# obtain dependencies
CPMFindPackage(NAME gsl-lite  VERSION  1.0.1 GITHUB_REPOSITORY gsl-lite/gsl-lite)

CPMFindPackage(NAME patton GIT_TAG master GITHUB_REPOSITORY mbeutel/patton)

patton follows Semantic Versioning guidelines. We maintain API and ABI compatibility and avoid breaking changes in minor and patch releases.

Development of patton happens in the master branch. Versioning semantics apply only to tagged releases: there is no stability guarantee between individual commits in the master branch, that is, anything added since the last tagged release may be renamed, removed, or have the semantics changed without further notice.

A minor-version release will be compatible (in both ABI and API) with the previous minor-version release. Thus, once a change is released, it becomes part of the API.