# Error handling

## Error structs

Errors are represented using `hbe_err_s` structs (type `hbe_err_t`). It has two fields:

- `code`: A value from the enum `hbe_errcode` (type `hbe_errcode_t`).
- `message`: A character array (`hb_char_t *`) describing the error and providing context.

## Error-prone functions

Every function that may result in errors should declare `hbe_err_t *hbe_err` as its first parameter.

Functions can result in errors if:

- it calls any function that may result in an error
- it sets the variable pointed to by `hbe_err`

If the function needs to do cleanup operations, it should declare a `finally:` label at the end of the function and put the cleanup code there. If the function returns a value, the function should start with a `rv_t rv = 0;` declaration (where `rv_t` is the return type), and the `finally` section should end with a `return rv;`.

`rv` should be initialised because technically an error can occur at any time after it, including immediately afterwards.

## Creating errors

To create an error, use the `hbe_err_t hbe_error(hbe_errcode_t code, hb_char_t *message)` function.
The result should be set to `*hbe_err`, and then the function should return.

When an error occurs, the function should return some arbitrary return value such as `0`.
Return values from a function call are not considered reliable if errors occurred during their execution.

```c
int error_prone(hbe_err_t *hbe_err, char *msg) {
  if (some_error_condition) {
    *hbe_err = hbe_error(1, "Bad!");
    return 0;
  }

  printf("%s\n", msg);

  return 42;
}
```

To simplify this code, a macro is available:

```c
int error_prone(hbe_err_t *hbe_err, char *msg) {
  if (some_error_condition) {
    HBE_THROW(1, "Bad!");
    /* Translates to:
    *hbe_err = hbe_error(1, "Bad!");
    return 0;
    */
  }

  printf("%s\n", msg);

  return 42;
}
```

If the return type is `void`, use `HBE_THROW_V` instead of `HBE_THROW`.
If there is a cleanup section, use `HBE_THROW_F`.

## Handling errors

When a function call may result in an error, pass `hbe_err` to the function and check if the value dereferenced is not `NULL`. If it isn't, an error occurred and the callee should return.

The return value should not be used if an error occurred.

```c
int callee(hbe_err_t *hbe_err, int a, int b) {
  int meaning_of_life = error_prone(hbe_err, "Yes");
  if (*hbe_err != NULL) {
    // An error occurred, $meaning_of_life is unreliable
    return 0;
  }

  return 3;
}
```

To simplify this code, a macro is available:

```c
int callee(hbe_err_t *hbe_err, int a, int b) {
  int meaning_of_life = HBE_CATCH(error_prone, hbe_err, "Yes");
  /* Translates to:
  int meaning_of_life = error_prone(hbe_err, "Yes");
  if (*hbe_err != NULL) {
    return 0;
  }
  */

  return 3;
}
```

If the return type is `void`, use `HBE_CATCH_V` instead.
If there is a cleanup section, use `HBE_CATCH_F`.

## Returning with cleanup

Use the macro `HBE_RETURN_F` to set the return value and go to the cleanup section:

```c
int fn(hbe_err_t *hbe_err) {
  int rv = 0;

  HBE_RETURN_F(1);
  /* Translates to:
  rv = 1;
  goto finally;
  */

  finally:
    return rv;
}
```

## Top-level error handler

At the very root, where the call to the first error-prone function resides, create a variable with type `hbe_err_t` set to `NULL` on the stack, and pass a reference to it:

After the call, if an error occurred, the variable will be set to a value other than `NULL`.

```c
int main(void) {
  hbe_err_t err = NULL;
  fn(&err);
  if (err != NULL) {
    // An error occurred
  }
}
```