SDL_mutex.h

00001 /*
00002   Simple DirectMedia Layer
00003   Copyright (C) 1997-2014 Sam Lantinga <slouken@libsdl.org>
00004 
00005   This software is provided 'as-is', without any express or implied
00006   warranty.  In no event will the authors be held liable for any damages
00007   arising from the use of this software.
00008 
00009   Permission is granted to anyone to use this software for any purpose,
00010   including commercial applications, and to alter it and redistribute it
00011   freely, subject to the following restrictions:
00012 
00013   1. The origin of this software must not be misrepresented; you must not
00014      claim that you wrote the original software. If you use this software
00015      in a product, an acknowledgment in the product documentation would be
00016      appreciated but is not required.
00017   2. Altered source versions must be plainly marked as such, and must not be
00018      misrepresented as being the original software.
00019   3. This notice may not be removed or altered from any source distribution.
00020 */
00021 
00022 #ifndef _SDL_mutex_h
00023 #define _SDL_mutex_h
00024 
00025 /**
00026  *  \file SDL_mutex.h
00027  *
00028  *  Functions to provide thread synchronization primitives.
00029  */
00030 
00031 #include "SDL_stdinc.h"
00032 #include "SDL_error.h"
00033 
00034 #include "begin_code.h"
00035 /* Set up for C function definitions, even when using C++ */
00036 #ifdef __cplusplus
00037 extern "C" {
00038 #endif
00039 
00040 /**
00041  *  Synchronization functions which can time out return this value
00042  *  if they time out.
00043  */
00044 #define SDL_MUTEX_TIMEDOUT  1
00045 
00046 /**
00047  *  This is the timeout value which corresponds to never time out.
00048  */
00049 #define SDL_MUTEX_MAXWAIT   (~(Uint32)0)
00050 
00051 
00052 /**
00053  *  \name Mutex functions
00054  */
00055 /* @{ */
00056 
00057 /* The SDL mutex structure, defined in SDL_sysmutex.c */
00058 struct SDL_mutex;
00059 typedef struct SDL_mutex SDL_mutex;
00060 
00061 /**
00062  *  Create a mutex, initialized unlocked.
00063  */
00064 extern DECLSPEC SDL_mutex *SDLCALL SDL_CreateMutex(void);
00065 
00066 /**
00067  *  Lock the mutex.
00068  *
00069  *  \return 0, or -1 on error.
00070  */
00071 #define SDL_mutexP(m)   SDL_LockMutex(m)
00072 extern DECLSPEC int SDLCALL SDL_LockMutex(SDL_mutex * mutex);
00073 
00074 /**
00075  *  Try to lock the mutex
00076  *
00077  *  \return 0, SDL_MUTEX_TIMEDOUT, or -1 on error
00078  */
00079 extern DECLSPEC int SDLCALL SDL_TryLockMutex(SDL_mutex * mutex);
00080 
00081 /**
00082  *  Unlock the mutex.
00083  *
00084  *  \return 0, or -1 on error.
00085  *
00086  *  \warning It is an error to unlock a mutex that has not been locked by
00087  *           the current thread, and doing so results in undefined behavior.
00088  */
00089 #define SDL_mutexV(m)   SDL_UnlockMutex(m)
00090 extern DECLSPEC int SDLCALL SDL_UnlockMutex(SDL_mutex * mutex);
00091 
00092 /**
00093  *  Destroy a mutex.
00094  */
00095 extern DECLSPEC void SDLCALL SDL_DestroyMutex(SDL_mutex * mutex);
00096 
00097 /* @} *//* Mutex functions */
00098 
00099 
00100 /**
00101  *  \name Semaphore functions
00102  */
00103 /* @{ */
00104 
00105 /* The SDL semaphore structure, defined in SDL_syssem.c */
00106 struct SDL_semaphore;
00107 typedef struct SDL_semaphore SDL_sem;
00108 
00109 /**
00110  *  Create a semaphore, initialized with value, returns NULL on failure.
00111  */
00112 extern DECLSPEC SDL_sem *SDLCALL SDL_CreateSemaphore(Uint32 initial_value);
00113 
00114 /**
00115  *  Destroy a semaphore.
00116  */
00117 extern DECLSPEC void SDLCALL SDL_DestroySemaphore(SDL_sem * sem);
00118 
00119 /**
00120  *  This function suspends the calling thread until the semaphore pointed
00121  *  to by \c sem has a positive count. It then atomically decreases the
00122  *  semaphore count.
00123  */
00124 extern DECLSPEC int SDLCALL SDL_SemWait(SDL_sem * sem);
00125 
00126 /**
00127  *  Non-blocking variant of SDL_SemWait().
00128  *
00129  *  \return 0 if the wait succeeds, ::SDL_MUTEX_TIMEDOUT if the wait would
00130  *          block, and -1 on error.
00131  */
00132 extern DECLSPEC int SDLCALL SDL_SemTryWait(SDL_sem * sem);
00133 
00134 /**
00135  *  Variant of SDL_SemWait() with a timeout in milliseconds.
00136  *
00137  *  \return 0 if the wait succeeds, ::SDL_MUTEX_TIMEDOUT if the wait does not
00138  *          succeed in the allotted time, and -1 on error.
00139  *
00140  *  \warning On some platforms this function is implemented by looping with a
00141  *           delay of 1 ms, and so should be avoided if possible.
00142  */
00143 extern DECLSPEC int SDLCALL SDL_SemWaitTimeout(SDL_sem * sem, Uint32 ms);
00144 
00145 /**
00146  *  Atomically increases the semaphore's count (not blocking).
00147  *
00148  *  \return 0, or -1 on error.
00149  */
00150 extern DECLSPEC int SDLCALL SDL_SemPost(SDL_sem * sem);
00151 
00152 /**
00153  *  Returns the current count of the semaphore.
00154  */
00155 extern DECLSPEC Uint32 SDLCALL SDL_SemValue(SDL_sem * sem);
00156 
00157 /* @} *//* Semaphore functions */
00158 
00159 
00160 /**
00161  *  \name Condition variable functions
00162  */
00163 /* @{ */
00164 
00165 /* The SDL condition variable structure, defined in SDL_syscond.c */
00166 struct SDL_cond;
00167 typedef struct SDL_cond SDL_cond;
00168 
00169 /**
00170  *  Create a condition variable.
00171  *
00172  *  Typical use of condition variables:
00173  *
00174  *  Thread A:
00175  *    SDL_LockMutex(lock);
00176  *    while ( ! condition ) {
00177  *        SDL_CondWait(cond, lock);
00178  *    }
00179  *    SDL_UnlockMutex(lock);
00180  *
00181  *  Thread B:
00182  *    SDL_LockMutex(lock);
00183  *    ...
00184  *    condition = true;
00185  *    ...
00186  *    SDL_CondSignal(cond);
00187  *    SDL_UnlockMutex(lock);
00188  *
00189  *  There is some discussion whether to signal the condition variable
00190  *  with the mutex locked or not.  There is some potential performance
00191  *  benefit to unlocking first on some platforms, but there are some
00192  *  potential race conditions depending on how your code is structured.
00193  *
00194  *  In general it's safer to signal the condition variable while the
00195  *  mutex is locked.
00196  */
00197 extern DECLSPEC SDL_cond *SDLCALL SDL_CreateCond(void);
00198 
00199 /**
00200  *  Destroy a condition variable.
00201  */
00202 extern DECLSPEC void SDLCALL SDL_DestroyCond(SDL_cond * cond);
00203 
00204 /**
00205  *  Restart one of the threads that are waiting on the condition variable.
00206  *
00207  *  \return 0 or -1 on error.
00208  */
00209 extern DECLSPEC int SDLCALL SDL_CondSignal(SDL_cond * cond);
00210 
00211 /**
00212  *  Restart all threads that are waiting on the condition variable.
00213  *
00214  *  \return 0 or -1 on error.
00215  */
00216 extern DECLSPEC int SDLCALL SDL_CondBroadcast(SDL_cond * cond);
00217 
00218 /**
00219  *  Wait on the condition variable, unlocking the provided mutex.
00220  *
00221  *  \warning The mutex must be locked before entering this function!
00222  *
00223  *  The mutex is re-locked once the condition variable is signaled.
00224  *
00225  *  \return 0 when it is signaled, or -1 on error.
00226  */
00227 extern DECLSPEC int SDLCALL SDL_CondWait(SDL_cond * cond, SDL_mutex * mutex);
00228 
00229 /**
00230  *  Waits for at most \c ms milliseconds, and returns 0 if the condition
00231  *  variable is signaled, ::SDL_MUTEX_TIMEDOUT if the condition is not
00232  *  signaled in the allotted time, and -1 on error.
00233  *
00234  *  \warning On some platforms this function is implemented by looping with a
00235  *           delay of 1 ms, and so should be avoided if possible.
00236  */
00237 extern DECLSPEC int SDLCALL SDL_CondWaitTimeout(SDL_cond * cond,
00238                                                 SDL_mutex * mutex, Uint32 ms);
00239 
00240 /* @} *//* Condition variable functions */
00241 
00242 
00243 /* Ends C function definitions when using C++ */
00244 #ifdef __cplusplus
00245 }
00246 #endif
00247 #include "close_code.h"
00248 
00249 #endif /* _SDL_mutex_h */
00250 
00251 /* vi: set ts=4 sw=4 expandtab: */