Exception Handling
[Miscelaneous]

Functions
pj_status_t	pj_exception_id_alloc (const char name, pj_exception_id_t id)
pj_status_t	pj_exception_id_free (pj_exception_id_t id)
const char *	pj_exception_id_name (pj_exception_id_t id)

Detailed Description

Quick Example

For the impatient, take a look at some examples:

This module provides exception handling syntactically similar to C++ in C language. In Win32 systems, it uses Windows Structured Exception Handling (SEH) if macro PJ_EXCEPTION_USE_WIN32_SEH is non-zero. Otherwise it will use setjmp() and longjmp().

On some platforms where setjmp/longjmp is not available, setjmp/longjmp implementation is provided. See <pj/compat/setjmp.h> for compatibility.

The exception handling mechanism is completely thread safe, so the exception thrown by one thread will not interfere with other thread.

The exception handling constructs are similar to C++. The blocks will be constructed similar to the following sample:

   #define NO_MEMORY     1
   #define SYNTAX_ERROR  2
  
   int sample1()
   {
      PJ_USE_EXCEPTION;  // declare local exception stack.
  
      PJ_TRY {
        ...// do something..
      }
      PJ_CATCH(NO_MEMORY) {
        ... // handle exception 1
      }
      PJ_END;
   }

   int sample2()
   {
      PJ_USE_EXCEPTION;  // declare local exception stack.
  
      PJ_TRY {
        ...// do something..
      }
      PJ_CATCH_ANY {
         if (PJ_GET_EXCEPTION() == NO_MEMORY)
	    ...; // handle no memory situation
	 else if (PJ_GET_EXCEPTION() == SYNTAX_ERROR)
	    ...; // handle syntax error
      }
      PJ_END;
   }

The above sample uses hard coded exception ID. It is strongly recommended that applications request a unique exception ID instead of hard coded value like above.

Exception ID Allocation

To ensure that exception ID (number) are used consistently and to prevent ID collisions in an application, it is strongly suggested that applications allocate an exception ID for each possible exception type. As a bonus of this process, the application can identify the name of the exception when the particular exception is thrown.

Exception ID management are performed with the following APIs:

PJLIB itself automatically allocates one exception id, i.e. PJ_NO_MEMORY_EXCEPTION which is declared in <pj/pool.h>. This exception ID is raised by default pool policy when it fails to allocate memory.

CAVEATS:

unlike C++ exception, the scheme here won't call destructors of local objects if exception is thrown. Care must be taken when a function hold some resorce such as pool or mutex etc.

You CAN NOT make nested exception in one single function without using a nested PJ_USE_EXCEPTION. Samples:

	void wrong_sample()
	{
	    PJ_USE_EXCEPTION;

	    PJ_TRY {
		// Do stuffs
		...
	    }
	    PJ_CATCH_ANY {
		// Do other stuffs
		....
		..

		// The following block is WRONG! You MUST declare 
		// PJ_USE_EXCEPTION once again in this block.
		PJ_TRY {
		    ..
		}
		PJ_CATCH_ANY {
		    ..
		}
		PJ_END;
	    }
	    PJ_END;
	}

You MUST NOT exit the function inside the PJ_TRY block. The correct way is to return from the function after PJ_END block is executed. For example, the following code will yield crash not in this code, but rather in the subsequent execution of PJ_TRY block:
```
        void wrong_sample()
	{
	    PJ_USE_EXCEPTION;

	    PJ_TRY {
		// do some stuffs
		...
		return;	        <======= DO NOT DO THIS!
	    }
	    PJ_CATCH_ANY {
	    }
	    PJ_END;
	}
  
```

You can not provide more than PJ_CATCH or PJ_CATCH_ANY nor use PJ_CATCH and PJ_CATCH_ANY for a single PJ_TRY.
Exceptions will always be caught by the first handler (unlike C++ where exception is only caught if the type matches.

Keywords

PJ_THROW(expression)

Throw an exception. The expression thrown is an integer as the result of the expression. This keyword can be specified anywhere within the program.

PJ_USE_EXCEPTION

Specify this in the variable definition section of the function block (or any blocks) to specify that the block has PJ_TRY/PJ_CATCH exception block. Actually, this is just a macro to declare local variable which is used to push the exception state to the exception stack. Note: you must specify PJ_USE_EXCEPTION as the last statement in the local variable declarations, since it may evaluate to nothing.

PJ_TRY

The PJ_TRY keyword is typically followed by a block. If an exception is thrown in this block, then the execution will resume to the PJ_CATCH handler.

PJ_CATCH(expression)

The PJ_CATCH is normally followed by a block. This block will be executed if the exception being thrown is equal to the expression specified in the PJ_CATCH.

PJ_CATCH_ANY

The PJ_CATCH is normally followed by a block. This block will be executed if any exception was raised in the TRY block.

PJ_END

Specify this keyword to mark the end of PJ_TRY / PJ_CATCH blocks.

PJ_GET_EXCEPTION(void)

Get the last exception thrown. This macro is normally called inside the PJ_CATCH or PJ_CATCH_ANY block, altough it can be used anywhere where the PJ_USE_EXCEPTION definition is in scope.

Examples

For some examples on how to use the exception construct, please see:

Function Documentation

pj_status_t pj_exception_id_alloc	(	const char *	name,
		pj_exception_id_t *	id
	)

Allocate a unique exception id. Applications don't have to allocate a unique exception ID before using the exception construct. However, by doing so it ensures that there is no collisions of exception ID.

As a bonus, when exception number is acquired through this function, the library can assign name to the exception (only if PJ_HAS_EXCEPTION_NAMES is enabled (default is yes)) and find out the exception name when it catches an exception.

Parameters:

	name	Name to be associated with the exception ID.
	id	Pointer to receive the ID.

Returns:: PJ_SUCCESS on success or PJ_ETOOMANY if the library is running out out ids.

pj_status_t pj_exception_id_free ( pj_exception_id_t id )

Free an exception id.

Parameters:

id

The exception ID.

Returns:: PJ_SUCCESS or the appropriate error code.

const char* pj_exception_id_name ( pj_exception_id_t id )

Retrieve name associated with the exception id.

Parameters:

id

The exception ID.

Returns:: The name associated with the specified ID.

Exception Handling [Miscelaneous]

Functions

Detailed Description

Function Documentation

Exception Handling
[Miscelaneous]