include/SDL_mutex.h
author Ryan C. Gordon <icculus@icculus.org>
Fri, 10 Aug 2018 15:22:02 -0400
changeset 12108 eb2820ee52ee
parent 11811 5d94cb6b24d3
permissions -rw-r--r--
libm: one more static analysis fix.
     1 /*
     2   Simple DirectMedia Layer
     3   Copyright (C) 1997-2018 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
    37 extern "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 */
    58 struct SDL_mutex;
    59 typedef struct SDL_mutex SDL_mutex;
    60 
    61 /**
    62  *  Create a mutex, initialized unlocked.
    63  */
    64 extern 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)
    72 extern 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  */
    79 extern 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)
    90 extern DECLSPEC int SDLCALL SDL_UnlockMutex(SDL_mutex * mutex);
    91 
    92 /**
    93  *  Destroy a mutex.
    94  */
    95 extern 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 */
   106 struct SDL_semaphore;
   107 typedef struct SDL_semaphore SDL_sem;
   108 
   109 /**
   110  *  Create a semaphore, initialized with value, returns NULL on failure.
   111  */
   112 extern DECLSPEC SDL_sem *SDLCALL SDL_CreateSemaphore(Uint32 initial_value);
   113 
   114 /**
   115  *  Destroy a semaphore.
   116  */
   117 extern 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  */
   124 extern 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  */
   132 extern 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  */
   143 extern 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  */
   150 extern DECLSPEC int SDLCALL SDL_SemPost(SDL_sem * sem);
   151 
   152 /**
   153  *  Returns the current count of the semaphore.
   154  */
   155 extern 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 */
   166 struct SDL_cond;
   167 typedef 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  */
   197 extern DECLSPEC SDL_cond *SDLCALL SDL_CreateCond(void);
   198 
   199 /**
   200  *  Destroy a condition variable.
   201  */
   202 extern 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  */
   209 extern 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  */
   216 extern 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  */
   227 extern 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  */
   237 extern 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: */