1 /* |
|
2 SDL - Simple DirectMedia Layer |
|
3 Copyright (C) 1997-2012 Sam Lantinga |
|
4 |
|
5 This library is free software; you can redistribute it and/or |
|
6 modify it under the terms of the GNU Lesser General Public |
|
7 License as published by the Free Software Foundation; either |
|
8 version 2.1 of the License, or (at your option) any later version. |
|
9 |
|
10 This library is distributed in the hope that it will be useful, |
|
11 but WITHOUT ANY WARRANTY; without even the implied warranty of |
|
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
|
13 Lesser General Public License for more details. |
|
14 |
|
15 You should have received a copy of the GNU Lesser General Public |
|
16 License along with this library; if not, write to the Free Software |
|
17 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA |
|
18 |
|
19 Sam Lantinga |
|
20 slouken@libsdl.org |
|
21 */ |
|
22 |
|
23 #ifndef _SDL_mutex_h |
|
24 #define _SDL_mutex_h |
|
25 |
|
26 /** @file SDL_mutex.h |
|
27 * Functions to provide thread synchronization primitives |
|
28 * |
|
29 * @note These are independent of the other SDL routines. |
|
30 */ |
|
31 |
|
32 #include "SDL_stdinc.h" |
|
33 #include "SDL_error.h" |
|
34 |
|
35 #include "begin_code.h" |
|
36 /* Set up for C function definitions, even when using C++ */ |
|
37 #ifdef __cplusplus |
|
38 extern "C" { |
|
39 #endif |
|
40 |
|
41 /** Synchronization functions which can time out return this value |
|
42 * if they time out. |
|
43 */ |
|
44 #define SDL_MUTEX_TIMEDOUT 1 |
|
45 |
|
46 /** This is the timeout value which corresponds to never time out */ |
|
47 #define SDL_MUTEX_MAXWAIT (~(Uint32)0) |
|
48 |
|
49 |
|
50 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ |
|
51 /** @name Mutex functions */ /*@{*/ |
|
52 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ |
|
53 |
|
54 /** The SDL mutex structure, defined in SDL_mutex.c */ |
|
55 struct SDL_mutex; |
|
56 typedef struct SDL_mutex SDL_mutex; |
|
57 |
|
58 /** Create a mutex, initialized unlocked */ |
|
59 extern DECLSPEC SDL_mutex * SDLCALL SDL_CreateMutex(void); |
|
60 |
|
61 #define SDL_LockMutex(m) SDL_mutexP(m) |
|
62 /** Lock the mutex |
|
63 * @return 0, or -1 on error |
|
64 */ |
|
65 extern DECLSPEC int SDLCALL SDL_mutexP(SDL_mutex *mutex); |
|
66 |
|
67 #define SDL_UnlockMutex(m) SDL_mutexV(m) |
|
68 /** Unlock the mutex |
|
69 * @return 0, or -1 on error |
|
70 * |
|
71 * It is an error to unlock a mutex that has not been locked by |
|
72 * the current thread, and doing so results in undefined behavior. |
|
73 */ |
|
74 extern DECLSPEC int SDLCALL SDL_mutexV(SDL_mutex *mutex); |
|
75 |
|
76 /** Destroy a mutex */ |
|
77 extern DECLSPEC void SDLCALL SDL_DestroyMutex(SDL_mutex *mutex); |
|
78 |
|
79 /*@}*/ |
|
80 |
|
81 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ |
|
82 /** @name Semaphore functions */ /*@{*/ |
|
83 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ |
|
84 |
|
85 /** The SDL semaphore structure, defined in SDL_sem.c */ |
|
86 struct SDL_semaphore; |
|
87 typedef struct SDL_semaphore SDL_sem; |
|
88 |
|
89 /** Create a semaphore, initialized with value, returns NULL on failure. */ |
|
90 extern DECLSPEC SDL_sem * SDLCALL SDL_CreateSemaphore(Uint32 initial_value); |
|
91 |
|
92 /** Destroy a semaphore */ |
|
93 extern DECLSPEC void SDLCALL SDL_DestroySemaphore(SDL_sem *sem); |
|
94 |
|
95 /** |
|
96 * This function suspends the calling thread until the semaphore pointed |
|
97 * to by sem has a positive count. It then atomically decreases the semaphore |
|
98 * count. |
|
99 */ |
|
100 extern DECLSPEC int SDLCALL SDL_SemWait(SDL_sem *sem); |
|
101 |
|
102 /** Non-blocking variant of SDL_SemWait(). |
|
103 * @return 0 if the wait succeeds, |
|
104 * SDL_MUTEX_TIMEDOUT if the wait would block, and -1 on error. |
|
105 */ |
|
106 extern DECLSPEC int SDLCALL SDL_SemTryWait(SDL_sem *sem); |
|
107 |
|
108 /** Variant of SDL_SemWait() with a timeout in milliseconds, returns 0 if |
|
109 * the wait succeeds, SDL_MUTEX_TIMEDOUT if the wait does not succeed in |
|
110 * the allotted time, and -1 on error. |
|
111 * |
|
112 * On some platforms this function is implemented by looping with a delay |
|
113 * of 1 ms, and so should be avoided if possible. |
|
114 */ |
|
115 extern DECLSPEC int SDLCALL SDL_SemWaitTimeout(SDL_sem *sem, Uint32 ms); |
|
116 |
|
117 /** Atomically increases the semaphore's count (not blocking). |
|
118 * @return 0, or -1 on error. |
|
119 */ |
|
120 extern DECLSPEC int SDLCALL SDL_SemPost(SDL_sem *sem); |
|
121 |
|
122 /** Returns the current count of the semaphore */ |
|
123 extern DECLSPEC Uint32 SDLCALL SDL_SemValue(SDL_sem *sem); |
|
124 |
|
125 /*@}*/ |
|
126 |
|
127 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ |
|
128 /** @name Condition_variable_functions */ /*@{*/ |
|
129 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ |
|
130 |
|
131 /*@{*/ |
|
132 /** The SDL condition variable structure, defined in SDL_cond.c */ |
|
133 struct SDL_cond; |
|
134 typedef struct SDL_cond SDL_cond; |
|
135 /*@}*/ |
|
136 |
|
137 /** Create a condition variable */ |
|
138 extern DECLSPEC SDL_cond * SDLCALL SDL_CreateCond(void); |
|
139 |
|
140 /** Destroy a condition variable */ |
|
141 extern DECLSPEC void SDLCALL SDL_DestroyCond(SDL_cond *cond); |
|
142 |
|
143 /** Restart one of the threads that are waiting on the condition variable, |
|
144 * @return 0 or -1 on error. |
|
145 */ |
|
146 extern DECLSPEC int SDLCALL SDL_CondSignal(SDL_cond *cond); |
|
147 |
|
148 /** Restart all threads that are waiting on the condition variable, |
|
149 * @return 0 or -1 on error. |
|
150 */ |
|
151 extern DECLSPEC int SDLCALL SDL_CondBroadcast(SDL_cond *cond); |
|
152 |
|
153 /** Wait on the condition variable, unlocking the provided mutex. |
|
154 * The mutex must be locked before entering this function! |
|
155 * The mutex is re-locked once the condition variable is signaled. |
|
156 * @return 0 when it is signaled, or -1 on error. |
|
157 */ |
|
158 extern DECLSPEC int SDLCALL SDL_CondWait(SDL_cond *cond, SDL_mutex *mut); |
|
159 |
|
160 /** Waits for at most 'ms' milliseconds, and returns 0 if the condition |
|
161 * variable is signaled, SDL_MUTEX_TIMEDOUT if the condition is not |
|
162 * signaled in the allotted time, and -1 on error. |
|
163 * On some platforms this function is implemented by looping with a delay |
|
164 * of 1 ms, and so should be avoided if possible. |
|
165 */ |
|
166 extern DECLSPEC int SDLCALL SDL_CondWaitTimeout(SDL_cond *cond, SDL_mutex *mutex, Uint32 ms); |
|
167 |
|
168 /*@}*/ |
|
169 |
|
170 /* Ends C function definitions when using C++ */ |
|
171 #ifdef __cplusplus |
|
172 } |
|
173 #endif |
|
174 #include "close_code.h" |
|
175 |
|
176 #endif /* _SDL_mutex_h */ |
|
177 |
|