Hi,
We would like to implement thread pool capability, and think it might be
a good addition to apr-util or apr.
I have defined a header file and is going to implement it, if you can
review it and give some feedback, it is much appreciated.
Cheers,
Henry
/* Copyright 2000-2005 The Apache Software Foundation or its licensors, as
* applicable.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
#ifdef APR_THREAD_POOL_H
#define APR_THREAD_POOL_H
/**
* @file apr_thread_pool.h
* @brief APR Thread Pool Library
* @remarks This library implements a thread pool using apr_thread_t. A thread
* pool is a set of threads that can be created in advance or on demand until a
* maximum number. When a task is scheduled, the thread pool will find an idle
* thread to handle the task. In case all existing threads are busy, the pool
* will try to create a new thread to serve the task if the maximum number has
* not been reached. Otherwise, the task will be put into a queue based on
* priority, which can be valued from 0 to 255, with higher value been served
* first. In case there are tasks with the same priority, the new task is put at
* the top or the bottom depeneds on which function is used to put the task.
*
* @remarks There may be the case that a thread pool can use up the maximum
* number of threads at peak load, but having those threads idle afterwards. A
* maximum number of idle threads can be set so that extra idling threads will
* be terminated to save system resrouces.
*/
#ifdef __cplusplus
extern "C" {
#if 0
};
#endif
#endif /* __cplusplus */
/** Opaque Thread Pool structure. */
typedef struct _apr_thread_pool apr_thread_pool_t;
/**
* The prototype for any APR thread pool task functions.
* @param apr_thread_t the apr_thread_t structure for the thread is executing the task
* @param void * a pointer to the user data passed in when schedule the task
*/
typedef void* (APR_THREAD_FUNC *apr_thread_pool_task_t) (apr_thread_t *, void *)
#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
/**
* Setup all of the internal structures required to use thread pools
*/
APR_DECLARE(apr_status_t) apr_thread_pool_init(void);
/**
* Tear down all of the internal structures required to use pools
*/
APR_DECLARE(void) apr_thread_pool_terminate(void);
/**
* Create a thread pool
* @param pool The pool to use
* @param init_threads The number of threads to be created initially, the number
* will also be used as the initial value for maximum number of idle threads.
* @param max_threads The maximum number of threads that can be created
* @param err Receive the error code, can be NULL if not needed.
* @return The thread pool. NULL if failed to create the thread pool. Put the
* error code in the err parameter if it is not NULL.
*/
APR_DECLARE(apr_thread_pool_t*) apr_thread_pool_create(apr_pool_t *pool,
int init_threads,
int max_threads,
apr_status_t *err);
/**
* Destroy the thread pool and stop all the threads
* @return APR_SUCCESS if all threads are stopped.
*/
APR_DECLARE(apr_status_t) apr_thread_pool_destroy(apr_thread_pool_t *self);
/**
* Schedule a task to the bottom of the tasks of same priority.
* @param self The thread pool
* @param task The task function
* @param param The parameter for the task function
* @param priority The priority of the task.
* @return APR_SUCCESS if the task had been scheduled successfully
*/
APR_DECLARE(apr_status_t) apr_thread_pool_push(apr_thread_pool_t *self,
apr_thread_pool_task_t *task,
void *param,
apr_byte_t priority);
/**
* Schedule a task to the top of the tasks of same priority.
* @param self The thread pool
* @param task The task function
* @param param The parameter for the task function
* @param priority The priority of the task.
* @return APR_SUCCESS if the task had been scheduled successfully
*/
APR_DECLARE(apr_status_t) apr_thread_pool_top(apr_thread_pool_t *self,
apr_thread_pool_task_t *task,
void *param,
apr_byte_t priority);
/**
* Get current number of tasks waiting in the queue
* @return Number of tasks in the queue
*/
APR_DECLARE(int) apr_thread_pool_get_num_unprocessed(apr_thread_pool_t *self);
/**
* Access function for the maximum number of idling thread
*/
APR_DECLARE(void) apr_thread_pool_set_max_unused_threads(int);
/**
* Access function for the maximum number of idling thread
*/
APR_DECLARE(int) apr_thread_pool_get_max_unused_threads(void);
/**
* Get current number of idling thread
* @return Number of idling threads
*/
APR_DECLARE(int) apr_thread_pool_get_num_unused_threads(void);
/**
* Stop all unused threads. Ignore the maximum number of idling threads.
* @return The total number of threads stopped.
*/
APR_DECLARE(int) apr_thread_pool_stop_unused_threads(void);
#ifdef __cplusplus
#if 0
{
#endif
}
#endif
#endif /* APR_THREADPOOL_H */
