cscg22-gearboy

CSCG 2022 Challenge 'Gearboy'
git clone https://git.sinitax.com/sinitax/cscg22-gearboy
Log | Files | Refs | sfeed.txt

SDL_mutex.h (6665B)


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