00001 /* Copyright 2000-2004 The Apache Software Foundation 00002 * 00003 * Licensed under the Apache License, Version 2.0 (the "License"); 00004 * you may not use this file except in compliance with the License. 00005 * You may obtain a copy of the License at 00006 * 00007 * http://www.apache.org/licenses/LICENSE-2.0 00008 * 00009 * Unless required by applicable law or agreed to in writing, software 00010 * distributed under the License is distributed on an "AS IS" BASIS, 00011 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 00012 * See the License for the specific language governing permissions and 00013 * limitations under the License. 00014 */ 00015 00016 #ifndef APR_THREAD_COND_H 00017 #define APR_THREAD_COND_H 00018 00019 /** 00020 * @file apr_thread_cond.h 00021 * @brief APR Condition Variable Routines 00022 */ 00023 00024 #include "apr.h" 00025 #include "apr_pools.h" 00026 #include "apr_errno.h" 00027 #include "apr_time.h" 00028 #include "apr_thread_mutex.h" 00029 00030 #ifdef __cplusplus 00031 extern "C" { 00032 #endif /* __cplusplus */ 00033 00034 #if APR_HAS_THREADS || defined(DOXYGEN) 00035 00036 /** 00037 * @defgroup apr_thread_cond Condition Variable Routines 00038 * @ingroup APR 00039 * @{ 00040 */ 00041 00042 /** Opaque structure for thread condition variables */ 00043 typedef struct apr_thread_cond_t apr_thread_cond_t; 00044 00045 /** 00046 * Note: destroying a condition variable (or likewise, destroying or 00047 * clearing the pool from which a condition variable was allocated) if 00048 * any threads are blocked waiting on it gives undefined results. 00049 */ 00050 00051 /** 00052 * Create and initialize a condition variable that can be used to signal 00053 * and schedule threads in a single process. 00054 * @param cond the memory address where the newly created condition variable 00055 * will be stored. 00056 * @param pool the pool from which to allocate the mutex. 00057 */ 00058 APR_DECLARE(apr_status_t) apr_thread_cond_create(apr_thread_cond_t **cond, 00059 apr_pool_t *pool); 00060 00061 /** 00062 * Put the active calling thread to sleep until signaled to wake up. Each 00063 * condition variable must be associated with a mutex, and that mutex must 00064 * be locked before calling this function, or the behavior will be 00065 * undefined. As the calling thread is put to sleep, the given mutex 00066 * will be simultaneously released; and as this thread wakes up the lock 00067 * is again simultaneously acquired. 00068 * @param cond the condition variable on which to block. 00069 * @param mutex the mutex that must be locked upon entering this function, 00070 * is released while the thread is asleep, and is again acquired before 00071 * returning from this function. 00072 */ 00073 APR_DECLARE(apr_status_t) apr_thread_cond_wait(apr_thread_cond_t *cond, 00074 apr_thread_mutex_t *mutex); 00075 00076 /** 00077 * Put the active calling thread to sleep until signaled to wake up or 00078 * the timeout is reached. Each condition variable must be associated 00079 * with a mutex, and that mutex must be locked before calling this 00080 * function, or the behavior will be undefined. As the calling thread 00081 * is put to sleep, the given mutex will be simultaneously released; 00082 * and as this thread wakes up the lock is again simultaneously acquired. 00083 * @param cond the condition variable on which to block. 00084 * @param mutex the mutex that must be locked upon entering this function, 00085 * is released while the thread is asleep, and is again acquired before 00086 * returning from this function. 00087 * @param timeout The amount of time in microseconds to wait. This is 00088 * a maximum, not a minimum. If the condition is signaled, we 00089 * will wake up before this time, otherwise the error APR_TIMEUP 00090 * is returned. 00091 */ 00092 APR_DECLARE(apr_status_t) apr_thread_cond_timedwait(apr_thread_cond_t *cond, 00093 apr_thread_mutex_t *mutex, 00094 apr_interval_time_t timeout); 00095 00096 /** 00097 * Signals a single thread, if one exists, that is blocking on the given 00098 * condition variable. That thread is then scheduled to wake up and acquire 00099 * the associated mutex. Although it is not required, if predictable scheduling 00100 * is desired, that mutex must be locked while calling this function. 00101 * @param cond the condition variable on which to produce the signal. 00102 */ 00103 APR_DECLARE(apr_status_t) apr_thread_cond_signal(apr_thread_cond_t *cond); 00104 00105 /** 00106 * Signals all threads blocking on the given condition variable. 00107 * Each thread that was signaled is then scheduled to wake up and acquire 00108 * the associated mutex. This will happen in a serialized manner. 00109 * @param cond the condition variable on which to produce the broadcast. 00110 */ 00111 APR_DECLARE(apr_status_t) apr_thread_cond_broadcast(apr_thread_cond_t *cond); 00112 00113 /** 00114 * Destroy the condition variable and free the associated memory. 00115 * @param cond the condition variable to destroy. 00116 */ 00117 APR_DECLARE(apr_status_t) apr_thread_cond_destroy(apr_thread_cond_t *cond); 00118 00119 /** 00120 * Get the pool used by this thread_cond. 00121 * @return apr_pool_t the pool 00122 */ 00123 APR_POOL_DECLARE_ACCESSOR(thread_cond); 00124 00125 #endif /* APR_HAS_THREADS */ 00126 00127 /** @} */ 00128 00129 #ifdef __cplusplus 00130 } 00131 #endif 00132 00133 #endif /* ! APR_THREAD_COND_H */