Mercurial > molko

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