Mercurial > molko

annotate doxygen/page-howto-error.c @ 207:133926e08d6e

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
examples: use game_loop for all
author David Demelier <markand@malikania.fr>
date Wed, 11 Nov 2020 16:09:43 +0100
parents eb0a7ab71023
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
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 */