Apache Portable Runtime Utility Library
 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Macros | Typedefs | Functions
Thread Pool routines
APR Utility Functions

Macros

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

Detailed Description

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
meThe 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
meThe pointer in which to return the newly created apr_thread_pool object, or NULL if thread pool creation fails.
init_threadsThe 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_threadsThe maximum number of threads that can be created
poolThe 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
meThe 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
meThe 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
meThe thread pool
cntThe 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
meThe 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
meThe thread pool
timeoutThe 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
meThe thread pool
funcThe task function
paramThe parameter for the task function
priorityThe priority of the task.
ownerOwner 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
meThe thread pool
funcThe task function
paramThe parameter for the task function
timeTime in microseconds
ownerOwner 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
meThe 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
thdThe thread is executing a task
ownerPointer 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
meThe thread pool
ownerOwner 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
meThe 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
meThe 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
meThe 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
meThe 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
meThe thread pool
cntNumber 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
meThe 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
meThe 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
meThe 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
meThe 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
meThe thread pool
cntThe 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
meThe thread pool
funcThe task function
paramThe parameter for the task function
priorityThe priority of the task.
ownerOwner of this task.
Returns
APR_SUCCESS if the task had been scheduled successfully