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