Skip to content

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
libmlk-core Programming errors As much as possible Only in memory utilities from util.h Never called from libcore itself.
libmlk-ui Programming errors When applicable Mostly in rendering errors None.
libmlk-rpg Programming errors When applicable Mostly in rendering errors None.