Mercurial > sdl-ios-xcode

comparison include/SDL_atomic.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 72b542f34739
children f7b03b6838cb
comparison
equal deleted inserted replaced
3406:8ae607392409 3407:d3baf5ac4e37
21 21
22 Contributed by Bob Pendleton, bob@pendleton.com 22 Contributed by Bob Pendleton, bob@pendleton.com
23 */ 23 */
24 24
25 /** 25 /**
26 * \file SDL_atomic.h 26 * \file SDL_atomic.h
27 * 27 *
28 * Atomic operations. 28 * Atomic operations.
29 *
30 * These operations may, or may not, actually be implemented using
31 * processor specific atomic operations. When possible they are
32 * implemented as true processor specific atomic operations. When that
33 * is not possible the are implemented using locks that *do* use the
34 * available atomic operations.
35 *
36 * At the very minimum spin locks must be implemented. Without spin
37 * locks it is not possible (AFAICT) to emulate the rest of the atomic
38 * operations.
29 */ 39 */
30 40
31 #ifndef _SDL_atomic_h_ 41 #ifndef _SDL_atomic_h_
32 #define _SDL_atomic_h_ 42 #define _SDL_atomic_h_
33 43
41 /* *INDENT-OFF* */ 51 /* *INDENT-OFF* */
42 extern "C" { 52 extern "C" {
43 /* *INDENT-ON* */ 53 /* *INDENT-ON* */
44 #endif 54 #endif
45 55
46 /** 56 /* Function prototypes */
47 * These operations may, or may not, actually be implemented using 57
48 * processor specific atomic operations. When possible they are 58 /**
49 * implemented as true processor specific atomic operations. When that 59 * \name SDL AtomicLock
50 * is not possible the are implemented using locks that *do* use the 60 *
51 * available atomic operations. 61 * The spin lock functions and type are required and can not be
62 * emulated because they are used in the emulation code.
63 */
64 /*@{*/
65
66 typedef volatile Uint32 SDL_SpinLock;
67
68 /**
69 * \brief Lock a spin lock by setting it to a none zero value.
70 *
71 * \param lock Points to the lock.
72 */
73 extern DECLSPEC void SDLCALL SDL_AtomicLock(SDL_SpinLock *lock);
74
75 /**
76 * \brief Unlock a spin lock by setting it to 0. Always returns immediately
52 * 77 *
53 * At the very minimum spin locks must be implemented. Without spin 78 * \param lock Points to the lock.
54 * locks it is not possible (AFAICT) to emulate the rest of the atomic
55 * operations.
56 */
57
58 /* Function prototypes */
59
60 /**
61 * SDL AtomicLock.
62 *
63 * The spin lock functions and type are required and can not be
64 * emulated because they are used in the emulation code.
65 */
66
67 typedef volatile Uint32 SDL_SpinLock;
68
69 /**
70 * \fn void SDL_AtomicLock(SDL_SpinLock *lock);
71 *
72 * \brief Lock a spin lock by setting it to a none zero value.
73 *
74 * \param lock points to the lock.
75 *
76 */
77 extern DECLSPEC void SDLCALL SDL_AtomicLock(SDL_SpinLock *lock);
78
79 /**
80 * \fn void SDL_AtomicUnlock(SDL_SpinLock *lock);
81 *
82 * \brief Unlock a spin lock by setting it to 0. Always returns immediately
83 *
84 * \param lock points to the lock.
85 *
86 */ 79 */
87 extern DECLSPEC void SDLCALL SDL_AtomicUnlock(SDL_SpinLock *lock); 80 extern DECLSPEC void SDLCALL SDL_AtomicUnlock(SDL_SpinLock *lock);
88 81
89 /* 32 bit atomic operations */ 82 /*@}*//*SDL AtomicLock*/
90 83
91 /** 84 /**
92 * \fn SDL_bool SDL_AtomicTestThenSet32(volatile Uint32 * ptr); 85 * \name 32 bit atomic operations
93 * 86 */
94 * \brief Check to see if *ptr == 0 and set it to 1. 87 /*@{*/
95 * 88
96 * \return SDL_True if the value pointed to by ptr was zero and 89 /**
97 * SDL_False if it was not zero 90 * \brief Check to see if \c *ptr == 0 and set it to 1.
98 * 91 *
99 * \param ptr points to the value to be tested and set. 92 * \return SDL_True if the value pointed to by \c ptr was zero and
100 * 93 * SDL_False if it was not zero
94 *
95 * \param ptr Points to the value to be tested and set.
101 */ 96 */
102 extern DECLSPEC SDL_bool SDLCALL SDL_AtomicTestThenSet32(volatile Uint32 * ptr); 97 extern DECLSPEC SDL_bool SDLCALL SDL_AtomicTestThenSet32(volatile Uint32 * ptr);
103 98
104 /** 99 /**
105 * \fn void SDL_AtomicClear32(volatile Uint32 * ptr); 100 * \brief Set the value pointed to by \c ptr to be zero.
106 * 101 *
107 * \brief set the value pointed to by ptr to be zero. 102 * \param ptr Address of the value to be set to zero
108 *
109 * \param ptr address of the value to be set to zero
110 *
111 */ 103 */
112 extern DECLSPEC void SDLCALL SDL_AtomicClear32(volatile Uint32 * ptr); 104 extern DECLSPEC void SDLCALL SDL_AtomicClear32(volatile Uint32 * ptr);
113 105
114 /** 106 /**
115 * \fn Uint32 SDL_AtomicFetchThenIncrement32(volatile Uint32 * ptr); 107 * \brief Fetch the current value of \c *ptr and then increment that
116 * 108 * value in place.
117 * \brief fetch the current value of *ptr and then increment that 109 *
118 * value in place. 110 * \return The value before it was incremented.
119 * 111 *
120 * \return the value before it was incremented. 112 * \param ptr Address of the value to fetch and increment
121 *
122 * \param ptr address of the value to fetch and increment
123 *
124 */ 113 */
125 extern DECLSPEC Uint32 SDLCALL SDL_AtomicFetchThenIncrement32(volatile Uint32 * ptr); 114 extern DECLSPEC Uint32 SDLCALL SDL_AtomicFetchThenIncrement32(volatile Uint32 * ptr);
126 115
127 /** 116 /**
128 * \fn Uint32 SDL_AtomicFetchThenDecrement32(volatile Uint32 * ptr); 117 * \brief Fetch \c *ptr and then decrement the value in place.
129 * 118 *
130 * \brief fetch *ptr and then decrement the value in place. 119 * \return The value before it was decremented.
131 * 120 *
132 * \return the value before it was decremented. 121 * \param ptr Address of the value to fetch and drement
133 *
134 * \param ptr address of the value to fetch and drement
135 *
136 */ 122 */
137 extern DECLSPEC Uint32 SDLCALL SDL_AtomicFetchThenDecrement32(volatile Uint32 * ptr); 123 extern DECLSPEC Uint32 SDLCALL SDL_AtomicFetchThenDecrement32(volatile Uint32 * ptr);
138 124
139 /** 125 /**
140 * \fn Uint32 SDL_AtomicFetchThenAdd32(volatile Uint32 * ptr, Uint32 value); 126 * \brief Fetch the current value at \c ptr and then add \c value to \c *ptr.
141 * 127 *
142 * \brief fetch the current value at ptr and then add value to *ptr. 128 * \return \c *ptr before the addition took place.
143 * 129 *
144 * \return *ptr before the addition took place. 130 * \param ptr The address of data we are changing.
145 * 131 * \param value The value to add to \c *ptr.
146 * \param ptr the address of data we are changing.
147 * \param value the value to add to *ptr.
148 *
149 */ 132 */
150 extern DECLSPEC Uint32 SDLCALL SDL_AtomicFetchThenAdd32(volatile Uint32 * ptr, Uint32 value); 133 extern DECLSPEC Uint32 SDLCALL SDL_AtomicFetchThenAdd32(volatile Uint32 * ptr, Uint32 value);
151 134
152 /** 135 /**
153 * \fn Uint32 SDL_AtomicFetchThenSubtract32(volatile Uint32 * ptr, Uint32 value); 136 * \brief Fetch \c *ptr and then subtract \c value from it.
154 * 137 *
155 * \brief Fetch *ptr and then subtract value from it. 138 * \return \c *ptr before the subtraction took place.
156 * 139 *
157 * \return *ptr before the subtraction took place. 140 * \param ptr The address of the data being changed.
158 * 141 * \param value The value to subtract from \c *ptr.
159 * \param ptr the address of the data being changed.
160 * \param value the value to subtract from *ptr.
161 *
162 */ 142 */
163 extern DECLSPEC Uint32 SDLCALL SDL_AtomicFetchThenSubtract32(volatile Uint32 * ptr, Uint32 value); 143 extern DECLSPEC Uint32 SDLCALL SDL_AtomicFetchThenSubtract32(volatile Uint32 * ptr, Uint32 value);
164 144
165 /** 145 /**
166 * \fn Uint32 SDL_AtomicIncrementThenFetch32(volatile Uint32 * ptr); 146 * \brief Add one to the data pointed to by \c ptr and return that value.
167 * 147 *
168 * \brief Add one to the data pointed to by ptr and return that value. 148 * \return The incremented value.
169 * 149 *
170 * \return the incremented value. 150 * \param ptr The address of the data to increment.
171 *
172 * \param ptr address of the data to increment.
173 *
174 */ 151 */
175 extern DECLSPEC Uint32 SDLCALL SDL_AtomicIncrementThenFetch32(volatile Uint32 * ptr); 152 extern DECLSPEC Uint32 SDLCALL SDL_AtomicIncrementThenFetch32(volatile Uint32 * ptr);
176 153
177 /** 154 /**
178 * \fn Uint32 SDL_AtomicDecrementThenFetch32(volatile Uint32 * ptr); 155 * \brief Subtract one from data pointed to by \c ptr and return the new value.
179 * 156 *
180 * \brief Subtract one from data pointed to by ptr and return the new value. 157 * \return The decremented value.
181 * 158 *
182 * \return The decremented value. 159 * \param ptr The address of the data to decrement.
183 *
184 * \param ptr The address of the data to decrement.
185 *
186 */ 160 */
187 extern DECLSPEC Uint32 SDLCALL SDL_AtomicDecrementThenFetch32(volatile Uint32 * ptr); 161 extern DECLSPEC Uint32 SDLCALL SDL_AtomicDecrementThenFetch32(volatile Uint32 * ptr);
188 162
189 /** 163 /**
190 * \fn Uint32 SDL_AtomicAddThenFetch32(volatile Uint32 * ptr, Uint32 value); 164 * \brief Add \c value to the data pointed to by \c ptr and return result.
191 * 165 *
192 * \brief Add value to the data pointed to by ptr and return result. 166 * \return The sum of \c *ptr and \c value.
193 * 167 *
194 * \return The sum of *ptr and value. 168 * \param ptr The address of the data to be modified.
195 * 169 * \param value The value to be added.
196 * \param ptr The address of the data to be modified.
197 * \param value The value to be added.
198 *
199 */ 170 */
200 extern DECLSPEC Uint32 SDLCALL SDL_AtomicAddThenFetch32(volatile Uint32 * ptr, Uint32 value); 171 extern DECLSPEC Uint32 SDLCALL SDL_AtomicAddThenFetch32(volatile Uint32 * ptr, Uint32 value);
201 172
202 /** 173 /**
203 * \fn Uint32 SDL_AtomicSubtractThenFetch32(volatile Uint32 * ptr, Uint32 value); 174 * \brief Subtract \c value from the data pointed to by \c ptr and return the result.
204 * 175 *
205 * \brief Subtract value from the data pointed to by ptr and return the result. 176 * \return The difference between \c *ptr and \c value.
206 * 177 *
207 * \return the difference between *ptr and value. 178 * \param ptr The address of the data to be modified.
208 * 179 * \param value The value to be subtracted.
209 * \param ptr The address of the data to be modified.
210 * \param value The value to be subtracted.
211 *
212 */ 180 */
213 extern DECLSPEC Uint32 SDLCALL SDL_AtomicSubtractThenFetch32(volatile Uint32 * ptr, Uint32 value); 181 extern DECLSPEC Uint32 SDLCALL SDL_AtomicSubtractThenFetch32(volatile Uint32 * ptr, Uint32 value);
214 182
215 /* 64 bit atomic operations */ 183 /*@}*//*32 bit atomic operations*/
184
185 /**
186 * \name 64 bit atomic operations
187 */
188 /*@{*/
216 #ifdef SDL_HAS_64BIT_TYPE 189 #ifdef SDL_HAS_64BIT_TYPE
217 190
218 extern DECLSPEC SDL_bool SDLCALL SDL_AtomicTestThenSet64(volatile Uint64 * ptr); 191 extern DECLSPEC SDL_bool SDLCALL SDL_AtomicTestThenSet64(volatile Uint64 * ptr);
219 extern DECLSPEC void SDLCALL SDL_AtomicClear64(volatile Uint64 * ptr); 192 extern DECLSPEC void SDLCALL SDL_AtomicClear64(volatile Uint64 * ptr);
220 extern DECLSPEC Uint64 SDLCALL SDL_AtomicFetchThenIncrement64(volatile Uint64 * ptr); 193 extern DECLSPEC Uint64 SDLCALL SDL_AtomicFetchThenIncrement64(volatile Uint64 * ptr);
225 extern DECLSPEC Uint64 SDLCALL SDL_AtomicDecrementThenFetch64(volatile Uint64 * ptr); 198 extern DECLSPEC Uint64 SDLCALL SDL_AtomicDecrementThenFetch64(volatile Uint64 * ptr);
226 extern DECLSPEC Uint64 SDLCALL SDL_AtomicAddThenFetch64(volatile Uint64 * ptr, Uint64 value); 199 extern DECLSPEC Uint64 SDLCALL SDL_AtomicAddThenFetch64(volatile Uint64 * ptr, Uint64 value);
227 extern DECLSPEC Uint64 SDLCALL SDL_AtomicSubtractThenFetch64(volatile Uint64 * ptr, Uint64 value); 200 extern DECLSPEC Uint64 SDLCALL SDL_AtomicSubtractThenFetch64(volatile Uint64 * ptr, Uint64 value);
228 #endif /* SDL_HAS_64BIT_TYPE */ 201 #endif /* SDL_HAS_64BIT_TYPE */
229 202
203 /*@}*//*64 bit atomic operations*/
204
230 /* Ends C function definitions when using C++ */ 205 /* Ends C function definitions when using C++ */
231 #ifdef __cplusplus 206 #ifdef __cplusplus
232 /* *INDENT-OFF* */ 207 /* *INDENT-OFF* */
233 } 208 }
234 /* *INDENT-ON* */ 209 /* *INDENT-ON* */