include/SDL_mutex.h
changeset 3407 d3baf5ac4e37
parent 2859 99210400e8b9
child 3697 f7b03b6838cb
     1.1 --- a/include/SDL_mutex.h	Sun Oct 18 23:21:15 2009 +0000
     1.2 +++ b/include/SDL_mutex.h	Mon Oct 19 13:31:58 2009 +0000
     1.3 @@ -24,9 +24,9 @@
     1.4  #define _SDL_mutex_h
     1.5  
     1.6  /**
     1.7 - * \file SDL_mutex.h
     1.8 - *
     1.9 - * Functions to provide thread synchronization primitives
    1.10 + *  \file SDL_mutex.h
    1.11 + *  
    1.12 + *  Functions to provide thread synchronization primitives.
    1.13   */
    1.14  
    1.15  #include "SDL_stdinc.h"
    1.16 @@ -40,123 +40,176 @@
    1.17  /* *INDENT-ON* */
    1.18  #endif
    1.19  
    1.20 -/* Synchronization functions which can time out return this value
    1.21 -   if they time out.
    1.22 -*/
    1.23 +/**
    1.24 + *  Synchronization functions which can time out return this value
    1.25 + *  if they time out.
    1.26 + */
    1.27  #define SDL_MUTEX_TIMEDOUT	1
    1.28  
    1.29 -/* This is the timeout value which corresponds to never time out */
    1.30 +/**
    1.31 + *  This is the timeout value which corresponds to never time out.
    1.32 + */
    1.33  #define SDL_MUTEX_MAXWAIT	(~(Uint32)0)
    1.34  
    1.35  
    1.36 -/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
    1.37 -/* Mutex functions                                               */
    1.38 -/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
    1.39 +/**
    1.40 + *  \name Mutex functions
    1.41 + */
    1.42 +/*@{*/
    1.43  
    1.44  /* The SDL mutex structure, defined in SDL_mutex.c */
    1.45  struct SDL_mutex;
    1.46  typedef struct SDL_mutex SDL_mutex;
    1.47  
    1.48 -/* Create a mutex, initialized unlocked */
    1.49 +/**
    1.50 + *  Create a mutex, initialized unlocked.
    1.51 + */
    1.52  extern DECLSPEC SDL_mutex *SDLCALL SDL_CreateMutex(void);
    1.53  
    1.54 -/* Lock the mutex  (Returns 0, or -1 on error) */
    1.55 +/**
    1.56 + *  Lock the mutex.
    1.57 + *  
    1.58 + *  \return 0, or -1 on error.
    1.59 + */
    1.60  #define SDL_LockMutex(m)	SDL_mutexP(m)
    1.61  extern DECLSPEC int SDLCALL SDL_mutexP(SDL_mutex * mutex);
    1.62  
    1.63 -/* Unlock the mutex  (Returns 0, or -1 on error)
    1.64 -   It is an error to unlock a mutex that has not been locked by
    1.65 -   the current thread, and doing so results in undefined behavior.
    1.66 +/**
    1.67 + *  Unlock the mutex.
    1.68 + *  
    1.69 + *  \return 0, or -1 on error.
    1.70 + *  
    1.71 + *  \warning It is an error to unlock a mutex that has not been locked by
    1.72 + *           the current thread, and doing so results in undefined behavior.
    1.73   */
    1.74  #define SDL_UnlockMutex(m)	SDL_mutexV(m)
    1.75  extern DECLSPEC int SDLCALL SDL_mutexV(SDL_mutex * mutex);
    1.76  
    1.77 -/* Destroy a mutex */
    1.78 +/** 
    1.79 + *  Destroy a mutex.
    1.80 + */
    1.81  extern DECLSPEC void SDLCALL SDL_DestroyMutex(SDL_mutex * mutex);
    1.82  
    1.83 +/*@}*//*Mutex functions*/
    1.84  
    1.85 -/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
    1.86 -/* Semaphore functions                                           */
    1.87 -/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
    1.88 +
    1.89 +/**
    1.90 + *  \name Semaphore functions
    1.91 + */
    1.92 +/*@{*/
    1.93  
    1.94  /* The SDL semaphore structure, defined in SDL_sem.c */
    1.95  struct SDL_semaphore;
    1.96  typedef struct SDL_semaphore SDL_sem;
    1.97  
    1.98 -/* Create a semaphore, initialized with value, returns NULL on failure. */
    1.99 +/**
   1.100 + *  Create a semaphore, initialized with value, returns NULL on failure.
   1.101 + */
   1.102  extern DECLSPEC SDL_sem *SDLCALL SDL_CreateSemaphore(Uint32 initial_value);
   1.103  
   1.104 -/* Destroy a semaphore */
   1.105 +/**
   1.106 + *  Destroy a semaphore.
   1.107 + */
   1.108  extern DECLSPEC void SDLCALL SDL_DestroySemaphore(SDL_sem * sem);
   1.109  
   1.110 -/* This function suspends the calling thread until the semaphore pointed 
   1.111 - * to by sem has a positive count. It then atomically decreases the semaphore
   1.112 - * count.
   1.113 +/**
   1.114 + *  This function suspends the calling thread until the semaphore pointed 
   1.115 + *  to by \c sem has a positive count. It then atomically decreases the 
   1.116 + *  semaphore count.
   1.117   */
   1.118  extern DECLSPEC int SDLCALL SDL_SemWait(SDL_sem * sem);
   1.119  
   1.120 -/* Non-blocking variant of SDL_SemWait(), returns 0 if the wait succeeds,
   1.121 -   SDL_MUTEX_TIMEDOUT if the wait would block, and -1 on error.
   1.122 -*/
   1.123 +/**
   1.124 + *  Non-blocking variant of SDL_SemWait().
   1.125 + *  
   1.126 + *  \return 0 if the wait succeeds, ::SDL_MUTEX_TIMEDOUT if the wait would 
   1.127 + *          block, and -1 on error.
   1.128 + */
   1.129  extern DECLSPEC int SDLCALL SDL_SemTryWait(SDL_sem * sem);
   1.130  
   1.131 -/* Variant of SDL_SemWait() with a timeout in milliseconds, returns 0 if
   1.132 -   the wait succeeds, SDL_MUTEX_TIMEDOUT if the wait does not succeed in
   1.133 -   the allotted time, and -1 on error.
   1.134 -   On some platforms this function is implemented by looping with a delay
   1.135 -   of 1 ms, and so should be avoided if possible.
   1.136 -*/
   1.137 +/**
   1.138 + *  Variant of SDL_SemWait() with a timeout in milliseconds.
   1.139 + *  
   1.140 + *  \return 0 if the wait succeeds, ::SDL_MUTEX_TIMEDOUT if the wait does not 
   1.141 + *          succeed in the allotted time, and -1 on error.
   1.142 + *  
   1.143 + *  \warning On some platforms this function is implemented by looping with a 
   1.144 + *           delay of 1 ms, and so should be avoided if possible.
   1.145 + */
   1.146  extern DECLSPEC int SDLCALL SDL_SemWaitTimeout(SDL_sem * sem, Uint32 ms);
   1.147  
   1.148 -/* Atomically increases the semaphore's count (not blocking), returns 0,
   1.149 -   or -1 on error.
   1.150 +/**
   1.151 + *  Atomically increases the semaphore's count (not blocking).
   1.152 + *  
   1.153 + *  \return 0, or -1 on error.
   1.154   */
   1.155  extern DECLSPEC int SDLCALL SDL_SemPost(SDL_sem * sem);
   1.156  
   1.157 -/* Returns the current count of the semaphore */
   1.158 +/**
   1.159 + *  Returns the current count of the semaphore.
   1.160 + */
   1.161  extern DECLSPEC Uint32 SDLCALL SDL_SemValue(SDL_sem * sem);
   1.162  
   1.163 +/*@}*//*Semaphore functions*/
   1.164  
   1.165 -/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
   1.166 -/* Condition variable functions                                  */
   1.167 -/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
   1.168 +
   1.169 +/**
   1.170 + *  \name Condition variable functions
   1.171 + */
   1.172 +/*@{*/
   1.173  
   1.174  /* The SDL condition variable structure, defined in SDL_cond.c */
   1.175  struct SDL_cond;
   1.176  typedef struct SDL_cond SDL_cond;
   1.177  
   1.178 -/* Create a condition variable */
   1.179 +/**
   1.180 + *  Create a condition variable.
   1.181 + */
   1.182  extern DECLSPEC SDL_cond *SDLCALL SDL_CreateCond(void);
   1.183  
   1.184 -/* Destroy a condition variable */
   1.185 +/**
   1.186 + *  Destroy a condition variable.
   1.187 + */
   1.188  extern DECLSPEC void SDLCALL SDL_DestroyCond(SDL_cond * cond);
   1.189  
   1.190 -/* Restart one of the threads that are waiting on the condition variable,
   1.191 -   returns 0 or -1 on error.
   1.192 +/**
   1.193 + *  Restart one of the threads that are waiting on the condition variable.
   1.194 + *  
   1.195 + *  \return 0 or -1 on error.
   1.196   */
   1.197  extern DECLSPEC int SDLCALL SDL_CondSignal(SDL_cond * cond);
   1.198  
   1.199 -/* Restart all threads that are waiting on the condition variable,
   1.200 -   returns 0 or -1 on error.
   1.201 +/**
   1.202 + *  Restart all threads that are waiting on the condition variable.
   1.203 + *  \return 0 or -1 on error.
   1.204   */
   1.205  extern DECLSPEC int SDLCALL SDL_CondBroadcast(SDL_cond * cond);
   1.206  
   1.207 -/* Wait on the condition variable, unlocking the provided mutex.
   1.208 -   The mutex must be locked before entering this function!
   1.209 -   The mutex is re-locked once the condition variable is signaled.
   1.210 -   Returns 0 when it is signaled, or -1 on error.
   1.211 +/**
   1.212 + *  Wait on the condition variable, unlocking the provided mutex.
   1.213 + *  
   1.214 + *  \warning The mutex must be locked before entering this function!
   1.215 + *  
   1.216 + *  The mutex is re-locked once the condition variable is signaled.
   1.217 + *  
   1.218 + *  \return 0 when it is signaled, or -1 on error.
   1.219   */
   1.220  extern DECLSPEC int SDLCALL SDL_CondWait(SDL_cond * cond, SDL_mutex * mut);
   1.221  
   1.222 -/* Waits for at most 'ms' milliseconds, and returns 0 if the condition
   1.223 -   variable is signaled, SDL_MUTEX_TIMEDOUT if the condition is not
   1.224 -   signaled in the allotted time, and -1 on error.
   1.225 -   On some platforms this function is implemented by looping with a delay
   1.226 -   of 1 ms, and so should be avoided if possible.
   1.227 -*/
   1.228 +/**
   1.229 + *  Waits for at most \c ms milliseconds, and returns 0 if the condition
   1.230 + *  variable is signaled, ::SDL_MUTEX_TIMEDOUT if the condition is not
   1.231 + *  signaled in the allotted time, and -1 on error.
   1.232 + *
   1.233 + *  \warning On some platforms this function is implemented by looping with a 
   1.234 + *           delay of 1 ms, and so should be avoided if possible.
   1.235 + */
   1.236  extern DECLSPEC int SDLCALL SDL_CondWaitTimeout(SDL_cond * cond,
   1.237                                                  SDL_mutex * mutex, Uint32 ms);
   1.238  
   1.239 +/*@}*//*Condition variable functions*/
   1.240 +
   1.241 +
   1.242  /* Ends C function definitions when using C++ */
   1.243  #ifdef __cplusplus
   1.244  /* *INDENT-OFF* */