Mercurial > sdl-ios-xcode

comparison include/SDL_assert.h @ 3670:62b6a5b99918

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Clean up assertion API for public use.
author Ryan C. Gordon <icculus@icculus.org>
date Wed, 13 Jan 2010 19:29:33 +0000
parents 6952d2b783e6
children f7b03b6838cb
comparison
equal deleted inserted replaced
3669:46d27a9571fa 3670:62b6a5b99918
107 unsigned int trigger_count; 107 unsigned int trigger_count;
108 const char *condition; 108 const char *condition;
109 const char *filename; 109 const char *filename;
110 int linenum; 110 int linenum;
111 const char *function; 111 const char *function;
112 struct SDL_assert_data *next; 112 const struct SDL_assert_data *next;
113 } SDL_assert_data; 113 } SDL_assert_data;
114 114
115 /* Never call this directly. Use the SDL_assert* macros. */ 115 /* Never call this directly. Use the SDL_assert* macros. */
116 extern DECLSPEC SDL_assert_state SDLCALL SDL_ReportAssertion(SDL_assert_data *, 116 extern DECLSPEC SDL_assert_state SDLCALL SDL_ReportAssertion(SDL_assert_data *,
117 const char *, 117 const char *,
164 # define SDL_assert_paranoid(condition) SDL_enabled_assert(condition) 164 # define SDL_assert_paranoid(condition) SDL_enabled_assert(condition)
165 #else 165 #else
166 # error Unknown assertion level. 166 # error Unknown assertion level.
167 #endif 167 #endif
168 168
169
170 typedef SDL_assert_state (SDLCALL *SDL_AssertionHandler)(
171 const SDL_assert_data *, void *userdata);
172
173 /**
174 * \brief Set an application-defined assertion handler.
175 *
176 * This allows an app to show its own assertion UI and/or force the
177 * response to an assertion failure. If the app doesn't provide this, SDL
178 * will try to do the right thing, popping up a system-specific GUI dialog,
179 * and probably minimizing any fullscreen windows.
180 *
181 * This callback may fire from any thread, but it runs wrapped in a mutex, so
182 * it will only fire from one thread at a time.
183 *
184 * Setting the callback to NULL restores SDL's original internal handler.
185 *
186 * This callback is NOT reset to SDL's internal handler upon SDL_Quit()!
187 *
188 * \return SDL_assert_state value of how to handle the assertion failure.
189 *
190 * \param handler Callback function, called when an assertion fails.
191 * \param userdata A pointer passed to the callback as-is.
192 */
193 extern DECLSPEC void SDLCALL SDL_SetAssertionHandler(
194 SDL_AssertionHandler handler,
195 void *userdata);
196
197 /**
198 * \brief Get a list of all assertion failures.
199 *
200 * Get all assertions triggered since last call to SDL_ResetAssertionReport(),
201 * or the start of the program.
202 *
203 * The proper way to examine this data looks something like this:
204 *
205 * <code>
206 * const SDL_assert_data *item = SDL_GetAssertionReport();
207 * while (item->condition) {
208 * printf("'%s', %s (%s:%d), triggered %u times, always ignore: %s.\n",
209 * item->condition, item->function, item->filename,
210 * item->linenum, item->trigger_count,
211 * item->always_ignore ? "yes" : "no");
212 * item = item->next;
213 * }
214 * </code>
215 *
216 * \return List of all assertions. This never returns NULL,
217 * even if there are no items.
218 * \sa SDL_ResetAssertionReport
219 */
220 extern DECLSPEC const SDL_assert_data * SDLCALL SDL_GetAssertionReport(void);
221
222 /**
223 * \brief Reset the list of all assertion failures.
224 *
225 * Reset list of all assertions triggered.
226 *
227 * \sa SDL_GetAssertionReport
228 */
229 extern DECLSPEC void SDLCALL SDL_ResetAssertionReport(void);
230
169 /* Ends C function definitions when using C++ */ 231 /* Ends C function definitions when using C++ */
170 #ifdef __cplusplus 232 #ifdef __cplusplus
171 /* *INDENT-OFF* */ 233 /* *INDENT-OFF* */
172 } 234 }
173 /* *INDENT-ON* */ 235 /* *INDENT-ON* */