Exception handling
[GridLAB-D Core]

---

Detailed Description

Exception handlers are created and caught using the exception module.

Note that the exception handlers are only necessary for C code. This will usually by something like this:

    TRY {
        // some code...
        if (errno)
            THROW("Error %d: %s", errno, strerror(errno));
        // more code...
    } CATCH(char *msg) {
        output_error("Exception caught: %s", msg);
    } ENDCATCH

In C++ code, you can use THROW() to throw an exception that is to be caught by the main system exception handler.

The recommended format for exception messages is as follows:

• Core exceptions should include the offending function call and the specifics of the error in context, as in

          throw_exception("object_tree_add(obj='%s:%d', name='%s'): memory allocation failed (%s)", 
              obj->oclass->name, obj->id, name, strerror(errno));
  

  For functions that a static, you should include the file in which it is implemented, as in

          throw_exception("object.c/addto_tree(tree.name='%s', item.name='%s'): strcmp() returned unexpected value %d", tree->name, item->name, rel);
  

  One important situation to consider are exception that occur during I/O where the context in GridLAB may not be as important the context in the I/O stream, as in

          throw_exception("%s(%d): unexpected EOF", filename, linenum);
  

• Module exception should include the offending object as well as information about the location and nature of the exception, as in

          GL_THROW("%s:%d circuit %d has an invalid circuit type (%d)", obj->oclass->name, obj->id, c->id, (int)c->type);
  

Classes
struct	s_exception_handler
Defines
#define	CATCH(X)   } else {X = exception_msg();
#define	ENDCATCH   } delete_exception_handler(_handler);}
#define	THROW(X)   throw_exception(X);
#define	TRY   { EXCEPTIONHANDLER *_handler = create_exception_handler(); if (_handler==NULL) output_error("%s(%d): exception handler creation failed",__FILE__,__LINE__); else if (setjmp(_handler->buf)==0) {
Typedefs
typedef s_exception_handler	EXCEPTIONHANDLER
	the exception handler structure
Functions
EXCEPTIONHANDLER *	create_exception_handler (void)
	Creates an exception handler for use in a try block.
void	delete_exception_handler (EXCEPTIONHANDLER *ptr)
	Deletes an exception handler from the handler list.
char *	exception_msg (void)
	Retrieves the message of the most recently thrown exception.
void	throw_exception (char *format,...)
	Throw an exception.
Variables
EXCEPTIONHANDLER *	handlers = NULL

---

Function Documentation

EXCEPTIONHANDLER * create_exception_handler

(

void

)

Creates an exception handler for use in a try block.

Returns:

a pointer to an EXCEPTIONHANDLER structure

Definition at line 63 of file exception.c.

References handlers, s_exception_handler::id, s_exception_handler::msg, and s_exception_handler::next.

void delete_exception_handler

(

EXCEPTIONHANDLER *

ptr

)

Deletes an exception handler from the handler list.

Parameters:

ptr	a pointer to the exception handler

Definition at line 75 of file exception.c.

References handlers, and s_exception_handler::next.

char * exception_msg

(

void

)

Retrieves the message of the most recently thrown exception.

Returns:

a char* pointer to the message

Definition at line 113 of file exception.c.

References handlers, and s_exception_handler::msg.

void throw_exception	(	char *	format,
			...
	)

Throw an exception.

Parameters:

format

the format string

Definition at line 89 of file exception.c.

References s_exception_handler::buf, handlers, s_exception_handler::id, s_exception_handler::msg, and output_fatal().

Referenced by aggregate_value(), convert_from_timestamp(), global_create(), kml_dump(), load_tzspecs(), local_datetime(), object_dump(), random_exponential(), random_pareto(), random_sampled(), timestamp_set_tz(), unit_constant(), unit_derived(), unit_init(), and unit_primary().

---

GridLAB-D^TM Version 1.0

An open-source project initiated by the US Department of Energy