include/SDL_mutex.h
branchSDL-1.2
changeset 4217 4c4113c2162c
parent 4159 a1b03ba2fcd0
child 6137 4720145f848b
     1.1 --- a/include/SDL_mutex.h	Mon Sep 21 09:27:08 2009 +0000
     1.2 +++ b/include/SDL_mutex.h	Mon Sep 21 09:38:10 2009 +0000
     1.3 @@ -23,10 +23,11 @@
     1.4  #ifndef _SDL_mutex_h
     1.5  #define _SDL_mutex_h
     1.6  
     1.7 -/* Functions to provide thread synchronization primitives
     1.8 -
     1.9 -	These are independent of the other SDL routines.
    1.10 -*/
    1.11 +/** @file SDL_mutex.h
    1.12 + *  Functions to provide thread synchronization primitives
    1.13 + *
    1.14 + *  @note These are independent of the other SDL routines.
    1.15 + */
    1.16  
    1.17  #include "SDL_stdinc.h"
    1.18  #include "SDL_error.h"
    1.19 @@ -37,122 +38,135 @@
    1.20  extern "C" {
    1.21  #endif
    1.22  
    1.23 -/* Synchronization functions which can time out return this value
    1.24 -   if they time out.
    1.25 -*/
    1.26 +/** Synchronization functions which can time out return this value
    1.27 + *  if they time out.
    1.28 + */
    1.29  #define SDL_MUTEX_TIMEDOUT	1
    1.30  
    1.31 -/* This is the timeout value which corresponds to never time out */
    1.32 +/** This is the timeout value which corresponds to never time out */
    1.33  #define SDL_MUTEX_MAXWAIT	(~(Uint32)0)
    1.34  
    1.35  
    1.36  /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
    1.37 -/* Mutex functions                                               */
    1.38 +/** @name Mutex functions                                        */ /*@{*/
    1.39  /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
    1.40  
    1.41 -/* The SDL mutex structure, defined in SDL_mutex.c */
    1.42 +/** The SDL mutex structure, defined in SDL_mutex.c */
    1.43  struct SDL_mutex;
    1.44  typedef struct SDL_mutex SDL_mutex;
    1.45  
    1.46 -/* Create a mutex, initialized unlocked */
    1.47 +/** Create a mutex, initialized unlocked */
    1.48  extern DECLSPEC SDL_mutex * SDLCALL SDL_CreateMutex(void);
    1.49  
    1.50 -/* Lock the mutex  (Returns 0, or -1 on error) */
    1.51  #define SDL_LockMutex(m)	SDL_mutexP(m)
    1.52 +/** Lock the mutex
    1.53 + *  @return 0, or -1 on error
    1.54 + */
    1.55  extern DECLSPEC int SDLCALL SDL_mutexP(SDL_mutex *mutex);
    1.56  
    1.57 -/* Unlock the mutex  (Returns 0, or -1 on error)
    1.58 -   It is an error to unlock a mutex that has not been locked by
    1.59 -   the current thread, and doing so results in undefined behavior.
    1.60 +#define SDL_UnlockMutex(m)	SDL_mutexV(m)
    1.61 +/** Unlock the mutex
    1.62 + *  @return 0, or -1 on error
    1.63 + *
    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 -#define SDL_UnlockMutex(m)	SDL_mutexV(m)
    1.68  extern DECLSPEC int SDLCALL SDL_mutexV(SDL_mutex *mutex);
    1.69  
    1.70 -/* Destroy a mutex */
    1.71 +/** Destroy a mutex */
    1.72  extern DECLSPEC void SDLCALL SDL_DestroyMutex(SDL_mutex *mutex);
    1.73  
    1.74 +/*@}*/
    1.75  
    1.76  /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
    1.77 -/* Semaphore functions                                           */
    1.78 +/** @name Semaphore functions                                    */ /*@{*/
    1.79  /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
    1.80  
    1.81 -/* The SDL semaphore structure, defined in SDL_sem.c */
    1.82 +/** The SDL semaphore structure, defined in SDL_sem.c */
    1.83  struct SDL_semaphore;
    1.84  typedef struct SDL_semaphore SDL_sem;
    1.85  
    1.86 -/* Create a semaphore, initialized with value, returns NULL on failure. */
    1.87 +/** Create a semaphore, initialized with value, returns NULL on failure. */
    1.88  extern DECLSPEC SDL_sem * SDLCALL SDL_CreateSemaphore(Uint32 initial_value);
    1.89  
    1.90 -/* Destroy a semaphore */
    1.91 +/** Destroy a semaphore */
    1.92  extern DECLSPEC void SDLCALL SDL_DestroySemaphore(SDL_sem *sem);
    1.93  
    1.94 -/* This function suspends the calling thread until the semaphore pointed 
    1.95 +/**
    1.96 + * This function suspends the calling thread until the semaphore pointed 
    1.97   * to by sem has a positive count. It then atomically decreases the semaphore
    1.98   * count.
    1.99   */
   1.100  extern DECLSPEC int SDLCALL SDL_SemWait(SDL_sem *sem);
   1.101  
   1.102 -/* Non-blocking variant of SDL_SemWait(), returns 0 if the wait succeeds,
   1.103 -   SDL_MUTEX_TIMEDOUT if the wait would block, and -1 on error.
   1.104 -*/
   1.105 +/** Non-blocking variant of SDL_SemWait().
   1.106 + *  @return 0 if the wait succeeds,
   1.107 + *  SDL_MUTEX_TIMEDOUT if the wait would block, and -1 on error.
   1.108 + */
   1.109  extern DECLSPEC int SDLCALL SDL_SemTryWait(SDL_sem *sem);
   1.110  
   1.111 -/* Variant of SDL_SemWait() with a timeout in milliseconds, returns 0 if
   1.112 -   the wait succeeds, SDL_MUTEX_TIMEDOUT if the wait does not succeed in
   1.113 -   the allotted time, and -1 on error.
   1.114 -   On some platforms this function is implemented by looping with a delay
   1.115 -   of 1 ms, and so should be avoided if possible.
   1.116 -*/
   1.117 +/** Variant of SDL_SemWait() with a timeout in milliseconds, returns 0 if
   1.118 + *  the wait succeeds, SDL_MUTEX_TIMEDOUT if the wait does not succeed in
   1.119 + *  the allotted time, and -1 on error.
   1.120 + *
   1.121 + *  On some platforms this function is implemented by looping with a delay
   1.122 + *  of 1 ms, and so should be avoided if possible.
   1.123 + */
   1.124  extern DECLSPEC int SDLCALL SDL_SemWaitTimeout(SDL_sem *sem, Uint32 ms);
   1.125  
   1.126 -/* Atomically increases the semaphore's count (not blocking), returns 0,
   1.127 -   or -1 on error.
   1.128 +/** Atomically increases the semaphore's count (not blocking).
   1.129 + *  @return 0, or -1 on error.
   1.130   */
   1.131  extern DECLSPEC int SDLCALL SDL_SemPost(SDL_sem *sem);
   1.132  
   1.133 -/* Returns the current count of the semaphore */
   1.134 +/** Returns the current count of the semaphore */
   1.135  extern DECLSPEC Uint32 SDLCALL SDL_SemValue(SDL_sem *sem);
   1.136  
   1.137 +/*@}*/
   1.138  
   1.139  /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
   1.140 -/* Condition variable functions                                  */
   1.141 +/** @name Condition_variable_functions                           */ /*@{*/
   1.142  /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
   1.143  
   1.144 -/* The SDL condition variable structure, defined in SDL_cond.c */
   1.145 +/*@{*/
   1.146 +/** The SDL condition variable structure, defined in SDL_cond.c */
   1.147  struct SDL_cond;
   1.148  typedef struct SDL_cond SDL_cond;
   1.149 +/*@}*/
   1.150  
   1.151 -/* Create a condition variable */
   1.152 +/** Create a condition variable */
   1.153  extern DECLSPEC SDL_cond * SDLCALL SDL_CreateCond(void);
   1.154  
   1.155 -/* Destroy a condition variable */
   1.156 +/** Destroy a condition variable */
   1.157  extern DECLSPEC void SDLCALL SDL_DestroyCond(SDL_cond *cond);
   1.158  
   1.159 -/* Restart one of the threads that are waiting on the condition variable,
   1.160 -   returns 0 or -1 on error.
   1.161 +/** Restart one of the threads that are waiting on the condition variable,
   1.162 + *  @return 0 or -1 on error.
   1.163   */
   1.164  extern DECLSPEC int SDLCALL SDL_CondSignal(SDL_cond *cond);
   1.165  
   1.166 -/* Restart all threads that are waiting on the condition variable,
   1.167 -   returns 0 or -1 on error.
   1.168 +/** Restart all threads that are waiting on the condition variable,
   1.169 + *  @return 0 or -1 on error.
   1.170   */
   1.171  extern DECLSPEC int SDLCALL SDL_CondBroadcast(SDL_cond *cond);
   1.172  
   1.173 -/* Wait on the condition variable, unlocking the provided mutex.
   1.174 -   The mutex must be locked before entering this function!
   1.175 -   The mutex is re-locked once the condition variable is signaled.
   1.176 -   Returns 0 when it is signaled, or -1 on error.
   1.177 +/** Wait on the condition variable, unlocking the provided mutex.
   1.178 + *  The mutex must be locked before entering this function!
   1.179 + *  The mutex is re-locked once the condition variable is signaled.
   1.180 + *  @return 0 when it is signaled, or -1 on error.
   1.181   */
   1.182  extern DECLSPEC int SDLCALL SDL_CondWait(SDL_cond *cond, SDL_mutex *mut);
   1.183  
   1.184 -/* Waits for at most 'ms' milliseconds, and returns 0 if the condition
   1.185 -   variable is signaled, SDL_MUTEX_TIMEDOUT if the condition is not
   1.186 -   signaled in the allotted time, and -1 on error.
   1.187 -   On some platforms this function is implemented by looping with a delay
   1.188 -   of 1 ms, and so should be avoided if possible.
   1.189 -*/
   1.190 +/** Waits for at most 'ms' milliseconds, and returns 0 if the condition
   1.191 + *  variable is signaled, SDL_MUTEX_TIMEDOUT if the condition is not
   1.192 + *  signaled in the allotted time, and -1 on error.
   1.193 + *  On some platforms this function is implemented by looping with a delay
   1.194 + *  of 1 ms, and so should be avoided if possible.
   1.195 + */
   1.196  extern DECLSPEC int SDLCALL SDL_CondWaitTimeout(SDL_cond *cond, SDL_mutex *mutex, Uint32 ms);
   1.197  
   1.198 +/*@}*/
   1.199 +
   1.200  /* Ends C function definitions when using C++ */
   1.201  #ifdef __cplusplus
   1.202  }
   1.203 @@ -160,3 +174,4 @@
   1.204  #include "close_code.h"
   1.205  
   1.206  #endif /* _SDL_mutex_h */
   1.207 +