Mercurial > molko

annotate doc/docs/dev/error.md @ 239:d47e70da760e

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