The NPS Pthread Pool module interface. More...

#include <pthread.h>
#include <limits.h>

Include dependency graph for thr_pool.h:

This graph shows which files directly or indirectly include this file:

Defines
#define	THR_POOL_MAX_NUM (1024)
#define	THR_POOL_MAX_POOLS 32767
	max number of pools (= 2^15 - 1)
#define	THR_POOL_MAX_THREADS (THR_POOL_MAX_NUM - 2)
	max number of threads that can be in any pool.
#define	THR_POOL_BASE (-100)
	All return codes are in the interval [THR_POOL_BASE, THR_POOL_LAST].
#define	THR_POOL_SUCCESS (THR_POOL_BASE)
	Return code: operation successful.
#define	THR_POOL_ERROR (THR_POOL_BASE - 1)
	Return code: a soft error ocurred; the pool might still be usable.
#define	THR_POOL_UNRECOV_ERROR (THR_POOL_BASE - 2)
	Return code: a hard error ocurred; the pool may not be usable further.
#define	THR_POOL_NOT_INITIALIZED (THR_POOL_BASE - 3)
	Return code: operation failed because the pool was not initialized.
#define	THR_POOL_BAD_INPUT (THR_POOL_BASE - 4)
	Return code: operation failed because the input was bad.
#define	THR_POOL_INVALID_HANDLE (THR_POOL_BASE - 5)
	Return code: operation failed because the input pool handle was invalid.
#define	THR_POOL_RESOURCE_ERROR (THR_POOL_BASE - 6)
	Return code: a memory- or resource-related error ocurred.
#define	THR_POOL_LAST (THR_POOL_BASE - 6)
	A constant (ensures external / internal return codes don't overlap).
Typedefs
typedef int	thr_pool_handle_t
	The type defining the "handle" to a specific pool.
Functions
int	thr_pool_init (void)
int	thr_pool_create (const unsigned int pool_min, const unsigned int pool_max, const unsigned int timeout, const pthread_attr_t attr, thr_pool_handle_t pool_handle)
int	thr_pool_queue (const thr_pool_handle_t pool_handle, const int mode, const size_t len, void (func)(void ), void arg)
int	thr_pool_destroy (const thr_pool_handle_t pool_handle)
int	thr_pool_free (void)

Detailed Description

The NPS Pthread Pool module interface.

Inferface for a module to maniulate a simple POSIX thread pool. Each pool is manger-less, and supports a min- and max- thread population.

To create a new pool, see thr_pool_create(). The module can manage multiple pools; the caller is given a handle to identify the pool, upon pool creation.
To enqueue a job in a pool, see thr_pool_queue().
To destroy a pool, see thr_pool_destroy().

Precondition:: Initialize the module via thr_pool_init().

Postcondition:: Free the module via thr_pool_free().

Define Documentation

#define THR_POOL_BAD_INPUT (THR_POOL_BASE - 4)

Return code: operation failed because the input was bad.

#define THR_POOL_BASE (-100)

All return codes are in the interval [THR_POOL_BASE, THR_POOL_LAST].

#define THR_POOL_ERROR (THR_POOL_BASE - 1)

Return code: a soft error ocurred; the pool might still be usable.

#define THR_POOL_INVALID_HANDLE (THR_POOL_BASE - 5)

Return code: operation failed because the input pool handle was invalid.

#define THR_POOL_LAST (THR_POOL_BASE - 6)

A constant (ensures external / internal return codes don't overlap).

#define THR_POOL_MAX_NUM (1024)

#define THR_POOL_MAX_POOLS 32767

max number of pools (= 2^15 - 1)

#define THR_POOL_MAX_THREADS (THR_POOL_MAX_NUM - 2)

max number of threads that can be in any pool.

We use 2 less than THR_POOL_MAX_NUM since

LinuxThreads has a manager thread
the caller uses one thread

#define THR_POOL_NOT_INITIALIZED (THR_POOL_BASE - 3)

Return code: operation failed because the pool was not initialized.

#define THR_POOL_RESOURCE_ERROR (THR_POOL_BASE - 6)

Return code: a memory- or resource-related error ocurred.

#define THR_POOL_SUCCESS (THR_POOL_BASE)

Return code: operation successful.

#define THR_POOL_UNRECOV_ERROR (THR_POOL_BASE - 2)

Return code: a hard error ocurred; the pool may not be usable further.

Typedef Documentation

typedef int thr_pool_handle_t

The type defining the "handle" to a specific pool.

Function Documentation

int thr_pool_create	(	const unsigned int	pool_min,
		const unsigned int	pool_max,
		const unsigned int	timeout,
		const pthread_attr_t *	attr,
		thr_pool_handle_t *	pool_handle
	)

Create and initialize the thread pool.

Parameters:

[in]	pool_min	The minimum number of threads in the pool. If no jobs are present for the pool, these threads are present, but idle.
[in]	pool_max	The maximum number of active threads allowed in the queue; it should be the case that pool_max should be non-zero, no less than pool_min, and no greater than THR_POOL_MAX_THREADS.
[in]	timeout	A value, interpreted as seconds, at most THR_POOL_MAX_TIMEOUT; if the number of active threads in the thread pool is in excess of pool_min, any thread that becomes idle will wait for timeout seconds. If no tasks are present in the queue or entered in the queue during this time, the thread will be removed from the pool and the system resources for the thread will be reclaimed;
[in]	attr	Pointer to the POSIX thread attribute used to specify the attributes of any thread created in the thread pool. If NULL, the default attributes of pthread_create() are used.
[out]	pool_handle	A handle for the thread pool.

Returns:: An indicator of whether or not the operation was successful. On success: THR_POOL_SUCCESS is returned. On error: THR_POOL_BAD_INPUT, THR_POOL_RESOURCE_ERROR, THR_POOL_NOT_INITIALIZED, THR_POOL_ERROR, or THR_POOL_UNRECOV_ERROR is returned.

Here is the call graph for this function:

int thr_pool_destroy ( const thr_pool_handle_t pool_handle )

Cancels all queued jobs, kills all active threads, and frees all internal module resources related to the thread.

Parameters:

[in] pool_handle The handle for the thread pool.

Returns:: An indicator of whether or not the operation was successful On success: THR_POOL_SUCCESS is returned. On error: THR_POOL_INVALID_HANDLE, THR_POOL_NOT_INITIALIZED, THR_POOL_ERROR, or THR_POOL_UNRECOV_ERROR is returned.

Here is the call graph for this function:

int thr_pool_free ( void )

Cancels all queued jobs, kills all active threads, and frees all internal module resources. All thread pools being managed are destroyed.

Returns:: An indicator of whether or not the operation was successful On success: THR_POOL_SUCCESS is returned. On error: THR_POOL_NOT_INITIALIZED, or THR_POOL_UNRECOV_ERROR is returned.

Here is the call graph for this function:

int thr_pool_init ( void )

Initialize the thread management module data.

Returns:: An indicator of whether or not the operation was successful On success: THR_POOL_SUCCESS is returned. On error: THR_POOL_RESOURCE_ERROR, THR_POOL_ERROR, or THR_POOL_UNRECOV_ERROR is returned.

Here is the call graph for this function:

int thr_pool_queue	(	const thr_pool_handle_t	pool_handle,
		const int	mode,
		const size_t	len,
		void ()(void *)	func,
		void *	arg
	)

If there are idle threads in the pool, awaken one to perform the job. If there are no idle threads but the maximum number of threads in the pool has not been reached, create a new thread to perform the job. If no idle threads exist and the pool already has the maximum number of threads, then add the job to the queue and return success; some existing worker thread will perform the job when it becomes idle. If mode is 1, the len bytes at arg will be copied locally, and the job (when executed) will use the local copy of arg.

Parameters:

[in]	pool_handle	The handle for the thread pool.
[in]	mode	Can take any value. If 1, it indicates arg should be (shallow) copied. This is useful in many scenarios, e.g. when arg is a pointer to something on the caller's stack. If arguments are not copied, the caller must ensure arg persists until a thread is scheduled for the job, and throughout the duration of that job.
[in]	len	The length of arg.
[in]	func	A pointer to the job function.
[in,out]	arg	A pointer to the arguments for the job function. If argument is copied when enqueued, it cannot be used as an output argument.

Returns:: An indicator of whether or not the operation was successful On success: THR_POOL_SUCCESS is returned. On error: THR_POOL_BAD_INPUT, THR_POOL_RESOURCE_ERROR, THR_POOL_INVALID_HANDLE, THR_POOL_NOT_INITIALIZED, THR_POOL_ERROR, or THR_POOL_UNRECOV_ERROR is returned.

Here is the call graph for this function:

Defines

Typedefs

Functions

Detailed Description

Define Documentation

Typedef Documentation

Function Documentation