Skip to content

ThreadPool

Generated from engine/core/thread_pool.h at aceb130. The text under each declaration is the header's own comment, word for word. About the reference says how these pages are made.

Browse the core module

Audience: game code.

#include "engine/core/thread_pool.h" · namespace labrador

A pool of worker threads, and the one place a task's exception is caught and carried back to whoever waited for it.

NO <windows.h> HERE, WHICH IS WHAT Impl IS FOR. Spelling the private members as PTP_WORK, PTP_POOL, PTP_CLEANUP_GROUP, a TP_CALLBACK_ENVIRON and a static callback taking PVOID would open this header with it, and hand the whole Win32 surface to every module that wants a worker - engine/scene/scene.cpp and engine/app/application.h are the two - out of core/, which is the one module everything else is allowed to lean on. core/registry.h makes the same refusal for COM.

WHAT IS BEHIND THE POINTER ON WINDOWS IS THE WIN32 THREAD POOL - CreateThreadpoolWork, SubmitThreadpoolWork, a cleanup group - because it works and it is tested, and replacing it with std::thread would be rewriting a working primitive (T1). Everywhere else it is serial: each task runs inside add_task and the wait reports what happened, which keeps every promise below, because none of them is that two tasks overlap. That is the WebAssembly build, which has no threads (docs/port/web.md).

THE INDIRECTION IS NOT ON A HOT PATH. Scene::draw submits one task per slice of the view list per frame, and the slices are bounded by max_num_threads - a handful - so one pointer hop per submission is nothing T8 has an opinion about, where a virtual call per sprite would be.

ThreadPool(int min_num_threads, int max_num_threads);
~ThreadPool();

Throws std::invalid_argument unless 1 <= min_num_threads <= max_num_threads, and std::runtime_error if the platform cannot create the pool or its minimum of threads.

ThreadPool(const ThreadPool&) = delete;
ThreadPool& operator=(const ThreadPool&) = delete;
void add_task(std::function<void()> task);

ONE THREAD SUBMITS. This is not a work-stealing queue a worker can add to: the submitted-work list is unguarded, so add_task and wait_for_tasks_to_complete belong to whichever thread owns the pool. Scene::draw is that thread, and it waits before returning. What is guarded is the other direction - a task's exception, recorded from whichever worker ran it.

The pool keeps what it builds for a submission and reuses it after the wait, so once it has held as many tasks between two waits as it is given now, add_task allocates nothing for a callable small enough for std::function to store in place. Scene::draw's are. Each callable is destroyed no later than the wait that follows its submission.

void wait_for_tasks_to_complete();

Blocks until every submitted task has finished. If any task threw, the first such exception is rethrown here, on the calling thread. An exception escaping a Win32 thread-pool callback would otherwise terminate the process with no diagnostic.

int min_num_threads() const;
int max_num_threads() const;

The files that include this header directly. A file can also reach it through another header.

No guide or concept page links to this header yet.

Development documentation (unreleased). Built from Labrador aceb130 of 2026-11-20.

All documentation versions