Mercurial > sdl-ios-xcode

annotate include/SDL_mutex.h @ 5113:481dabb098ef

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Improved timer implementation The new timer model is formalized as using a separate thread to handle timer callbacks. This was the case on almost every platform before, but it's now a requirement, and simplifies the implementation and makes it perform consistently across platforms. Goals: * Minimize timer thread blocking * Dispatch timers as accurately as possible * SDL_AddTimer() and SDL_RemoveTimer() are completely threadsafe * SDL_RemoveTimer() doesn't crash with a timer that's expired or removed
author Sam Lantinga <slouken@libsdl.org>
date Thu, 27 Jan 2011 14:45:06 -0800
parents 0846f18eb625
children b530ef003506
rev   line source
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
1 /*
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
2 SDL - Simple DirectMedia Layer
3697
f7b03b6838cb Fixed bug #926
Sam Lantinga <slouken@libsdl.org>
parents: 3407
diff changeset
3 Copyright (C) 1997-2010 Sam Lantinga
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
4
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
5 This library is free software; you can redistribute it and/or
1312
c9b51268668f Updated copyright information and removed rcs id lines (problematic in branch merges)
Sam Lantinga <slouken@libsdl.org>
parents: 1263
diff changeset
6 modify it under the terms of the GNU Lesser General Public
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
7 License as published by the Free Software Foundation; either
1312
c9b51268668f Updated copyright information and removed rcs id lines (problematic in branch merges)
Sam Lantinga <slouken@libsdl.org>
parents: 1263
diff changeset
8 version 2.1 of the License, or (at your option) any later version.
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
9
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
10 This library is distributed in the hope that it will be useful,
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
1312
c9b51268668f Updated copyright information and removed rcs id lines (problematic in branch merges)
Sam Lantinga <slouken@libsdl.org>
parents: 1263
diff changeset
13 Lesser General Public License for more details.
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
14
1312
c9b51268668f Updated copyright information and removed rcs id lines (problematic in branch merges)
Sam Lantinga <slouken@libsdl.org>
parents: 1263
diff changeset
15 You should have received a copy of the GNU Lesser General Public
c9b51268668f Updated copyright information and removed rcs id lines (problematic in branch merges)
Sam Lantinga <slouken@libsdl.org>
parents: 1263
diff changeset
16 License along with this library; if not, write to the Free Software
c9b51268668f Updated copyright information and removed rcs id lines (problematic in branch merges)
Sam Lantinga <slouken@libsdl.org>
parents: 1263
diff changeset
17 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
18
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
19 Sam Lantinga
251
b8688cfdc232 Updated the headers with the correct e-mail address
Sam Lantinga <slouken@libsdl.org>
parents: 0
diff changeset
20 slouken@libsdl.org
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
21 */
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
22
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
23 #ifndef _SDL_mutex_h
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
24 #define _SDL_mutex_h
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
25
1895
c121d94672cb SDL 1.2 is moving to a branch, and SDL 1.3 is becoming the head.
Sam Lantinga <slouken@libsdl.org>
parents: 1358
diff changeset
26 /**
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
27 * \file SDL_mutex.h
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
28 *
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
29 * Functions to provide thread synchronization primitives.
1895
c121d94672cb SDL 1.2 is moving to a branch, and SDL 1.3 is becoming the head.
Sam Lantinga <slouken@libsdl.org>
parents: 1358
diff changeset
30 */
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
31
1356
67114343400d *** empty log message ***
Sam Lantinga <slouken@libsdl.org>
parents: 1312
diff changeset
32 #include "SDL_stdinc.h"
1358
c71e05b4dc2e More header massaging... works great on Windows. ;-)
Sam Lantinga <slouken@libsdl.org>
parents: 1356
diff changeset
33 #include "SDL_error.h"
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
34
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
35 #include "begin_code.h"
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
36 /* Set up for C function definitions, even when using C++ */
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
37 #ifdef __cplusplus
1895
c121d94672cb SDL 1.2 is moving to a branch, and SDL 1.3 is becoming the head.
Sam Lantinga <slouken@libsdl.org>
parents: 1358
diff changeset
38 /* *INDENT-OFF* */
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
39 extern "C" {
1895
c121d94672cb SDL 1.2 is moving to a branch, and SDL 1.3 is becoming the head.
Sam Lantinga <slouken@libsdl.org>
parents: 1358
diff changeset
40 /* *INDENT-ON* */
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
41 #endif
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
42
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
43 /**
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
44 * Synchronization functions which can time out return this value
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
45 * if they time out.
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
46 */
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
47 #define SDL_MUTEX_TIMEDOUT 1
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
48
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
49 /**
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
50 * This is the timeout value which corresponds to never time out.
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
51 */
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
52 #define SDL_MUTEX_MAXWAIT (~(Uint32)0)
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
53
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
54
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
55 /**
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
56 * \name Mutex functions
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
57 */
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
58 /*@{*/
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
59
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
60 /* The SDL mutex structure, defined in SDL_mutex.c */
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
61 struct SDL_mutex;
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
62 typedef struct SDL_mutex SDL_mutex;
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
63
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
64 /**
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
65 * Create a mutex, initialized unlocked.
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
66 */
1895
c121d94672cb SDL 1.2 is moving to a branch, and SDL 1.3 is becoming the head.
Sam Lantinga <slouken@libsdl.org>
parents: 1358
diff changeset
67 extern DECLSPEC SDL_mutex *SDLCALL SDL_CreateMutex(void);
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
68
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
69 /**
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
70 * Lock the mutex.
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
71 *
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
72 * \return 0, or -1 on error.
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
73 */
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
74 #define SDL_LockMutex(m) SDL_mutexP(m)
1895
c121d94672cb SDL 1.2 is moving to a branch, and SDL 1.3 is becoming the head.
Sam Lantinga <slouken@libsdl.org>
parents: 1358
diff changeset
75 extern DECLSPEC int SDLCALL SDL_mutexP(SDL_mutex * mutex);
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
76
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
77 /**
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
78 * Unlock the mutex.
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
79 *
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
80 * \return 0, or -1 on error.
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
81 *
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
82 * \warning It is an error to unlock a mutex that has not been locked by
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
83 * the current thread, and doing so results in undefined behavior.
417
04ec6995f75d *** empty log message ***
Sam Lantinga <slouken@libsdl.org>
parents: 337
diff changeset
84 */
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
85 #define SDL_UnlockMutex(m) SDL_mutexV(m)
1895
c121d94672cb SDL 1.2 is moving to a branch, and SDL 1.3 is becoming the head.
Sam Lantinga <slouken@libsdl.org>
parents: 1358
diff changeset
86 extern DECLSPEC int SDLCALL SDL_mutexV(SDL_mutex * mutex);
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
87
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
88 /**
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
89 * Destroy a mutex.
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
90 */
1895
c121d94672cb SDL 1.2 is moving to a branch, and SDL 1.3 is becoming the head.
Sam Lantinga <slouken@libsdl.org>
parents: 1358
diff changeset
91 extern DECLSPEC void SDLCALL SDL_DestroyMutex(SDL_mutex * mutex);
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
92
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
93 /*@}*//*Mutex functions*/
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
94
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
95
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
96 /**
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
97 * \name Semaphore functions
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
98 */
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
99 /*@{*/
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
100
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
101 /* The SDL semaphore structure, defined in SDL_sem.c */
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
102 struct SDL_semaphore;
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
103 typedef struct SDL_semaphore SDL_sem;
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
104
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
105 /**
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
106 * Create a semaphore, initialized with value, returns NULL on failure.
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
107 */
1895
c121d94672cb SDL 1.2 is moving to a branch, and SDL 1.3 is becoming the head.
Sam Lantinga <slouken@libsdl.org>
parents: 1358
diff changeset
108 extern DECLSPEC SDL_sem *SDLCALL SDL_CreateSemaphore(Uint32 initial_value);
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
109
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
110 /**
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
111 * Destroy a semaphore.
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
112 */
1895
c121d94672cb SDL 1.2 is moving to a branch, and SDL 1.3 is becoming the head.
Sam Lantinga <slouken@libsdl.org>
parents: 1358
diff changeset
113 extern DECLSPEC void SDLCALL SDL_DestroySemaphore(SDL_sem * sem);
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
114
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
115 /**
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
116 * This function suspends the calling thread until the semaphore pointed
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
117 * to by \c sem has a positive count. It then atomically decreases the
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
118 * semaphore count.
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
119 */
1895
c121d94672cb SDL 1.2 is moving to a branch, and SDL 1.3 is becoming the head.
Sam Lantinga <slouken@libsdl.org>
parents: 1358
diff changeset
120 extern DECLSPEC int SDLCALL SDL_SemWait(SDL_sem * sem);
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
121
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
122 /**
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
123 * Non-blocking variant of SDL_SemWait().
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
124 *
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
125 * \return 0 if the wait succeeds, ::SDL_MUTEX_TIMEDOUT if the wait would
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
126 * block, and -1 on error.
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
127 */
1895
c121d94672cb SDL 1.2 is moving to a branch, and SDL 1.3 is becoming the head.
Sam Lantinga <slouken@libsdl.org>
parents: 1358
diff changeset
128 extern DECLSPEC int SDLCALL SDL_SemTryWait(SDL_sem * sem);
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
129
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
130 /**
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
131 * Variant of SDL_SemWait() with a timeout in milliseconds.
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
132 *
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
133 * \return 0 if the wait succeeds, ::SDL_MUTEX_TIMEDOUT if the wait does not
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
134 * succeed in the allotted time, and -1 on error.
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
135 *
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
136 * \warning On some platforms this function is implemented by looping with a
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
137 * delay of 1 ms, and so should be avoided if possible.
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
138 */
1895
c121d94672cb SDL 1.2 is moving to a branch, and SDL 1.3 is becoming the head.
Sam Lantinga <slouken@libsdl.org>
parents: 1358
diff changeset
139 extern DECLSPEC int SDLCALL SDL_SemWaitTimeout(SDL_sem * sem, Uint32 ms);
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
140
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
141 /**
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
142 * Atomically increases the semaphore's count (not blocking).
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
143 *
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
144 * \return 0, or -1 on error.
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
145 */
1895
c121d94672cb SDL 1.2 is moving to a branch, and SDL 1.3 is becoming the head.
Sam Lantinga <slouken@libsdl.org>
parents: 1358
diff changeset
146 extern DECLSPEC int SDLCALL SDL_SemPost(SDL_sem * sem);
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
147
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
148 /**
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
149 * Returns the current count of the semaphore.
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
150 */
1895
c121d94672cb SDL 1.2 is moving to a branch, and SDL 1.3 is becoming the head.
Sam Lantinga <slouken@libsdl.org>
parents: 1358
diff changeset
151 extern DECLSPEC Uint32 SDLCALL SDL_SemValue(SDL_sem * sem);
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
152
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
153 /*@}*//*Semaphore functions*/
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
154
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
155
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
156 /**
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
157 * \name Condition variable functions
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
158 */
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
159 /*@{*/
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
160
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
161 /* The SDL condition variable structure, defined in SDL_cond.c */
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
162 struct SDL_cond;
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
163 typedef struct SDL_cond SDL_cond;
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
164
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
165 /**
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
166 * Create a condition variable.
5112
0846f18eb625 Improved condition variable documentation
Sam Lantinga <slouken@libsdl.org>
parents: 4469
diff changeset
167 *
0846f18eb625 Improved condition variable documentation
Sam Lantinga <slouken@libsdl.org>
parents: 4469
diff changeset
168 * Typical use of condition variables:
0846f18eb625 Improved condition variable documentation
Sam Lantinga <slouken@libsdl.org>
parents: 4469
diff changeset
169 *
0846f18eb625 Improved condition variable documentation
Sam Lantinga <slouken@libsdl.org>
parents: 4469
diff changeset
170 * Thread A:
0846f18eb625 Improved condition variable documentation
Sam Lantinga <slouken@libsdl.org>
parents: 4469
diff changeset
171 * SDL_LockMutex(lock);
0846f18eb625 Improved condition variable documentation
Sam Lantinga <slouken@libsdl.org>
parents: 4469
diff changeset
172 * while ( ! condition ) {
0846f18eb625 Improved condition variable documentation
Sam Lantinga <slouken@libsdl.org>
parents: 4469
diff changeset
173 * SDL_CondWait(cond, lock);
0846f18eb625 Improved condition variable documentation
Sam Lantinga <slouken@libsdl.org>
parents: 4469
diff changeset
174 * }
0846f18eb625 Improved condition variable documentation
Sam Lantinga <slouken@libsdl.org>
parents: 4469
diff changeset
175 * SDL_UnlockMutex(lock);
0846f18eb625 Improved condition variable documentation
Sam Lantinga <slouken@libsdl.org>
parents: 4469
diff changeset
176 *
0846f18eb625 Improved condition variable documentation
Sam Lantinga <slouken@libsdl.org>
parents: 4469
diff changeset
177 * Thread B:
0846f18eb625 Improved condition variable documentation
Sam Lantinga <slouken@libsdl.org>
parents: 4469
diff changeset
178 * SDL_LockMutex(lock);
0846f18eb625 Improved condition variable documentation
Sam Lantinga <slouken@libsdl.org>
parents: 4469
diff changeset
179 * ...
0846f18eb625 Improved condition variable documentation
Sam Lantinga <slouken@libsdl.org>
parents: 4469
diff changeset
180 * condition = true;
0846f18eb625 Improved condition variable documentation
Sam Lantinga <slouken@libsdl.org>
parents: 4469
diff changeset
181 * ...
0846f18eb625 Improved condition variable documentation
Sam Lantinga <slouken@libsdl.org>
parents: 4469
diff changeset
182 * SDL_CondSignal(cond);
0846f18eb625 Improved condition variable documentation
Sam Lantinga <slouken@libsdl.org>
parents: 4469
diff changeset
183 * SDL_UnlockMutex(lock);
0846f18eb625 Improved condition variable documentation
Sam Lantinga <slouken@libsdl.org>
parents: 4469
diff changeset
184 *
0846f18eb625 Improved condition variable documentation
Sam Lantinga <slouken@libsdl.org>
parents: 4469
diff changeset
185 * There is some discussion whether to signal the condition variable
0846f18eb625 Improved condition variable documentation
Sam Lantinga <slouken@libsdl.org>
parents: 4469
diff changeset
186 * with the mutex locked or not. There is some potential performance
0846f18eb625 Improved condition variable documentation
Sam Lantinga <slouken@libsdl.org>
parents: 4469
diff changeset
187 * benefit to unlocking first on some platforms, but there are some
0846f18eb625 Improved condition variable documentation
Sam Lantinga <slouken@libsdl.org>
parents: 4469
diff changeset
188 * potential race conditions depending on how your code is structured.
0846f18eb625 Improved condition variable documentation
Sam Lantinga <slouken@libsdl.org>
parents: 4469
diff changeset
189 *
0846f18eb625 Improved condition variable documentation
Sam Lantinga <slouken@libsdl.org>
parents: 4469
diff changeset
190 * In general it's safer to signal the condition variable while the
0846f18eb625 Improved condition variable documentation
Sam Lantinga <slouken@libsdl.org>
parents: 4469
diff changeset
191 * mutex is locked.
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
192 */
1895
c121d94672cb SDL 1.2 is moving to a branch, and SDL 1.3 is becoming the head.
Sam Lantinga <slouken@libsdl.org>
parents: 1358
diff changeset
193 extern DECLSPEC SDL_cond *SDLCALL SDL_CreateCond(void);
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
194
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
195 /**
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
196 * Destroy a condition variable.
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
197 */
1895
c121d94672cb SDL 1.2 is moving to a branch, and SDL 1.3 is becoming the head.
Sam Lantinga <slouken@libsdl.org>
parents: 1358
diff changeset
198 extern DECLSPEC void SDLCALL SDL_DestroyCond(SDL_cond * cond);
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
199
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
200 /**
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
201 * Restart one of the threads that are waiting on the condition variable.
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
202 *
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
203 * \return 0 or -1 on error.
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
204 */
1895
c121d94672cb SDL 1.2 is moving to a branch, and SDL 1.3 is becoming the head.
Sam Lantinga <slouken@libsdl.org>
parents: 1358
diff changeset
205 extern DECLSPEC int SDLCALL SDL_CondSignal(SDL_cond * cond);
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
206
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
207 /**
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
208 * Restart all threads that are waiting on the condition variable.
5112
0846f18eb625 Improved condition variable documentation
Sam Lantinga <slouken@libsdl.org>
parents: 4469
diff changeset
209 *
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
210 * \return 0 or -1 on error.
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
211 */
1895
c121d94672cb SDL 1.2 is moving to a branch, and SDL 1.3 is becoming the head.
Sam Lantinga <slouken@libsdl.org>
parents: 1358
diff changeset
212 extern DECLSPEC int SDLCALL SDL_CondBroadcast(SDL_cond * cond);
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
213
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
214 /**
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
215 * Wait on the condition variable, unlocking the provided mutex.
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
216 *
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
217 * \warning The mutex must be locked before entering this function!
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
218 *
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
219 * The mutex is re-locked once the condition variable is signaled.
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
220 *
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
221 * \return 0 when it is signaled, or -1 on error.
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
222 */
4469
f67139f6d87f Fixed wording for consistency
Sam Lantinga <slouken@libsdl.org>
parents: 3697
diff changeset
223 extern DECLSPEC int SDLCALL SDL_CondWait(SDL_cond * cond, SDL_mutex * mutex);
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
224
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
225 /**
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
226 * Waits for at most \c ms milliseconds, and returns 0 if the condition
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
227 * variable is signaled, ::SDL_MUTEX_TIMEDOUT if the condition is not
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
228 * signaled in the allotted time, and -1 on error.
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
229 *
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
230 * \warning On some platforms this function is implemented by looping with a
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
231 * delay of 1 ms, and so should be avoided if possible.
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
232 */
1895
c121d94672cb SDL 1.2 is moving to a branch, and SDL 1.3 is becoming the head.
Sam Lantinga <slouken@libsdl.org>
parents: 1358
diff changeset
233 extern DECLSPEC int SDLCALL SDL_CondWaitTimeout(SDL_cond * cond,
c121d94672cb SDL 1.2 is moving to a branch, and SDL 1.3 is becoming the head.
Sam Lantinga <slouken@libsdl.org>
parents: 1358
diff changeset
234 SDL_mutex * mutex, Uint32 ms);
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
235
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
236 /*@}*//*Condition variable functions*/
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
237
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
238
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
239 /* Ends C function definitions when using C++ */
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
240 #ifdef __cplusplus
1895
c121d94672cb SDL 1.2 is moving to a branch, and SDL 1.3 is becoming the head.
Sam Lantinga <slouken@libsdl.org>
parents: 1358
diff changeset
241 /* *INDENT-OFF* */
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
242 }
1895
c121d94672cb SDL 1.2 is moving to a branch, and SDL 1.3 is becoming the head.
Sam Lantinga <slouken@libsdl.org>
parents: 1358
diff changeset
243 /* *INDENT-ON* */
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
244 #endif
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
245 #include "close_code.h"
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
246
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
247 #endif /* _SDL_mutex_h */
1895
c121d94672cb SDL 1.2 is moving to a branch, and SDL 1.3 is becoming the head.
Sam Lantinga <slouken@libsdl.org>
parents: 1358
diff changeset
248
c121d94672cb SDL 1.2 is moving to a branch, and SDL 1.3 is becoming the head.
Sam Lantinga <slouken@libsdl.org>
parents: 1358
diff changeset
249 /* vi: set ts=4 sw=4 expandtab: */