Mercurial > molko
annotate doxygen/page-howto-error.c @ 236:4896bb07a8db
core: add pprintf function
author | David Demelier <markand@malikania.fr> |
---|---|
date | Fri, 27 Nov 2020 13:31:16 +0100 |
parents | eb0a7ab71023 |
children |
rev | line source |
---|---|
169
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
1 /** |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
2 * \page howto-error Howto: error handling |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
3 * \tableofcontents |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
4 * |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
5 * How error handling is used within the API and the user code. |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
6 * |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
7 * # Synopsis |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
8 * |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
9 * Error handling is always a complicated task in the software development. In |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
10 * Molko's Adventure there is three kinds of errors: |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
11 * |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
12 * 1. Programming error. |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
13 * 2. Recoverable error at runtime. |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
14 * 3. Unexpected error at runtime. |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
15 * |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
16 * # Kind of errors |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
17 * |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
18 * ## Assertions |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
19 * |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
20 * One of the easiest errors to detect are about programming errors. In the |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
21 * Molko's Adventure API they are usually detected at runtime when you use a |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
22 * function with preconditions unmet. In that case standard C `assert` is used. |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
23 * |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
24 * For example, it happens when you: |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
25 * |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
26 * - Pass a NULL pointer where the function expects non-NULL, |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
27 * - Pass invalid arguments such as out of bounds indicies. |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
28 * |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
29 * Always read carefully preconditions that are annotated through the |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
30 * documentation. |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
31 * |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
32 * ## Recoverable errors |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
33 * |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
34 * Next, come recoverable errors. Those arise when you may expect a failure from |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
35 * the API and can do something else. |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
36 * |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
37 * For example, it happens when you: |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
38 * |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
39 * - Open a font file that is invalid, |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
40 * - Open a music file that is no longer on the disk. |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
41 * |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
42 * In these situations, the API indicates usually by a return code that the |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
43 * function was unable to complete correctly (and you can use \ref error to |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
44 * retrieve the specified error). In some case, you *MUST* not ignore the return |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
45 * value because if the function takes an input as argument it will be kept |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
46 * untouched. For example, the \ref texture_new function may fail to create a |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
47 * texture and in that case it is left untouched. |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
48 * |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
49 * ## Unexpected errors |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
50 * |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
51 * Finally, come what we call unexpected errors. Those happen while they are not |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
52 * supposed to. |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
53 * |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
54 * For example, it happens when there is a severe issue either in the kernel, |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
55 * graphics or any other library that aren't raised by the API itself. |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
56 * |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
57 * This includes (but not limited to): |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
58 * |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
59 * - A rendering error (caused by an internal issue). |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
60 * |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
61 * In these situations, the API calls the function \ref panic which definitely |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
62 * calls the \ref panic_handler. The default implementation prints an error and |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
63 * exit with a code of 1. User may pass a custom function but should quit the |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
64 * game because the API does not take care of deallocating data before calling |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
65 * panic. |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
66 * |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
67 * # Error handling in Molko's Adventure API |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
68 * |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
69 * The following table shows what is used and when. |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
70 * |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
71 * | | `assert` | Booleans | panic | Notes | |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
72 * |---------|--------------------|---------------------|-------------------------------------------|-----------------------------------| |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
73 * | libcore | Programming errors | As much as possible | Only in memory utilities from util.h | Never called from libcore itself. | |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
74 * | libui | Programming errors | When applicable | Mostly in rendering errors | None. | |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
75 * | librpg | Programming errors | When applicable | Mostly in rendering errors | None. | |
eb0a7ab71023
misc: extreme cleanup, closes #2506
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
76 */ |