include/SDL_mutex.h
author Sam Lantinga <slouken@libsdl.org>
Thu, 07 Mar 2013 20:42:55 -0800
changeset 6978 e851407e9294
parent 6977 b73d51026c68
child 7191 75360622e65f
permissions -rw-r--r--
Put the real SDL_AtomicCAS() and SDL_AtomicCASPtr() symbols into the library.
     1 /*
     2   Simple DirectMedia Layer
     3   Copyright (C) 1997-2013 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 /* *INDENT-OFF* */
    38 extern "C" {
    39 /* *INDENT-ON* */
    40 #endif
    41 
    42 /**
    43  *  Synchronization functions which can time out return this value
    44  *  if they time out.
    45  */
    46 #define SDL_MUTEX_TIMEDOUT	1
    47 
    48 /**
    49  *  This is the timeout value which corresponds to never time out.
    50  */
    51 #define SDL_MUTEX_MAXWAIT	(~(Uint32)0)
    52 
    53 
    54 /**
    55  *  \name Mutex functions
    56  */
    57 /*@{*/
    58 
    59 /* The SDL mutex structure, defined in SDL_mutex.c */
    60 struct SDL_mutex;
    61 typedef struct SDL_mutex SDL_mutex;
    62 
    63 /**
    64  *  Create a mutex, initialized unlocked.
    65  */
    66 extern DECLSPEC SDL_mutex *SDLCALL SDL_CreateMutex(void);
    67 
    68 /**
    69  *  Lock the mutex.
    70  *  
    71  *  \return 0, or -1 on error.
    72  */
    73 #define SDL_mutexP(m)	SDL_LockMutex(m)
    74 extern DECLSPEC int SDLCALL SDL_LockMutex(SDL_mutex * mutex);
    75 
    76 /**
    77  *  Try to lock the mutex
    78  *  
    79  *  \return 0, SDL_MUTEX_TIMEDOUT, or -1 on error
    80  */
    81 extern DECLSPEC int SDLCALL SDL_TryLockMutex(SDL_mutex * mutex);
    82 
    83 /**
    84  *  Unlock the mutex.
    85  *  
    86  *  \return 0, or -1 on error.
    87  *  
    88  *  \warning It is an error to unlock a mutex that has not been locked by
    89  *           the current thread, and doing so results in undefined behavior.
    90  */
    91 #define SDL_mutexV(m)	SDL_UnlockMutex(m)
    92 extern DECLSPEC int SDLCALL SDL_UnlockMutex(SDL_mutex * mutex);
    93 
    94 /** 
    95  *  Destroy a mutex.
    96  */
    97 extern DECLSPEC void SDLCALL SDL_DestroyMutex(SDL_mutex * mutex);
    98 
    99 /*@}*//*Mutex functions*/
   100 
   101 
   102 /**
   103  *  \name Semaphore functions
   104  */
   105 /*@{*/
   106 
   107 /* The SDL semaphore structure, defined in SDL_sem.c */
   108 struct SDL_semaphore;
   109 typedef struct SDL_semaphore SDL_sem;
   110 
   111 /**
   112  *  Create a semaphore, initialized with value, returns NULL on failure.
   113  */
   114 extern DECLSPEC SDL_sem *SDLCALL SDL_CreateSemaphore(Uint32 initial_value);
   115 
   116 /**
   117  *  Destroy a semaphore.
   118  */
   119 extern DECLSPEC void SDLCALL SDL_DestroySemaphore(SDL_sem * sem);
   120 
   121 /**
   122  *  This function suspends the calling thread until the semaphore pointed 
   123  *  to by \c sem has a positive count. It then atomically decreases the 
   124  *  semaphore count.
   125  */
   126 extern DECLSPEC int SDLCALL SDL_SemWait(SDL_sem * sem);
   127 
   128 /**
   129  *  Non-blocking variant of SDL_SemWait().
   130  *  
   131  *  \return 0 if the wait succeeds, ::SDL_MUTEX_TIMEDOUT if the wait would 
   132  *          block, and -1 on error.
   133  */
   134 extern DECLSPEC int SDLCALL SDL_SemTryWait(SDL_sem * sem);
   135 
   136 /**
   137  *  Variant of SDL_SemWait() with a timeout in milliseconds.
   138  *  
   139  *  \return 0 if the wait succeeds, ::SDL_MUTEX_TIMEDOUT if the wait does not 
   140  *          succeed in the allotted time, and -1 on error.
   141  *  
   142  *  \warning On some platforms this function is implemented by looping with a 
   143  *           delay of 1 ms, and so should be avoided if possible.
   144  */
   145 extern DECLSPEC int SDLCALL SDL_SemWaitTimeout(SDL_sem * sem, Uint32 ms);
   146 
   147 /**
   148  *  Atomically increases the semaphore's count (not blocking).
   149  *  
   150  *  \return 0, or -1 on error.
   151  */
   152 extern DECLSPEC int SDLCALL SDL_SemPost(SDL_sem * sem);
   153 
   154 /**
   155  *  Returns the current count of the semaphore.
   156  */
   157 extern DECLSPEC Uint32 SDLCALL SDL_SemValue(SDL_sem * sem);
   158 
   159 /*@}*//*Semaphore functions*/
   160 
   161 
   162 /**
   163  *  \name Condition variable functions
   164  */
   165 /*@{*/
   166 
   167 /* The SDL condition variable structure, defined in SDL_cond.c */
   168 struct SDL_cond;
   169 typedef struct SDL_cond SDL_cond;
   170 
   171 /**
   172  *  Create a condition variable.
   173  *
   174  *  Typical use of condition variables:
   175  *
   176  *  Thread A:
   177  *    SDL_LockMutex(lock);
   178  *    while ( ! condition ) {
   179  *        SDL_CondWait(cond, lock);
   180  *    }
   181  *    SDL_UnlockMutex(lock);
   182  *
   183  *  Thread B:
   184  *    SDL_LockMutex(lock);
   185  *    ...
   186  *    condition = true;
   187  *    ...
   188  *    SDL_CondSignal(cond);
   189  *    SDL_UnlockMutex(lock);
   190  *
   191  *  There is some discussion whether to signal the condition variable
   192  *  with the mutex locked or not.  There is some potential performance
   193  *  benefit to unlocking first on some platforms, but there are some
   194  *  potential race conditions depending on how your code is structured.
   195  *
   196  *  In general it's safer to signal the condition variable while the
   197  *  mutex is locked.
   198  */
   199 extern DECLSPEC SDL_cond *SDLCALL SDL_CreateCond(void);
   200 
   201 /**
   202  *  Destroy a condition variable.
   203  */
   204 extern DECLSPEC void SDLCALL SDL_DestroyCond(SDL_cond * cond);
   205 
   206 /**
   207  *  Restart one of the threads that are waiting on the condition variable.
   208  *  
   209  *  \return 0 or -1 on error.
   210  */
   211 extern DECLSPEC int SDLCALL SDL_CondSignal(SDL_cond * cond);
   212 
   213 /**
   214  *  Restart all threads that are waiting on the condition variable.
   215  *
   216  *  \return 0 or -1 on error.
   217  */
   218 extern DECLSPEC int SDLCALL SDL_CondBroadcast(SDL_cond * cond);
   219 
   220 /**
   221  *  Wait on the condition variable, unlocking the provided mutex.
   222  *  
   223  *  \warning The mutex must be locked before entering this function!
   224  *  
   225  *  The mutex is re-locked once the condition variable is signaled.
   226  *  
   227  *  \return 0 when it is signaled, or -1 on error.
   228  */
   229 extern DECLSPEC int SDLCALL SDL_CondWait(SDL_cond * cond, SDL_mutex * mutex);
   230 
   231 /**
   232  *  Waits for at most \c ms milliseconds, and returns 0 if the condition
   233  *  variable is signaled, ::SDL_MUTEX_TIMEDOUT if the condition is not
   234  *  signaled in the allotted time, and -1 on error.
   235  *
   236  *  \warning On some platforms this function is implemented by looping with a 
   237  *           delay of 1 ms, and so should be avoided if possible.
   238  */
   239 extern DECLSPEC int SDLCALL SDL_CondWaitTimeout(SDL_cond * cond,
   240                                                 SDL_mutex * mutex, Uint32 ms);
   241 
   242 /*@}*//*Condition variable functions*/
   243 
   244 
   245 /* Ends C function definitions when using C++ */
   246 #ifdef __cplusplus
   247 /* *INDENT-OFF* */
   248 }
   249 /* *INDENT-ON* */
   250 #endif
   251 #include "close_code.h"
   252 
   253 #endif /* _SDL_mutex_h */
   254 
   255 /* vi: set ts=4 sw=4 expandtab: */