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