Miguel Ruiz / SDL_lib

SDL standard library

Dependents:   H261_encoder

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?

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