Error Handling and Propogation
[State Utility Library]

Defines
#define	sul_error_create   (sul_error_locate(__FILE__,__LINE__), (sul_error_create))
#define	sul_error_quick_wrap   (sul_error_locate(__FILE__,__LINE__), (sul_error_quick_wrap))
#define	SUL_ERR_WRAP0(expr, wrap_msg)
#define	SUL_ERR_WRAP1(expr, wrap_msg, a1)
#define	SUL_ERR_WRAP4(expr, wrap_msg, a1, a2, a3, a4)
#define	SUL_ERR_WRAP3(expr, wrap_msg, a1, a2, a3)
#define	SUL_ERR_WRAP2(expr, wrap_msg, a1, a2)
#define	SUL_ERR_HOOK(expr, code)
#define	SUL_ERR(expr)
#define	SUL_ERR_IGN(expr, code)
#define	SUL_WARN(expr)
#define	SUL_ERR_IGN_ALL(expr)
#define	APR_ERR(expr, pool, msg)
#define	SUL_NO_ERROR   (NULL)
#define	SUL_ERR_NONE   (0)
#define	SUL_ERR_DB_NO_ROWS   (1)
#define	SUL_ERR_DB_TOO_MANY_ROWS   (2)
Functions
	sul_errors_initialize (apr_pool_t *pool)
	sul_pool_create (apr_pool_t *pp, const char *tag)
	sul_error_locate (const char *file, apr_int32_t line)
	sul_errprintf (const char *strf,...)
	sul_error_printf (sul_error_t *err, apr_size_t indention, sul_stringbuf_t *stream, apr_pool_t *pool)
	sul_error_qualify (sul_error_t *err, apr_status_t apr_err, sul_status_t sul_err, sul_error_t *cause)
	sul_error_create (apr_status_t apr_err, sul_status_t sul_err, sul_error_t *cause, const char *msg,...)
	sul_error_quick_wrap (sul_error_t *cause, const char *msg,...)
	sul_error_handle (sul_error_t *error, sul_boolean_t fatal)
	sul_error_get_cause (sul_error_t *error)
	sul_error_get_message (sul_error_t *error)
	sul_error_get_apr_error (sul_error_t *error)
	sul_error_get_sul_error (sul_error_t *error)
	sul_error_destroy (sul_error_t *error)

---

Define Documentation

#define APR_ERR (  expr, pool, msg   )

Value: do { \ apr_status_t apr_err__temp = (expr); \ if (apr_err__temp != APR_SUCCESS) \ return (sul_error_create(apr_err__temp, 0, \ NULL, msg)); \ } while (0)

#define SUL_ERR (  expr   )

Value: do { \ sul_error_t *sul_err__temp = (expr); \ if (sul_err__temp) \ return (sul_err__temp); \ } while (0) If the given expression evaluates to a non null sul_error_t pointer then it'll be returned from the calling function.

#define SUL_ERR_HOOK (  expr, code   )

Value: do { \ sul_error_t *sul_err__temp = (expr); \ if (sul_err__temp) { \ code; \ return (sul_err__temp); \ } \ } while (0) If the given expression evaluates to a non null sul_error_t pointer then it'll be returned from the calling function.

#define SUL_ERR_IGN (  expr, code   )

Value: do { \ sul_error_t *sul_err__temp = (expr); \ if (sul_err__temp) { \ if (sul_error_get_sul_error(sul_err__temp) != code) \ sul_error_destroy(sul_err__temp); \ } \ } while (0) If the given expression evaluates to a non null sul_error_t pointer then it'll be returned from the calling function.

#define SUL_ERR_IGN_ALL (  expr   )

Value: do { \ sul_error_t *sul_err__temp = (expr); \ if (sul_err__temp) \ sul_error_destroy(sul_err__temp); \ } while (0)

#define SUL_ERR_WRAP0 (  expr, wrap_msg   )

Value: do { \ sul_error_t *sul_err__temp = (expr); \ if (sul_err__temp) \ return (sul_error_quick_wrap(sul_err__temp, wrap_msg)); \ } while (0) If the given expression evaluates to a non null sul_error_t pointer then it'll be wrapped in a new error with the given message and then returned from the calling function.

#define SUL_ERR_WRAP1 (  expr, wrap_msg, a1   )

Value: do { \ sul_error_t *sul_err__temp = (expr); \ if (sul_err__temp) \ return (sul_error_quick_wrap(sul_err__temp, wrap_msg, a1)); \ } while (0)

#define SUL_ERR_WRAP2 (  expr, wrap_msg, a1, a2   )

Value: do { \ sul_error_t *sul_err__temp = (expr); \ if (sul_err__temp) \ return (sul_error_quick_wrap(sul_err__temp, wrap_msg, a1, a2)); \ } while (0)

#define SUL_ERR_WRAP3 (  expr, wrap_msg, a1, a2, a3   )

Value: do { \ sul_error_t *sul_err__temp = (expr); \ if (sul_err__temp) \ return (sul_error_quick_wrap(sul_err__temp, wrap_msg, a1, a2, a3)); \ } while (0)

#define SUL_ERR_WRAP4 (  expr, wrap_msg, a1, a2, a3, a4   )

Value: do { \ sul_error_t *sul_err__temp = (expr); \ if (sul_err__temp) \ return (sul_error_quick_wrap(sul_err__temp, wrap_msg, a1, a2, a3, a4)); \ } while (0)

#define SUL_NO_ERROR   (NULL)

Error returned and used when no Error has occured and everything is peachy.

#define SUL_WARN (  expr   )

Value: do { \ sul_error_t *sul_err__temp = (expr); \ if (sul_err__temp) \ sul_error_handle(sul_err__temp, FALSE); \ } while (0)

---

Function Documentation

sul_error_create (  apr_status_t  apr_err, sul_status_t  sul_err, sul_error_t *  cause, const char *  msg, ...  )

Creates a new error object, hopefully this will rarely be used. Parameters: apr_err  APR specific error code. sul_err  SUL specific error code. cause  Optional cause of this error, for cascading errors. msg  Message describing the error, giving the user something to work with. Returns: A new sul_error_t object.

sul_error_destroy (  sul_error_t *  error  )

Destroys an Error. Parameters: error  A valid error instance.

sul_error_get_apr_error (  sul_error_t *  error  )

Returns the SUL code of the error. Parameters: error  A valid error instance. Returns: SUL status code of the error.

sul_error_get_cause (  sul_error_t *  error  )

Returns the error that caused the given error, if any. Parameters: error  A valid error instance. Returns: An error.

sul_error_get_message (  sul_error_t *  error  )

Returns the message for the given error. Parameters: error  A valid error instance. Returns: Error message.

sul_error_get_sul_error (  sul_error_t *  error  )

Returns the SUL code of the error. Parameters: error  A valid error instance. Returns: SUL status code of the error.

sul_error_handle (  sul_error_t *  error, sul_boolean_t  fatal )

Handles the given error, printing its details to STREAM and then if fatal, aborting program execution. Parameters: error  Error to be reported and displayed. fatal  Flag indicating if this error is a fatal one.

sul_error_locate (  const char *  file, apr_int32_t  line )

Debugging function to specify the location of an error prior to creation so that when reported it has the source location. Parameters: file  Source file where the error occured. line  Line number where the error occured.

sul_error_printf (  sul_error_t *  err, apr_size_t  indention, sul_stringbuf_t *  stream, apr_pool_t *  pool )

Parameters: err  indention  stream  pool  Returns:

sul_error_qualify (  sul_error_t *  err, apr_status_t  apr_err, sul_status_t  sul_err, sul_error_t *  cause )

Parameters: err  apr_err  sul_err  cause  Returns:

sul_error_quick_wrap (  sul_error_t *  cause, const char *  msg, ...  )

Wraps an new error around an existing one, assigning a new descriptive message for better debugging. Parameters: cause  Error that is the cause of the new error. msg  Message describing the new error. Returns: A new sul_error_t object.

sul_errors_initialize (  apr_pool_t *  pool  )

Create the Errors system. Parameters: pool  Pool to allocate from. Returns: APR_SUCCESS or otherwise.

sul_errprintf (  const char *  strf, ...  )

Parameters: strf  Returns:

sul_pool_create (  apr_pool_t *  pp, const char *  tag )

Create a new APR pool for use in an application using the SUL library. Parameters: pp  Pool to serve as the new pool's parent, or NULL for a top level pool, you know. . . tag  Tag to name the pool, this can make debugging easier. Returns: An APR pool ready for work!

---