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
32extern "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 */
44typedef 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 */
59APR_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 */
77APR_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 */
96APR_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 */
108APR_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 */
117APR_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 */
123APR_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 */
129APR_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