Error Management

Recoverable error handling facilities. More...

Collaboration diagram for Error Management:

Detailed Description

This API provides a simple mechanism for communicating recoverable errors from callee to caller.

When a function may fail, it takes a bj_error pointer as a parameter. The failing function may fill in this value to communicate error while the caller can check for the value of bj_error_code to check if any error occurred:

    bj_error* error = 0;
 
    function_returning_error(&error);
 
    if(error != 0) {
        bj_info("There was an error");
    }

Use bj_set_error from inside a custom function that may result in an error:

void function_returning_error(bj_error** error) {
    bj_set_error(error, CODE, "An error occured");
}

Data Structures
struct	bj_error
	Error structure. More...

Macros
#define	bj_error_code_is_user   (c) (((c >> 24) & 0xFF) > 0x00)
	Checks if an error code is user-provided or Banjo.
#define	bj_error_code_kind(c)
	Evaluates to an error code kind.
#define	BJ_ERROR_MESSAGE_MAX_LEN   127
	Maximum number of characters an error message in bj_error can hold.

Enumerations
enum	bj_error_code {   BJ_ERROR_NONE = 0x00000000 , BJ_ERROR = 0x00000001 , BJ_ERROR_UNSUPPORTED = 0x00000101 , BJ_ERROR_NOT_IMPLEMENTED = 0x00000201 ,   BJ_ERROR_SYSTEM = 0x00000002 , BJ_ERROR_FILE_NOT_FOUND = 0x00000102 , BJ_ERROR_CANNOT_ALLOCATE = 0x00000202 , BJ_ERROR_INITIALIZE = 0x00000302 ,   BJ_ERROR_DISPOSE = 0x00000302 , BJ_ERROR_IO = 0x00000003 , BJ_ERROR_CANNOT_READ_FILE = 0x00000103 , BJ_ERROR_INVALID_DATA = 0x00000004 ,   BJ_ERROR_INVALID_FORMAT = 0x00000104 , BJ_ERROR_INCORRECT_VALUE = 0x00000204 , BJ_ERROR_VIDEO = 0x00000005 , BJ_ERROR_AUDIO = 0x00000006 }
	A numeric representation of an error in Banjo. More...

Functions
void	bj_set_error (bj_error **p_error, uint32_t code, const char *message)
	Fills in a bj_error object with given code and message.
bj_bool	bj_error_check (const bj_error *p_error, uint32_t code)
	Checks if the given error matches the error code.
bj_bool	bj_forward_error (bj_error *p_source, bj_error **p_destination)
	Forward an error into another error location.
void	bj_clear_error (bj_error **p_error)
	Clears the given error location.

---

Data Structure Documentation

bj_error

struct bj_error

Described any error reported by a potentially failing function.

Banjo-internals guarantee code to be a value of bj_error_code.

Examples

audio_pcm.c, bitmap_blit.c, drawing_2d.c, events.c, handling_errors.c, load_bmp.c, shaders.c, sprite_animation.c, time.c, and window.c.

Data Fields
uint32_t	code	Error code.
char	message[BJ_ERROR_MESSAGE_MAX_LEN+1]	Optional error description.

Macro Definition Documentation

bj_error_code_is_user

#define bj_error_code_is_user   (c) (((c >> 24) & 0xFF) > 0x00)

All Banjo error codes are guaranted to have their most signigicant byte set to 0x00. This helper macro evaluates to BJ_TRUE if the provided error is user-defined.

Parameters

c	The error code

bj_error_code_kind

#define bj_error_code_kind

(

c

)

Value:

(c & 0x000000FF)

Banjo error codes are hierarchical. The least significant byte is the same value for all error codes of the same kind, and corresponds to the generic error code value of the said kind.

This helper macro evaluates to the kind error code of any given code.

For example, bj_error_code_kind(BJ_ERROR_CANNOT_ALLOCATE) evaluates to BJ_ERROR_OS.

Parameters

c	The error code

Enumeration Type Documentation

bj_error_code

enum bj_error_code

Within a bj_error object, the first field is a uint32_t value indicating the type of error encountered.

An error code is a 32-bit value composed as follows:

• The most significant byte is always 0x00.
• The least significant byte represents the error kind.
• The two middle bytes represent the specific error code.

For example, BJ_ERROR_INCORRECT_VALUE is 0x204, where:

• The most significant byte is 0x00,
• The next two bytes are 0x0002,
• The least significant byte is 0x04.

Internal specifier

The most significant byte is always 0x00 for Banjo errors. User applications can set a different value to this byte to identify the origin of the error code.

You can use bj_error_code_is_user to check if an error code is defined outside of Banjo.

Error Kind

The error kind is a numerical value set on the least significant byte that is the same for all values of the same category.

For example, BJ_ERROR_INVALID_FORMAT and BJ_ERROR_INCORRECT_VALUE have the same kind, which is equal to 0x04.

Every error kind has its own error code, represented by a uint32_t with only the least significant byte set. For example: BJ_ERROR_INVALID_DATA.

You can use bj_error_code_kind to get the error kind code of any error code.

Enumerator
BJ_ERROR_NONE	No Error.
BJ_ERROR	General Error (unspecified)
BJ_ERROR_UNSUPPORTED	Unsupported operation error.
BJ_ERROR_NOT_IMPLEMENTED	Unsupported operation error.
BJ_ERROR_SYSTEM	Generic OS error.
BJ_ERROR_FILE_NOT_FOUND	The requested file was not found.
BJ_ERROR_CANNOT_ALLOCATE	Cannot allocate the specified memory block.
BJ_ERROR_INITIALIZE	A system component cannot be initalized.
BJ_ERROR_DISPOSE	A system component cannot be terminated properly.
BJ_ERROR_IO	IO-related errors.
BJ_ERROR_CANNOT_READ_FILE	Error while attempting to read a file.
BJ_ERROR_INVALID_DATA	Incorrect data.
BJ_ERROR_INVALID_FORMAT	Data format does not match expected format.
BJ_ERROR_INCORRECT_VALUE	Mismatched expected value.
BJ_ERROR_VIDEO	Error while running video layer.
BJ_ERROR_AUDIO	Error while running audio layer.

Function Documentation

bj_clear_error()

void bj_clear_error

(

bj_error **

p_error

)

Parameters

p_error

The error to clear.

Examples

handling_errors.c.

bj_error_check()

bj_bool bj_error_check	(	const bj_error *	p_error,
		uint32_t	code )

If p_error is 0, return false, which must be interpreted as "no error". Otherwise, returns true only if p_error->code == code.

Parameters

p_error	The error to check
code	The error code to match

Returns

true if p_error matches code, false otherwise.

Examples

handling_errors.c.

bj_forward_error()

bj_bool bj_forward_error	(	bj_error *	p_source,
		bj_error **	p_destination )

This function is used when calling an error-returning function from another error-returning function.

If p_source contains a non-zero error, it is moved to p_destination. If *p_destination already contains an error, p_source is only logged (using bj_error).

Parameters

p_source	The source error.
p_destination	The destination error pointer.

Returns

BJ_TRUE if both p_source and p_destination are non-zero. When this happens, this means there was an error to propagate and that the caller asked for it.

Examples

handling_errors.c.

bj_set_error()

void bj_set_error	(	bj_error **	p_error,
		uint32_t	code,
		const char *	message )

Parameters

p_error	The error to fill in.
code	Error code.
message	The error message to set.

If p_error is null, the function does nothing.

If p_error is not null, the function only stored the error if code == 0. Otherwise, code and message are only reported as logs.

message must point to a 0-terminated C-string of at max BJ_ERROR_MESSAGE_MAX_LEN character. If the given string is larger, it is truncated to BJ_ERROR_MESSAGE_MAX_LEN and the nul pointer is enforced.

Examples

handling_errors.c.