]>
Commit | Line | Data |
---|---|---|
7407ac7f BB |
1 | /* |
2 | Simple DirectMedia Layer | |
3 | Copyright (C) 1997-2013 Sam Lantinga <slouken@libsdl.org> | |
4 | ||
5 | This software is provided 'as-is', without any express or implied | |
6 | warranty. In no event will the authors be held liable for any damages | |
7 | arising from the use of this software. | |
8 | ||
9 | Permission is granted to anyone to use this software for any purpose, | |
10 | including commercial applications, and to alter it and redistribute it | |
11 | freely, subject to the following restrictions: | |
12 | ||
13 | 1. The origin of this software must not be misrepresented; you must not | |
14 | claim that you wrote the original software. If you use this software | |
15 | in a product, an acknowledgment in the product documentation would be | |
16 | appreciated but is not required. | |
17 | 2. Altered source versions must be plainly marked as such, and must not be | |
18 | misrepresented as being the original software. | |
19 | 3. This notice may not be removed or altered from any source distribution. | |
20 | */ | |
21 | ||
22 | #ifndef _SDL_mutex_h | |
23 | #define _SDL_mutex_h | |
24 | ||
25 | /** | |
26 | * \file SDL_mutex.h | |
27 | * | |
28 | * Functions to provide thread synchronization primitives. | |
29 | */ | |
30 | ||
31 | #include "SDL_stdinc.h" | |
32 | #include "SDL_error.h" | |
33 | ||
34 | #include "begin_code.h" | |
35 | /* Set up for C function definitions, even when using C++ */ | |
36 | #ifdef __cplusplus | |
37 | extern "C" { | |
38 | #endif | |
39 | ||
40 | /** | |
41 | * Synchronization functions which can time out return this value | |
42 | * if they time out. | |
43 | */ | |
44 | #define SDL_MUTEX_TIMEDOUT 1 | |
45 | ||
46 | /** | |
47 | * This is the timeout value which corresponds to never time out. | |
48 | */ | |
49 | #define SDL_MUTEX_MAXWAIT (~(Uint32)0) | |
50 | ||
51 | ||
52 | /** | |
53 | * \name Mutex functions | |
54 | */ | |
55 | /*@{*/ | |
56 | ||
57 | /* The SDL mutex structure, defined in SDL_mutex.c */ | |
58 | struct SDL_mutex; | |
59 | typedef struct SDL_mutex SDL_mutex; | |
60 | ||
61 | /** | |
62 | * Create a mutex, initialized unlocked. | |
63 | */ | |
64 | extern DECLSPEC SDL_mutex *SDLCALL SDL_CreateMutex(void); | |
65 | ||
66 | /** | |
67 | * Lock the mutex. | |
68 | * | |
69 | * \return 0, or -1 on error. | |
70 | */ | |
71 | #define SDL_mutexP(m) SDL_LockMutex(m) | |
72 | extern DECLSPEC int SDLCALL SDL_LockMutex(SDL_mutex * mutex); | |
73 | ||
74 | /** | |
75 | * Try to lock the mutex | |
76 | * | |
77 | * \return 0, SDL_MUTEX_TIMEDOUT, or -1 on error | |
78 | */ | |
79 | extern DECLSPEC int SDLCALL SDL_TryLockMutex(SDL_mutex * mutex); | |
80 | ||
81 | /** | |
82 | * Unlock the mutex. | |
83 | * | |
84 | * \return 0, or -1 on error. | |
85 | * | |
86 | * \warning It is an error to unlock a mutex that has not been locked by | |
87 | * the current thread, and doing so results in undefined behavior. | |
88 | */ | |
89 | #define SDL_mutexV(m) SDL_UnlockMutex(m) | |
90 | extern DECLSPEC int SDLCALL SDL_UnlockMutex(SDL_mutex * mutex); | |
91 | ||
92 | /** | |
93 | * Destroy a mutex. | |
94 | */ | |
95 | extern DECLSPEC void SDLCALL SDL_DestroyMutex(SDL_mutex * mutex); | |
96 | ||
97 | /*@}*//*Mutex functions*/ | |
98 | ||
99 | ||
100 | /** | |
101 | * \name Semaphore functions | |
102 | */ | |
103 | /*@{*/ | |
104 | ||
105 | /* The SDL semaphore structure, defined in SDL_sem.c */ | |
106 | struct SDL_semaphore; | |
107 | typedef struct SDL_semaphore SDL_sem; | |
108 | ||
109 | /** | |
110 | * Create a semaphore, initialized with value, returns NULL on failure. | |
111 | */ | |
112 | extern DECLSPEC SDL_sem *SDLCALL SDL_CreateSemaphore(Uint32 initial_value); | |
113 | ||
114 | /** | |
115 | * Destroy a semaphore. | |
116 | */ | |
117 | extern DECLSPEC void SDLCALL SDL_DestroySemaphore(SDL_sem * sem); | |
118 | ||
119 | /** | |
120 | * This function suspends the calling thread until the semaphore pointed | |
121 | * to by \c sem has a positive count. It then atomically decreases the | |
122 | * semaphore count. | |
123 | */ | |
124 | extern DECLSPEC int SDLCALL SDL_SemWait(SDL_sem * sem); | |
125 | ||
126 | /** | |
127 | * Non-blocking variant of SDL_SemWait(). | |
128 | * | |
129 | * \return 0 if the wait succeeds, ::SDL_MUTEX_TIMEDOUT if the wait would | |
130 | * block, and -1 on error. | |
131 | */ | |
132 | extern DECLSPEC int SDLCALL SDL_SemTryWait(SDL_sem * sem); | |
133 | ||
134 | /** | |
135 | * Variant of SDL_SemWait() with a timeout in milliseconds. | |
136 | * | |
137 | * \return 0 if the wait succeeds, ::SDL_MUTEX_TIMEDOUT if the wait does not | |
138 | * succeed in the allotted time, and -1 on error. | |
139 | * | |
140 | * \warning On some platforms this function is implemented by looping with a | |
141 | * delay of 1 ms, and so should be avoided if possible. | |
142 | */ | |
143 | extern DECLSPEC int SDLCALL SDL_SemWaitTimeout(SDL_sem * sem, Uint32 ms); | |
144 | ||
145 | /** | |
146 | * Atomically increases the semaphore's count (not blocking). | |
147 | * | |
148 | * \return 0, or -1 on error. | |
149 | */ | |
150 | extern DECLSPEC int SDLCALL SDL_SemPost(SDL_sem * sem); | |
151 | ||
152 | /** | |
153 | * Returns the current count of the semaphore. | |
154 | */ | |
155 | extern DECLSPEC Uint32 SDLCALL SDL_SemValue(SDL_sem * sem); | |
156 | ||
157 | /*@}*//*Semaphore functions*/ | |
158 | ||
159 | ||
160 | /** | |
161 | * \name Condition variable functions | |
162 | */ | |
163 | /*@{*/ | |
164 | ||
165 | /* The SDL condition variable structure, defined in SDL_cond.c */ | |
166 | struct SDL_cond; | |
167 | typedef struct SDL_cond SDL_cond; | |
168 | ||
169 | /** | |
170 | * Create a condition variable. | |
171 | * | |
172 | * Typical use of condition variables: | |
173 | * | |
174 | * Thread A: | |
175 | * SDL_LockMutex(lock); | |
176 | * while ( ! condition ) { | |
177 | * SDL_CondWait(cond, lock); | |
178 | * } | |
179 | * SDL_UnlockMutex(lock); | |
180 | * | |
181 | * Thread B: | |
182 | * SDL_LockMutex(lock); | |
183 | * ... | |
184 | * condition = true; | |
185 | * ... | |
186 | * SDL_CondSignal(cond); | |
187 | * SDL_UnlockMutex(lock); | |
188 | * | |
189 | * There is some discussion whether to signal the condition variable | |
190 | * with the mutex locked or not. There is some potential performance | |
191 | * benefit to unlocking first on some platforms, but there are some | |
192 | * potential race conditions depending on how your code is structured. | |
193 | * | |
194 | * In general it's safer to signal the condition variable while the | |
195 | * mutex is locked. | |
196 | */ | |
197 | extern DECLSPEC SDL_cond *SDLCALL SDL_CreateCond(void); | |
198 | ||
199 | /** | |
200 | * Destroy a condition variable. | |
201 | */ | |
202 | extern DECLSPEC void SDLCALL SDL_DestroyCond(SDL_cond * cond); | |
203 | ||
204 | /** | |
205 | * Restart one of the threads that are waiting on the condition variable. | |
206 | * | |
207 | * \return 0 or -1 on error. | |
208 | */ | |
209 | extern DECLSPEC int SDLCALL SDL_CondSignal(SDL_cond * cond); | |
210 | ||
211 | /** | |
212 | * Restart all threads that are waiting on the condition variable. | |
213 | * | |
214 | * \return 0 or -1 on error. | |
215 | */ | |
216 | extern DECLSPEC int SDLCALL SDL_CondBroadcast(SDL_cond * cond); | |
217 | ||
218 | /** | |
219 | * Wait on the condition variable, unlocking the provided mutex. | |
220 | * | |
221 | * \warning The mutex must be locked before entering this function! | |
222 | * | |
223 | * The mutex is re-locked once the condition variable is signaled. | |
224 | * | |
225 | * \return 0 when it is signaled, or -1 on error. | |
226 | */ | |
227 | extern DECLSPEC int SDLCALL SDL_CondWait(SDL_cond * cond, SDL_mutex * mutex); | |
228 | ||
229 | /** | |
230 | * Waits for at most \c ms milliseconds, and returns 0 if the condition | |
231 | * variable is signaled, ::SDL_MUTEX_TIMEDOUT if the condition is not | |
232 | * signaled in the allotted time, and -1 on error. | |
233 | * | |
234 | * \warning On some platforms this function is implemented by looping with a | |
235 | * delay of 1 ms, and so should be avoided if possible. | |
236 | */ | |
237 | extern DECLSPEC int SDLCALL SDL_CondWaitTimeout(SDL_cond * cond, | |
238 | SDL_mutex * mutex, Uint32 ms); | |
239 | ||
240 | /*@}*//*Condition variable functions*/ | |
241 | ||
242 | ||
243 | /* Ends C function definitions when using C++ */ | |
244 | #ifdef __cplusplus | |
245 | } | |
246 | #endif | |
247 | #include "close_code.h" | |
248 | ||
249 | #endif /* _SDL_mutex_h */ | |
250 | ||
251 | /* vi: set ts=4 sw=4 expandtab: */ |