Mercurial > molko
view doxygen/page-howto-error.c @ 228:2734223d3daf
core: add a alloc_pool module
A miniamlist expandable array that gros each time new data is required, ideal
where data must be allocated dynamically without knowing in advance the number
of items.
author | David Demelier <markand@malikania.fr> |
---|---|
date | Thu, 19 Nov 2020 14:11:11 +0100 |
parents | eb0a7ab71023 |
children |
line wrap: on
line source
/** * \page howto-error Howto: error handling * \tableofcontents * * 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 \ref 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 \ref 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 \ref panic which definitely * calls the \ref 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. | */