Apache Portable Runtime
|
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_Util 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 APU_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 APU_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 APU_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 APU_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 APU_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 APU_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 APU_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 APU_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 APU_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 APU_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 APU_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 APU_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 APU_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 APU_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 APU_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 APU_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 APU_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 APU_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 APU_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 APU_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 APU_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 APU_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 APU_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 APU_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 */