Apache Portable Runtime
Main Page
Related Pages
Modules
Data Structures
Files
File List
Globals
All
Data Structures
Files
Functions
Variables
Typedefs
Enumerations
Enumerator
Macros
Groups
Pages
include
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 */
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 */
Generated on Sun Jul 7 2013 03:35:11 for Apache Portable Runtime by
1.8.1.2