vlink::ThreadPool类 参考

Fixed worker pool that consumes a shared task queue. 更多...

#include <thread_pool.h>

vlink::ThreadPool 的协作图:

Public 类型
enum	Type : uint8_t { kNormalType = 0 , kLockfreeType = 1 }
	Queue implementation backing the pool. 更多...
enum	Strategy : uint8_t { kOptimizationStrategy = 0 , kPopStrategy = 1 , kBlockStrategy = 2 }
	Submission-side strategy applied when the bounded queue is full. 更多...
using	Callback = MoveFunction< void()>
	Callback signature used for submitted tasks. 更多...

Public 成员函数
	ThreadPool (size_t thread_count=4U)
	Constructs a pool with thread_count workers and the default kNormalType queue. 更多...
	ThreadPool (size_t thread_count, Type type)
	Constructs a pool with a custom queue implementation. 更多...
virtual	~ThreadPool ()
	Destructor. Calls shutdown() and joins worker threads. 更多...
void	set_name (const std::string &name)
	Assigns a human-readable name to the pool and its workers (used by debuggers). 更多...
const std::string &	get_name () const
	Returns the display name assigned via set_name(). 更多...
Type	get_type () const
	Returns the queue implementation used by this pool. 更多...
Strategy	get_strategy () const
	Returns the current submission-side back-pressure strategy. 更多...
void	set_strategy (Strategy strategy)
	Updates the submission-side back-pressure strategy. 更多...
bool	shutdown ()
	Marks the pool as quitting, drains in-flight tasks, and joins workers. 更多...
bool	post_task (Callback &&callback)
	Submits a task to the queue for execution by a worker thread. 更多...
TaskHandle	post_task_handle (Callback &&callback, const PostTaskOptions &options={})
	Submits a task that produces an observable TaskHandle. 更多...
size_t	get_task_count () const
	Returns the current number of tasks waiting in the queue. 更多...
bool	is_in_work_thread () const
	Reports whether the calling thread is one of this pool's workers. 更多...
virtual size_t	get_max_task_count () const
	Returns the maximum queue capacity. 更多...
template<class FunctionT , class... ArgsT, typename ResultT = std::invoke_result_t<FunctionT, ArgsT...>>
std::future< ResultT >	invoke_task (FunctionT &&function, ArgsT &&... args)
	Submits a callable to a worker thread and returns a std::future for the result. 更多...

详细描述

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

using vlink::ThreadPool::Callback = MoveFunction<void()>

Callback signature used for submitted tasks.

Move-only (MoveFunction<void()>); see MessageLoop::Callback for rationale.

成员枚举类型说明

Strategy

enum vlink::ThreadPool::Strategy : uint8_t

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.

枚举值
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

enum vlink::ThreadPool::Type : uint8_t

Queue implementation backing the pool.

枚举值
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.

参数

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.

参数

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.

返回

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().

返回

Reference to the stored name string.

get_strategy()

Strategy vlink::ThreadPool::get_strategy

(

)

const

Returns the current submission-side back-pressure strategy.

返回

Current strategy.

get_task_count()

size_t vlink::ThreadPool::get_task_count

(

)

const

Returns the current number of tasks waiting in the queue.

返回

Pending task count.

get_type()

Type vlink::ThreadPool::get_type

(

)

const

Returns the queue implementation used by this pool.

返回

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.

警告

Do not block on the returned future from a pool worker thread while all workers are busy; doing so deadlocks the pool.

模板参数

FunctionT	Callable type.
ArgsT	Argument types forwarded to the callable.
ResultT	Deduced result type.

参数

function	Callable to dispatch.
args	Arguments to forward.

返回

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.

返回

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.

注解

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.

参数

callback

Task to execute.

返回

true when the task was eventually enqueued.

这是这个函数的调用关系图:

post_task_handle()

TaskHandle vlink::ThreadPool::post_task_handle	(	Callback &&	callback,
		const PostTaskOptions &	options = {}
	)

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.

参数

callback	Task to execute.
options	Optional overflow, drop, and cancellation policy.

返回

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).

参数

name	Display name.

set_strategy()

void vlink::ThreadPool::set_strategy

(

Strategy

strategy

)

Updates the submission-side back-pressure strategy.

参数

strategy

New strategy.

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.

返回

true on the first successful shutdown; false on subsequent calls.

---

该类的文档由以下文件生成:

• include/vlink/base/thread_pool.h