diff options
Diffstat (limited to 'dependencies/SDL/SDL_mutex.h')
| -rw-r--r-- | dependencies/SDL/SDL_mutex.h | 471 |
1 files changed, 0 insertions, 471 deletions
diff --git a/dependencies/SDL/SDL_mutex.h b/dependencies/SDL/SDL_mutex.h deleted file mode 100644 index 173468f..0000000 --- a/dependencies/SDL/SDL_mutex.h +++ /dev/null @@ -1,471 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2022 Sam Lantinga <slouken@libsdl.org> - - This software is provided 'as-is', without any express or implied - warranty. In no event will the authors be held liable for any damages - arising from the use of this software. - - Permission is granted to anyone to use this software for any purpose, - including commercial applications, and to alter it and redistribute it - freely, subject to the following restrictions: - - 1. The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. - 2. Altered source versions must be plainly marked as such, and must not be - misrepresented as being the original software. - 3. This notice may not be removed or altered from any source distribution. -*/ - -#ifndef SDL_mutex_h_ -#define SDL_mutex_h_ - -/** - * \file SDL_mutex.h - * - * Functions to provide thread synchronization primitives. - */ - -#include "SDL_stdinc.h" -#include "SDL_error.h" - -#include "begin_code.h" -/* Set up for C function definitions, even when using C++ */ -#ifdef __cplusplus -extern "C" { -#endif - -/** - * Synchronization functions which can time out return this value - * if they time out. - */ -#define SDL_MUTEX_TIMEDOUT 1 - -/** - * This is the timeout value which corresponds to never time out. - */ -#define SDL_MUTEX_MAXWAIT (~(Uint32)0) - - -/** - * \name Mutex functions - */ -/* @{ */ - -/* The SDL mutex structure, defined in SDL_sysmutex.c */ -struct SDL_mutex; -typedef struct SDL_mutex SDL_mutex; - -/** - * Create a new mutex. - * - * All newly-created mutexes begin in the _unlocked_ state. - * - * Calls to SDL_LockMutex() will not return while the mutex is locked by - * another thread. See SDL_TryLockMutex() to attempt to lock without blocking. - * - * SDL mutexes are reentrant. - * - * \returns the initialized and unlocked mutex or NULL on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_DestroyMutex - * \sa SDL_LockMutex - * \sa SDL_TryLockMutex - * \sa SDL_UnlockMutex - */ -extern DECLSPEC SDL_mutex *SDLCALL SDL_CreateMutex(void); - -/** - * Lock the mutex. - * - * This will block until the mutex is available, which is to say it is in the - * unlocked state and the OS has chosen the caller as the next thread to lock - * it. Of all threads waiting to lock the mutex, only one may do so at a time. - * - * It is legal for the owning thread to lock an already-locked mutex. It must - * unlock it the same number of times before it is actually made available for - * other threads in the system (this is known as a "recursive mutex"). - * - * \param mutex the mutex to lock - * \return 0, or -1 on error. - * - * \since This function is available since SDL 2.0.0. - */ -extern DECLSPEC int SDLCALL SDL_LockMutex(SDL_mutex * mutex); -#define SDL_mutexP(m) SDL_LockMutex(m) - -/** - * Try to lock a mutex without blocking. - * - * This works just like SDL_LockMutex(), but if the mutex is not available, - * this function returns `SDL_MUTEX_TIMEOUT` immediately. - * - * This technique is useful if you need exclusive access to a resource but - * don't want to wait for it, and will return to it to try again later. - * - * \param mutex the mutex to try to lock - * \returns 0, `SDL_MUTEX_TIMEDOUT`, or -1 on error; call SDL_GetError() for - * more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_CreateMutex - * \sa SDL_DestroyMutex - * \sa SDL_LockMutex - * \sa SDL_UnlockMutex - */ -extern DECLSPEC int SDLCALL SDL_TryLockMutex(SDL_mutex * mutex); - -/** - * Unlock the mutex. - * - * It is legal for the owning thread to lock an already-locked mutex. It must - * unlock it the same number of times before it is actually made available for - * other threads in the system (this is known as a "recursive mutex"). - * - * It is an error to unlock a mutex that has not been locked by the current - * thread, and doing so results in undefined behavior. - * - * It is also an error to unlock a mutex that isn't locked at all. - * - * \param mutex the mutex to unlock. - * \returns 0, or -1 on error. - * - * \since This function is available since SDL 2.0.0. - */ -extern DECLSPEC int SDLCALL SDL_UnlockMutex(SDL_mutex * mutex); -#define SDL_mutexV(m) SDL_UnlockMutex(m) - -/** - * Destroy a mutex created with SDL_CreateMutex(). - * - * This function must be called on any mutex that is no longer needed. Failure - * to destroy a mutex will result in a system memory or resource leak. While - * it is safe to destroy a mutex that is _unlocked_, it is not safe to attempt - * to destroy a locked mutex, and may result in undefined behavior depending - * on the platform. - * - * \param mutex the mutex to destroy - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_CreateMutex - * \sa SDL_LockMutex - * \sa SDL_TryLockMutex - * \sa SDL_UnlockMutex - */ -extern DECLSPEC void SDLCALL SDL_DestroyMutex(SDL_mutex * mutex); - -/* @} *//* Mutex functions */ - - -/** - * \name Semaphore functions - */ -/* @{ */ - -/* The SDL semaphore structure, defined in SDL_syssem.c */ -struct SDL_semaphore; -typedef struct SDL_semaphore SDL_sem; - -/** - * Create a semaphore. - * - * This function creates a new semaphore and initializes it with the value - * `initial_value`. Each wait operation on the semaphore will atomically - * decrement the semaphore value and potentially block if the semaphore value - * is 0. Each post operation will atomically increment the semaphore value and - * wake waiting threads and allow them to retry the wait operation. - * - * \param initial_value the starting value of the semaphore - * \returns a new semaphore or NULL on failure; call SDL_GetError() for more - * information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_DestroySemaphore - * \sa SDL_SemPost - * \sa SDL_SemTryWait - * \sa SDL_SemValue - * \sa SDL_SemWait - * \sa SDL_SemWaitTimeout - */ -extern DECLSPEC SDL_sem *SDLCALL SDL_CreateSemaphore(Uint32 initial_value); - -/** - * Destroy a semaphore. - * - * It is not safe to destroy a semaphore if there are threads currently - * waiting on it. - * - * \param sem the semaphore to destroy - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_CreateSemaphore - * \sa SDL_SemPost - * \sa SDL_SemTryWait - * \sa SDL_SemValue - * \sa SDL_SemWait - * \sa SDL_SemWaitTimeout - */ -extern DECLSPEC void SDLCALL SDL_DestroySemaphore(SDL_sem * sem); - -/** - * Wait until a semaphore has a positive value and then decrements it. - * - * This function suspends the calling thread until either the semaphore - * pointed to by `sem` has a positive value or the call is interrupted by a - * signal or error. If the call is successful it will atomically decrement the - * semaphore value. - * - * This function is the equivalent of calling SDL_SemWaitTimeout() with a time - * length of `SDL_MUTEX_MAXWAIT`. - * - * \param sem the semaphore wait on - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_CreateSemaphore - * \sa SDL_DestroySemaphore - * \sa SDL_SemPost - * \sa SDL_SemTryWait - * \sa SDL_SemValue - * \sa SDL_SemWait - * \sa SDL_SemWaitTimeout - */ -extern DECLSPEC int SDLCALL SDL_SemWait(SDL_sem * sem); - -/** - * See if a semaphore has a positive value and decrement it if it does. - * - * This function checks to see if the semaphore pointed to by `sem` has a - * positive value and atomically decrements the semaphore value if it does. If - * the semaphore doesn't have a positive value, the function immediately - * returns SDL_MUTEX_TIMEDOUT. - * - * \param sem the semaphore to wait on - * \returns 0 if the wait succeeds, `SDL_MUTEX_TIMEDOUT` if the wait would - * block, or a negative error code on failure; call SDL_GetError() - * for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_CreateSemaphore - * \sa SDL_DestroySemaphore - * \sa SDL_SemPost - * \sa SDL_SemValue - * \sa SDL_SemWait - * \sa SDL_SemWaitTimeout - */ -extern DECLSPEC int SDLCALL SDL_SemTryWait(SDL_sem * sem); - -/** - * Wait until a semaphore has a positive value and then decrements it. - * - * This function suspends the calling thread until either the semaphore - * pointed to by `sem` has a positive value, the call is interrupted by a - * signal or error, or the specified time has elapsed. If the call is - * successful it will atomically decrement the semaphore value. - * - * \param sem the semaphore to wait on - * \param ms the length of the timeout, in milliseconds - * \returns 0 if the wait succeeds, `SDL_MUTEX_TIMEDOUT` if the wait does not - * succeed in the allotted time, or a negative error code on failure; - * call SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_CreateSemaphore - * \sa SDL_DestroySemaphore - * \sa SDL_SemPost - * \sa SDL_SemTryWait - * \sa SDL_SemValue - * \sa SDL_SemWait - */ -extern DECLSPEC int SDLCALL SDL_SemWaitTimeout(SDL_sem * sem, Uint32 ms); - -/** - * Atomically increment a semaphore's value and wake waiting threads. - * - * \param sem the semaphore to increment - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_CreateSemaphore - * \sa SDL_DestroySemaphore - * \sa SDL_SemTryWait - * \sa SDL_SemValue - * \sa SDL_SemWait - * \sa SDL_SemWaitTimeout - */ -extern DECLSPEC int SDLCALL SDL_SemPost(SDL_sem * sem); - -/** - * Get the current value of a semaphore. - * - * \param sem the semaphore to query - * \returns the current value of the semaphore. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_CreateSemaphore - */ -extern DECLSPEC Uint32 SDLCALL SDL_SemValue(SDL_sem * sem); - -/* @} *//* Semaphore functions */ - - -/** - * \name Condition variable functions - */ -/* @{ */ - -/* The SDL condition variable structure, defined in SDL_syscond.c */ -struct SDL_cond; -typedef struct SDL_cond SDL_cond; - -/** - * Create a condition variable. - * - * \returns a new condition variable or NULL on failure; call SDL_GetError() - * for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_CondBroadcast - * \sa SDL_CondSignal - * \sa SDL_CondWait - * \sa SDL_CondWaitTimeout - * \sa SDL_DestroyCond - */ -extern DECLSPEC SDL_cond *SDLCALL SDL_CreateCond(void); - -/** - * Destroy a condition variable. - * - * \param cond the condition variable to destroy - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_CondBroadcast - * \sa SDL_CondSignal - * \sa SDL_CondWait - * \sa SDL_CondWaitTimeout - * \sa SDL_CreateCond - */ -extern DECLSPEC void SDLCALL SDL_DestroyCond(SDL_cond * cond); - -/** - * Restart one of the threads that are waiting on the condition variable. - * - * \param cond the condition variable to signal - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_CondBroadcast - * \sa SDL_CondWait - * \sa SDL_CondWaitTimeout - * \sa SDL_CreateCond - * \sa SDL_DestroyCond - */ -extern DECLSPEC int SDLCALL SDL_CondSignal(SDL_cond * cond); - -/** - * Restart all threads that are waiting on the condition variable. - * - * \param cond the condition variable to signal - * \returns 0 on success or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_CondSignal - * \sa SDL_CondWait - * \sa SDL_CondWaitTimeout - * \sa SDL_CreateCond - * \sa SDL_DestroyCond - */ -extern DECLSPEC int SDLCALL SDL_CondBroadcast(SDL_cond * cond); - -/** - * Wait until a condition variable is signaled. - * - * This function unlocks the specified `mutex` and waits for another thread to - * call SDL_CondSignal() or SDL_CondBroadcast() on the condition variable - * `cond`. Once the condition variable is signaled, the mutex is re-locked and - * the function returns. - * - * The mutex must be locked before calling this function. - * - * This function is the equivalent of calling SDL_CondWaitTimeout() with a - * time length of `SDL_MUTEX_MAXWAIT`. - * - * \param cond the condition variable to wait on - * \param mutex the mutex used to coordinate thread access - * \returns 0 when it is signaled or a negative error code on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_CondBroadcast - * \sa SDL_CondSignal - * \sa SDL_CondWaitTimeout - * \sa SDL_CreateCond - * \sa SDL_DestroyCond - */ -extern DECLSPEC int SDLCALL SDL_CondWait(SDL_cond * cond, SDL_mutex * mutex); - -/** - * Wait until a condition variable is signaled or a certain time has passed. - * - * This function unlocks the specified `mutex` and waits for another thread to - * call SDL_CondSignal() or SDL_CondBroadcast() on the condition variable - * `cond`, or for the specified time to elapse. Once the condition variable is - * signaled or the time elapsed, the mutex is re-locked and the function - * returns. - * - * The mutex must be locked before calling this function. - * - * \param cond the condition variable to wait on - * \param mutex the mutex used to coordinate thread access - * \param ms the maximum time to wait, in milliseconds, or `SDL_MUTEX_MAXWAIT` - * to wait indefinitely - * \returns 0 if the condition variable is signaled, `SDL_MUTEX_TIMEDOUT` if - * the condition is not signaled in the allotted time, or a negative - * error code on failure; call SDL_GetError() for more information. - * - * \since This function is available since SDL 2.0.0. - * - * \sa SDL_CondBroadcast - * \sa SDL_CondSignal - * \sa SDL_CondWait - * \sa SDL_CreateCond - * \sa SDL_DestroyCond - */ -extern DECLSPEC int SDLCALL SDL_CondWaitTimeout(SDL_cond * cond, - SDL_mutex * mutex, Uint32 ms); - -/* @} *//* Condition variable functions */ - - -/* Ends C function definitions when using C++ */ -#ifdef __cplusplus -} -#endif -#include "close_code.h" - -#endif /* SDL_mutex_h_ */ - -/* vi: set ts=4 sw=4 expandtab: */ |