Thread Pool routines

Defines
#define	APR_THREAD_TASK_PRIORITY_LOWEST   0
#define	APR_THREAD_TASK_PRIORITY_LOW   63
#define	APR_THREAD_TASK_PRIORITY_NORMAL   127
#define	APR_THREAD_TASK_PRIORITY_HIGH   191
#define	APR_THREAD_TASK_PRIORITY_HIGHEST   255
Typedefs
typedef struct apr_thread_pool	apr_thread_pool_t
Functions
apr_status_t	apr_thread_pool_create (apr_thread_pool_t **me, apr_size_t init_threads, apr_size_t max_threads, apr_pool_t *pool)
apr_status_t	apr_thread_pool_destroy (apr_thread_pool_t *me)
apr_status_t	apr_thread_pool_push (apr_thread_pool_t *me, apr_thread_start_t func, void *param, apr_byte_t priority, void *owner)
apr_status_t	apr_thread_pool_schedule (apr_thread_pool_t *me, apr_thread_start_t func, void *param, apr_interval_time_t time, void *owner)
apr_status_t	apr_thread_pool_top (apr_thread_pool_t *me, apr_thread_start_t func, void *param, apr_byte_t priority, void *owner)
apr_status_t	apr_thread_pool_tasks_cancel (apr_thread_pool_t *me, void *owner)
apr_size_t	apr_thread_pool_tasks_count (apr_thread_pool_t *me)
apr_size_t	apr_thread_pool_scheduled_tasks_count (apr_thread_pool_t *me)
apr_size_t	apr_thread_pool_threads_count (apr_thread_pool_t *me)
apr_size_t	apr_thread_pool_busy_count (apr_thread_pool_t *me)
apr_size_t	apr_thread_pool_idle_count (apr_thread_pool_t *me)
apr_size_t	apr_thread_pool_idle_max_set (apr_thread_pool_t *me, apr_size_t cnt)
apr_size_t	apr_thread_pool_tasks_run_count (apr_thread_pool_t *me)
apr_size_t	apr_thread_pool_tasks_high_count (apr_thread_pool_t *me)
apr_size_t	apr_thread_pool_threads_high_count (apr_thread_pool_t *me)
apr_size_t	apr_thread_pool_threads_idle_timeout_count (apr_thread_pool_t *me)
apr_size_t	apr_thread_pool_idle_max_get (apr_thread_pool_t *me)
apr_size_t	apr_thread_pool_thread_max_set (apr_thread_pool_t *me, apr_size_t cnt)
apr_interval_time_t	apr_thread_pool_idle_wait_set (apr_thread_pool_t *me, apr_interval_time_t timeout)
apr_interval_time_t	apr_thread_pool_idle_wait_get (apr_thread_pool_t *me)
apr_size_t	apr_thread_pool_thread_max_get (apr_thread_pool_t *me)
apr_size_t	apr_thread_pool_threshold_set (apr_thread_pool_t *me, apr_size_t val)
apr_size_t	apr_thread_pool_threshold_get (apr_thread_pool_t *me)
apr_status_t	apr_thread_pool_task_owner_get (apr_thread_t *thd, void **owner)

---

Typedef Documentation

typedef struct apr_thread_pool apr_thread_pool_t

Opaque Thread Pool structure.

---

Function Documentation

apr_size_t apr_thread_pool_busy_count

(

apr_thread_pool_t *

me

)

Get the current number of busy threads

Parameters:

me

The thread pool

Returns:

Number of busy threads

apr_status_t apr_thread_pool_create	(	apr_thread_pool_t **	me,
		apr_size_t	init_threads,
		apr_size_t	max_threads,
		apr_pool_t *	pool
	)

Create a thread pool

Parameters:

	me	The pointer in which to return the newly created apr_thread_pool object, or NULL if thread pool creation fails.
	init_threads	The number of threads to be created initially, this number will also be used as the initial value for the maximum number of idle threads.
	max_threads	The maximum number of threads that can be created
	pool	The pool to use

Returns:

APR_SUCCESS if the thread pool was created successfully. Otherwise, the error code.

apr_status_t apr_thread_pool_destroy

(

apr_thread_pool_t *

me

)

Destroy the thread pool and stop all the threads

Returns:

APR_SUCCESS if all threads are stopped.

apr_size_t apr_thread_pool_idle_count

(

apr_thread_pool_t *

me

)

Get the current number of idle threads

Parameters:

me

The thread pool

Returns:

Number of idle threads

apr_size_t apr_thread_pool_idle_max_get

(

apr_thread_pool_t *

me

)

Access function for the maximum number of idle threads

Parameters:

me

The thread pool

Returns:

The current maximum number

apr_size_t apr_thread_pool_idle_max_set	(	apr_thread_pool_t *	me,
		apr_size_t	cnt
	)

Access function for the maximum number of idle threads. Number of current idle threads will be reduced to the new limit.

Parameters:

	me	The thread pool
	cnt	The number

Returns:

The number of threads that were stopped.

apr_interval_time_t apr_thread_pool_idle_wait_get

(

apr_thread_pool_t *

me

)

Access function for the maximum wait time (in microseconds) of an idling thread that exceeds the maximum number of idling threads

Parameters:

me

The thread pool

Returns:

The current maximum wait time

apr_interval_time_t apr_thread_pool_idle_wait_set	(	apr_thread_pool_t *	me,
		apr_interval_time_t	timeout
	)

Access function for the maximum wait time (in microseconds) of an idling thread that exceeds the maximum number of idling threads. A non-zero value allows for the reaping of idling threads to shrink over time. Which helps reduce thrashing.

Parameters:

	me	The thread pool
	timeout	The number of microseconds an idle thread should wait till it reaps itself

Returns:

The original maximum wait time

apr_status_t apr_thread_pool_push	(	apr_thread_pool_t *	me,
		apr_thread_start_t	func,
		void *	param,
		apr_byte_t	priority,
		void *	owner
	)

Schedule a task to the bottom of the tasks of same priority.

Parameters:

	me	The thread pool
	func	The task function
	param	The parameter for the task function
	priority	The priority of the task.
	owner	Owner of this task.

Returns:

APR_SUCCESS if the task had been scheduled successfully

apr_status_t apr_thread_pool_schedule	(	apr_thread_pool_t *	me,
		apr_thread_start_t	func,
		void *	param,
		apr_interval_time_t	time,
		void *	owner
	)

Schedule a task to be run after a delay

Parameters:

	me	The thread pool
	func	The task function
	param	The parameter for the task function
	time	Time in microseconds
	owner	Owner of this task.

Returns:

APR_SUCCESS if the task had been scheduled successfully

apr_size_t apr_thread_pool_scheduled_tasks_count

(

apr_thread_pool_t *

me

)

Get the current number of scheduled tasks waiting in the queue

Parameters:

me

The thread pool

Returns:

Number of scheduled tasks in the queue

apr_status_t apr_thread_pool_task_owner_get	(	apr_thread_t *	thd,
		void **	owner
	)

Get owner of the task currently been executed by the thread.

Parameters:

	thd	The thread is executing a task
	owner	Pointer to receive owner of the task.

Returns:

APR_SUCCESS if the owner is retrieved successfully

apr_status_t apr_thread_pool_tasks_cancel	(	apr_thread_pool_t *	me,
		void *	owner
	)

Cancel tasks submitted by the owner. If there is any task from the owner that is currently running, the function will spin until the task finished.

Parameters:

	me	The thread pool
	owner	Owner of the task

Returns:

APR_SUCCESS if the task has been cancelled successfully

Note:

The task function should not be calling cancel, otherwise the function may get stuck forever. The function assert if it detect such a case.

apr_size_t apr_thread_pool_tasks_count

(

apr_thread_pool_t *

me

)

Get the current number of tasks waiting in the queue

Parameters:

me

The thread pool

Returns:

Number of tasks in the queue

apr_size_t apr_thread_pool_tasks_high_count

(

apr_thread_pool_t *

me

)

Get high water mark of the number of tasks waiting to run

Parameters:

me

The thread pool

Returns:

High water mark of tasks waiting to run

apr_size_t apr_thread_pool_tasks_run_count

(

apr_thread_pool_t *

me

)

Get number of tasks that have run

Parameters:

me

The thread pool

Returns:

Number of tasks that have run

apr_size_t apr_thread_pool_thread_max_get

(

apr_thread_pool_t *

me

)

Access function for the maximum number of threads

Parameters:

me

The thread pool

Returns:

The current maximum number

apr_size_t apr_thread_pool_thread_max_set	(	apr_thread_pool_t *	me,
		apr_size_t	cnt
	)

Access function for the maximum number of threads.

Parameters:

	me	The thread pool
	cnt	Number of threads

Returns:

The original maximum number of threads

apr_size_t apr_thread_pool_threads_count

(

apr_thread_pool_t *

me

)

Get the current number of threads

Parameters:

me

The thread pool

Returns:

Total number of threads

apr_size_t apr_thread_pool_threads_high_count

(

apr_thread_pool_t *

me

)

Get high water mark of the number of threads

Parameters:

me

The thread pool

Returns:

High water mark of threads in thread pool

apr_size_t apr_thread_pool_threads_idle_timeout_count

(

apr_thread_pool_t *

me

)

Get the number of idle threads that were destroyed after timing out

Parameters:

me

The thread pool

Returns:

Number of idle threads that timed out

apr_size_t apr_thread_pool_threshold_get

(

apr_thread_pool_t *

me

)

Access function for the threshold of tasks in queue to trigger a new thread.

Parameters:

me

The thread pool

Returns:

The current threshold

apr_size_t apr_thread_pool_threshold_set	(	apr_thread_pool_t *	me,
		apr_size_t	val
	)

Access function for the threshold of tasks in queue to trigger a new thread.

Parameters:

	me	The thread pool
	cnt	The new threshold

Returns:

The original threshold

apr_status_t apr_thread_pool_top	(	apr_thread_pool_t *	me,
		apr_thread_start_t	func,
		void *	param,
		apr_byte_t	priority,
		void *	owner
	)

Schedule a task to the top of the tasks of same priority.

Parameters:

	me	The thread pool
	func	The task function
	param	The parameter for the task function
	priority	The priority of the task.
	owner	Owner of this task.

Returns:

APR_SUCCESS if the task had been scheduled successfully