except.h File Reference

#include <glib.h>
#include <setjmp.h>
#include <stdlib.h>
#include <stdarg.h>
#include <assert.h>
#include "ws_symbol_export.h"
#include "ws_attributes.h"

Go to the source code of this file.

Classes
struct	except_id_t
	Identifies an exception class by group and code. More...
struct	except_t
	Represents a thrown exception instance, including its identity, message, and dynamic data. More...
struct	except_cleanup
	A cleanup handler registered to run when a scope is exited due to an exception. More...
struct	except_catch
	A catch block descriptor associating a set of exception IDs with a longjmp target. More...
struct	except_stacknode
	Represents a node in the exception handling stack. More...

Macros
#define	XCEPT_GROUP_ANY   0
#define	XCEPT_CODE_ANY   0
#define	XCEPT_BAD_ALLOC   1
#define	except_code(E)   ((E)->except_id.except_code)
#define	except_group(E)   ((E)->except_id.except_group)
#define	except_message(E)   ((E)->except_message)
#define	except_data(E)   ((E)->except_dyndata)
#define	except_cleanup_push(F, C)
#define	except_cleanup_pop(E)
#define	except_checked_cleanup_pop(F, E)
#define	except_cleanup_push_pfx(pfx, F, C)
#define	except_cleanup_pop_pfx(pfx, E)
#define	except_checked_cleanup_pop_pfx(pfx, F, E)
#define	except_try_push(ID, NUM, PPE)
#define	except_try_pop()

Enumerations
enum	{ except_no_call , except_call }
	Discriminator indicating whether an exception context involves a call frame. More...
enum	except_stacktype { XCEPT_CLEANUP , XCEPT_CATCHER }
	Discriminator tag for entries on the exception handler stack. More...

Functions
WS_DLL_PUBLIC void	except_setup_clean (struct except_stacknode *, struct except_cleanup *, void(*)(void *), void *)
	Set up a cleanup handler for exception handling.
WS_DLL_PUBLIC void	except_setup_try (struct except_stacknode *, struct except_catch *, const except_id_t[], size_t)
	Set up a try block for exception handling.
WS_DLL_PUBLIC struct except_stacknode *	except_pop (void)
	Pop the top node from the exception stack.
WS_DLL_PUBLIC int	except_init (void)
	Initialize the exception handling system.
WS_DLL_PUBLIC void	except_deinit (void)
	Deinitialize the exception handling system.
WS_DLL_PUBLIC WS_NORETURN void	except_rethrow (except_t *except)
	Rethrow an exception.
WS_DLL_PUBLIC WS_NORETURN void	except_throw (long group, long code, const char *msg)
	Throw an exception with a message and optional data.
WS_DLL_PUBLIC WS_NORETURN void	except_throwd (long group, long code, const char *msg, void *data)
	Throw an exception with a detailed message and data.
WS_DLL_PUBLIC WS_NORETURN void	except_vthrowf (long group, long code, const char *fmt, va_list vl)
	Throw an exception with a formatted message.
WS_DLL_PUBLIC WS_NORETURN void	except_throwf (long group, long code, const char *fmt,...)
	Throws an exception with a formatted message.
unsigned long	except_code (except_t *ex)
	Retrieves exception code from an exception object.
unsigned long	except_group (except_t *ex)
	Retrieves exception group from an exception object.
const char *	except_message (except_t *ex)
	Retrieves exception message from an exception object.
void *	except_data (except_t *ex)
	Retrieves exception data from an exception object.
WS_DLL_PUBLIC void *	except_take_data (except_t *ex)
	Take data from an exception object.
WS_DLL_PUBLIC void	except_set_allocator (void *(*alloc)(size_t), void(*dealloc)(void *))
	Sets custom memory allocation and deallocation functions for exception handling.
WS_DLL_PUBLIC void *	except_alloc (size_t size)
	Allocates memory for an exception object.
WS_DLL_PUBLIC void	except_free (void *ptr)
	Frees memory allocated for an exception node.
const struct except_stacknode *	except_get_top (void)
	Get the top node from the exception stack.
void	except_set_top (struct except_stacknode *node)
	Set the top node of an exception stack.

Variables
WS_DLL_PUBLIC void(*)(except_t *)	except_unhandled_catcher (void(*new_catcher)(except_t *))
	Sets the unhandled exception catcher.

Detailed Description

Portable Exception Handling for ANSI C.
Modified to support throwing an exception with a null message pointer, and to have the message not be const (as we generate messages with "ws_strdup_printf()", which means they need to be freed; using a null message means that we don't have to use a special string for exceptions with no message, and don't have to worry about not freeing that).

Macro Definition Documentation

except_checked_cleanup_pop

#define except_checked_cleanup_pop	(		F,
			E
	)

Value:

            except_pop();                                       \
        assert (except_cl.except_func == (F));                  \
        if (E)                                                  \
            except_cl.except_func(except_cl.except_context);    \
    }

except_checked_cleanup_pop_pfx

#define except_checked_cleanup_pop_pfx	(		pfx,
			F,
			E
	)

Value:

            except_pop();                                       \
        assert (pfx##_except_cl.except_func == (F));            \
        if (E)                                                  \
            pfx##_except_cl.except_func(pfx##_except_cl.except_context);\
    }

except_cleanup_pop

#define except_cleanup_pop

(

E

)

Value:

        except_pop();                                           \
        if (E)                                                  \
            except_cl.except_func(except_cl.except_context);    \
    }

except_cleanup_pop_pfx

#define except_cleanup_pop_pfx	(		pfx,
			E
	)

Value:

        except_pop();                                           \
        if (E)                                                  \
            pfx##_except_cl.except_func(pfx##_except_cl.except_context);\
    }

except_cleanup_push

#define except_cleanup_push	(		F,
			C
	)

Value:

    {                                                           \
        struct except_stacknode except_sn;                      \
        struct except_cleanup except_cl;                        \
        except_setup_clean(&except_sn, &except_cl, F, C)

except_cleanup_push_pfx

#define except_cleanup_push_pfx	(		pfx,
			F,
			C
	)

Value:

    {                                                           \
        struct except_stacknode pfx##_except_sn;                \
        struct except_cleanup pfx##_except_cl;                  \
        except_setup_clean(&pfx##_except_sn, &pfx##_except_cl, F, C)

except_try_pop

#define except_try_pop

(

)

Value:

        except_free(except_ch.except_obj.except_dyndata);       \
        except_pop();                                           \
    }

except_try_push

#define except_try_push	(		ID,
			NUM,
			PPE
	)

Value:

     {                                                          \
        struct except_stacknode except_sn;                      \
        struct except_catch except_ch;                          \
        except_setup_try(&except_sn, &except_ch, ID, NUM);      \
        if (setjmp(except_ch.except_jmp))                       \
            *(PPE) = &except_ch.except_obj;                     \
        else                                                    \
            *(PPE) = 0

Enumeration Type Documentation

anonymous enum

anonymous enum

Discriminator indicating whether an exception context involves a call frame.

Enumerator
except_no_call	No active function call associated with this context
except_call	An active function call is associated with this context

except_stacktype

enum except_stacktype

Discriminator tag for entries on the exception handler stack.

Enumerator
XCEPT_CLEANUP	Stack entry is a cleanup handler (struct except_cleanup)
XCEPT_CATCHER	Stack entry is a catch block (struct except_catch)

Function Documentation

except_alloc()

WS_DLL_PUBLIC void * except_alloc

(

size_t

size

)

Allocates memory for an exception object.

Parameters

size	The size of the memory to allocate.

Returns

Pointer to the allocated memory.

except_code()

unsigned long except_code ( except_t *  ex )

extern

Retrieves exception code from an exception object.

Parameters

ex	Pointer to the exception object.

Returns

The exception code.

except_data()

void * except_data ( except_t *  ex )

extern

Retrieves exception data from an exception object.

Parameters

ex	Pointer to the exception object.

Returns

The exception data.

except_free()

WS_DLL_PUBLIC void except_free

(

void *

ptr

)

Frees memory allocated for an exception node.

Parameters

ptr	Pointer to the memory to be freed.

except_get_top()

const struct except_stacknode * except_get_top

(

void

)

Get the top node from the exception stack.

Returns

const struct except_stacknode* Pointer to the top node in the exception stack.

except_group()

unsigned long except_group ( except_t *  ex )

extern

Retrieves exception group from an exception object.

Parameters

ex	Pointer to the exception object.

Returns

The exception group.

except_init()

WS_DLL_PUBLIC int except_init

(

void

)

Initialize the exception handling system.

Returns

int 0 on success, -1 on failure.

except_message()

const char * except_message ( except_t *  ex )

extern

Retrieves exception message from an exception object.

Parameters

ex	Pointer to the exception object.

Returns

The exception message.

except_pop()

WS_DLL_PUBLIC struct except_stacknode * except_pop

(

void

)

Pop the top node from the exception stack.

Returns

struct except_stacknode* Pointer to the popped node from the exception stack.

except_rethrow()

WS_DLL_PUBLIC WS_NORETURN void except_rethrow

(

except_t *

except

)

Rethrow an exception.

Parameters

except

Pointer to the exception object.

except_set_allocator()

WS_DLL_PUBLIC void except_set_allocator	(	void *(*)(size_t)	alloc,
		void(*)(void *)	dealloc
	)

Sets custom memory allocation and deallocation functions for exception handling.

Parameters

alloc	Pointer to a function that allocates memory.
dealloc	Pointer to a function that frees memory.

except_set_top()

void except_set_top

(

struct except_stacknode *

node

)

Set the top node of an exception stack.

Parameters

node	Pointer to the new top node of the exception stack.

except_take_data()

WS_DLL_PUBLIC void * except_take_data

(

except_t *

ex

)

Take data from an exception object.

Parameters

ex	Pointer to the exception object.

Returns

The data that was stored in the exception object, or NULL if no data was stored.

except_throw()

WS_DLL_PUBLIC WS_NORETURN void except_throw	(	long	group,
		long	code,
		const char *	msg
	)

Throw an exception with a message and optional data.

Parameters

group	The exception group identifier.
code	The exception code identifier.
msg	The message associated with the exception.

except_throwd()

WS_DLL_PUBLIC WS_NORETURN void except_throwd	(	long	group,
		long	code,
		const char *	msg,
		void *	data
	)

Throw an exception with a detailed message and data.

Parameters

group	The exception group identifier.
code	The exception code.
msg	The exception message.
data	Additional data associated with the exception.

except_throwf()

WS_DLL_PUBLIC WS_NORETURN void except_throwf	(	long	group,
		long	code,
		const char *	fmt,
			...
	)

Throws an exception with a formatted message.

Parameters

group	The exception group.
code	The exception code.
fmt	The format string for the exception message.

except_vthrowf()

WS_DLL_PUBLIC WS_NORETURN void except_vthrowf	(	long	group,
		long	code,
		const char *	fmt,
		va_list	vl
	)

Throw an exception with a formatted message.

Parameters

group	The exception group identifier.
code	The exception code identifier.
fmt	The format string for the exception message.
vl	The variable argument list for the format string.

Variable Documentation

except_unhandled_catcher

WS_DLL_PUBLIC void(*)(except_t *) except_unhandled_catcher(void(*new_catcher)(except_t *))

(

void(*)(except_t *)

new_catcher

)

Sets the unhandled exception catcher.

Parameters

new_catcher

The function to be called when an unhandled exception occurs.

Returns

Pointer to the previous unhandled exception catcher.