Thread pool

Worker pool where every thread runs the same entry function with a shared common argument plus a per-thread specific argument. More...

Macros
#define	r_thread_pool_ref   r_ref_ref
	Take a reference on the pool (alias for r_ref_ref).
#define	r_thread_pool_unref   r_ref_unref
	Drop a reference on the pool (alias for r_ref_unref).

Typedefs
typedef struct RThreadPool	RThreadPool
	Opaque, refcounted thread-pool handle.
typedef rpointer(*	RThreadPoolFunc) (rpointer common, rpointer specific)
	Worker entry-point signature.

Functions
RThreadPool *	r_thread_pool_new (const rchar *prefix, RThreadPoolFunc func, rpointer data)
	Create a new pool that will spawn workers running func.
rboolean	r_thread_pool_start_thread (RThreadPool *pool, const rchar *name, const RBitset *affinity, rpointer data)
	Spawn one worker with optional name and CPU-affinity mask.
rboolean	r_thread_pool_start_thread_on_cpu (RThreadPool *pool, rsize cpuidx, rpointer data)
	Spawn one worker pinned to a single CPU index.
rboolean	r_thread_pool_start_thread_on_cpuset (RThreadPool *pool, const RBitset *cpuset, rpointer data)
	Spawn one worker whose affinity is the given cpuset.
rboolean	r_thread_pool_start_thread_on_each_cpu (RThreadPool *pool, const RBitset *cpuset, rpointer data)
	Spawn one worker per CPU set in cpuset, each pinned to its respective CPU.
void	r_thread_pool_join (RThreadPool *pool)
	Wait for all workers to finish; the pool must not be used for further _start_thread_* calls after this returns.
ruint	r_thread_pool_running_threads (RThreadPool *pool)
	Return the number of workers currently running in pool.

Detailed Description

Worker pool where every thread runs the same entry function with a shared common argument plus a per-thread specific argument.

Workers are launched explicitly via one of the _start_thread_* calls; the pool does not auto-size or auto-scale. r_thread_pool_join waits for all workers and tears the pool down.

Use Task queue when you want a queue of pending jobs to be pulled by a fixed set of consumers; use Thread pool when you want N long-running parallel workers pinned to specific CPUs.

Typedef Documentation

RThreadPoolFunc

typedef rpointer(* RThreadPoolFunc) (rpointer common, rpointer specific)

Worker entry-point signature.

Parameters

common	Shared argument given at pool creation.
specific	Per-thread argument supplied at _start_thread_*.

Returns

Discarded; the pool does not expose per-worker results.

Function Documentation

r_thread_pool_new()

RThreadPool * r_thread_pool_new	(	const rchar *	prefix,
		RThreadPoolFunc	func,
		rpointer	data
	)

Create a new pool that will spawn workers running func.

Parameters

prefix	Used as the per-worker thread-name prefix for diagnostics; may be NULL.
func	Worker entry point shared by every thread in the pool.
data	common argument forwarded to every func call.

r_thread_pool_start_thread()

rboolean r_thread_pool_start_thread	(	RThreadPool *	pool,
		const rchar *	name,
		const RBitset *	affinity,
		rpointer	data
	)

Spawn one worker with optional name and CPU-affinity mask.

Returns

TRUE on success, FALSE if thread creation failed.