ObitErr.h File Reference

ObitErr Error stack class definition. More...

#include <glib.h>

Go to the source code of this file.

Classes
struct	ObitErr
	ObitErr Class structure. More...
struct	ObitErrElem
	ObitErr Stack Element structure. More...
Defines
#define	OBITERRBUFSIZE   120
	Size of message buffer in characters.
#define	Obit_log_error(err, errCode, format...)
	Macro to log error message adds errMsg/traceback to err for errors err = ObitErr to receive messages.
#define	Obit_log_error_no_trace(err, errCode, format...)
	Macro to log error message without tracepacb Evaluates expression and if false, adds errMsg/traceback to err err = ObitErr to receive messages.
#define	Obit_return_if_fail(expr, err, format...)
	Macro to evaluate expression, log in err and return on failure.
#define	Obit_retval_if_fail(expr, err, out, format...)
	Macro to evaluate expression, log in err and return a value on failure.
#define	Obit_traceback_msg(err, me, name)
	Macro for traceback when an error in a called routine is encountered.
#define	Obit_traceback_val(err, me, name, out)
	Macro for traceback logging with a return value Writes traceback info and returns, optionally passing a value.
#define	Obit_cfitsio_error(err)
	Macro to dump cfitsio error stack to an ObitErr.
Enumerations
enum	ObitErrCode {   OBIT_None = 0, OBIT_InfoErr, OBIT_InfoWarn, OBIT_Traceback,   OBIT_MildError, OBIT_Error, OBIT_StrongError, OBIT_Fatal }
	enum for error codes. More...
Functions
ObitErr *	newObitErr (void)
	Public: Constructor.
ObitErr *	ObitErrRef (ObitErr *in)
	Public: Reference to object, update reference count.
ObitErr *	ObitErrUnref (ObitErr *in)
	Public: Unreference object, destroy if no more references.
void	ObitErrClear (ObitErr *in)
	Public: Clear error stack.
void	ObitErrClearErr (ObitErr *in)
	Public: Clear only error messages and status in stack.
void	ObitErrPush (ObitErr *in, ObitErrCode errLevel, gchar *errMsg)
	Public: Add entry in error stack.
void	ObitErrPop (ObitErr *in, ObitErrCode *errLevel, gchar **errMsg)
	Public: Pop last entry from top of stack.
void	ObitErrLog (ObitErr *in)
	Public: Write all entries in log file.
gboolean	ObitErrIsA (ObitErr *in)
	Public: Returns true if input is a ObitErr*.

---

Detailed Description

ObitErr Error stack class definition.

This is an error stack class for obtaining tracebacks for error conditions. When an error is detected, it should be entered onto the ObitErr and the function returns. Each function with an ObitErr argument should check at the beginning to see if an error condition already exists (number > 0) and if so return. Any function calling a function which encounters an error should add its message to the stack and return. Numerous macroes assist with use of the ObitErr.

A number of macroes are defined to simplify managing the error stack. Implementation uses a glib GQueue.

Usage of member pointers.

Instances can be obtained using the newObitErr constructor or a pointer duplicated using the ObitErrRef function. When an instance is no longer needed, use the ObitErrUnref function to release it.

---

Define Documentation

#define Obit_cfitsio_error (  err   )

Value: G_STMT_START{ \ while (fits_read_errmsg(err->buffer)) \ ObitErrPush (err, OBIT_Error, err->buffer); \ fits_clear_errmsg(); }G_STMT_END Macro to dump cfitsio error stack to an ObitErr. Clears cfitsio error stack when done err = ObitErr to recieve messages.

#define Obit_log_error (  err, errCode, format...   )

Value: G_STMT_START{ \ g_snprintf (err->buffer, OBITERRBUFSIZE, format); \ ObitErrPush (err, errCode, err->buffer); \ if (errCode>OBIT_Traceback) { \ g_snprintf (err->buffer, OBITERRBUFSIZE, \ " This occured at file %s: line %d (%s)", \ __FILE__, __LINE__, __PRETTY_FUNCTION__); \ ObitErrPush (err, OBIT_Error, err->buffer); \ } \ }G_STMT_END Macro to log error message adds errMsg/traceback to err for errors err = ObitErr to receive messages. errCode = ObitErr level for message format = formatting string and arguments.

#define Obit_log_error_no_trace (  err, errCode, format...   )

Value: G_STMT_START{ \ g_snprintf (err->buffer, OBITERRBUFSIZE, format); \ ObitErrPush (err, errCode, err->buffer); \ }G_STMT_END Macro to log error message without tracepacb Evaluates expression and if false, adds errMsg/traceback to err err = ObitErr to receive messages. errCode = ObitErr level for message format = formatting string and arguments.

#define Obit_return_if_fail (  expr, err, format...   )

Value: G_STMT_START{ \ if (expr) { } else { \ g_snprintf (err->buffer, OBITERRBUFSIZE, format); \ ObitErrPush (err, OBIT_Error, err->buffer); \ g_snprintf (err->buffer, OBITERRBUFSIZE, \ " Occured at file %s: line %d (%s)", \ __FILE__, __LINE__, __PRETTY_FUNCTION__); \ ObitErrPush (err, OBIT_Error, err->buffer); \ return; \ } }G_STMT_END Macro to evaluate expression, log in err and return on failure. Evaluates expression and if false, adds errMsg to err log the location and then return (no return value). \ li expr = expression to evaluate err = ObitErr to receive messages. format = formatting string and arguments.

#define Obit_retval_if_fail (  expr, err, out, format...   )

Value: G_STMT_START{ \ if (expr) { } else { \ g_snprintf (err->buffer, OBITERRBUFSIZE, format); \ ObitErrPush (err, OBIT_Error, err->buffer); \ g_snprintf (err->buffer, OBITERRBUFSIZE, \ " Occured at file %s: line %d (%s)", \ __FILE__, __LINE__, __PRETTY_FUNCTION__); \ ObitErrPush (err, OBIT_Error, err->buffer); \ return out; \ } }G_STMT_END Macro to evaluate expression, log in err and return a value on failure. Evaluates expression and if false, adds errMsg to err log the location and then return, passing out if nonNULL. expr = expression to evaluate err = ObitErr to receive messages. out = return value. format = formatting string and arguments.

#define Obit_traceback_msg (  err, me, name   )

Value: G_STMT_START{ \ g_snprintf (err->buffer, OBITERRBUFSIZE, \ "Traceback: routine %s: object %s", me, name); \ ObitErrPush (err, OBIT_Traceback, err->buffer); \ g_snprintf (err->buffer, OBITERRBUFSIZE, \ " Occured at file %s: line %d (%s)", \ __FILE__, __LINE__, __PRETTY_FUNCTION__); \ ObitErrPush (err, OBIT_Traceback, err->buffer); \ return; \ }G_STMT_END Macro for traceback when an error in a called routine is encountered. Writes traceback info and returns (no return value). err = ObitErr structure to log to. me = name of calling routine; name = object name.

#define Obit_traceback_val (  err, me, name, out   )

Value: G_STMT_START{ \ g_snprintf (err->buffer, OBITERRBUFSIZE, \ "Traceback: routine %s: object %s", me, name); \ ObitErrPush (err, OBIT_Traceback, err->buffer); \ g_snprintf (err->buffer, OBITERRBUFSIZE, \ " at file %s: line %d (%s)", \ __FILE__, __LINE__, __PRETTY_FUNCTION__); \ ObitErrPush (err, OBIT_Traceback, err->buffer); \ return out; \ }G_STMT_END Macro for traceback logging with a return value Writes traceback info and returns, optionally passing a value. err = ObitErr structure to log to. me = name of calling routine; name = object name. out = return code

#define OBITERRBUFSIZE   120

Size of message buffer in characters.

---

Enumeration Type Documentation

enum ObitErrCode

enum for error codes. Should be coordinated with ObitErrorLevelString in ObitErr.c. Enumeration values: OBIT_None  no message OBIT_InfoErr  information OBIT_InfoWarn  warning OBIT_Traceback  no new error - use for traceback OBIT_MildError  mild error OBIT_Error  error OBIT_StrongError  serious error OBIT_Fatal  Fatal condition.

---

Function Documentation

ObitErr* newObitErr (  void   )

Public: Constructor. Returns: the new object.

void ObitErrClear (  ObitErr *  in  )

Public: Clear error stack. Parameters: in  Pointer to object to clear. Returns: NULL pointer.

void ObitErrClearErr (  ObitErr *  in  )

Public: Clear only error messages and status in stack. Parameters: in  Pointer to object to clear. Returns: NULL pointer.

gboolean ObitErrIsA (  ObitErr *  in  )

Public: Returns true if input is a ObitErr*. Parameters: in  Pointer to object to test. Returns: TRUE if member else FALSE.

void ObitErrLog (  ObitErr *  in  )

Public: Write all entries in log file. Stack will be cleared when done Parameters: in  Input ObitErr. NULL if there are no more messages.

void ObitErrPop (  ObitErr *  in, ObitErrCode *  errLevel, gchar **  errMsg )

Public: Pop last entry from top of stack. This item is then removed. Parameters: in  Input ObitErr. errLevel  (output) Error level code. errMsg  (output) Error message (deallocate with g_free when done). NULL if there are no more messages.

void ObitErrPush (  ObitErr *  in, ObitErrCode  errLevel, gchar *  errMsg )

Public: Add entry in error stack. Parameters: in  Pointer to object to add message to. errLevel  Error level code. errMsg  Error message.

ObitErr* ObitErrRef (  ObitErr *  in  )

Public: Reference to object, update reference count. This function should always be used to copy pointers as this will ensure a proper reference count. Parameters: in  Pointer to object to link. Returns: the pointer to in.

ObitErr* ObitErrUnref (  ObitErr *  in  )

Public: Unreference object, destroy if no more references. Parameters: in  Pointer to object to unlink. Returns: NULL pointer.

---