Apache Portable Runtime
apr_thread_pool.h
Go to the documentation of this file.
00001 /*
00002  * Licensed to the Apache Software Foundation (ASF) under one or more
00003  * contributor license agreements.  See the NOTICE file distributed
00004  * with this work for additional information regarding copyright
00005  * ownership.  The ASF licenses this file to you under the Apache
00006  * License, Version 2.0 (the "License"); you may not use this file
00007  * except in compliance with the License.  You may obtain a copy of
00008  * the License at
00009  *
00010  *     http://www.apache.org/licenses/LICENSE-2.0
00011  *
00012  * Unless required by applicable law or agreed to in writing, software
00013  * distributed under the License is distributed on an "AS IS" BASIS,
00014  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
00015  * implied.  See the License for the specific language governing
00016  * permissions and limitations under the License.
00017  */
00018 
00019 #ifndef APU_THREAD_POOL_H
00020 #define APU_THREAD_POOL_H
00021 
00022 #include "apu.h"
00023 #include "apr_thread_proc.h"
00024 
00025 /**
00026  * @file apr_thread_pool.h
00027  * @brief APR Thread Pool Library
00028 
00029  * @remarks This library implements a thread pool using apr_thread_t. A thread
00030  * pool is a set of threads that can be created in advance or on demand until a
00031  * maximum number. When a task is scheduled, the thread pool will find an idle
00032  * thread to handle the task. In case all existing threads are busy and the
00033  * number of tasks in the queue is higher than the adjustable threshold, the
00034  * pool will try to create a new thread to serve the task if the maximum number
00035  * has not been reached. Otherwise, the task will be put into a queue based on
00036  * priority, which can be valued from 0 to 255, with higher values being served
00037  * first. If there are tasks with the same priority, the new task might be put at
00038  * the top or at the bottom - it depends on which function is used to put the task.
00039  *
00040  * @remarks There may be the case where the thread pool can use up to the maximum
00041  * number of threads at peak load, but having those threads idle afterwards. A
00042  * maximum number of idle threads can be set so that the extra idling threads will
00043  * be terminated to save system resources.
00044  */
00045 #if APR_HAS_THREADS
00046 
00047 #ifdef __cplusplus
00048 extern "C" {
00049 #endif /* __cplusplus */
00050 
00051 /**
00052  * @defgroup APR_Util_TP Thread Pool routines
00053  * @ingroup APR
00054  * @{
00055  */
00056 
00057 /** Opaque Thread Pool structure. */
00058 typedef struct apr_thread_pool apr_thread_pool_t;
00059 
00060 #define APR_THREAD_TASK_PRIORITY_LOWEST 0
00061 #define APR_THREAD_TASK_PRIORITY_LOW 63
00062 #define APR_THREAD_TASK_PRIORITY_NORMAL 127
00063 #define APR_THREAD_TASK_PRIORITY_HIGH 191
00064 #define APR_THREAD_TASK_PRIORITY_HIGHEST 255
00065 
00066 /**
00067  * Create a thread pool
00068  * @param me The pointer in which to return the newly created apr_thread_pool
00069  * object, or NULL if thread pool creation fails.
00070  * @param init_threads The number of threads to be created initially, this number
00071  * will also be used as the initial value for the maximum number of idle threads.
00072  * @param max_threads The maximum number of threads that can be created
00073  * @param pool The pool to use
00074  * @return APR_SUCCESS if the thread pool was created successfully. Otherwise,
00075  * the error code.
00076  */
00077 APR_DECLARE(apr_status_t) apr_thread_pool_create(apr_thread_pool_t **me,
00078                                                  apr_size_t init_threads,
00079                                                  apr_size_t max_threads,
00080                                                  apr_pool_t *pool);
00081 
00082 /**
00083  * Destroy the thread pool and stop all the threads
00084  * @return APR_SUCCESS if all threads are stopped.
00085  */
00086 APR_DECLARE(apr_status_t) apr_thread_pool_destroy(apr_thread_pool_t *me);
00087 
00088 /**
00089  * Schedule a task to the bottom of the tasks of same priority.
00090  * @param me The thread pool
00091  * @param func The task function
00092  * @param param The parameter for the task function
00093  * @param priority The priority of the task.
00094  * @param owner Owner of this task.
00095  * @return APR_SUCCESS if the task had been scheduled successfully
00096  */
00097 APR_DECLARE(apr_status_t) apr_thread_pool_push(apr_thread_pool_t *me,
00098                                                apr_thread_start_t func,
00099                                                void *param,
00100                                                apr_byte_t priority,
00101                                                void *owner);
00102 /**
00103  * Schedule a task to be run after a delay
00104  * @param me The thread pool
00105  * @param func The task function
00106  * @param param The parameter for the task function
00107  * @param time Time in microseconds
00108  * @param owner Owner of this task.
00109  * @return APR_SUCCESS if the task had been scheduled successfully
00110  */
00111 APR_DECLARE(apr_status_t) apr_thread_pool_schedule(apr_thread_pool_t *me,
00112                                                    apr_thread_start_t func,
00113                                                    void *param,
00114                                                    apr_interval_time_t time,
00115                                                    void *owner);
00116 
00117 /**
00118  * Schedule a task to the top of the tasks of same priority.
00119  * @param me The thread pool
00120  * @param func The task function
00121  * @param param The parameter for the task function
00122  * @param priority The priority of the task.
00123  * @param owner Owner of this task.
00124  * @return APR_SUCCESS if the task had been scheduled successfully
00125  */
00126 APR_DECLARE(apr_status_t) apr_thread_pool_top(apr_thread_pool_t *me,
00127                                               apr_thread_start_t func,
00128                                               void *param,
00129                                               apr_byte_t priority,
00130                                               void *owner);
00131 
00132 /**
00133  * Cancel tasks submitted by the owner. If there is any task from the owner that
00134  * is currently running, the function will spin until the task finished.
00135  * @param me The thread pool
00136  * @param owner Owner of the task
00137  * @return APR_SUCCESS if the task has been cancelled successfully
00138  * @note The task function should not be calling cancel, otherwise the function
00139  * may get stuck forever. The function assert if it detect such a case.
00140  */
00141 APR_DECLARE(apr_status_t) apr_thread_pool_tasks_cancel(apr_thread_pool_t *me,
00142                                                        void *owner);
00143 
00144 /**
00145  * Get the current number of tasks waiting in the queue
00146  * @param me The thread pool
00147  * @return Number of tasks in the queue
00148  */
00149 APR_DECLARE(apr_size_t) apr_thread_pool_tasks_count(apr_thread_pool_t *me);
00150 
00151 /**
00152  * Get the current number of scheduled tasks waiting in the queue
00153  * @param me The thread pool
00154  * @return Number of scheduled tasks in the queue
00155  */
00156 APR_DECLARE(apr_size_t) apr_thread_pool_scheduled_tasks_count(apr_thread_pool_t *me);
00157 
00158 /**
00159  * Get the current number of threads
00160  * @param me The thread pool
00161  * @return Total number of threads
00162  */
00163 APR_DECLARE(apr_size_t) apr_thread_pool_threads_count(apr_thread_pool_t *me);
00164 
00165 /**
00166  * Get the current number of busy threads
00167  * @param me The thread pool
00168  * @return Number of busy threads
00169  */
00170 APR_DECLARE(apr_size_t) apr_thread_pool_busy_count(apr_thread_pool_t *me);
00171 
00172 /**
00173  * Get the current number of idle threads
00174  * @param me The thread pool
00175  * @return Number of idle threads
00176  */
00177 APR_DECLARE(apr_size_t) apr_thread_pool_idle_count(apr_thread_pool_t *me);
00178 
00179 /**
00180  * Access function for the maximum number of idle threads. Number of current
00181  * idle threads will be reduced to the new limit.
00182  * @param me The thread pool
00183  * @param cnt The number
00184  * @return The number of threads that were stopped.
00185  */
00186 APR_DECLARE(apr_size_t) apr_thread_pool_idle_max_set(apr_thread_pool_t *me,
00187                                                      apr_size_t cnt);
00188 
00189 /**
00190  * Get number of tasks that have run
00191  * @param me The thread pool
00192  * @return Number of tasks that have run
00193  */
00194 APR_DECLARE(apr_size_t)
00195     apr_thread_pool_tasks_run_count(apr_thread_pool_t * me);
00196 
00197 /**
00198  * Get high water mark of the number of tasks waiting to run
00199  * @param me The thread pool
00200  * @return High water mark of tasks waiting to run
00201  */
00202 APR_DECLARE(apr_size_t)
00203     apr_thread_pool_tasks_high_count(apr_thread_pool_t * me);
00204 
00205 /**
00206  * Get high water mark of the number of threads
00207  * @param me The thread pool
00208  * @return High water mark of threads in thread pool
00209  */
00210 APR_DECLARE(apr_size_t)
00211     apr_thread_pool_threads_high_count(apr_thread_pool_t * me);
00212 
00213 /**
00214  * Get the number of idle threads that were destroyed after timing out
00215  * @param me The thread pool
00216  * @return Number of idle threads that timed out
00217  */
00218 APR_DECLARE(apr_size_t)
00219     apr_thread_pool_threads_idle_timeout_count(apr_thread_pool_t * me);
00220 
00221 /**
00222  * Access function for the maximum number of idle threads
00223  * @param me The thread pool
00224  * @return The current maximum number
00225  */
00226 APR_DECLARE(apr_size_t) apr_thread_pool_idle_max_get(apr_thread_pool_t *me);
00227 
00228 /**
00229  * Access function for the maximum number of threads.
00230  * @param me The thread pool
00231  * @param cnt Number of threads
00232  * @return The original maximum number of threads
00233  */
00234 APR_DECLARE(apr_size_t) apr_thread_pool_thread_max_set(apr_thread_pool_t *me,
00235                                                        apr_size_t cnt);
00236 
00237 /**
00238  * Access function for the maximum wait time (in microseconds) of an
00239  * idling thread that exceeds the maximum number of idling threads.
00240  * A non-zero value allows for the reaping of idling threads to shrink
00241  * over time.  Which helps reduce thrashing.
00242  * @param me The thread pool
00243  * @param timeout The number of microseconds an idle thread should wait
00244  * till it reaps itself
00245  * @return The original maximum wait time
00246  */
00247 APR_DECLARE(apr_interval_time_t)
00248     apr_thread_pool_idle_wait_set(apr_thread_pool_t * me,
00249                                   apr_interval_time_t timeout);
00250 
00251 /**
00252  * Access function for the maximum wait time (in microseconds) of an
00253  * idling thread that exceeds the maximum number of idling threads
00254  * @param me The thread pool
00255  * @return The current maximum wait time
00256  */
00257 APR_DECLARE(apr_interval_time_t)
00258     apr_thread_pool_idle_wait_get(apr_thread_pool_t * me);
00259 
00260 /**
00261  * Access function for the maximum number of threads
00262  * @param me The thread pool
00263  * @return The current maximum number
00264  */
00265 APR_DECLARE(apr_size_t) apr_thread_pool_thread_max_get(apr_thread_pool_t *me);
00266 
00267 /**
00268  * Access function for the threshold of tasks in queue to trigger a new thread.
00269  * @param me The thread pool
00270  * @param cnt The new threshold
00271  * @return The original threshold
00272  */
00273 APR_DECLARE(apr_size_t) apr_thread_pool_threshold_set(apr_thread_pool_t *me,
00274                                                       apr_size_t val);
00275 
00276 /**
00277  * Access function for the threshold of tasks in queue to trigger a new thread.
00278  * @param me The thread pool
00279  * @return The current threshold
00280  */
00281 APR_DECLARE(apr_size_t) apr_thread_pool_threshold_get(apr_thread_pool_t * me);
00282 
00283 /**
00284  * Get owner of the task currently been executed by the thread.
00285  * @param thd The thread is executing a task
00286  * @param owner Pointer to receive owner of the task.
00287  * @return APR_SUCCESS if the owner is retrieved successfully
00288  */
00289 APR_DECLARE(apr_status_t) apr_thread_pool_task_owner_get(apr_thread_t *thd,
00290                                                          void **owner);
00291 
00292 /** @} */
00293 
00294 #ifdef __cplusplus
00295 }
00296 #endif
00297 
00298 #endif /* APR_HAS_THREADS */
00299 #endif /* !APR_THREAD_POOL_H */
 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Defines