KallistiOS  ##version##
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups
cond.h
Go to the documentation of this file.
1 /* KallistiOS ##version##
2 
3  include/kos/cond.h
4  Copyright (C)2001,2003 Dan Potter
5 
6 */
7 
8 /** \file kos/cond.h
9  \brief Condition variables.
10 
11  This file contains the definition of a Condition Variable. Condition
12  Variables (or condvars for short) are used with a mutex to act as a lock and
13  checkpoint pair for threads.
14 
15  Basically, things work as follows (for the thread doing work):
16  \li The associated mutex is locked.
17  \li A predicate is checked to see if its safe to do something.
18  \li If it is not safe, you call cond_wait(), which releases the mutex.
19  \li When cond_wait() returns, the mutex is reaquired, and work can go on.
20  \li Update any predicates so that we konw that the work is done, and unlock
21  the mutex.
22 
23  Meanwhile, the thread updating the condition works as follows:
24  \li Lock the mutex associated with the condvar.
25  \li Produce work to be done.
26  \li Call cond_signal() (with the associated mutex still locked), so that any
27  threads waiting on the condvar will know they can continue on when the
28  mutex is released, also update any predicates that say whether work can
29  be done.
30  \li Unlock the mutex so that worker threads can acquire the mutex and do
31  whatever work needs to be done.
32 
33  Condition variables can be quite useful when used properly, and provide a
34  fairly easy way to wait for work to be ready to be done.
35 
36  Condition variables should never be used with mutexes that are of the type
37  MUTEX_TYPE_RECURSIVE. The lock will only be released once by the wait
38  function, and thus you will end up deadlocking if you use a recursive mutex
39  that has been locked more than once.
40 
41  \author Dan Potter
42 */
43 
44 #ifndef __KOS_COND_H
45 #define __KOS_COND_H
46 
47 #include <sys/cdefs.h>
48 __BEGIN_DECLS
49 
50 #include <arch/types.h>
51 #include <kos/thread.h>
52 #include <kos/mutex.h>
53 
54 /** \brief Condition variable.
55 
56  There are no public members of this structure for you to actually do
57  anything with in your code, so don't try.
58 
59  \headerfile kos/cond.h
60 */
61 typedef struct condvar {
63  int dynamic;
64 } condvar_t;
65 
66 /** \brief Initializer for a transient condvar. */
67 #define COND_INITIALIZER { 1, 0 }
68 
69 /** \brief Allocate a new condition variable.
70 
71  This function allocates and initializes a new condition variable for use.
72 
73  This function is formally deprecated and should not be used in new code.
74  Instead you should use either the static initializer or the cond_init()
75  function.
76 
77  \return The created condvar on success. NULL is returned on
78  failure and errno is set as appropriate.
79 
80  \par Error Conditions:
81  \em ENOMEM - out of memory
82 */
83 condvar_t *cond_create() __attribute__((deprecated));
84 
85 /** \brief Initialize a condition variable.
86 
87  This function initializes a new condition variable for use.
88 
89  \param cv The condition variable to initialize
90  \retval 0 On success
91  \retval -1 On error, sets errno as appropriate
92 */
93 int cond_init(condvar_t *cv);
94 
95 /** \brief Free a condition variable.
96 
97  This function frees a condition variable, releasing all memory associated
98  with it (but not with the mutex that is associated with it). This will also
99  wake all threads waiting on the condition.
100 
101  \retval 0 On success (no error conditions currently defined)
102 */
103 int cond_destroy(condvar_t *cv);
104 
105 /** \brief Wait on a condition variable.
106 
107  This function will wait on the condition variable, unlocking the mutex and
108  putting the calling thread to sleep as one atomic operation. The wait in
109  this function has no timeout, and will sleep forever if the condition is not
110  signalled.
111 
112  The mutex will be locked and owned by the calling thread on return,
113  regardless of whether it is a successful or error return.
114 
115  \param cv The condition to wait on
116  \param m The associated mutex
117  \retval 0 On success
118  \retval -1 On error, sets errno as appropriate
119 
120  \par Error Conditions:
121  \em EPERM - called inside an interrupt \n
122  \em EINVAL - the condvar was not initialized \n
123  \em EINVAL - the mutex is not initialized or not locked \n
124  \em ENOTRECOVERABLE - the condvar was destroyed while waiting
125 */
126 int cond_wait(condvar_t *cv, mutex_t * m);
127 
128 /** \brief Wait on a condition variable with a timeout.
129 
130  This function will wait on the condition variable, unlocking the mutex and
131  putting the calling thread to sleep as one atomic operation. If the timeout
132  elapses before the condition is signalled, this function will return error.
133  If a timeout of 0 is given, the call is equivalent to cond_wait() (there is
134  no timeout).
135 
136  The mutex will be locked and owned by the calling thread on return,
137  regardless of whether it is a successful or error return.
138 
139  \param cv The condition to wait on
140  \param m The associated mutex
141  \param timeout The number of milliseconds before timeout
142  \retval 0 On success
143  \retval -1 On error, sets errno as appropriate
144 
145  \par Error Conditions:
146  \em EPERM - called inside an interrupt \n
147  \em ETIMEDOUT - timed out \n
148  \em EINVAL - the condvar was not initialized \n
149  \em EINVAL - the mutex is not initialized or not locked \n
150  \em ENOTRECOVERABLE - the condvar was destroyed while waiting
151 */
152 int cond_wait_timed(condvar_t *cv, mutex_t * m, int timeout);
153 
154 /** \brief Signal a single thread waiting on the condition variable.
155 
156  This function will wake up a single thread that is waiting on the condition.
157  The calling thread should be holding the associated mutex or recursive lock
158  before calling this to guarantee sane behavior.
159 
160  \param cv The condition to signal
161  \retval 0 On success
162  \retval -1 On error, errno will be set as appropriate
163 
164  \par Error Conditions:
165  \em EINVAL - the condvar was not initialized
166 */
167 int cond_signal(condvar_t *cv);
168 
169 /** \brief Signal all threads waiting on the condition variable.
170 
171  This function will wake up all threads that are waiting on the condition.
172  The calling thread should be holding the associated mutex or recursive lock
173  before calling this to guarantee sane behavior.
174 
175  \param cv The condition to signal
176  \retval 0 On success
177  \retval -1 On error, errno will be set as appropriate
178 
179  \par Error Conditions:
180  \em EINVAL - the condvar was not initialized
181 */
182 int cond_broadcast(condvar_t *cv);
183 
184 __END_DECLS
185 
186 #endif /* __KOS_COND_H */
187 
Common integer types.
int dynamic
Definition: cond.h:63
int cond_wait(condvar_t *cv, mutex_t *m)
Wait on a condition variable.
int cond_broadcast(condvar_t *cv)
Signal all threads waiting on the condition variable.
Threading support.
Condition variable.
Definition: cond.h:61
Mutual exclusion lock type.
Definition: mutex.h:70
int initialized
Definition: cond.h:62
condvar_t * cond_create() __attribute__((deprecated))
Allocate a new condition variable.
int cond_wait_timed(condvar_t *cv, mutex_t *m, int timeout)
Wait on a condition variable with a timeout.
Mutual exclusion locks.
int cond_init(condvar_t *cv)
Initialize a condition variable.
int cond_destroy(condvar_t *cv)
Free a condition variable.
int cond_signal(condvar_t *cv)
Signal a single thread waiting on the condition variable.
struct condvar condvar_t
Condition variable.