Exception class - a standard ooc error reporting class. More...

#include "ooc.h"

Include dependency graph for exception.h:

This graph shows which files directly or indirectly include this file:

Macros
#define	end_try
	Closing mark for the try catch construct. More...

Exception handling.
#define	try
	Opens a try ... More...

#define	catch(ec)
	Catches an exception of a given class. More...

#define	catch_any
	Catches any thrown Exceptions. More...

#define	finally
	Finally block. More...

Managed pointers, managed Objects
Using managed pointers you will not get the program control in case of an exception, but it is guaranteed, that the memory is freed or the Object is deleted in case of an exception. (You may consider this as analogie for `std::auto_ptr<>` in C++.) Using managed pointers is faster than using the `try`...finally...end_try constructs, so it is more advisable if you do not need the program control in case of an exception. Warning Use `ooc_manage()` / `ooc_manage_object()` and `ooc_pass()` always as a pair in the same name scope! These macros use local variables, and the variable created by `ooc_manage()` must be accessible by `ooc_pass()!` Never let `ooc_manage()` be executed more than once without executing the corresponding `ooc_pass()` before!
#define	ooc_manage(p_target, p_destroyer)
	Manage a pointer. More...

#define	ooc_manage_object(p_target)
	Manage an Object. More...

#define	ooc_pass(target)
	Removes the most recently pushed pointer from the managed pointers' stack. More...

Typedefs
typedef struct ExceptionObject *	Exception
	Exception class declaration.

Enumerations
enum	error_codes { err_no_error = 0, err_out_of_memory, err_bad_throw, err_bad_cast, err_undefined_virtual, err_uninitialized, err_can_not_be_duplicated, err_wrong_position, err_bad_connect, err_already_in_use, err_interface_not_implemented, err_user_code = ~0 }
	Error codes. More...

Functions
Exception	exception_new (enum error_codes error)
	Creates a new ooc system Exception. More...

int	exception_get_error_code (const Exception exception)
	Gets the ooc core error code. More...

int	exception_get_user_code (const Exception exception)
	Gets the user error code. More...

void	ooc_throw (Exception exception)
	Throws an exception. More...

void	ooc_rethrow (void)
	Retrhows a caught exception. More...

Detailed Description

Exception class - a standard ooc error reporting class.

Exception class is used to throw exceptions either by the ooc core, or by the user of the ooc as well. Exception should be used as a base class for the User defined exception classes. Exceptions can be caught by class types, so if you would like to distinguish the caught exceptions, always use a derived class! The usual way of throwing an excetption is:

ooc_throw( exception_new( err_out_of_memory ) );

The recommended way of using your own exception class is:

DeclareClass( MyException, Exception );
Virtuals( MyException, Exception )
EndOfVirtuals;
ClassMembers( MyException, Exception )
EndOfClassMembers;
AllocateClass( MyException, Exception );
static void MyException_initialize( Class this ) {}
static void MyException_finalize( Class this ) {}
static void MyException_constructor( MyException self, const void * params )
{
    chain_constructor( MyException, self, NULL );
    if( params )
         self->Exception.user_code = * ( (int*) params );
}
static void MyException_destructor( MyException self ) {}
static void MyException_copy( MyException self, MyException other ) { return OOC_COPY_DEFAULT; }
Exception myexception_new( int myerror_code ) 
{ 
        ooc_init_class( MyException );
        return (Exception) ooc_new( MyException, & myerror_code );
}
...
try {
        ooc_throw( myexception_new( 5 ) );
       }
catch( MyException ) {
        printf( "MyException, code %d\n", exception_get_user_code( exception ) );
    }
catch( Exception ) {
        printf( "ooc core Exception, code %d\n", exception_get_error_code( exception ) );
    }
end_try;

Macro Definition Documentation

#define catch ( ec )

Catches an exception of a given class.

It must include exactly one statement, or group of statements in curly braces.

Parameters

ec	The name of the exception class to be caought. Must be a subclass of Exception.

Note: The predefined exception variable of Exception type can be used as the caught object. You must not delete the exception Object!

#define catch_any

Catches any thrown Exceptions.

It must include exactly one statement, or group of statements in curly braces.

Note: The predefined exception variable of Exception type can be used as the caught object. You must not delete the exception Object!

#define end_try

Closing mark for the try catch construct.

This must be used to terminate the try catch finally constructs.

#define finally

Finally block.

This block is executed in every case: either exception was thrown or not, caught or not. It must include exactly one statement, or group of statements in curly braces.

#define ooc_manage	(	p_target,
		p_destroyer
	)

Manage a pointer.

Provides protection to a pointer, preventing memory leak in case of an exception. Pushes a pointer onto the top of the managed pointers' stack.

Parameters

p_target	Pointer to the resource to be managed.
p_destroyer	Appropriate destroyer function for the target (typically `ooc_delete` or `ooc_free`).

Returns: Does not return anything.

See Also: ooc_pass()

#define ooc_manage_object ( p_target )

Manage an Object.

Provides protection to an Object, preventing memory leak in case of an exception. This is a comfortable shortcut for

ooc_manage( my_object, (ooc_destroyer) ooc_delete );

Parameters

p_target Pointer to the Objcet to be managed.

See Also: ooc_pass()

Note: In non-dynamic memory models (OOC_NO_DYNAMIC_MEM) this macro uses ooc_release() instead of ooc_delete(), ensuring proper object destruction but without freeing the allocated memory.

#define ooc_pass ( target )

Removes the most recently pushed pointer from the managed pointers' stack.

Always use in the reverse order of using ooc_manage()! The name is coming from passing the ownership of the pointer to an other object or function.

Parameters

target The pointer to be removed.

Returns: The pointer to the target itself.

Note: Please note that since the most recently pushed pointer is removed, the parameter is used only for verifying that the push an pop orders are correct!

Warning: In release versions this verification is skipped to gain some speed.; Pass a pure pointer only! This macro has a side effect otherwise! (e.g. passing a function as a parameter that returns the object is called twice!)

See Also: ooc_manage(), ooc_manage_object()

#define try

Opens a try ...

catch block. It must include exactly one statement, or group of statements in curly braces.

Enumeration Type Documentation

enum error_codes

Error codes.

These error codes are included in the Exceptions thorwn by the ooc core.

Enumerator
err_no_error	no error
err_out_of_memory	no memory for allocating an object
err_bad_throw	bad use of throw (rethow whithout try, wrong code, etc.)
err_bad_cast	bad cast of an object
err_undefined_virtual	calling of an undefined virtual function
err_uninitialized	Class is uninitialized.
err_can_not_be_duplicated	duplication of an object is invalid
err_wrong_position	insertion at wrong position into a container
err_bad_connect	signal connection failure
err_already_in_use	resource (Object) is already in use
err_interface_not_implemented	The requested interface is not implemented for the class.
err_user_code	Non ooc core exception == user defined exception.

Function Documentation

int exception_get_error_code ( const Exception exception )

Gets the ooc core error code.

Gets the ooc core error code for the Exception.

Parameters

exception The Exception Object.

Returns: ooc core error code.

Note: For user defined exception (Objects inherited from Exception class) this function returns err_user_code.

int exception_get_user_code ( const Exception exception )

Gets the user error code.

Gets the useer error code for the Exception.

Parameters

exception The Exception Object.

Returns: User error code.

Note: For ooc core exceptions (Objects of Exception class) this function returns 0.

Exception exception_new ( enum error_codes error )

Creates a new ooc system Exception.

Creates a new ooc Exception, that must have an error_code of a valid ooc system error code.

Parameters

error ooc system error code.

Returns: New Exception object.

Note: In case of the lack of dynamic memory handling (e.g. mcc18) this method is a fake! Simply returns a statically allocated Exception object, and overwrites the previous contents of it! (This way we can avoid recoding the whole ooc stuff for these platforms.)

void ooc_rethrow ( void )

Retrhows a caught exception.

Can be used only within a catch() or a catch_any block. Must be the last statement in the block!

void ooc_throw ( Exception exception )

Throws an exception.

Exceptions can be thrown anywhere but in Object destructors and in finally blocks.

Parameters

exception The Object to be thrown. Must be a newly created object of Exception class or a derived class. ooc will manage this Exception object, you must not delete it yourself!

Note: An uncaught exception is caught by the ooc core, and aborts the program execution.

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

Enumeration Type Documentation

Function Documentation