include/SDL_mutex.h
changeset 1895 c121d94672cb
parent 1358 c71e05b4dc2e
child 2859 99210400e8b9
equal deleted inserted replaced
1894:c69cee13dd76 1895:c121d94672cb
    21 */
    21 */
    22 
    22 
    23 #ifndef _SDL_mutex_h
    23 #ifndef _SDL_mutex_h
    24 #define _SDL_mutex_h
    24 #define _SDL_mutex_h
    25 
    25 
    26 /* Functions to provide thread synchronization primitives
    26 /**
    27 
    27  * \file SDL_mutex.h
    28 	These are independent of the other SDL routines.
    28  *
    29 */
    29  * Functions to provide thread synchronization primitives
       
    30  */
    30 
    31 
    31 #include "SDL_stdinc.h"
    32 #include "SDL_stdinc.h"
    32 #include "SDL_error.h"
    33 #include "SDL_error.h"
    33 
    34 
    34 #include "begin_code.h"
    35 #include "begin_code.h"
    35 /* Set up for C function definitions, even when using C++ */
    36 /* Set up for C function definitions, even when using C++ */
    36 #ifdef __cplusplus
    37 #ifdef __cplusplus
       
    38 /* *INDENT-OFF* */
    37 extern "C" {
    39 extern "C" {
       
    40 /* *INDENT-ON* */
    38 #endif
    41 #endif
    39 
    42 
    40 /* Synchronization functions which can time out return this value
    43 /* Synchronization functions which can time out return this value
    41    if they time out.
    44    if they time out.
    42 */
    45 */
    53 /* The SDL mutex structure, defined in SDL_mutex.c */
    56 /* The SDL mutex structure, defined in SDL_mutex.c */
    54 struct SDL_mutex;
    57 struct SDL_mutex;
    55 typedef struct SDL_mutex SDL_mutex;
    58 typedef struct SDL_mutex SDL_mutex;
    56 
    59 
    57 /* Create a mutex, initialized unlocked */
    60 /* Create a mutex, initialized unlocked */
    58 extern DECLSPEC SDL_mutex * SDLCALL SDL_CreateMutex(void);
    61 extern DECLSPEC SDL_mutex *SDLCALL SDL_CreateMutex(void);
    59 
    62 
    60 /* Lock the mutex  (Returns 0, or -1 on error) */
    63 /* Lock the mutex  (Returns 0, or -1 on error) */
    61 #define SDL_LockMutex(m)	SDL_mutexP(m)
    64 #define SDL_LockMutex(m)	SDL_mutexP(m)
    62 extern DECLSPEC int SDLCALL SDL_mutexP(SDL_mutex *mutex);
    65 extern DECLSPEC int SDLCALL SDL_mutexP(SDL_mutex * mutex);
    63 
    66 
    64 /* Unlock the mutex  (Returns 0, or -1 on error)
    67 /* Unlock the mutex  (Returns 0, or -1 on error)
    65    It is an error to unlock a mutex that has not been locked by
    68    It is an error to unlock a mutex that has not been locked by
    66    the current thread, and doing so results in undefined behavior.
    69    the current thread, and doing so results in undefined behavior.
    67  */
    70  */
    68 #define SDL_UnlockMutex(m)	SDL_mutexV(m)
    71 #define SDL_UnlockMutex(m)	SDL_mutexV(m)
    69 extern DECLSPEC int SDLCALL SDL_mutexV(SDL_mutex *mutex);
    72 extern DECLSPEC int SDLCALL SDL_mutexV(SDL_mutex * mutex);
    70 
    73 
    71 /* Destroy a mutex */
    74 /* Destroy a mutex */
    72 extern DECLSPEC void SDLCALL SDL_DestroyMutex(SDL_mutex *mutex);
    75 extern DECLSPEC void SDLCALL SDL_DestroyMutex(SDL_mutex * mutex);
    73 
    76 
    74 
    77 
    75 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
    78 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
    76 /* Semaphore functions                                           */
    79 /* Semaphore functions                                           */
    77 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
    80 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
    79 /* The SDL semaphore structure, defined in SDL_sem.c */
    82 /* The SDL semaphore structure, defined in SDL_sem.c */
    80 struct SDL_semaphore;
    83 struct SDL_semaphore;
    81 typedef struct SDL_semaphore SDL_sem;
    84 typedef struct SDL_semaphore SDL_sem;
    82 
    85 
    83 /* Create a semaphore, initialized with value, returns NULL on failure. */
    86 /* Create a semaphore, initialized with value, returns NULL on failure. */
    84 extern DECLSPEC SDL_sem * SDLCALL SDL_CreateSemaphore(Uint32 initial_value);
    87 extern DECLSPEC SDL_sem *SDLCALL SDL_CreateSemaphore(Uint32 initial_value);
    85 
    88 
    86 /* Destroy a semaphore */
    89 /* Destroy a semaphore */
    87 extern DECLSPEC void SDLCALL SDL_DestroySemaphore(SDL_sem *sem);
    90 extern DECLSPEC void SDLCALL SDL_DestroySemaphore(SDL_sem * sem);
    88 
    91 
    89 /* This function suspends the calling thread until the semaphore pointed 
    92 /* This function suspends the calling thread until the semaphore pointed 
    90  * to by sem has a positive count. It then atomically decreases the semaphore
    93  * to by sem has a positive count. It then atomically decreases the semaphore
    91  * count.
    94  * count.
    92  */
    95  */
    93 extern DECLSPEC int SDLCALL SDL_SemWait(SDL_sem *sem);
    96 extern DECLSPEC int SDLCALL SDL_SemWait(SDL_sem * sem);
    94 
    97 
    95 /* Non-blocking variant of SDL_SemWait(), returns 0 if the wait succeeds,
    98 /* Non-blocking variant of SDL_SemWait(), returns 0 if the wait succeeds,
    96    SDL_MUTEX_TIMEDOUT if the wait would block, and -1 on error.
    99    SDL_MUTEX_TIMEDOUT if the wait would block, and -1 on error.
    97 */
   100 */
    98 extern DECLSPEC int SDLCALL SDL_SemTryWait(SDL_sem *sem);
   101 extern DECLSPEC int SDLCALL SDL_SemTryWait(SDL_sem * sem);
    99 
   102 
   100 /* Variant of SDL_SemWait() with a timeout in milliseconds, returns 0 if
   103 /* Variant of SDL_SemWait() with a timeout in milliseconds, returns 0 if
   101    the wait succeeds, SDL_MUTEX_TIMEDOUT if the wait does not succeed in
   104    the wait succeeds, SDL_MUTEX_TIMEDOUT if the wait does not succeed in
   102    the allotted time, and -1 on error.
   105    the allotted time, and -1 on error.
   103    On some platforms this function is implemented by looping with a delay
   106    On some platforms this function is implemented by looping with a delay
   104    of 1 ms, and so should be avoided if possible.
   107    of 1 ms, and so should be avoided if possible.
   105 */
   108 */
   106 extern DECLSPEC int SDLCALL SDL_SemWaitTimeout(SDL_sem *sem, Uint32 ms);
   109 extern DECLSPEC int SDLCALL SDL_SemWaitTimeout(SDL_sem * sem, Uint32 ms);
   107 
   110 
   108 /* Atomically increases the semaphore's count (not blocking), returns 0,
   111 /* Atomically increases the semaphore's count (not blocking), returns 0,
   109    or -1 on error.
   112    or -1 on error.
   110  */
   113  */
   111 extern DECLSPEC int SDLCALL SDL_SemPost(SDL_sem *sem);
   114 extern DECLSPEC int SDLCALL SDL_SemPost(SDL_sem * sem);
   112 
   115 
   113 /* Returns the current count of the semaphore */
   116 /* Returns the current count of the semaphore */
   114 extern DECLSPEC Uint32 SDLCALL SDL_SemValue(SDL_sem *sem);
   117 extern DECLSPEC Uint32 SDLCALL SDL_SemValue(SDL_sem * sem);
   115 
   118 
   116 
   119 
   117 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
   120 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
   118 /* Condition variable functions                                  */
   121 /* Condition variable functions                                  */
   119 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
   122 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
   121 /* The SDL condition variable structure, defined in SDL_cond.c */
   124 /* The SDL condition variable structure, defined in SDL_cond.c */
   122 struct SDL_cond;
   125 struct SDL_cond;
   123 typedef struct SDL_cond SDL_cond;
   126 typedef struct SDL_cond SDL_cond;
   124 
   127 
   125 /* Create a condition variable */
   128 /* Create a condition variable */
   126 extern DECLSPEC SDL_cond * SDLCALL SDL_CreateCond(void);
   129 extern DECLSPEC SDL_cond *SDLCALL SDL_CreateCond(void);
   127 
   130 
   128 /* Destroy a condition variable */
   131 /* Destroy a condition variable */
   129 extern DECLSPEC void SDLCALL SDL_DestroyCond(SDL_cond *cond);
   132 extern DECLSPEC void SDLCALL SDL_DestroyCond(SDL_cond * cond);
   130 
   133 
   131 /* Restart one of the threads that are waiting on the condition variable,
   134 /* Restart one of the threads that are waiting on the condition variable,
   132    returns 0 or -1 on error.
   135    returns 0 or -1 on error.
   133  */
   136  */
   134 extern DECLSPEC int SDLCALL SDL_CondSignal(SDL_cond *cond);
   137 extern DECLSPEC int SDLCALL SDL_CondSignal(SDL_cond * cond);
   135 
   138 
   136 /* Restart all threads that are waiting on the condition variable,
   139 /* Restart all threads that are waiting on the condition variable,
   137    returns 0 or -1 on error.
   140    returns 0 or -1 on error.
   138  */
   141  */
   139 extern DECLSPEC int SDLCALL SDL_CondBroadcast(SDL_cond *cond);
   142 extern DECLSPEC int SDLCALL SDL_CondBroadcast(SDL_cond * cond);
   140 
   143 
   141 /* Wait on the condition variable, unlocking the provided mutex.
   144 /* Wait on the condition variable, unlocking the provided mutex.
   142    The mutex must be locked before entering this function!
   145    The mutex must be locked before entering this function!
   143    The mutex is re-locked once the condition variable is signaled.
   146    The mutex is re-locked once the condition variable is signaled.
   144    Returns 0 when it is signaled, or -1 on error.
   147    Returns 0 when it is signaled, or -1 on error.
   145  */
   148  */
   146 extern DECLSPEC int SDLCALL SDL_CondWait(SDL_cond *cond, SDL_mutex *mut);
   149 extern DECLSPEC int SDLCALL SDL_CondWait(SDL_cond * cond, SDL_mutex * mut);
   147 
   150 
   148 /* Waits for at most 'ms' milliseconds, and returns 0 if the condition
   151 /* Waits for at most 'ms' milliseconds, and returns 0 if the condition
   149    variable is signaled, SDL_MUTEX_TIMEDOUT if the condition is not
   152    variable is signaled, SDL_MUTEX_TIMEDOUT if the condition is not
   150    signaled in the allotted time, and -1 on error.
   153    signaled in the allotted time, and -1 on error.
   151    On some platforms this function is implemented by looping with a delay
   154    On some platforms this function is implemented by looping with a delay
   152    of 1 ms, and so should be avoided if possible.
   155    of 1 ms, and so should be avoided if possible.
   153 */
   156 */
   154 extern DECLSPEC int SDLCALL SDL_CondWaitTimeout(SDL_cond *cond, SDL_mutex *mutex, Uint32 ms);
   157 extern DECLSPEC int SDLCALL SDL_CondWaitTimeout(SDL_cond * cond,
       
   158                                                 SDL_mutex * mutex, Uint32 ms);
   155 
   159 
   156 /* Ends C function definitions when using C++ */
   160 /* Ends C function definitions when using C++ */
   157 #ifdef __cplusplus
   161 #ifdef __cplusplus
       
   162 /* *INDENT-OFF* */
   158 }
   163 }
       
   164 /* *INDENT-ON* */
   159 #endif
   165 #endif
   160 #include "close_code.h"
   166 #include "close_code.h"
   161 
   167 
   162 #endif /* _SDL_mutex_h */
   168 #endif /* _SDL_mutex_h */
       
   169 
       
   170 /* vi: set ts=4 sw=4 expandtab: */