Failure reporting/handling

Failure API used all over the CAPS universe. More...

Macros
#define	caps_developers_failure_report(fmt)
#define	caps_memory_failure_report(fn)
#define	caps_assert(expr)
	Assert the given expression is true, else terminate the program.

Functions
void	caps_developers_failure_report_and_terminate (const char *scope, const char *fn, int ln, const char *message)
void	caps_memory_failure_report_and_terminate (const char *scope, const char *fn, int ln)
void	caps_terminate (int rc)

Detailed Description

Don't do failure reporting and termination by your own, use the functions provided by this library instead.

Macro Definition Documentation

caps_developers_failure_report

#define caps_developers_failure_report

(

fmt

)

Convenience macro to report a bad usage

caps_developers_failure_report("Some message");

It parametrizes the call to caps_developers_failure_report_and_terminate()

Attention

The message has no printf() style. It is just one fixed string.

caps_memory_failure_report

#define caps_memory_failure_report

(

fn

)

Convenience macro to report a lack of memory

caps_memory_failure_report(__func__);

Since the system is out of resources, it is most of the time a useless action to report more than the function name here. Use the __func__ macro provided by the compiler.

It parametrizes the call to caps_memory_failure_report_and_terminate()

caps_assert

#define caps_assert

(

expr

)

Parameters

[in]

expr

The expression to check

Creates an error message of the form:

  <filename>:<line number>: <function name>: Assertion '<assertion>' failed

and a stack trace (if supported on the architecture) and terminates (or aborts) the program.

It uses caps_terminate() to terminate.

Function Documentation

caps_developers_failure_report_and_terminate()

void caps_developers_failure_report_and_terminate	(	const char *	scope,
		const char *	fn,
		int	ln,
		const char *	message
	)

Report a bad usage of something and terminate

Parameters

[in]	message	Main failure description (in English) without newline
[in]	scope	The report's scope, like it's package name
[in]	fn	Name of the function, this report is from
[in]	ln	Line number this call is from

Report the message and add a stack trace when debugging is enabled. Then terminate.

The goal is to terminate whenever something is used in a bad way. This should force the developer to fix the code and do things right. I know this is a pain - but it is intentional.

Refer Abort or Exit Choice how to setup if exit() or abort() is used to terminate.

Attention

The message has no printf() style. It is just one fixed string.

Note

This function does not return

Precondition

The given message is not intended for translation (NLS). It should be for the developer and thus, English language is enough.

caps_memory_failure_report_and_terminate()

void caps_memory_failure_report_and_terminate	(	const char *	scope,
		const char *	fn,
		int	ln
	)

Report a memory failure and terminate

Parameters

[in]	scope	The report's scope, like it's package name
[in]	fn	The function name where the failure happened
[in]	ln	Line number this call is from

Report something when the system is out of resources is most of the time a useless action. But we can still try... and then terminate/abort the process

Refer Abort or Exit Choice how to setup if exit() or abort() is used to terminate.

Note

This function does not return

caps_terminate()

void caps_terminate

(

int

rc

)

Generic function to terminate with a backtrace. It is more a development feature

Parameters

[in]

rc

Return value to the OS, used if '–disable-abort' is used while configuration

Refer Abort or Exit Choice how to setup if exit() or abort() is used to terminate.

Precondition

No memory pressure

In order to make the backtrace work as expected, full debug must be enabled when configuring the library. Refer Setting up Debugging Support for details.

Note

This function does not return