[](LICENSE)

ThreadSchedule is a C++17 library for creating, configuring, scheduling, and observing threads on Linux and Windows. It is header-only by default. C++20 consumers additionally get threadschedule::jthread when the standard library provides std::jthread.

The v3 core deliberately stays small and uses lowercase, standard-style names. Operations whose normal failure mode should not require exceptions return threadschedule::expected<T, std::error_code>.

Requirements

CMake 3.14 or newer
C++17 or newer
Linux with GCC/libstdc++, or Windows with MinGW-w64/GCC or MSVC

The tested compiler versions are the compatibility contract. See Compatibility for the current matrix.

GCC 14 ThreadSanitizer limitation

GCC 14's ThreadSanitizer can incorrectly report unlock of an unlocked mutex (or by a wrong thread) when a pool uses shutdown_for(...). libstdc++ acquires the timed mutex through pthread_mutex_clocklock, which GCC 14's TSan does not fully intercept, but it does observe the later unlock. This is a sanitizer false positive rather than an unmatched unlock in ThreadSchedule. The sanitizer CI therefore uses GCC 16, where the same tests pass cleanly.

Install

The recommended source integration uses CMake FetchContent:

include(FetchContent)
FetchContent_Declare(
    ThreadSchedule
    GIT_REPOSITORY https://github.com/Katze719/ThreadSchedule.git
    GIT_TAG v3.0.0
)
FetchContent_MakeAvailable(ThreadSchedule)
 
target_link_libraries(my_app PRIVATE ThreadSchedule::ThreadSchedule)

An existing checkout can be added directly:

add_subdirectory(path/to/ThreadSchedule)

target_link_libraries(my_app PRIVATE ThreadSchedule::ThreadSchedule)

To install and consume the CMake package:

cmake -S . -B build -DTHREADSCHEDULE_INSTALL=ON
cmake --build build
cmake --install build --prefix /your/prefix

find_package(ThreadSchedule 3 CONFIG REQUIRED)

target_link_libraries(my_app PRIVATE ThreadSchedule::ThreadSchedule)

Conan 2 consumers can build a local package directly from the release source:

conan profile detect

conan create . --build=missing

Windows Vista compatibility mode is available when older platform targeting is required. It reduces Windows feature usage to avoid Win7+ only paths. This mode is currently not tested on real Vista hardware and may be unstable. Validation is limited because no active Vista test machine is available.

cmake -S . -B build -DTHREADSCHEDULE_WINDOWS_VISTA_COMPAT=ON

conan create . -o '&:windows_vista_compat=True' --build=missing

The recipe is tested in CI. Its standard shared=True option packages the optional ThreadSchedule::Runtime; header-only mode remains the default.

Start in five minutes

#include <threadschedule/threadschedule.hpp>
 
#include <iostream>
 
int main()
{
    threadschedule::thread_pool pool(threadschedule::worker_count{2});
    auto answer = pool.submit([] { return 42; });
    if (!answer) {
        std::cerr << answer.error().message() << '\n';
        return 1;
    }
 
    std::cout << answer->get() << '\n';
}

The complete getting-started project includes its own CMakeLists.txt and is tested against a freshly installed package.

Choose the right type

Need	Start with
Own one thread	`thread`
Own one cooperatively cancellable C++20 thread	`jthread`
Configure the calling thread	`this_thread`
Submit general-purpose work	`thread_pool`
Run delayed or periodic work	`scheduled_pool`
Discover and control registered threads	`thread_registry`
Find unregistered Linux threads by OS name	`advanced::thread_by_name_view`
Select a specialized pool or native control	`advanced::*`

Include <threadschedule/threadschedule.hpp> for the complete core. Include <threadschedule/advanced.hpp> only when the workload requires native or specialized choices.

For small consumers, each core contract is independently includable. For example, a single managed thread needs only:

#include <threadschedule/thread.hpp>

#include <threadschedule/thread_config.hpp>

thread.hpp

Owning std::thread wrapper with portable configuration helpers.

thread_config.hpp

Portable thread startup and runtime configuration.

Pools can use <threadschedule/thread_pool.hpp> or <threadschedule/scheduled_pool.hpp> directly; registry-only code can use <threadschedule/thread_registry.hpp>. The focused headers avoid making an application opt into unrelated APIs, while threadschedule.hpp remains the convenient complete core umbrella.

Results, exceptions, and lifetime

ThreadSchedule keeps failure channels explicit:

Operation	Failure channel
Direct construction	May throw `std::system_error`, like standard types
`create(...)`	Returns `expected<T, std::error_code>`
Configuration and shutdown	Return `expected<void, std::error_code>`
`thread_pool::submit(...)`	Submission error in `expected`; task exception in the future
`thread_pool::post(...)`	Submission error in `expected`; task exception via the configured error callback
Explicit `*_or_throw` operation	Throws `std::system_error` on failure

Always inspect an expected before dereferencing it. A task submitted with post() has no future; call set_error_callback(...) on the pool config if its exceptions must be observed.

threadschedule::thread owns a std::thread but deliberately joins a joinable thread on destruction. Destruction and move assignment can therefore block. Call join(), detach(), or release() explicitly when that timing matters.

Threads and configuration

Direct construction is the ordinary path:

threadschedule::thread worker([] { do_work(); });
if (auto joined = worker.join(); !joined)
    report(joined.error());

Use create(...) when initial configuration failures should be returned as an error value:

threadschedule::thread_config config;
config.set_name("metrics").set_scheduling(threadschedule::schedule::background());
 
auto worker = threadschedule::thread::create(config, [] {
    collect_metrics();
});
if (!worker) {
    report(worker.error());
} else if (auto joined = worker->join(); !joined) {
    report(joined.error());
}

Affinity uses logical CPU indices and is intentionally absent from this first configured example: containers and restricted CPU sets may not make CPU 0 available. Query the deployment environment before pinning a thread.

Code running inside any thread can configure itself without wrapping or registering the thread first:

auto allowed = threadschedule::this_thread::get_affinity();
if (!allowed) {
    report(allowed.error());
} else {
    threadschedule::thread_affinity pinned({ allowed->cpus().front() });
    if (auto result = threadschedule::this_thread::set_affinity(pinned);
        !result)
        report(result.error());
}
 
if (auto result = threadschedule::this_thread::set_priority(
        threadschedule::priority_level::low);
    !result)
    report(result.error());

this_thread also provides configure, set_nice, get_priority, set_name, and get_name. Affinity readback reports the logical CPU indices the process is actually allowed to use, which is safer than assuming CPU 0 is available.

Under C++20, jthread mirrors standard callable forwarding and stop-token injection:

#if defined(__cpp_lib_jthread) && __cpp_lib_jthread >= 201911L
threadschedule::jthread worker([](std::stop_token stop) {
    while (!stop.stop_requested())
        do_work();
});
(void)worker.request_stop();
#endif

See the compile-tested jthread example.

Thread pools

threadschedule::thread_pool_config config;
threadschedule::thread_config workers;
workers.set_name("worker");
config.set_worker_count(threadschedule::worker_count{4})
    .set_worker_config(std::move(workers))
    .set_error_callback([](threadschedule::task_error const& error) {
        log(error.what());
    });
 
threadschedule::thread_pool pool(std::move(config));
auto answer = pool.submit([] { return calculate(); });
if (!answer)
    report(answer.error());
else
    use(answer->get());

Task exceptions from submit() remain attached to the returned future and are rethrown by get(). Direct pool construction can throw when worker creation or configuration fails; thread_pool::create(...) offers the error-value path.

Scheduling

Portable intent factories cover ordinary use:

auto background = threadschedule::schedule::background();
auto interactive = threadschedule::schedule::interactive();
auto low_latency = threadschedule::schedule::low_latency();
auto lower_priority = threadschedule::schedule::priority(
    threadschedule::priority_level::low);
auto exact_nice = threadschedule::schedule::nice(
    threadschedule::nice_value{10});
auto realtime = threadschedule::schedule::realtime_fifo(
    threadschedule::realtime_priority{80});

The five priority_level values are the simplest cross-platform choice. Negative nice values and realtime policies normally require elevated privileges on Linux. Native scheduling remains available through threadschedule::advanced.

Advanced usage

#include <threadschedule/advanced.hpp>
 
threadschedule::advanced::work_stealing_pool pool(
    threadschedule::worker_count{8});
auto future = pool.submit(expensive_work);
if (!future)
    report(future.error());
else
    use(future->get());

On Linux, an unregistered process thread can also be found by its exact kernel-visible name. A singular lookup rejects duplicate names; use find_all() when duplicates are intentional:

auto worker = threadschedule::advanced::thread_by_name_view::create("io-worker");
if (!worker)
    report(worker.error());
else if (auto lowered = worker->set_priority(
             threadschedule::priority_level::low);
         !lowered)
    report(lowered.error());

The view remembers the Linux TID and its start-time generation, so exited or recycled targets report no_such_process. This native lookup cannot fully close the race between the last identity check and a TID-based syscall; use thread_registry when target lifetime must be coupled to control operations.

The advanced namespace is public and follows semantic versioning. See Advanced APIs for native controls, profiles, topology, future combinators, task groups, chaos testing, and lower-level error handling.

Optional shared registry runtime

Header-only mode owns one registry per linked image. Applications that need one registry shared by an executable and compatible DSOs can link the optional C++ runtime:

set(THREADSCHEDULE_RUNTIME ON)
add_subdirectory(ThreadSchedule)
target_link_libraries(my_app PRIVATE ThreadSchedule::Runtime)

This is a same-toolchain C++ ABI, not a portable plugin ABI. Do not mix GCC, MinGW, and MSVC artifacts.

Documentation

License

ThreadSchedule is available under the [MIT License](LICENSE).