functions
📝:
Exception context handling functions:
-
e4c_context_is_ready: checks if the current exception context is ready. -
e4c_context_begin: begins an exception context. -
e4c_context_end: ends the current exception context. -
e4c_context_set_signal_mappings: assigns the specified signal mappings to the exception context. -
e4c_context_get_signal_mappings: retrieves the signal mappings for the current exception context. -
e4c_get_status: e4cgetstatus returns the completeness status of the executing code block. -
e4c_get_exception: returns the exception that was thrown.
Other integration and convenience functions:
-
e4c_library_version: gets the library version number. -
e4c_is_instance_of: returns whether an exception instance is of a given type. -
e4c_print_exception: prints a fatal error message regarding the specified exception. -
e4c_print_exception_type: prints an ASCII graph representing an exception type's hierarchy.
Checks if the current exception context is ready.
- Whether the current exception context of the program (or current thread) is ready to be used.
This function returns whether there is an actual exception context ready to be used by the program or current thread.
Begins an exception context.
-
handle_signals: ifE4C_TRUE, the signal handling system will be set up with the default mapping.
This function begins the current exception context to be used by the program (or current thread), until e4c_context_end is called.
Calling e4c_context_begin twice is considered a programming error, and therefore the program (or thread) will exit abruptly. Nevertheless, e4c_context_begin can be called several times if, and only if, e4c_context_end is called in between.
The signal handling system can be automatically initialized with the default signal mapping via handle_signals parameter when calling e4c_context_begin. This is equivalent to:
e4c_context_set_signal_mappings(e4c_default_signal_mappings);
Warning: Note that, on some specific platforms, the behavior of the standard signal function might be undefined for a multithreaded program, so use the signal handling system with caution.
The convenience function e4c_print_exception will be used as the default uncaught handler. It will be called in the event of an uncaught exception, before exiting the program or thread. This handler can be set through the function e4c_context_set_handlers.
- [e4c_context_end]functions.md#e4c_context_end)
- [e4c_context_is_ready]functions.md#e4c_context_is_ready)
- [e4c_using_context]macros.md#e4c_using_context)
- [e4c_reusing_context]macros.md#e4c_reusing_context)
- [e4c_uncaught_handler]types.md#e4c_uncaught_handler)
- [e4c_print_exception]functions.md#e4c_print_exception)
- [e4c_context_set_handlers]functions.md#e4c_context_set_handlers)
Ends the current exception context.
This function ends the current exception context.
- A program (or thread) must begin an exception context prior to calling
e4c_context_end. Such programming error will lead to an abrupt exit of the program (or thread).
Assigns the specified signal mappings to the exception context.
-
mappings: the array of mappings.
This function assigns an array of mappings between the signals to be handled and the corresponding exception to be thrown.
Warning: Note that, on some specific platforms, the behavior of the standard signal function might be undefined for a multithreaded program, so use the signal handling system with caution.
- A program (or thread) must begin an exception context prior to calling
e4c_context_set_signal_mappings. Such programming error will lead to an abrupt exit of the program (or thread). -
mappingsmust be terminated by E4C_NULL_SIGNAL_MAPPING.
Retrieves the signal mappings for the current exception context.
- The current array of mappings.
This function retrieves the current array of mappings between the signals to be handled and the corresponding exception to be thrown.
- A program (or thread) must begin an exception context prior to calling
e4c_context_get_signal_mappings. Such programming error will lead to an abrupt exit of the program (or thread).
Returns the completeness status of the executing code block.
- The completeness status of the executing code block.
Exception-aware code blocks have a completeness status regarding the exception handling system. This status determines whether an exception was actually thrown or not, and whether the exception was caught or not.
The status of the current block can be obtained any time, provided that the exception context has begun at the time of the function call. However, it is sensible to call this function only during the execution of finally blocks.
- A program (or thread) must begin an exception context prior to calling
e4c_get_status. Such programming error will lead to an abrupt exit of the program (or thread).
Returns the exception that was thrown.
- The exception that was thrown in the current exception context (if any) otherwise
NULL.
This function returns a pointer to the exception that was thrown in the surrounding exception-aware block, if any; otherwise NULL.
The function e4c_is_instance_of will determine if the thrown exception is an instance of any of the defined exception types. The type of the thrown exception can also be compared for an exact type match.
try{
/* ... */
}catch(RuntimeException){
const e4c_exception * exception = e4c_get_exception();
if( e4c_is_instance_of(exception, SignalException.type) ){
/* ... */
}else if(exception->type == NotEnoughMemoryException.type){
/* ... */
}
}
The thrown exception can be obtained any time, provided that the exception context has begun at the time of the function call. However, it is sensible to call this function only during the execution of finally or catch blocks.
Moreover, a pointer to the thrown exception obtained inside a finally or catch block must not be used from the outside.
The exception system objects are dinamically allocated and deallocated, as the program enters or exits try/catch/finally blocks. While it is legal to copy the thrown exception and access its name and message outside these blocks, care must be taken in order not to dereference the cause of the exception, unless it is a deep copy (as opposed to a shallow copy).
- A program (or thread) must begin an exception context prior to calling
e4c_get_exception. Such programming error will lead to an abrupt exit of the program (or thread).
Gets the library version number.
- The version number associated with the library.
This function provides the same information as the E4C_VERSION_NUMBER macro, but the returned version number is associated with the actual, compiled library.
Note: This version number can be considered as the run-time library version number, as opposed to the compile-time library version number (specified by the header file).
Remarks: The library must be compiled with the corresponding header (i.e. library version number should be equal to header version number).
Returns whether an exception instance is of a given type.
-
instance: the thrown exception. -
exception_type: a previously defined type of exceptions.
- Whether the specified exception is an instance of the given type.
e4c_is_instance_of can be used to determine if a thrown exception is an instance of a given type defined through E4C_DEFINE_EXCEPTION and/or declared through E4C_DECLARE_EXCEPTION.
This macro is intended to be used in a catch block, or in a finally block provided that some exception was actually thrown (i.e. e4c_get_status returned e4c_failed or e4c_recovered).
try{
...
}catch(RuntimeException){
const e4c_exception * exception = e4c_get_exception();
if( e4c_is_instance_of(exception, SignalException.type) ){
...
}else if(exception->type == NotEnoughMemoryException.type){
...
}
}
-
instancecannot beNULL. -
typecannot beNULL.
-
NullPointerException: if eitherinstanceortypeisNULL.
Prints a fatal error message regarding the specified exception.
-
exception: the uncaught exception.
This is a convenience function for showing an error message through the standard error output. It can be passed to e4c_context_set_handlers as the handler for uncaught exceptions, and will be used, by default, unless otherwise set up.
In absence of NDEBUG, this function prints as much information regarding the exception as it is available, whereas in presence of NDEBUG, only the name and message of the exception are printed.
-
exceptioncannot beNULL.
-
NullPointerException: ifexceptionisNULL.
Prints an ASCII graph representing an exception type's hierarchy.
-
exception_type: an exception type.
This is a convenience function for showing an ASCII graph representing an exception type's hierarchy through the standard error output.
For example, the output for ProgramSignal2Exception would be:
Exception hierarchy
________________________________________________________________
RuntimeException
|
+--SignalException
|
+--ProgramSignalException
|
+--ProgramSignal2Exception
________________________________________________________________
-
exception_typecannot beNULL.
-
NullPointerException: ifexception_typeisNULL.
