Mercurial > sdl-ios-xcode

comparison include/SDL_mutex.h @ 3407:d3baf5ac4e37

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Partial fix for bug #859 Header file update from Ken for improved doxygen output
author Sam Lantinga <slouken@libsdl.org>
date Mon, 19 Oct 2009 13:31:58 +0000
parents 99210400e8b9
children f7b03b6838cb
comparison
equal deleted inserted replaced
3406:8ae607392409 3407:d3baf5ac4e37
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 /** 26 /**
27 * \file SDL_mutex.h 27 * \file SDL_mutex.h
28 * 28 *
29 * Functions to provide thread synchronization primitives 29 * Functions to provide thread synchronization primitives.
30 */ 30 */
31 31
32 #include "SDL_stdinc.h" 32 #include "SDL_stdinc.h"
33 #include "SDL_error.h" 33 #include "SDL_error.h"
34 34
38 /* *INDENT-OFF* */ 38 /* *INDENT-OFF* */
39 extern "C" { 39 extern "C" {
40 /* *INDENT-ON* */ 40 /* *INDENT-ON* */
41 #endif 41 #endif
42 42
43 /* Synchronization functions which can time out return this value 43 /**
44 if they time out. 44 * Synchronization functions which can time out return this value
45 */ 45 * if they time out.
46 */
46 #define SDL_MUTEX_TIMEDOUT 1 47 #define SDL_MUTEX_TIMEDOUT 1
47 48
48 /* This is the timeout value which corresponds to never time out */ 49 /**
50 * This is the timeout value which corresponds to never time out.
51 */
49 #define SDL_MUTEX_MAXWAIT (~(Uint32)0) 52 #define SDL_MUTEX_MAXWAIT (~(Uint32)0)
50 53
51 54
52 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ 55 /**
53 /* Mutex functions */ 56 * \name Mutex functions
54 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ 57 */
58 /*@{*/
55 59
56 /* The SDL mutex structure, defined in SDL_mutex.c */ 60 /* The SDL mutex structure, defined in SDL_mutex.c */
57 struct SDL_mutex; 61 struct SDL_mutex;
58 typedef struct SDL_mutex SDL_mutex; 62 typedef struct SDL_mutex SDL_mutex;
59 63
60 /* Create a mutex, initialized unlocked */ 64 /**
65 * Create a mutex, initialized unlocked.
66 */
61 extern DECLSPEC SDL_mutex *SDLCALL SDL_CreateMutex(void); 67 extern DECLSPEC SDL_mutex *SDLCALL SDL_CreateMutex(void);
62 68
63 /* Lock the mutex (Returns 0, or -1 on error) */ 69 /**
70 * Lock the mutex.
71 *
72 * \return 0, or -1 on error.
73 */
64 #define SDL_LockMutex(m) SDL_mutexP(m) 74 #define SDL_LockMutex(m) SDL_mutexP(m)
65 extern DECLSPEC int SDLCALL SDL_mutexP(SDL_mutex * mutex); 75 extern DECLSPEC int SDLCALL SDL_mutexP(SDL_mutex * mutex);
66 76
67 /* Unlock the mutex (Returns 0, or -1 on error) 77 /**
68 It is an error to unlock a mutex that has not been locked by 78 * Unlock the mutex.
69 the current thread, and doing so results in undefined behavior. 79 *
80 * \return 0, or -1 on error.
81 *
82 * \warning It is an error to unlock a mutex that has not been locked by
83 * the current thread, and doing so results in undefined behavior.
70 */ 84 */
71 #define SDL_UnlockMutex(m) SDL_mutexV(m) 85 #define SDL_UnlockMutex(m) SDL_mutexV(m)
72 extern DECLSPEC int SDLCALL SDL_mutexV(SDL_mutex * mutex); 86 extern DECLSPEC int SDLCALL SDL_mutexV(SDL_mutex * mutex);
73 87
74 /* Destroy a mutex */ 88 /**
89 * Destroy a mutex.
90 */
75 extern DECLSPEC void SDLCALL SDL_DestroyMutex(SDL_mutex * mutex); 91 extern DECLSPEC void SDLCALL SDL_DestroyMutex(SDL_mutex * mutex);
76 92
77 93 /*@}*//*Mutex functions*/
78 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ 94
79 /* Semaphore functions */ 95
80 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ 96 /**
97 * \name Semaphore functions
98 */
99 /*@{*/
81 100
82 /* The SDL semaphore structure, defined in SDL_sem.c */ 101 /* The SDL semaphore structure, defined in SDL_sem.c */
83 struct SDL_semaphore; 102 struct SDL_semaphore;
84 typedef struct SDL_semaphore SDL_sem; 103 typedef struct SDL_semaphore SDL_sem;
85 104
86 /* Create a semaphore, initialized with value, returns NULL on failure. */ 105 /**
106 * Create a semaphore, initialized with value, returns NULL on failure.
107 */
87 extern DECLSPEC SDL_sem *SDLCALL SDL_CreateSemaphore(Uint32 initial_value); 108 extern DECLSPEC SDL_sem *SDLCALL SDL_CreateSemaphore(Uint32 initial_value);
88 109
89 /* Destroy a semaphore */ 110 /**
111 * Destroy a semaphore.
112 */
90 extern DECLSPEC void SDLCALL SDL_DestroySemaphore(SDL_sem * sem); 113 extern DECLSPEC void SDLCALL SDL_DestroySemaphore(SDL_sem * sem);
91 114
92 /* This function suspends the calling thread until the semaphore pointed 115 /**
93 * to by sem has a positive count. It then atomically decreases the semaphore 116 * This function suspends the calling thread until the semaphore pointed
94 * count. 117 * to by \c sem has a positive count. It then atomically decreases the
118 * semaphore count.
95 */ 119 */
96 extern DECLSPEC int SDLCALL SDL_SemWait(SDL_sem * sem); 120 extern DECLSPEC int SDLCALL SDL_SemWait(SDL_sem * sem);
97 121
98 /* Non-blocking variant of SDL_SemWait(), returns 0 if the wait succeeds, 122 /**
99 SDL_MUTEX_TIMEDOUT if the wait would block, and -1 on error. 123 * Non-blocking variant of SDL_SemWait().
100 */ 124 *
125 * \return 0 if the wait succeeds, ::SDL_MUTEX_TIMEDOUT if the wait would
126 * block, and -1 on error.
127 */
101 extern DECLSPEC int SDLCALL SDL_SemTryWait(SDL_sem * sem); 128 extern DECLSPEC int SDLCALL SDL_SemTryWait(SDL_sem * sem);
102 129
103 /* Variant of SDL_SemWait() with a timeout in milliseconds, returns 0 if 130 /**
104 the wait succeeds, SDL_MUTEX_TIMEDOUT if the wait does not succeed in 131 * Variant of SDL_SemWait() with a timeout in milliseconds.
105 the allotted time, and -1 on error. 132 *
106 On some platforms this function is implemented by looping with a delay 133 * \return 0 if the wait succeeds, ::SDL_MUTEX_TIMEDOUT if the wait does not
107 of 1 ms, and so should be avoided if possible. 134 * succeed in the allotted time, and -1 on error.
108 */ 135 *
136 * \warning On some platforms this function is implemented by looping with a
137 * delay of 1 ms, and so should be avoided if possible.
138 */
109 extern DECLSPEC int SDLCALL SDL_SemWaitTimeout(SDL_sem * sem, Uint32 ms); 139 extern DECLSPEC int SDLCALL SDL_SemWaitTimeout(SDL_sem * sem, Uint32 ms);
110 140
111 /* Atomically increases the semaphore's count (not blocking), returns 0, 141 /**
112 or -1 on error. 142 * Atomically increases the semaphore's count (not blocking).
143 *
144 * \return 0, or -1 on error.
113 */ 145 */
114 extern DECLSPEC int SDLCALL SDL_SemPost(SDL_sem * sem); 146 extern DECLSPEC int SDLCALL SDL_SemPost(SDL_sem * sem);
115 147
116 /* Returns the current count of the semaphore */ 148 /**
149 * Returns the current count of the semaphore.
150 */
117 extern DECLSPEC Uint32 SDLCALL SDL_SemValue(SDL_sem * sem); 151 extern DECLSPEC Uint32 SDLCALL SDL_SemValue(SDL_sem * sem);
118 152
119 153 /*@}*//*Semaphore functions*/
120 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ 154
121 /* Condition variable functions */ 155
122 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ 156 /**
157 * \name Condition variable functions
158 */
159 /*@{*/
123 160
124 /* The SDL condition variable structure, defined in SDL_cond.c */ 161 /* The SDL condition variable structure, defined in SDL_cond.c */
125 struct SDL_cond; 162 struct SDL_cond;
126 typedef struct SDL_cond SDL_cond; 163 typedef struct SDL_cond SDL_cond;
127 164
128 /* Create a condition variable */ 165 /**
166 * Create a condition variable.
167 */
129 extern DECLSPEC SDL_cond *SDLCALL SDL_CreateCond(void); 168 extern DECLSPEC SDL_cond *SDLCALL SDL_CreateCond(void);
130 169
131 /* Destroy a condition variable */ 170 /**
171 * Destroy a condition variable.
172 */
132 extern DECLSPEC void SDLCALL SDL_DestroyCond(SDL_cond * cond); 173 extern DECLSPEC void SDLCALL SDL_DestroyCond(SDL_cond * cond);
133 174
134 /* Restart one of the threads that are waiting on the condition variable, 175 /**
135 returns 0 or -1 on error. 176 * Restart one of the threads that are waiting on the condition variable.
177 *
178 * \return 0 or -1 on error.
136 */ 179 */
137 extern DECLSPEC int SDLCALL SDL_CondSignal(SDL_cond * cond); 180 extern DECLSPEC int SDLCALL SDL_CondSignal(SDL_cond * cond);
138 181
139 /* Restart all threads that are waiting on the condition variable, 182 /**
140 returns 0 or -1 on error. 183 * Restart all threads that are waiting on the condition variable.
184 * \return 0 or -1 on error.
141 */ 185 */
142 extern DECLSPEC int SDLCALL SDL_CondBroadcast(SDL_cond * cond); 186 extern DECLSPEC int SDLCALL SDL_CondBroadcast(SDL_cond * cond);
143 187
144 /* Wait on the condition variable, unlocking the provided mutex. 188 /**
145 The mutex must be locked before entering this function! 189 * Wait on the condition variable, unlocking the provided mutex.
146 The mutex is re-locked once the condition variable is signaled. 190 *
147 Returns 0 when it is signaled, or -1 on error. 191 * \warning The mutex must be locked before entering this function!
192 *
193 * The mutex is re-locked once the condition variable is signaled.
194 *
195 * \return 0 when it is signaled, or -1 on error.
148 */ 196 */
149 extern DECLSPEC int SDLCALL SDL_CondWait(SDL_cond * cond, SDL_mutex * mut); 197 extern DECLSPEC int SDLCALL SDL_CondWait(SDL_cond * cond, SDL_mutex * mut);
150 198
151 /* Waits for at most 'ms' milliseconds, and returns 0 if the condition 199 /**
152 variable is signaled, SDL_MUTEX_TIMEDOUT if the condition is not 200 * Waits for at most \c ms milliseconds, and returns 0 if the condition
153 signaled in the allotted time, and -1 on error. 201 * variable is signaled, ::SDL_MUTEX_TIMEDOUT if the condition is not
154 On some platforms this function is implemented by looping with a delay 202 * signaled in the allotted time, and -1 on error.
155 of 1 ms, and so should be avoided if possible. 203 *
156 */ 204 * \warning On some platforms this function is implemented by looping with a
205 * delay of 1 ms, and so should be avoided if possible.
206 */
157 extern DECLSPEC int SDLCALL SDL_CondWaitTimeout(SDL_cond * cond, 207 extern DECLSPEC int SDLCALL SDL_CondWaitTimeout(SDL_cond * cond,
158 SDL_mutex * mutex, Uint32 ms); 208 SDL_mutex * mutex, Uint32 ms);
209
210 /*@}*//*Condition variable functions*/
211
159 212
160 /* Ends C function definitions when using C++ */ 213 /* Ends C function definitions when using C++ */
161 #ifdef __cplusplus 214 #ifdef __cplusplus
162 /* *INDENT-OFF* */ 215 /* *INDENT-OFF* */
163 } 216 }