Apache Portable Runtime
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
apr_thread_cond.h
Go to the documentation of this file.
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 */
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  */
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  */
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  */
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  */
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  */
118 
119 /**
120  * Destroy the condition variable and free the associated memory.
121  * @param cond the condition variable to destroy.
122  */
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 */