Mercurial > molko
annotate doc/docs/dev/error.md @ 646:7e1eb7f6c049 default tip @
misc: remove .clang
author | David Demelier <markand@malikania.fr> |
---|---|
date | Sun, 04 Feb 2024 15:24:37 +0100 |
parents | 19782ea1cf4a |
children |
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 |
366
19782ea1cf4a
misc: start rebranding
David Demelier <markand@malikania.fr>
parents:
285
diff
changeset
|
8 Molko's Engine there is three kinds of errors: |
239
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 |
285
c43e39745cd8
doc: add note about console logs
David Demelier <markand@malikania.fr>
parents:
245
diff
changeset
|
14 ## About logs |
c43e39745cd8
doc: add note about console logs
David Demelier <markand@malikania.fr>
parents:
245
diff
changeset
|
15 |
c43e39745cd8
doc: add note about console logs
David Demelier <markand@malikania.fr>
parents:
245
diff
changeset
|
16 By itself, the core API never write anything to stdout/stderr. Instead it uses |
c43e39745cd8
doc: add note about console logs
David Demelier <markand@malikania.fr>
parents:
245
diff
changeset
|
17 the [trace][] and [panic][] functions which by default can write to the console, |
c43e39745cd8
doc: add note about console logs
David Demelier <markand@malikania.fr>
parents:
245
diff
changeset
|
18 if this is undesired, you can replace both handlers to use your custom logs. |
c43e39745cd8
doc: add note about console logs
David Demelier <markand@malikania.fr>
parents:
245
diff
changeset
|
19 |
239
d47e70da760e
doc: switch to mkdocs+doxybook2, closes #2516 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
20 ## Kind of errors |
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 ### Assertions |
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 One of the easiest errors to detect are about programming errors. In the |
366
19782ea1cf4a
misc: start rebranding
David Demelier <markand@malikania.fr>
parents:
285
diff
changeset
|
25 Molko's Engine API they are usually detected at runtime when you use a |
239
d47e70da760e
doc: switch to mkdocs+doxybook2, closes #2516 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
26 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
|
27 |
d47e70da760e
doc: switch to mkdocs+doxybook2, closes #2516 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
28 For example, it happens when you: |
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 - 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
|
31 - 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
|
32 |
d47e70da760e
doc: switch to mkdocs+doxybook2, closes #2516 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
33 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
|
34 documentation. |
d47e70da760e
doc: switch to mkdocs+doxybook2, closes #2516 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
35 |
d47e70da760e
doc: switch to mkdocs+doxybook2, closes #2516 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
36 ### Recoverable errors |
d47e70da760e
doc: switch to mkdocs+doxybook2, closes #2516 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
37 |
d47e70da760e
doc: switch to mkdocs+doxybook2, closes #2516 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
38 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
|
39 the API and can do something else. |
d47e70da760e
doc: switch to mkdocs+doxybook2, closes #2516 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
40 |
d47e70da760e
doc: switch to mkdocs+doxybook2, closes #2516 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
41 For example, it happens when you: |
d47e70da760e
doc: switch to mkdocs+doxybook2, closes #2516 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
42 |
d47e70da760e
doc: switch to mkdocs+doxybook2, closes #2516 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
43 - Open a font file that is invalid, |
d47e70da760e
doc: switch to mkdocs+doxybook2, closes #2516 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
44 - 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
|
45 |
d47e70da760e
doc: switch to mkdocs+doxybook2, closes #2516 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
46 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
|
47 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
|
48 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
|
49 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
|
50 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
|
51 case it is left untouched. |
d47e70da760e
doc: switch to mkdocs+doxybook2, closes #2516 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
52 |
d47e70da760e
doc: switch to mkdocs+doxybook2, closes #2516 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
53 ### Unexpected errors |
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 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
|
56 supposed to. |
d47e70da760e
doc: switch to mkdocs+doxybook2, closes #2516 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
57 |
d47e70da760e
doc: switch to mkdocs+doxybook2, closes #2516 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
58 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
|
59 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
|
60 |
d47e70da760e
doc: switch to mkdocs+doxybook2, closes #2516 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
61 This includes (but not limited to): |
d47e70da760e
doc: switch to mkdocs+doxybook2, closes #2516 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
62 |
d47e70da760e
doc: switch to mkdocs+doxybook2, closes #2516 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
63 - 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
|
64 |
d47e70da760e
doc: switch to mkdocs+doxybook2, closes #2516 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
65 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
|
66 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
|
67 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
|
68 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
|
69 |
366
19782ea1cf4a
misc: start rebranding
David Demelier <markand@malikania.fr>
parents:
285
diff
changeset
|
70 ## Error handling in Molko's Engine API |
239
d47e70da760e
doc: switch to mkdocs+doxybook2, closes #2516 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
71 |
d47e70da760e
doc: switch to mkdocs+doxybook2, closes #2516 @2h
David Demelier <markand@malikania.fr>
parents:
diff
changeset
|
72 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
|
73 |
245
97f55f6b9593
doc: add CMake macros documentation
David Demelier <markand@malikania.fr>
parents:
239
diff
changeset
|
74 | | `assert` | Booleans | panic | Notes | |
97f55f6b9593
doc: add CMake macros documentation
David Demelier <markand@malikania.fr>
parents:
239
diff
changeset
|
75 |-------------|--------------------|---------------------|-------------------------------------------|-----------------------------------| |
97f55f6b9593
doc: add CMake macros documentation
David Demelier <markand@malikania.fr>
parents:
239
diff
changeset
|
76 | libmlk-core | Programming errors | As much as possible | Only in memory utilities from util.h | Never called from libcore itself. | |
97f55f6b9593
doc: add CMake macros documentation
David Demelier <markand@malikania.fr>
parents:
239
diff
changeset
|
77 | libmlk-ui | Programming errors | When applicable | Mostly in rendering errors | None. | |
97f55f6b9593
doc: add CMake macros documentation
David Demelier <markand@malikania.fr>
parents:
239
diff
changeset
|
78 | libmlk-rpg | Programming errors | When applicable | Mostly in rendering errors | None. | |
285
c43e39745cd8
doc: add note about console logs
David Demelier <markand@malikania.fr>
parents:
245
diff
changeset
|
79 |
c43e39745cd8
doc: add note about console logs
David Demelier <markand@malikania.fr>
parents:
245
diff
changeset
|
80 [panic]: api/core/panic.md |
c43e39745cd8
doc: add note about console logs
David Demelier <markand@malikania.fr>
parents:
245
diff
changeset
|
81 [trace]: api/core/trace.md |