ooc 1.3
Object Oriented tollkit fo ANSI C

exception.h File Reference

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:

Defines

#define end_try
 Closing mark for the try catch construct.
Exception handling.
#define try
 Opens a try ...
#define catch(ec)
 Catches an exception of a given class.
#define catch_any
 Catches any thrown Exceptions.
#define finally
 Finally block.
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.
#define ooc_manage_object(p_target)
 Manage an Object.
#define ooc_pass(target)
 Removes the most recently pushed pointer from the managed pointers' stack.

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.
int exception_get_error_code (const Exception exception)
 Gets the ooc core error code.
int exception_get_user_code (const Exception exception)
 Gets the user error code.
void ooc_throw (Exception exception)
 Throws an exception.
void ooc_rethrow (void)
 Retrhows a caught exception.

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;

Define 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:
ecThe 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_targetPointer to the resource to be managed.
p_destroyerAppropriate 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_targetPointer 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:
targetThe 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

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:
exceptionThe 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:
exceptionThe 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:
errorooc 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:
exceptionThe 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.
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines