From 03e9b8a96dadfe1439d6bb68dc40bea334f08ce8 Mon Sep 17 00:00:00 2001 From: Andrew Kesterson Date: Fri, 15 May 2026 19:41:22 -0400 Subject: [PATCH] Update docs, replace the missing VALID() macro to safeguard against misbehaving functions, add PASS, remove CATCH_AND_RETURN --- README.md | 42 ++++++++++++++++++++++++++++++++++++++---- include/akerror.tmpl.h | 32 ++++++++++++++++++++------------ 2 files changed, 58 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index af3df7e..ea8570d 100644 --- a/README.md +++ b/README.md @@ -137,6 +137,14 @@ pkg_check_modules(akerror REQUIRED akerror) target_link_libraries(YOUR_TARGET PRIVATE akerror::akerror) ``` +Using this project as a submodule with cmake: + +```cmake +add_subdirectory(deps/libakerror EXCLUDE_FROM_ALL) + +target_link_libraries(YOUR_PROJECT PRIVATE akerror::akerror) +``` + ## (Optional) Configuring the logging function @@ -222,6 +230,28 @@ ATTEMPT { When either of these two macros are used, the `ATTEMPT` block is immediately exited, and the `CLEANUP` block begins. +# Passing errors + +Sometimes you can't actually do anything about the errors that come out of a given method, but you want that error to be propagated back up the call chain, and to be properly reported. If this is your goal, you can avoid using a `ATTEMPT ... FINISH` block, and simply use the `PASS` macro. + +``` +PREPARE_ERROR(e); +PASS(e, some_method_that_may_fail()); +SUCCEED_RETURN(e); +``` + +This does the same thing as this, but with less code: + +``` +PREPARE_ERROR(e); +ATTEMPT { + CATCH(e, some_method_that_may_fail()); +} CLEANUP { +} PROCESS(e) { +} FINISH(e, true); +SUCCEED_RETURN(e); +``` + # Handling errors Inside of the `PROCESS { ... }` block, you must handle any errors that occurred during the `ATTEMPT { ... }` block. You do this with `HANDLE`, `HANDLE_GROUP`, and `HANDLE_DEFAULT`. @@ -310,20 +340,24 @@ FAIL_NONZERO_RETURN(errctx, strcmp("not", "equal"), AKERR_VALUE, "Strings are no # Uncaught errors +## Misbehaving methods + +Any function which returns `akerr_ErrorContext *` and completes successfully MUST call `SUCCEED_RETURN(errctx)`. Failure to do this may result in an invalid `akerr_ErrorContext *` being returned, which will cause an `AKERR_BEHAVIOR` error to be triggered from your code. + ## Ensuring that all error codes are captured -Any function which returns `akerr_ErrorContext *` should also be marked with `ERROR_NOIGNORE`. +Any function which returns `akerr_ErrorContext *` should also be marked with `AKERROR_NOIGNORE`. ```c -akerr_ErrorContext ERROR_NOIGNORE *f(...); +akerr_ErrorContext AKERROR_NOIGNORE *f(...); ``` This will cause a compile-time error if the return value of such a function is not used. "Used" here means assigned to a variable - it does not necessarily mean that the value is checked. However assuming that such functions are called inside of `ATTEMPT { ... }` blocks, it is safe to assume that such returns will be caught with `CATCH(...)`; therefore this error is a generally effective safeguard against careless coding where errors are not checked. -Beware that `ERROR_NOIGNORE` is not a failsafe - it implements the `warn_unused_result` mechanic. By design users may explicitly ignore an error code from a function marked with `warn_unused_result` by explicitly casting the return to `void`. +Beware that `AKERROR_NOIGNORE` is not a failsafe - it implements the `warn_unused_result` mechanic. By design users may explicitly ignore an error code from a function marked with `warn_unused_result` by explicitly casting the return to `void`. ```c -#define ERROR_NOIGNORE __attribute__((warn_unused_result)) +#define AKERROR_NOIGNORE __attribute__((warn_unused_result)) ``` ## Stack Traces diff --git a/include/akerror.tmpl.h b/include/akerror.tmpl.h index 6277278..6d9da68 100644 --- a/include/akerror.tmpl.h +++ b/include/akerror.tmpl.h @@ -176,8 +176,14 @@ void akerr_init_errno(void); switch ( 0 ) { \ case 0: \ +#define VALID(__err_context, __stmt) \ + __stmt; \ + if ( akerr_valid_error_address(__err_context) == 0 ) { \ + FAIL(__err_context, AKERR_BEHAVIOR, "Received (akerr_Error *) from an invalid memory region. (Did the method finish without calling SUCCEED_RETURN?)"); \ + } + #define DETECT(__err_context, __stmt) \ - __stmt; \ + VALID(__err_context, __stmt); \ if ( __err_context != NULL ) { \ __err_context->stacktracebufptr += snprintf(__err_context->stacktracebufptr, AKERR_MAX_ERROR_STACKTRACE_BUF_LENGTH, "%s:%s:%d: Detected error %d from array (refcount %d)\n", (char *)__FILE__, (char *)__func__, __LINE__, __err_context->arrayid, __err_context->refcount); \ if ( __err_context->status != 0 ) { \ @@ -189,6 +195,13 @@ void akerr_init_errno(void); #define CATCH(__err_context, __stmt) \ DETECT(__err_context, __err_context = __stmt); +#define PASS(__err_context, __stmt) \ + switch ( 0 ) { \ + case 0: \ + DETECT(__err_context, __err_context = __stmt); \ + } \ + FINISH_LOGIC(__err_context, true); + #define IGNORE(__stmt) \ __akerr_last_ignored = __stmt; \ if ( __akerr_last_ignored != NULL ) { \ @@ -221,15 +234,18 @@ void akerr_init_errno(void); __err_context->stacktracebufptr = (char *)&__err_context->stacktracebuf; \ __err_context->handled = true; -#define FINISH(__err_context, __pass_up) \ - }; \ - }; \ +#define FINISH_LOGIC(__err_context, __pass_up) \ if ( __err_context != NULL ) { \ if ( __err_context->handled == false && __pass_up == true ) { \ __err_context->stacktracebufptr += snprintf(__err_context->stacktracebufptr, AKERR_MAX_ERROR_STACKTRACE_BUF_LENGTH, "%s:%s:%d\n", (char *)__FILE__, (char *)__func__, __LINE__); \ return __err_context; \ } \ } \ + +#define FINISH(__err_context, __pass_up) \ + }; \ + }; \ + FINISH_LOGIC(__err_context, __pass_up) \ RELEASE_ERROR(__err_context); #define FINISH_NORETURN(__err_context) \ @@ -243,12 +259,4 @@ void akerr_init_errno(void); } \ RELEASE_ERROR(__err_context); -#define CATCH_AND_RETURN(__err_context, __stmt) \ - ATTEMPT { \ - CATCH(__err_context, __stmt); \ - } CLEANUP { \ - } PROCESS(__err_context) { \ - } FINISH(__err_context, true); - - #endif // _AKERR_H_