Thread pool

Synchronous parallel processing of queue entries. More...

Functions
sgl_threadpool_t *	sgl_threadpool_create (sgl_size_t num_threads, sgl_size_t max_routine_lists, const char *base_name)
	Creates a worker-thread pool.
sgl_result_t	sgl_threadpool_destroy (sgl_threadpool_t *pool)
	Stops workers and destroys a thread pool.
sgl_size_t	sgl_threadpool_get_num_threads (const sgl_threadpool_t *pool)
	Returns the number of background workers.
sgl_result_t	sgl_threadpool_attach_routine (sgl_threadpool_t *pool, sgl_threadpool_routine_t routine, sgl_queue_t *operations, void *cookie)
	Processes all queued operations and restores their queue entries.
sgl_result_t	sgl_threadpool_attach_routine_consuming (sgl_threadpool_t *pool, sgl_threadpool_routine_t routine, sgl_queue_t *operations, void *cookie)
	Processes and removes every operation entry from the queue.

Detailed Description

Synchronous parallel processing of queue entries.

Attach calls block until every entry has been processed. The submitting thread participates in execution, so num_threads is the maximum number of background workers rather than a total concurrency count.

Function Documentation

sgl_threadpool_attach_routine()

sgl_result_t sgl_threadpool_attach_routine	(	sgl_threadpool_t *	pool,
		sgl_threadpool_routine_t	routine,
		sgl_queue_t *	operations,
		void *	cookie
	)

Processes all queued operations and restores their queue entries.

Parameters

[in,out]	pool	Worker pool.
[in]	routine	Callback invoked once for each operation.
[in,out]	operations	Queue of non-NULL operation pointers.
[in,out]	cookie	Optional callback context.

Return values

SGL_SUCCESS	Every operation completed and the queue was restored.
SGL_ERROR_INVALID_ARGUMENTS	A required argument is SGL_NULL or the pool is shutting down.
SGL_ERROR_MEMORY_ALLOCATION	The temporary completion queue could not be allocated.

Note

Queue entry order after parallel execution is completion order and may differ from the original enqueue order.

sgl_threadpool_attach_routine_consuming()

sgl_result_t sgl_threadpool_attach_routine_consuming	(	sgl_threadpool_t *	pool,
		sgl_threadpool_routine_t	routine,
		sgl_queue_t *	operations,
		void *	cookie
	)

Processes and removes every operation entry from the queue.

Parameters

[in,out]	pool	Worker pool.
[in]	routine	Callback invoked once for each operation.
[in,out]	operations	Queue that is empty when the call succeeds.
[in,out]	cookie	Optional callback context.

Return values

SGL_SUCCESS	Every operation completed and was consumed.
SGL_ERROR_INVALID_ARGUMENTS	A required argument is SGL_NULL or the pool is shutting down.

Note

The caller retains ownership of the empty queue and all operation objects. This variant avoids allocating a completion queue.

sgl_threadpool_create()

sgl_threadpool_t * sgl_threadpool_create	(	sgl_size_t	num_threads,
		sgl_size_t	max_routine_lists,
		const char *	base_name
	)

Creates a worker-thread pool.

Parameters

[in]	num_threads	Positive number of background worker threads.
[in]	max_routine_lists	Positive submission-capacity contract; use SGL_THREADPOOL_DEFAULT_MAX_ROUTINE_LISTS for the default.
[in]	base_name	Optional caller-owned thread-name prefix retained for the lifetime of the pool.

Returns

New thread pool, or SGL_NULL for invalid input or allocation failure.

sgl_threadpool_destroy()

sgl_result_t sgl_threadpool_destroy

(

sgl_threadpool_t *

pool

)

Stops workers and destroys a thread pool.

Parameters

[in]

pool

Pool to destroy; must not be SGL_NULL.

Return values

SGL_SUCCESS	Pool destroyed.
SGL_ERROR_INVALID_ARGUMENTS	pool is SGL_NULL.

sgl_threadpool_get_num_threads()

sgl_size_t sgl_threadpool_get_num_threads

(

const sgl_threadpool_t *

pool

)

Returns the number of background workers.

Parameters

[in]

pool

Pool or SGL_NULL.

Returns

Worker count, or 0 for SGL_NULL.