Mercurial > molko
annotate doc/docs/dev/api/core/panic.md @ 376:b75fa5f47bf0
doc: document presence of (panic|trace)_data
| author | David Demelier <markand@malikania.fr> |
|---|---|
| date | Tue, 02 Nov 2021 15:35:53 +0100 |
| parents | c4da052c0def |
| children |
| rev | line source |
|---|---|
| 253 | 1 # Module: panic |
| 2 | |
| 3 Synopsis | |
| 4 | |
| 5 ```c | |
| 6 #include <core/panic.h> | |
| 7 ``` | |
| 8 | |
| 9 Unrecoverable error handling. | |
| 10 | |
| 11 This set of functions should be used to detect runtime errors that are | |
| 12 unexpected. They should be used only when the game cannot continue because it is | |
| 13 in a unrecoverable state. | |
| 14 | |
| 15 Examples of appropriate use cases: | |
| 16 | |
| 17 - Game saved data is corrupt, | |
| 18 - Assets are missing, | |
| 19 - No more memory. | |
| 20 | |
| 21 In other contexts, use asserts to indicates programming error and appropriate | |
| 22 solutions to recover the game otherwise. | |
| 23 | |
| 24 ## Globals | |
| 25 | |
| 26 | Variable | Type | | |
| 27 |---------------------------------|------------------| | |
| 28 | [panic_handler](#panic_handler) | `void (*)(void)` | | |
|
376
b75fa5f47bf0
doc: document presence of (panic|trace)_data
David Demelier <markand@malikania.fr>
parents:
253
diff
changeset
|
29 | [panic_data](#panic_data) | `void *` | |
| 253 | 30 |
| 31 ### panic\_handler | |
| 32 | |
| 33 Global panic handler. | |
| 34 | |
| 35 The default implementation shows the last error and exit with code 1. The | |
| 36 function must not return so you have to implement a setjmp/longjmp or a | |
| 37 exception to be thrown. | |
| 38 | |
| 39 If the user defined function returns, panic routines will finally exit with code | |
| 40 1. | |
| 41 | |
|
376
b75fa5f47bf0
doc: document presence of (panic|trace)_data
David Demelier <markand@malikania.fr>
parents:
253
diff
changeset
|
42 ### panic\_data |
|
b75fa5f47bf0
doc: document presence of (panic|trace)_data
David Demelier <markand@malikania.fr>
parents:
253
diff
changeset
|
43 |
|
b75fa5f47bf0
doc: document presence of (panic|trace)_data
David Demelier <markand@malikania.fr>
parents:
253
diff
changeset
|
44 Placeholder data for the handler if needed. |
|
b75fa5f47bf0
doc: document presence of (panic|trace)_data
David Demelier <markand@malikania.fr>
parents:
253
diff
changeset
|
45 |
| 253 | 46 ## Functions |
| 47 | |
| 48 ### panicf | |
| 49 | |
| 50 Terminate the program using the [panic_handler](#panic_handler) routine. | |
| 51 | |
| 52 This function will first set the global error with the provided format | |
| 53 string using the [printf][] format and then call the handler. | |
| 54 | |
| 55 ```c | |
| 56 noreturn void | |
| 57 panicf(const char *fmt, ...) | |
| 58 ``` | |
| 59 | |
| 60 ### panicva | |
| 61 | |
| 62 Like [panicf](#panicf) but using a `va_list`. | |
| 63 | |
| 64 ```c | |
| 65 noreturn void | |
| 66 panicva(const char *fmt, va_list ap) | |
| 67 ``` | |
| 68 | |
| 69 ### panic | |
| 70 | |
| 71 Call the [panic_handler](#panic_handler) using the last registered error. | |
| 72 | |
| 73 ```c | |
| 74 noreturn void | |
| 75 panic(void) | |
| 76 ``` | |
| 77 | |
| 78 [printf]: https://en.cppreference.com/w/c/io/fprintf |