Mercurial > molko
view doc/docs/dev/error.md @ 239:d47e70da760e
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 |
line wrap: on
line source
# Error handling How error handling is used within the API and the user code. ## Synopsis Error handling is always a complicated task in the software development. In Molko's Adventure there is three kinds of errors: 1. Programming error. 2. Recoverable error at runtime. 3. Unexpected error at runtime. ## Kind of errors ### Assertions One of the easiest errors to detect are about programming errors. In the Molko's Adventure API they are usually detected at runtime when you use a function with preconditions unmet. In that case standard C `assert` is used. For example, it happens when you: - Pass a NULL pointer where the function expects non-NULL, - Pass invalid arguments such as out of bounds indicies. Always read carefully preconditions that are annotated through the documentation. ### Recoverable errors Next, come recoverable errors. Those arise when you may expect a failure from the API and can do something else. For example, it happens when you: - Open a font file that is invalid, - Open a music file that is no longer on the disk. In these situations, the API indicates usually by a return code that the function was unable to complete correctly (and you can use error to retrieve the specified error). In some case, you *MUST* not ignore the return value because if the function takes an input as argument it will be kept untouched. For example, the texture_new function may fail to create a texture and in that case it is left untouched. ### Unexpected errors Finally, come what we call unexpected errors. Those happen while they are not supposed to. For example, it happens when there is a severe issue either in the kernel, graphics or any other library that aren't raised by the API itself. This includes (but not limited to): - A rendering error (caused by an internal issue). In these situations, the API calls the function panic which definitely calls the panic_handler. The default implementation prints an error and exit with a code of 1. User may pass a custom function but should quit the game because the API does not take care of deallocating data before calling panic. ## Error handling in Molko's Adventure API The following table shows what is used and when. | | `assert` | Booleans | panic | Notes | |---------|--------------------|---------------------|-------------------------------------------|-----------------------------------| | libcore | Programming errors | As much as possible | Only in memory utilities from util.h | Never called from libcore itself. | | libui | Programming errors | When applicable | Mostly in rendering errors | None. | | librpg | Programming errors | When applicable | Mostly in rendering errors | None. |