summaryrefslogtreecommitdiffstats
path: root/libdimension/dimension/error.h
diff options
context:
space:
mode:
Diffstat (limited to 'libdimension/dimension/error.h')
-rw-r--r--libdimension/dimension/error.h79
1 files changed, 63 insertions, 16 deletions
diff --git a/libdimension/dimension/error.h b/libdimension/dimension/error.h
index a0b3857..8482266 100644
--- a/libdimension/dimension/error.h
+++ b/libdimension/dimension/error.h
@@ -18,22 +18,29 @@
* <http://www.gnu.org/licenses/>. *
*************************************************************************/
-/*
- * Error handling. Errors are reported at a given severity by the dmnsn_error()
- * macro at a given severity, which prints a warning if it is below the set
- * resilience, or prints an error and exits if it's at or above the set
- * resilience.
+/**
+ * @file
+ * Error reporting interface. Errors are reported at a given severity by the
+ * dmnsn_error() macro at a given severity, which prints a warning if it is
+ * below the set resilience, or prints an error and exits if it's at or above
+ * the set resilience.
*/
#ifndef DIMENSION_ERROR_H
#define DIMENSION_ERROR_H
-typedef enum {
- DMNSN_SEVERITY_LOW, /* Only die on low resilience */
- DMNSN_SEVERITY_MEDIUM, /* Die on low or medium resilience */
- DMNSN_SEVERITY_HIGH /* Always die */
+/** Error severity codes */
+typedef enum dmnsn_severity {
+ DMNSN_SEVERITY_LOW, /**< Only die on low resilience */
+ DMNSN_SEVERITY_MEDIUM, /**< Die on low or medium resilience */
+ DMNSN_SEVERITY_HIGH /**< Always die */
} dmnsn_severity;
+/**
+ * @internal
+ * @def DMNSN_FUNC
+ * @brief Expands to the name of the current function
+ */
#ifdef __GNUC__
#define DMNSN_FUNC __PRETTY_FUNCTION__
#elif __STDC_VERSION__ >= 199901L
@@ -42,13 +49,24 @@ typedef enum {
#define DMNSN_FUNC "<unknown function>"
#endif
-/* Use this macro to report an error */
+/**
+ * Report an error.
+ * @param[in] severity A @ref dmnsn_severity representing the severity of the
+ * error. DMNSN_SEVERITY_HIGH will always terminate the
+ * running thread.
+ * @param[in] str A string to print explaining the error.
+ */
#define dmnsn_error(severity, str) \
dmnsn_report_error((dmnsn_severity)(severity), \
DMNSN_FUNC, __FILE__, __LINE__, \
str)
-/* Make an assertion */
+/**
+ * @def dmnsn_assert
+ * Make an assertion.
+ * @param[in] expr The expression to assert.
+ * @param[in] str A string to print if the assertion fails.
+ */
#ifdef NDEBUG
#define dmnsn_assert(expr, str) ((void)0)
#else
@@ -60,21 +78,50 @@ typedef enum {
} while (0)
#endif
-/* Called by dmnsn_error() - don't call directly */
+/**
+ * @internal
+ * Called by dmnsn_error(); don't call directly.
+ * @param[in] severity The severity of the error.
+ * @param[in] func The name of the function where the error originated.
+ * @param[in] file The file where the error originated.
+ * @param[in] line The line number where the error originated.
+ * @param[in] str A string describing the error.
+ */
void dmnsn_report_error(dmnsn_severity severity,
const char *func, const char *file, unsigned int line,
const char *str);
-/* Get and set the library resilience, thread-safely */
+/**
+ * Get the library resilience, thread-safely.
+ * @return The error severity considered fatal.
+ */
dmnsn_severity dmnsn_get_resilience(void);
+
+/**
+ * Set the library resilience, thread-safely.
+ * @param[in] resilience The new minimum severity that will cause a fatal
+ * error.
+ */
void dmnsn_set_resilience(dmnsn_severity resilience);
-/* Fatal error callback type */
+/**
+ * Fatal error callback type. This function should never return.
+ */
typedef void dmnsn_fatal_error_fn(void);
-/* Get and set libdimension fatal error handling strategy - the default is
- exit(EXIT_FAILURE) */
+/**
+ * Get the libdimension fatal error handler, thread-safely. The default fatal
+ * error handler terminates the current thread, or the entire program if the
+ * current thread is the main thread.
+ * @return The current fatal error handler.
+ */
dmnsn_fatal_error_fn *dmnsn_get_fatal_error_fn(void);
+
+/**
+ * Set the libdimension fatal error handler, thread-safely.
+ * @param[in] fatal The new fatal error handler. This function must never
+ * return.
+ */
void dmnsn_set_fatal_error_fn(dmnsn_fatal_error_fn *fatal);
#endif /* DIMENSION_ERROR_H */