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