Thread support library
Curated hub for C++ concurrency: threads, locks, condition variables, futures, stop tokens, semaphores, latches, barriers, and adjacent atomic/runtime routes.
The C++ thread support library covers several concurrency models at once: raw threads and joining, mutex and lock orchestration, waiting and notification, task/future result transport, cooperative cancellation, and newer coordination primitives such as latches, barriers, and semaphores. This hub helps you choose the right concurrency surface before you drop into specific classes or member functions.
# Start Here
Create and manage threads directly
Start here when you need explicit thread objects, joining or detaching, IDs, and the classic `std::thread` lifecycle.
thread · jthread · this thread id · yield
Protect shared state with mutexes and locks
Use the lock-based route for critical sections, ownership transfer of locks, multiple-mutex coordination, and reader/writer locking.
Wait and notify
Use condition variables and one-time initialization helpers when threads coordinate around shared state changes and wakeup conditions.
condition_variable · condition_variable_any · call_once · once_flag
Return asynchronous results
Choose the futures route when work completion, result transport, exceptions, and producer/consumer task hand-off matter more than raw thread control.
future · promise · packaged_task · async · shared_future
Use cooperative cancellation
Start here for stop tokens, stop sources, callbacks, and the modern cancellation model integrated with `jthread`.
Coordinate phases across threads
Use latches, barriers, and semaphores when many threads need a structured hand-off or bounded admission instead of ad hoc waiting loops.
# Concurrency Model Map
| If you need to... | Start with | Why | Common adjacent route |
|---|---|---|---|
| Launch a thread and explicitly own its lifetime | thread or jthread | `thread` is the explicit baseline; `jthread` adds automatic joining and stop-token integration. | stop_token |
| Protect mutable shared data with a mutex | mutex, lock_guard, unique_lock | This is the primary lock-based route for critical sections and condition-variable waiting. | atomic operations |
| Block until a condition becomes true | condition_variable or condition_variable_any | Condition variables coordinate waiting with lock ownership and notification semantics. | mutexes |
| Return a value or exception from background work | future, promise, async | The future/promise model is about result transport and completion, not just thread identity. | execution |
| Request cancellation cooperatively | stop_token and stop_source | This is the standard cancellation surface for code that checks and propagates stop requests. | jthread |
| Synchronize phases or limit concurrent entry | latch, barrier, counting_semaphore | These primitives express structured coordination patterns more directly than hand-rolled counters and waits. | condition variables |
| Sleep, yield, or identify the current thread | sleep_for, sleep_until, yield, get_id | Use the thread-utility route when the concern is timing or current-thread behavior rather than shared-state coordination. | chrono |
# Thread Families
| Family | Core destinations | Use it for |
|---|---|---|
| Thread objects and current-thread utilities | thread, jthread, get_id, sleep_for, yield | Owning threads directly, observing the current thread, and controlling basic scheduling/timing behavior. |
| Mutexes and lock wrappers | mutex, timed_mutex, recursive_mutex, shared_mutex, unique_lock, scoped_lock | Exclusive, timed, recursive, and shared locking together with RAII wrappers and multi-lock coordination. |
| Waiting and one-time coordination | condition_variable, condition_variable_any, call_once, once_flag, notify_all_at_thread_exit | Wake/sleep coordination around predicates and one-time initialization patterns. |
| Tasks, futures, and async results | future, shared_future, promise, packaged_task, async, launch | Communicating results, exceptions, and readiness across asynchronous work boundaries. |
| Cancellation and stop-state model | stop_token, stop_source, stop_callback | Cooperative stop requests and callback registration for cancellable operations. |
| Structured coordination primitives | latch, barrier, counting_semaphore | Expressing one-shot countdowns, reusable phase barriers, and admission control. |
# Version Highlights
| Standard | Notable concurrency additions here | Why it changes navigation |
|---|---|---|
| C++11 | thread, mutex, condition_variable, future, async | Established the baseline thread, lock, condition-variable, and future/promise model that most code still builds on. |
| C++14 | shared_timed_mutex | Expanded the reader/writer locking story before the later shared-mutex refinements. |
| C++17 | scoped_lock, shared_mutex, interference size constants | Improved multi-lock ergonomics and shared-locking support for modern lock-based designs. |
| C++20 | jthread, stop_token, latch, barrier, counting_semaphore | Added cooperative cancellation and a much broader set of structured coordination primitives. |
| C++26 | stoppable_token, unstoppable_token, never_stop_token | Extends the stop-token model and makes cancellation-related navigation broader than the original C++20 surface. |
# Boundary Lines
| If the real question is about... | Go here instead | Why |
|---|---|---|
| Atomic object types, memory ordering, wait/notify on atomics, or lock-free coordination | Atomic operations | The atomic hub is the canonical route for the memory model and low-level synchronization primitives. |
| Sender/scheduler execution composition rather than thread objects and futures | Execution | `/cpp/thread/` covers the thread support library; execution is the newer generic async composition model. |
| Error reporting, exceptions, error categories, or assertions | Diagnostics | Futures can transport exceptions, but the exception and diagnostic taxonomy lives in the diagnostics hub. |
| Durations, clocks, deadlines, and time-point arithmetic | Chrono | Thread utilities consume chrono types, but chrono remains the canonical home for time measurement and clocks. |
| The C thread and atomic surface instead of the C++ library | C thread support, C atomics | The C model is a separate library surface with different types and naming. |