Miguel Ruiz / SDL_lib2

SDL Library

Dependents:   H261_decoder

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?

UserRevisionLine numberNew 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: */