ThreadSchedule 1.0.0
Modern C++ thread management library
Loading...
Searching...
No Matches
ThreadSchedule Integration Guide

ThreadSchedule is a modern, cross-platform, header-only C++ library for thread management. This guide covers all integration methods.

Requirements

  • CMake: 3.14 or later
  • C++ Standard: C++17, C++20, or C++23
  • Compilers:
    • GCC 10+ or Clang 12+ (Linux/macOS)
    • MSVC 2019+ (Windows)
    • MinGW-w64 (Windows cross-compilation)
  • Platforms: Linux, Windows, macOS (limited support)

Integration Methods

Method 1: CPM.cmake (Recommended)

Best for: Most projects - automatic dependency management with caching and version control.

CPM.cmake is a modern CMake dependency manager that combines the best of FetchContent with advanced caching and version management.

Setup: Add to your CMakeLists.txt:

cmake_minimum_required(VERSION 3.14)
project(YourProject LANGUAGES CXX)
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
# Download CPM.cmake if not already present
if(NOT EXISTS "${CMAKE_BINARY_DIR}/cmake/CPM.cmake")
file(DOWNLOAD
https://github.com/cpm-cmake/CPM.cmake/releases/download/v0.40.8/CPM.cmake
${CMAKE_BINARY_DIR}/cmake/CPM.cmake
EXPECTED_HASH SHA256=78ba32abdf798bc616bab7c73aac32a17bbd7b06ad9e26a6add69de8f3ae4791
)
endif()
include(${CMAKE_BINARY_DIR}/cmake/CPM.cmake)
# Add ThreadSchedule
CPMAddPackage(
NAME ThreadSchedule
GITHUB_REPOSITORY Katze719/ThreadSchedule
GIT_TAG main # or specific version tag
OPTIONS
"THREADSCHEDULE_BUILD_EXAMPLES OFF"
"THREADSCHEDULE_BUILD_TESTS OFF"
)
add_executable(your_app src/main.cpp)
target_link_libraries(your_app PRIVATE ThreadSchedule::ThreadSchedule)

Use in your code:

int main() {
using namespace threadschedule;
auto future = pool.submit([]() { return 42; });
std::cout << "Result: " << future.get() << std::endl;
return 0;
}
High-performance thread pool optimized for high-frequency task submission.
Modern C++23 Thread Scheduling Library.

Why CPM?

  • ✅ Automatic caching - downloads dependencies once
  • ✅ Version pinning - reproducible builds
  • ✅ No git submodules needed
  • ✅ Works seamlessly with CI/CD
  • ✅ Compatible with all CMake features

Method 2: CMake FetchContent

Best for: Projects that download dependencies automatically.

cmake_minimum_required(VERSION 3.14)
project(YourProject LANGUAGES CXX)
set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
# Include FetchContent module
include(FetchContent)
# Fetch ThreadSchedule
FetchContent_Declare(
ThreadSchedule
GIT_REPOSITORY https://github.com/Katze719/ThreadSchedule.git
GIT_TAG v1.0.0 # or main for latest
)
# Make ThreadSchedule available
FetchContent_MakeAvailable(ThreadSchedule)
# Your executable
add_executable(your_app src/main.cpp)
# Link ThreadSchedule
target_link_libraries(your_app PRIVATE ThreadSchedule::ThreadSchedule)

Method 3: Conan Package Manager

Best for: Projects using Conan package manager.

Step 1: Create conanfile.txt in your project

[requires]
threadschedule/1.0.0
[generators]
CMakeDeps
CMakeToolchain
[options]
threadschedule:build_examples=False
threadschedule:build_tests=False

Step 2: Install dependencies

conan install . --output-folder=build --build=missing

Step 3: Configure your CMakeLists.txt

cmake_minimum_required(VERSION 3.14)
project(YourProject LANGUAGES CXX)
set(CMAKE_CXX_STANDARD 17)
# Use Conan toolchain
include(${CMAKE_BINARY_DIR}/conan_toolchain.cmake)
find_package(ThreadSchedule REQUIRED)
add_executable(your_app src/main.cpp)
target_link_libraries(your_app PRIVATE ThreadSchedule::ThreadSchedule)

Step 4: Build your project

cd build
cmake .. -DCMAKE_TOOLCHAIN_FILE=conan_toolchain.cmake -DCMAKE_BUILD_TYPE=Release
cmake --build .

Method 4: CMake add_subdirectory

Best for: Projects with dependencies as subdirectories or git submodules.

Step 1: Add ThreadSchedule to your project

# Clone into your project
cd your_project
mkdir -p external
cd external
git clone https://github.com/Katze719/ThreadSchedule.git

Step 2: Add to your CMakeLists.txt

cmake_minimum_required(VERSION 3.14)
project(YourProject LANGUAGES CXX)
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
# Add ThreadSchedule
add_subdirectory(external/ThreadSchedule)
add_executable(your_app src/main.cpp)
target_link_libraries(your_app PRIVATE ThreadSchedule::ThreadSchedule)

Method 5: System Installation

Best for: System-wide installation or package maintainers.

Step 1: Clone and install

git clone https://github.com/Katze719/ThreadSchedule.git
cd ThreadSchedule
mkdir build && cd build
cmake .. -DCMAKE_INSTALL_PREFIX=/usr/local -DTHREADSCHEDULE_INSTALL=ON
sudo cmake --install .

Step 2: Use in your CMakeLists.txt

cmake_minimum_required(VERSION 3.14)
project(YourProject LANGUAGES CXX)
set(CMAKE_CXX_STANDARD 17)
# Find installed ThreadSchedule
find_package(ThreadSchedule REQUIRED)
add_executable(your_app src/main.cpp)
target_link_libraries(your_app PRIVATE ThreadSchedule::ThreadSchedule)

C++ Standard Compatibility

ThreadSchedule supports C++17, C++20, and C++23:

C++17 (Minimum)

set(CMAKE_CXX_STANDARD 17)
  • Full ThreadWrapper support
  • Full PThreadWrapper support (Linux only)
  • Thread pools and scheduling

C++20

set(CMAKE_CXX_STANDARD 20)
  • All C++17 features
  • JThreadWrapper with stop tokens
  • Enhanced thread management

C++23 (Recommended)

set(CMAKE_CXX_STANDARD 23)
  • All C++20 features
  • Latest language features
  • Best performance

Note: The library will automatically adapt based on your project's C++ standard. You don't need to specify anything special in ThreadSchedule.

Cross-Compilation

Linux to Windows (MinGW)

Step 1: Install MinGW toolchain

sudo apt-get install mingw-w64 g++-mingw-w64

Step 2: Create toolchain file (mingw-toolchain.cmake)

set(CMAKE_SYSTEM_NAME Windows)
set(CMAKE_C_COMPILER x86_64-w64-mingw32-gcc)
set(CMAKE_CXX_COMPILER x86_64-w64-mingw32-g++)
set(CMAKE_RC_COMPILER x86_64-w64-mingw32-windres)
set(CMAKE_FIND_ROOT_PATH /usr/x86_64-w64-mingw32)
set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)
set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)
set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)

Step 3: Build with toolchain

mkdir build-mingw
cd build-mingw
cmake .. -DCMAKE_TOOLCHAIN_FILE=../mingw-toolchain.cmake
cmake --build .

Native MinGW Build on Windows

Step 1: Install MinGW-w64 via MSYS2

# Download and install MSYS2 from https://www.msys2.org/
# Then in MSYS2 terminal:
pacman -S mingw-w64-x86_64-gcc mingw-w64-x86_64-cmake mingw-w64-x86_64-ninja

Step 2: Build with MinGW

# In MSYS2 MinGW64 shell:
cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build build

Notes:

  • MinGW-w64 provides full Windows API support including thread naming (Windows 10+)
  • All ThreadSchedule features work with MinGW, including SetThreadDescription/GetThreadDescription
  • The library automatically sets _WIN32_WINNT=0x0A00 for MinGW to enable Windows 10 APIs
  • Use the MSYS2 MinGW64 shell, not the MSYS shell, for native Windows builds

ARM Cross-Compilation

Example: Building for Raspberry Pi

# arm-toolchain.cmake
set(CMAKE_SYSTEM_NAME Linux)
set(CMAKE_SYSTEM_PROCESSOR arm)
set(CMAKE_C_COMPILER arm-linux-gnueabihf-gcc)
set(CMAKE_CXX_COMPILER arm-linux-gnueabihf-g++)

Build:

cmake .. -DCMAKE_TOOLCHAIN_FILE=../arm-toolchain.cmake
cmake --build .

Configuration Options

ThreadSchedule provides several CMake options:

Option Default Description
THREADSCHEDULE_BUILD_EXAMPLES ON (main project)
OFF (subdirectory)
Build example programs
THREADSCHEDULE_BUILD_TESTS OFF Build unit tests
THREADSCHEDULE_BUILD_BENCHMARKS OFF Build benchmarks
THREADSCHEDULE_INSTALL ON (main project)
OFF (subdirectory)
Generate install targets

Example: Enable all options

set(THREADSCHEDULE_BUILD_EXAMPLES ON)
set(THREADSCHEDULE_BUILD_TESTS ON)
set(THREADSCHEDULE_BUILD_BENCHMARKS ON)
add_subdirectory(external/ThreadSchedule)

Example: Custom install location

cmake .. -DCMAKE_INSTALL_PREFIX=$HOME/.local -DTHREADSCHEDULE_INSTALL=ON
cmake --install .

Platform-Specific Notes

Linux

  • Full pthread support
  • All features available
  • Recommended for production use

Windows

  • ThreadWrapper and JThreadWrapper fully supported
  • PThreadWrapper not available (use ThreadWrapper instead)
  • Use MSVC or MinGW-w64 compiler

macOS

  • Basic support
  • Some features may be limited
  • Testing on macOS is limited

Troubleshooting

C++ Standard Errors

Error: ThreadSchedule requires at least C++17

Solution: Set CMAKE_CXX_STANDARD to 17 or higher in your project.

Threading Errors on Linux

undefined reference to pthread_create

Solution: ThreadSchedule automatically links pthread on Linux. Make sure you're using target_link_libraries() correctly.

CPM Download Issues

Solution: If CPM.cmake download fails, manually download it:

wget https://github.com/cpm-cmake/CPM.cmake/releases/download/v0.40.8/CPM.cmake
# Place in your cmake/ directory

Conan Package Not Found

Solution: Build from source:

conan create . --build=missing

MinGW: Missing Windows APIs

undefined reference to `SetThreadDescription'

Solution: Ensure you're using a recent MinGW-w64 version (8.0+) and that _WIN32_WINNT is set to 0x0A00 or higher. ThreadSchedule does this automatically, but if you override compiler flags, you may need to add:

target_compile_definitions(your_target PRIVATE _WIN32_WINNT=0x0A00)

MinGW: Wrong Shell

Problem: Build fails with strange errors on Windows with MinGW Solution: Make sure you're using the MSYS2 MinGW64 shell (not MSYS or UCRT64) when building with MinGW-w64.

Complete Integration Example

Here's a complete example project structure:

MyProject/
├── CMakeLists.txt
├── src/
│ └── main.cpp
└── external/
└── ThreadSchedule/ (or use FetchContent/CPM)

CMakeLists.txt:

cmake_minimum_required(VERSION 3.14)
project(MyProject VERSION 1.0.0 LANGUAGES CXX)
# C++20 for modern features
set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
set(CMAKE_CXX_EXTENSIONS OFF)
# Option 1: subdirectory
add_subdirectory(external/ThreadSchedule)
# Option 2: FetchContent
# include(FetchContent)
# FetchContent_Declare(ThreadSchedule
# GIT_REPOSITORY https://github.com/Katze719/ThreadSchedule.git
# GIT_TAG v1.0.0
# )
# FetchContent_MakeAvailable(ThreadSchedule)
# Your application
add_executable(my_app src/main.cpp)
target_link_libraries(my_app PRIVATE
ThreadSchedule::ThreadSchedule
)
# Optional: compiler warnings
if(CMAKE_CXX_COMPILER_ID MATCHES "GNU|Clang")
target_compile_options(my_app PRIVATE -Wall -Wextra -Wpedantic)
elseif(MSVC)
target_compile_options(my_app PRIVATE /W4)
endif()

src/main.cpp:

#include <iostream>
int main() {
using namespace threadschedule;
// Create high-performance thread pool
pool.configure_threads("worker");
// Submit tasks
auto future = pool.submit([]() {
return 42;
});
std::cout << "Result: " << future.get() << std::endl;
return 0;
}

Build and run:

mkdir build && cd build
cmake ..
cmake --build .
./my_app

Getting Help