Fixed worker pool that consumes a shared task queue.
More...
#include <thread_pool.h>
Fixed worker pool that consumes a shared task queue.
Worker threads are created during construction and joined during shutdown() or destruction. The pool object itself is non-copyable.
◆ Callback
◆ Strategy
Submission-side strategy applied when the bounded queue is full.
Worker wake-up is independent of this enum. It controls only how post_task and invoke_task react when capacity is reached.
| Enumerator |
|---|
| kOptimizationStrategy | Retry up to 10 times with 1 ms sleep; then drop one eligible task and push.
|
| kPopStrategy | Immediately drop one eligible task and push the new one.
|
| kBlockStrategy | Retry indefinitely with 1 ms sleep until capacity frees up.
|
◆ Type
Queue implementation backing the pool.
| Enumerator |
|---|
| kNormalType | Default mutex-protected FIFO queue.
|
| kLockfreeType | Lock-free MPMC queue.
|
◆ ThreadPool() [1/2]
| vlink::ThreadPool::ThreadPool |
( |
size_t |
thread_count = 4U | ) |
|
|
explicit |
Constructs a pool with thread_count workers and the default kNormalType queue.
- Parameters
-
| thread_count | Worker thread count. Default: 4. Zero leaves the pool in the shutdown state. |
◆ ThreadPool() [2/2]
| vlink::ThreadPool::ThreadPool |
( |
size_t |
thread_count, |
|
|
Type |
type |
|
) |
| |
|
explicit |
Constructs a pool with a custom queue implementation.
- Parameters
-
| thread_count | Worker thread count. Zero leaves the pool in the shutdown state. |
| type | Queue implementation type. |
◆ ~ThreadPool()
| virtual vlink::ThreadPool::~ThreadPool |
( |
| ) |
|
|
virtual |
Destructor. Calls shutdown() and joins worker threads.
◆ get_max_task_count()
| virtual size_t vlink::ThreadPool::get_max_task_count |
( |
| ) |
const |
|
virtual |
Returns the maximum queue capacity.
- Returns
- Maximum number of tasks that may be queued at the same time.
◆ get_name()
| const std::string& vlink::ThreadPool::get_name |
( |
| ) |
const |
Returns the display name assigned via set_name().
- Returns
- Reference to the stored name string.
◆ get_strategy()
| Strategy vlink::ThreadPool::get_strategy |
( |
| ) |
const |
Returns the current submission-side back-pressure strategy.
- Returns
- Current strategy.
◆ get_task_count()
| size_t vlink::ThreadPool::get_task_count |
( |
| ) |
const |
Returns the current number of tasks waiting in the queue.
- Returns
- Pending task count.
◆ get_type()
| Type vlink::ThreadPool::get_type |
( |
| ) |
const |
Returns the queue implementation used by this pool.
- Returns
- Queue type.
◆ invoke_task()
template<class FunctionT , class... ArgsT, typename ResultT >
| std::future< ResultT > vlink::ThreadPool::invoke_task |
( |
FunctionT && |
function, |
|
|
ArgsT &&... |
args |
|
) |
| |
|
inline |
Submits a callable to a worker thread and returns a std::future for the result.
Details.
Thread-safe. The future is satisfied once the callable returns. When posting fails the future becomes ready with a broken_promise / future_error result.
- Warning
- Do not block on the returned future from a pool worker thread while all workers are busy; doing so deadlocks the pool.
- Template Parameters
-
| FunctionT | Callable type. |
| ArgsT | Argument types forwarded to the callable. |
| ResultT | Deduced result type. |
- Parameters
-
| function | Callable to dispatch. |
| args | Arguments to forward. |
- Returns
- Future resolved with the callable's result.
◆ is_in_work_thread()
| bool vlink::ThreadPool::is_in_work_thread |
( |
| ) |
const |
Reports whether the calling thread is one of this pool's workers.
- Returns
true when called from a worker.
◆ post_task()
| bool vlink::ThreadPool::post_task |
( |
Callback && |
callback | ) |
|
Submits a task to the queue for execution by a worker thread.
Thread-safe. Returns false when the pool is already shut down or when overflow handling cannot make room for the new task. Overflow behaviour depends on the configured Strategy:
kOptimizationStrategy: retry up to 10 times with a 1 ms sleep, then drop one eligible task and push the new one.kPopStrategy: drop one eligible task immediately and push the new one.kBlockStrategy: retry indefinitely with 1 ms sleep until space is available.
- Note
- Drop-policy semantics:
kNormalType respects TaskDropPolicy::kProtected; protected tasks are never selected as eviction victims, and if every queued task is protected the post fails and returns false.kLockfreeType does not track per-task drop policy; overflow drop simply removes one queued task regardless of how it was submitted.
- Parameters
-
- Returns
true when the task was eventually enqueued.
◆ post_task_handle()
Submits a task that produces an observable TaskHandle.
Tracked counterpart of post_task(). The returned handle allows callers to wait for completion, request cooperative cancellation, and observe whether the task was rejected or dropped before execution.
- Parameters
-
| callback | Task to execute. |
| options | Optional overflow, drop, and cancellation policy. |
- Returns
- Handle observing the posted task; the handle remains valid even when the post is rejected so callers can inspect
state().
◆ set_name()
| void vlink::ThreadPool::set_name |
( |
const std::string & |
name | ) |
|
Assigns a human-readable name to the pool and its workers (used by debuggers).
- Parameters
-
◆ set_strategy()
| void vlink::ThreadPool::set_strategy |
( |
Strategy |
strategy | ) |
|
Updates the submission-side back-pressure strategy.
- Parameters
-
◆ shutdown()
| bool vlink::ThreadPool::shutdown |
( |
| ) |
|
Marks the pool as quitting, drains in-flight tasks, and joins workers.
After shutdown() returns, further submissions are rejected. Workers complete the task they are currently running plus any already-queued tasks before exiting. When called from a worker thread the calling worker's handle is detached instead of joined because a thread cannot join itself; the Impl block is kept alive via std::shared_ptr so the detached worker continues to see a valid pool state until it returns.
- Returns
true on the first successful shutdown; false on subsequent calls.
The documentation for this class was generated from the following file:
1.9.1