1 /* Licensed to the Apache Software Foundation (ASF) under one or more 2 * contributor license agreements. See the NOTICE file distributed with 3 * this work for additional information regarding copyright ownership. 4 * The ASF licenses this file to You under the Apache License, Version 2.0 5 * (the "License"); you may not use this file except in compliance with 6 * the License. You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 #ifndef APR_THREAD_COND_H 18 #define APR_THREAD_COND_H 19 20 /** 21 * @file apr_thread_cond.h 22 * @brief APR Condition Variable Routines 23 */ 24 25 #include "apr.h" 26 #include "apr_pools.h" 27 #include "apr_errno.h" 28 #include "apr_time.h" 29 #include "apr_thread_mutex.h" 30 31 #ifdef __cplusplus 32 extern "C" { 33 #endif /* __cplusplus */ 34 35 #if APR_HAS_THREADS || defined(DOXYGEN) 36 37 /** 38 * @defgroup apr_thread_cond Condition Variable Routines 39 * @ingroup APR 40 * @{ 41 */ 42 43 /** Opaque structure for thread condition variables */ 44 typedef struct apr_thread_cond_t apr_thread_cond_t; 45 46 /** 47 * Note: destroying a condition variable (or likewise, destroying or 48 * clearing the pool from which a condition variable was allocated) if 49 * any threads are blocked waiting on it gives undefined results. 50 */ 51 52 /** 53 * Create and initialize a condition variable that can be used to signal 54 * and schedule threads in a single process. 55 * @param cond the memory address where the newly created condition variable 56 * will be stored. 57 * @param pool the pool from which to allocate the condition. 58 */ 59 APR_DECLARE(apr_status_t) apr_thread_cond_create(apr_thread_cond_t **cond, 60 apr_pool_t *pool); 61 62 /** 63 * Put the active calling thread to sleep until signaled to wake up. Each 64 * condition variable must be associated with a mutex, and that mutex must 65 * be locked before calling this function, or the behavior will be 66 * undefined. As the calling thread is put to sleep, the given mutex 67 * will be simultaneously released; and as this thread wakes up the lock 68 * is again simultaneously acquired. 69 * @param cond the condition variable on which to block. 70 * @param mutex the mutex that must be locked upon entering this function, 71 * is released while the thread is asleep, and is again acquired before 72 * returning from this function. 73 * @remark Spurious wakeups may occur. Before and after every call to wait on 74 * a condition variable, the caller should test whether the condition is already 75 * met. 76 */ 77 APR_DECLARE(apr_status_t) apr_thread_cond_wait(apr_thread_cond_t *cond, 78 apr_thread_mutex_t *mutex); 79 80 /** 81 * Put the active calling thread to sleep until signaled to wake up or 82 * the timeout is reached. Each condition variable must be associated 83 * with a mutex, and that mutex must be locked before calling this 84 * function, or the behavior will be undefined. As the calling thread 85 * is put to sleep, the given mutex will be simultaneously released; 86 * and as this thread wakes up the lock is again simultaneously acquired. 87 * @param cond the condition variable on which to block. 88 * @param mutex the mutex that must be locked upon entering this function, 89 * is released while the thread is asleep, and is again acquired before 90 * returning from this function. 91 * @param timeout The amount of time in microseconds to wait. This is 92 * a maximum, not a minimum. If the condition is signaled, we 93 * will wake up before this time, otherwise the error APR_TIMEUP 94 * is returned. 95 */ 96 APR_DECLARE(apr_status_t) apr_thread_cond_timedwait(apr_thread_cond_t *cond, 97 apr_thread_mutex_t *mutex, 98 apr_interval_time_t timeout); 99 100 /** 101 * Signals a single thread, if one exists, that is blocking on the given 102 * condition variable. That thread is then scheduled to wake up and acquire 103 * the associated mutex. Although it is not required, if predictable scheduling 104 * is desired, that mutex must be locked while calling this function. 105 * @param cond the condition variable on which to produce the signal. 106 * @remark If no threads are waiting on the condition variable, nothing happens. 107 */ 108 APR_DECLARE(apr_status_t) apr_thread_cond_signal(apr_thread_cond_t *cond); 109 110 /** 111 * Signals all threads blocking on the given condition variable. 112 * Each thread that was signaled is then scheduled to wake up and acquire 113 * the associated mutex. This will happen in a serialized manner. 114 * @param cond the condition variable on which to produce the broadcast. 115 * @remark If no threads are waiting on the condition variable, nothing happens. 116 */ 117 APR_DECLARE(apr_status_t) apr_thread_cond_broadcast(apr_thread_cond_t *cond); 118 119 /** 120 * Destroy the condition variable and free the associated memory. 121 * @param cond the condition variable to destroy. 122 */ 123 APR_DECLARE(apr_status_t) apr_thread_cond_destroy(apr_thread_cond_t *cond); 124 125 /** 126 * Get the pool used by this thread_cond. 127 * @return apr_pool_t the pool 128 */ 129 APR_POOL_DECLARE_ACCESSOR(thread_cond); 130 131 #endif /* APR_HAS_THREADS */ 132 133 /** @} */ 134 135 #ifdef __cplusplus 136 } 137 #endif 138 139 #endif /* ! APR_THREAD_COND_H */ 140