From 2b1084fab363d473385d5be2da6036dc997ef70e Mon Sep 17 00:00:00 2001 From: Marcel Admiraal Date: Wed, 6 Nov 2019 08:38:23 +0100 Subject: Clean up error_macros.h --- core/error_macros.h | 459 +++++++++++++++++++++++----------------------------- 1 file changed, 201 insertions(+), 258 deletions(-) (limited to 'core/error_macros.h') diff --git a/core/error_macros.h b/core/error_macros.h index 8ba6618942..c0be752a6c 100644 --- a/core/error_macros.h +++ b/core/error_macros.h @@ -32,21 +32,8 @@ #define ERROR_MACROS_H #include "core/typedefs.h" -/** - * Error macros. Unlike exceptions and asserts, these macros try to maintain consistency and stability - * inside the code. It is recommended to always return processable data, so in case of an error, - * the engine can keep working well. - * In most cases, bugs and/or invalid data are not fatal and should never allow a perfectly running application - * to fail or crash. - */ - -/** - * Pointer to the error macro printing function. Reassign to any function to have errors printed - */ - -/** Function used by the error macros */ -// function, file, line, error, explanation +class String; enum ErrorHandlerType { ERR_HANDLER_ERROR, @@ -55,7 +42,8 @@ enum ErrorHandlerType { ERR_HANDLER_SHADER, }; -class String; +// Pointer to the error handler printing function. Reassign to any function to have errors printed. +// Parameters: userdata, function, file, line, error, explanation, type. typedef void (*ErrorHandlerFunc)(void *, const char *, const char *, int p_line, const char *, const char *, ErrorHandlerType p_type); struct ErrorHandlerList { @@ -75,6 +63,7 @@ struct ErrorHandlerList { void add_error_handler(ErrorHandlerList *p_handler); void remove_error_handler(ErrorHandlerList *p_handler); +// Functions used by the error macros. void _err_print_error(const char *p_function, const char *p_file, int p_line, const char *p_error, ErrorHandlerType p_type = ERR_HANDLER_ERROR); void _err_print_error(const char *p_function, const char *p_file, int p_line, const String &p_error, ErrorHandlerType p_type = ERR_HANDLER_ERROR); void _err_print_error(const char *p_function, const char *p_file, int p_line, const char *p_error, const char *p_message, ErrorHandlerType p_type = ERR_HANDLER_ERROR); @@ -84,15 +73,6 @@ void _err_print_error(const char *p_function, const char *p_file, int p_line, co void _err_print_index_error(const char *p_function, const char *p_file, int p_line, int64_t p_index, int64_t p_size, const char *p_index_str, const char *p_size_str, const char *p_message = "", bool fatal = false); void _err_print_index_error(const char *p_function, const char *p_file, int p_line, int64_t p_index, int64_t p_size, const char *p_index_str, const char *p_size_str, const String &p_message, bool fatal = false); -#ifndef _STR -#define _STR(m_x) #m_x -#define _MKSTR(m_x) _STR(m_x) -#endif - -#define _FNL __FILE__ ":" - -/** An index has failed if m_index<0 or m_index >=m_size, the function exits */ - #ifdef __GNUC__ //#define FUNCTION_STR __PRETTY_FUNCTION__ - too annoying #define FUNCTION_STR __FUNCTION__ @@ -102,13 +82,9 @@ void _err_print_index_error(const char *p_function, const char *p_file, int p_li // Don't use this directly; instead, use any of the CRASH_* macros #ifdef _MSC_VER -#define GENERATE_TRAP \ - __debugbreak(); \ - /* Avoid warning about control paths */ \ - for (;;) { \ - } +#define GENERATE_TRAP() __debugbreak() #else -#define GENERATE_TRAP __builtin_trap(); +#define GENERATE_TRAP() __builtin_trap() #endif // Used to strip debug messages in release mode @@ -118,117 +94,141 @@ void _err_print_index_error(const char *p_function, const char *p_file, int p_li #define DEBUG_STR(m_msg) "" #endif -// (*): See https://stackoverflow.com/questions/257418/do-while-0-what-is-it-good-for - /** - * If `m_index` is less than 0 or greater than or equal to `m_size`, prints a generic - * error message and returns from the function. This macro should be preferred to - * `ERR_FAIL_COND` for bounds checking. + * Error macros. + * WARNING: These macros work in the opposite way to assert(). + * + * Unlike exceptions and asserts, these macros try to maintain consistency and stability. + * In most cases, bugs and/or invalid data are not fatal. They should never allow a perfectly + * running application to fail or crash. + * Always try to return processable data, so the engine can keep running well. + * Use the _MSG versions to print a meaningful message to help with debugging. + * + * Note: See https://stackoverflow.com/questions/257418/do-while-0-what-is-it-good-for */ + +// Index out of bounds error macros. +// These macros should be used instead of `ERR_FAIL_COND` for bounds checking. + +// Integer index out of bounds error macros. +// Ensures an integer index `m_index` is less than `m_size` and greater than or equal to 0. + +// The current function returns. + #define ERR_FAIL_INDEX(m_index, m_size) \ do { \ if (unlikely((m_index) < 0 || (m_index) >= (m_size))) { \ _err_print_index_error(FUNCTION_STR, __FILE__, __LINE__, m_index, m_size, _STR(m_index), _STR(m_size)); \ return; \ } \ - } while (0); // (*) + } while (0); -/** - * If `m_index` is less than 0 or greater than or equal to `m_size`, prints a custom - * error message and returns from the function. This macro should be preferred to - * `ERR_FAIL_COND_MSG` for bounds checking. - */ #define ERR_FAIL_INDEX_MSG(m_index, m_size, m_msg) \ do { \ if (unlikely((m_index) < 0 || (m_index) >= (m_size))) { \ _err_print_index_error(FUNCTION_STR, __FILE__, __LINE__, m_index, m_size, _STR(m_index), _STR(m_size), DEBUG_STR(m_msg)); \ return; \ } \ - } while (0); // (*) + } while (0); + +// The current function returns m_retval. -/** - * If `m_index` is less than 0 or greater than or equal to `m_size`, - * prints a generic error message and returns the value specified in `m_retval`. - * This macro should be preferred to `ERR_FAIL_COND_V` for bounds checking. - */ #define ERR_FAIL_INDEX_V(m_index, m_size, m_retval) \ do { \ if (unlikely((m_index) < 0 || (m_index) >= (m_size))) { \ _err_print_index_error(FUNCTION_STR, __FILE__, __LINE__, m_index, m_size, _STR(m_index), _STR(m_size)); \ return m_retval; \ } \ - } while (0); // (*) + } while (0); -/** - * If `m_index` is less than 0 or greater than or equal to `m_size`, - * prints a custom error message and returns the value specified in `m_retval`. - * This macro should be preferred to `ERR_FAIL_COND_V_MSG` for bounds checking. - */ #define ERR_FAIL_INDEX_V_MSG(m_index, m_size, m_retval, m_msg) \ do { \ if (unlikely((m_index) < 0 || (m_index) >= (m_size))) { \ _err_print_index_error(FUNCTION_STR, __FILE__, __LINE__, m_index, m_size, _STR(m_index), _STR(m_size), DEBUG_STR(m_msg)); \ return m_retval; \ } \ - } while (0); // (*) + } while (0); + +// Only use CRASH macros if there is no sensible fallback, that is, the error is unrecoverable. + +#define CRASH_BAD_INDEX(m_index, m_size) \ + do { \ + if (unlikely((m_index) < 0 || (m_index) >= (m_size))) { \ + _err_print_index_error(FUNCTION_STR, __FILE__, __LINE__, m_index, m_size, _STR(m_index), _STR(m_size), "", true); \ + GENERATE_TRAP(); \ + } \ + } while (0); + +#define CRASH_BAD_INDEX_MSG(m_index, m_size, m_msg) \ + do { \ + if (unlikely((m_index) < 0 || (m_index) >= (m_size))) { \ + _err_print_index_error(FUNCTION_STR, __FILE__, __LINE__, m_index, m_size, _STR(m_index), _STR(m_size), DEBUG_STR(m_msg), true); \ + GENERATE_TRAP(); \ + } \ + } while (0); + +// Unsigned integer index out of bounds error macros. +// Ensures an unsigned integer index `m_index` is less than `m_size` + +// The current function returns. + +#define ERR_FAIL_UNSIGNED_INDEX(m_index, m_size) \ + do { \ + if (unlikely((m_index) >= (m_size))) { \ + _err_print_index_error(FUNCTION_STR, __FILE__, __LINE__, m_index, m_size, _STR(m_index), _STR(m_size)); \ + return; \ + } \ + } while (0); + +#define ERR_FAIL_UNSIGNED_INDEX_MSG(m_index, m_size, m_msg) \ + do { \ + if (unlikely((m_index) >= (m_size))) { \ + _err_print_index_error(FUNCTION_STR, __FILE__, __LINE__, m_index, m_size, _STR(m_index), _STR(m_size), DEBUG_STR(m_msg)); \ + return; \ + } \ + } while (0); + +// The current function returns m_retval. -/** - * If `m_index` is greater than or equal to `m_size`, - * prints a generic error message and returns the value specified in `m_retval`. - * This macro should be preferred to `ERR_FAIL_COND_V` for unsigned bounds checking. - */ #define ERR_FAIL_UNSIGNED_INDEX_V(m_index, m_size, m_retval) \ do { \ if (unlikely((m_index) >= (m_size))) { \ _err_print_index_error(FUNCTION_STR, __FILE__, __LINE__, m_index, m_size, _STR(m_index), _STR(m_size)); \ return m_retval; \ } \ - } while (0); // (*) + } while (0); -/** - * If `m_index` is greater than or equal to `m_size`, - * prints a custom error message and returns the value specified in `m_retval`. - * This macro should be preferred to `ERR_FAIL_COND_V_MSG` for unsigned bounds checking. - */ #define ERR_FAIL_UNSIGNED_INDEX_V_MSG(m_index, m_size, m_retval, m_msg) \ do { \ if (unlikely((m_index) >= (m_size))) { \ _err_print_index_error(FUNCTION_STR, __FILE__, __LINE__, m_index, m_size, _STR(m_index), _STR(m_size), DEBUG_STR(m_msg)); \ return m_retval; \ } \ - } while (0); // (*) + } while (0); -/** - * If `m_index` is less than 0 or greater than or equal to `m_size`, - * crashes the engine immediately with a generic error message. - * Only use this if there's no sensible fallback (i.e. the error is unrecoverable). - * This macro should be preferred to `CRASH_COND` for bounds checking. - */ -#define CRASH_BAD_INDEX(m_index, m_size) \ +// Only use CRASH macros if there is no sensible fallback, that is, the error is unrecoverable. + +#define CRASH_BAD_UNSIGNED_INDEX(m_index, m_size) \ do { \ - if (unlikely((m_index) < 0 || (m_index) >= (m_size))) { \ + if (unlikely((m_index) >= (m_size))) { \ _err_print_index_error(FUNCTION_STR, __FILE__, __LINE__, m_index, m_size, _STR(m_index), _STR(m_size), "", true); \ - GENERATE_TRAP \ + GENERATE_TRAP(); \ } \ - } while (0); // (*) + } while (0); -/** - * If `m_index` is less than 0 or greater than or equal to `m_size`, - * crashes the engine immediately with a custom error message. - * Only use this if there's no sensible fallback (i.e. the error is unrecoverable). - * This macro should be preferred to `CRASH_COND` for bounds checking. - */ -#define CRASH_BAD_INDEX_MSG(m_index, m_size, m_msg) \ - do { \ - if (unlikely((m_index) < 0 || (m_index) >= (m_size))) { \ - _err_print_index_error(FUNCTION_STR, __FILE__, __LINE__, m_index, m_size, _STR(m_index), _STR(m_size), m_msg, true); \ - GENERATE_TRAP \ - } \ - } while (0); // (*) +#define CRASH_BAD_UNSIGNED_INDEX_MSG(m_index, m_size, m_msg) \ + do { \ + if (unlikely((m_index) >= (m_size))) { \ + _err_print_index_error(FUNCTION_STR, __FILE__, __LINE__, m_index, m_size, _STR(m_index), _STR(m_size), DEBUG_STR(m_msg), true); \ + GENERATE_TRAP(); \ + } \ + } while (0); + +// Null reference error macros. +// Ensures a pointer `m_param` is not null. + +// The current function returns. -/** - * If `m_param` is `null`, prints a generic error message and returns from the function. - */ #define ERR_FAIL_NULL(m_param) \ { \ if (unlikely(!m_param)) { \ @@ -237,9 +237,6 @@ void _err_print_index_error(const char *p_function, const char *p_file, int p_li } \ } -/** - * If `m_param` is `null`, prints a custom error message and returns from the function. - */ #define ERR_FAIL_NULL_MSG(m_param, m_msg) \ { \ if (unlikely(!m_param)) { \ @@ -248,9 +245,8 @@ void _err_print_index_error(const char *p_function, const char *p_file, int p_li } \ } -/** - * If `m_param` is `null`, prints a generic error message and returns the value specified in `m_retval`. - */ +// The current function returns m_retval. + #define ERR_FAIL_NULL_V(m_param, m_retval) \ { \ if (unlikely(!m_param)) { \ @@ -259,9 +255,6 @@ void _err_print_index_error(const char *p_function, const char *p_file, int p_li } \ } -/** - * If `m_param` is `null`, prints a custom error message and returns the value specified in `m_retval`. - */ #define ERR_FAIL_NULL_V_MSG(m_param, m_retval, m_msg) \ { \ if (unlikely(!m_param)) { \ @@ -270,9 +263,11 @@ void _err_print_index_error(const char *p_function, const char *p_file, int p_li } \ } -/** - * If `m_cond` evaluates to `true`, prints a generic error message and returns from the function. - */ +// Error condition macros. +// Ensures that `m_cond` is not true. + +// The current function returns. + #define ERR_FAIL_COND(m_cond) \ { \ if (unlikely(m_cond)) { \ @@ -281,9 +276,6 @@ void _err_print_index_error(const char *p_function, const char *p_file, int p_li } \ } -/** - * If `m_cond` evaluates to `true`, prints a custom error message and returns from the function. - */ #define ERR_FAIL_COND_MSG(m_cond, m_msg) \ { \ if (unlikely(m_cond)) { \ @@ -292,55 +284,26 @@ void _err_print_index_error(const char *p_function, const char *p_file, int p_li } \ } -/** - * If `m_cond` evaluates to `true`, crashes the engine immediately with a generic error message. - * Only use this if there's no sensible fallback (i.e. the error is unrecoverable). - */ -#define CRASH_COND(m_cond) \ - { \ - if (unlikely(m_cond)) { \ - _err_print_error(FUNCTION_STR, __FILE__, __LINE__, "FATAL: Condition \"" _STR(m_cond) "\" is true."); \ - GENERATE_TRAP \ - } \ - } - -/** - * If `m_cond` evaluates to `true`, crashes the engine immediately with a custom error message. - * Only use this if there's no sensible fallback (i.e. the error is unrecoverable). - */ -#define CRASH_COND_MSG(m_cond, m_msg) \ - { \ - if (unlikely(m_cond)) { \ - _err_print_error(FUNCTION_STR, __FILE__, __LINE__, "FATAL: Condition \"" _STR(m_cond) "\" is true.", DEBUG_STR(m_msg)); \ - GENERATE_TRAP \ - } \ - } +// The current function returns m_retval. -/** - * If `m_cond` evaluates to `true`, prints a generic error message and returns the value specified in `m_retval`. - */ #define ERR_FAIL_COND_V(m_cond, m_retval) \ { \ if (unlikely(m_cond)) { \ - _err_print_error(FUNCTION_STR, __FILE__, __LINE__, "Condition \"" _STR(m_cond) "\" is true. Returned: " _STR(m_retval)); \ + _err_print_error(FUNCTION_STR, __FILE__, __LINE__, "Condition \"" _STR(m_cond) "\" is true. returned: " _STR(m_retval)); \ return m_retval; \ } \ } -/** - * If `m_cond` evaluates to `true`, prints a custom error message and returns the value specified in `m_retval`. - */ #define ERR_FAIL_COND_V_MSG(m_cond, m_retval, m_msg) \ { \ if (unlikely(m_cond)) { \ - _err_print_error(FUNCTION_STR, __FILE__, __LINE__, "Condition \"" _STR(m_cond) "\" is true. Returned: " _STR(m_retval), DEBUG_STR(m_msg)); \ + _err_print_error(FUNCTION_STR, __FILE__, __LINE__, "Condition \"" _STR(m_cond) "\" is true. returned: " _STR(m_retval), DEBUG_STR(m_msg)); \ return m_retval; \ } \ } -/** - * If `m_cond` evaluates to `true`, prints a custom error message and continues the loop the macro is located in. - */ +// The current loop continues. + #define ERR_CONTINUE(m_cond) \ { \ if (unlikely(m_cond)) { \ @@ -349,9 +312,6 @@ void _err_print_index_error(const char *p_function, const char *p_file, int p_li } \ } -/** - * If `m_cond` evaluates to `true`, prints a custom error message and continues the loop the macro is located in. - */ #define ERR_CONTINUE_MSG(m_cond, m_msg) \ { \ if (unlikely(m_cond)) { \ @@ -360,9 +320,8 @@ void _err_print_index_error(const char *p_function, const char *p_file, int p_li } \ } -/** - * If `m_cond` evaluates to `true`, prints a generic error message and breaks from the loop the macro is located in. - */ +// The current loop breaks. + #define ERR_BREAK(m_cond) \ { \ if (unlikely(m_cond)) { \ @@ -371,9 +330,6 @@ void _err_print_index_error(const char *p_function, const char *p_file, int p_li } \ } -/** - * If `m_cond` evaluates to `true`, prints a custom error message and breaks from the loop the macro is located in. - */ #define ERR_BREAK_MSG(m_cond, m_msg) \ { \ if (unlikely(m_cond)) { \ @@ -382,127 +338,104 @@ void _err_print_index_error(const char *p_function, const char *p_file, int p_li } \ } -/** - * Prints a generic error message and returns from the function. - */ -#define ERR_FAIL() \ - { \ - _err_print_error(FUNCTION_STR, __FILE__, __LINE__, "Method failed."); \ - return; \ +// Only use CRASH macros if there is no sensible fallback, that is, the error is unrecoverable. + +#define CRASH_COND(m_cond) \ + { \ + if (unlikely(m_cond)) { \ + _err_print_error(FUNCTION_STR, __FILE__, __LINE__, "FATAL: Condition \"" _STR(m_cond) "\" is true."); \ + GENERATE_TRAP(); \ + } \ } -/** - * Prints a custom error message and returns from the function. - */ -#define ERR_FAIL_MSG(m_msg) \ - { \ - _err_print_error(FUNCTION_STR, __FILE__, __LINE__, "Method failed.", DEBUG_STR(m_msg)); \ - return; \ +#define CRASH_COND_MSG(m_cond, m_msg) \ + { \ + if (unlikely(m_cond)) { \ + _err_print_error(FUNCTION_STR, __FILE__, __LINE__, "FATAL: Condition \"" _STR(m_cond) "\" is true.", DEBUG_STR(m_msg)); \ + GENERATE_TRAP(); \ + } \ } -/** - * Prints a generic error message and returns the value specified in `m_retval`. - */ -#define ERR_FAIL_V(m_retval) \ - { \ - _err_print_error(FUNCTION_STR, __FILE__, __LINE__, "Method failed. Returning: " __STR(m_retval)); \ - return m_retval; \ +// Generic error macros. + +// The current function returns. + +#define ERR_FAIL() \ + { \ + _err_print_error(FUNCTION_STR, __FILE__, __LINE__, "Method/Function Failed."); \ + return; \ } -/** - * Prints a custom error message and returns the value specified in `m_retval`. - */ -#define ERR_FAIL_V_MSG(m_retval, m_msg) \ - { \ - _err_print_error(FUNCTION_STR, __FILE__, __LINE__, "Method failed. Returning: " __STR(m_retval), DEBUG_STR(m_msg)); \ - return m_retval; \ +#define ERR_FAIL_MSG(m_msg) \ + { \ + _err_print_error(FUNCTION_STR, __FILE__, __LINE__, "Method/Function Failed.", DEBUG_STR(m_msg)); \ + return; \ } -/** - * Crashes the engine immediately with a generic error message. - * Only use this if there's no sensible fallback (i.e. the error is unrecoverable). - */ -#define CRASH_NOW() \ - { \ - _err_print_error(FUNCTION_STR, __FILE__, __LINE__, "FATAL: Method failed."); \ - GENERATE_TRAP \ +// The current function returns m_retval. + +#define ERR_FAIL_V(m_retval) \ + { \ + _err_print_error(FUNCTION_STR, __FILE__, __LINE__, "Method/Function Failed, returning: " __STR(m_value)); \ + return m_retval; \ } -/** - * Crashes the engine immediately with a custom error message. - * Only use this if there's no sensible fallback (i.e. the error is unrecoverable). - */ -#define CRASH_NOW_MSG(m_msg) \ - { \ - _err_print_error(FUNCTION_STR, __FILE__, __LINE__, "FATAL: Method failed.", DEBUG_STR(m_msg)); \ - GENERATE_TRAP \ +#define ERR_FAIL_V_MSG(m_value, m_msg) \ + { \ + _err_print_error(FUNCTION_STR, __FILE__, __LINE__, "Method/Function Failed, returning: " __STR(m_value), DEBUG_STR(m_msg)); \ + return m_value; \ } -/** - * Prints an error message without returning. - */ -#define ERR_PRINT(m_string) \ - { \ - _err_print_error(FUNCTION_STR, __FILE__, __LINE__, m_string); \ +// Print error message macros. + +#define ERR_PRINT(m_msg) \ + { \ + _err_print_error(FUNCTION_STR, __FILE__, __LINE__, DEBUG_STR(m_msg)); \ } -/** - * Prints an error message without returning. - * FIXME: Remove this macro and replace all uses with `ERR_PRINT` as it's identical. - */ -#define ERR_PRINTS(m_string) \ - { \ - _err_print_error(FUNCTION_STR, __FILE__, __LINE__, m_string); \ +#define ERR_PRINTS(m_msg) \ + { \ + _err_print_error(FUNCTION_STR, __FILE__, __LINE__, DEBUG_STR(m_msg)); \ } -/** - * Prints an error message without returning, but only do so once in the application lifecycle. - * This can be used to avoid spamming the console with error messages. - */ -#define ERR_PRINT_ONCE(m_string) \ - { \ - static bool first_print = true; \ - if (first_print) { \ - _err_print_error(FUNCTION_STR, __FILE__, __LINE__, m_string); \ - first_print = false; \ - } \ +// Only prints the error message once. + +#define ERR_PRINT_ONCE(m_msg) \ + { \ + static bool first_print = true; \ + if (first_print) { \ + _err_print_error(FUNCTION_STR, __FILE__, __LINE__, DEBUG_STR(m_msg)); \ + first_print = false; \ + } \ } -/** - * Prints a warning message without returning. To warn about deprecated usage, - * use `WARN_DEPRECATED` or `WARN_DEPRECATED_MSG` instead. - */ -#define WARN_PRINT(m_string) \ - { \ - _err_print_error(FUNCTION_STR, __FILE__, __LINE__, m_string, ERR_HANDLER_WARNING); \ +// Print warning message macros. +// To warn about deprecated usage, use `WARN_DEPRECATED` or `WARN_DEPRECATED_MSG` instead. + +#define WARN_PRINT(m_msg) \ + { \ + _err_print_error(FUNCTION_STR, __FILE__, __LINE__, DEBUG_STR(m_msg), ERR_HANDLER_WARNING); \ } -/** - * Prints a warning message without returning. - * FIXME: Remove this macro and replace all uses with `WARN_PRINT` as it's identical. - */ -#define WARN_PRINTS(m_string) \ - { \ - _err_print_error(FUNCTION_STR, __FILE__, __LINE__, m_string, ERR_HANDLER_WARNING); \ +#define WARN_PRINTS(m_msg) \ + { \ + _err_print_error(FUNCTION_STR, __FILE__, __LINE__, DEBUG_STR(m_msg), ERR_HANDLER_WARNING); \ } -/** - * Prints a warning message without returning, but only do so once in the application lifecycle. - * This can be used to avoid spamming the console with warning messages. - */ -#define WARN_PRINT_ONCE(m_string) \ - { \ - static bool first_print = true; \ - if (first_print) { \ - _err_print_error(FUNCTION_STR, __FILE__, __LINE__, m_string, ERR_HANDLER_WARNING); \ - first_print = false; \ - } \ +// Only prints the warning message once. + +#define WARN_PRINT_ONCE(m_msg) \ + { \ + static bool first_print = true; \ + if (first_print) { \ + _err_print_error(FUNCTION_STR, __FILE__, __LINE__, DEBUG_STR(m_msg), ERR_HANDLER_WARNING); \ + first_print = false; \ + } \ } -/** - * Prints a generic deprecation warning message without returning. - * This should be preferred to `WARN_PRINT` for deprecation warnings. - */ +// Print deprecated warning message macros. +// Only prints the warning message once. + #define WARN_DEPRECATED \ { \ static volatile bool warning_shown = false; \ @@ -512,17 +445,27 @@ void _err_print_index_error(const char *p_function, const char *p_file, int p_li } \ } -/** - * Prints a custom deprecation warning message without returning. - * This should be preferred to `WARN_PRINT` for deprecation warnings. - */ -#define WARN_DEPRECATED_MSG(m_msg) \ - { \ - static volatile bool warning_shown = false; \ - if (!warning_shown) { \ - _err_print_error(FUNCTION_STR, __FILE__, __LINE__, "This method has been deprecated and will be removed in the future.", m_msg, ERR_HANDLER_WARNING); \ - warning_shown = true; \ - } \ +#define WARN_DEPRECATED_MSG(m_msg) \ + { \ + static volatile bool warning_shown = false; \ + if (!warning_shown) { \ + _err_print_error(FUNCTION_STR, __FILE__, __LINE__, "This method has been deprecated and will be removed in the future.", DEBUG_STR(m_msg), ERR_HANDLER_WARNING); \ + warning_shown = true; \ + } \ + } + +// Only use CRASH macros if there is no sensible fallback, that is, the error is unrecoverable. + +#define CRASH_NOW() \ + { \ + _err_print_error(FUNCTION_STR, __FILE__, __LINE__, "FATAL: Method/Function Failed."); \ + GENERATE_TRAP(); \ + } + +#define CRASH_NOW_MSG(m_msg) \ + { \ + _err_print_error(FUNCTION_STR, __FILE__, __LINE__, "FATAL: Method/Function Failed.", DEBUG_STR(m_msg)); \ + GENERATE_TRAP(); \ } #endif -- cgit v1.2.3 From 5af3b4ca279c6dac32a8aef45d5d4a5b27fdb718 Mon Sep 17 00:00:00 2001 From: Marcel Admiraal Date: Wed, 6 Nov 2019 17:03:04 +0100 Subject: Remove duplicate ERR_PRINT macro. --- core/error_macros.h | 5 ----- 1 file changed, 5 deletions(-) (limited to 'core/error_macros.h') diff --git a/core/error_macros.h b/core/error_macros.h index c0be752a6c..4d6dedb654 100644 --- a/core/error_macros.h +++ b/core/error_macros.h @@ -393,11 +393,6 @@ void _err_print_index_error(const char *p_function, const char *p_file, int p_li _err_print_error(FUNCTION_STR, __FILE__, __LINE__, DEBUG_STR(m_msg)); \ } -#define ERR_PRINTS(m_msg) \ - { \ - _err_print_error(FUNCTION_STR, __FILE__, __LINE__, DEBUG_STR(m_msg)); \ - } - // Only prints the error message once. #define ERR_PRINT_ONCE(m_msg) \ -- cgit v1.2.3 From f0db13502aa455f7bef320261ea3929589fcc6d9 Mon Sep 17 00:00:00 2001 From: Marcel Admiraal Date: Thu, 7 Nov 2019 09:44:15 +0100 Subject: Remove duplicate WARN_PRINT macro. --- core/error_macros.h | 5 ----- 1 file changed, 5 deletions(-) (limited to 'core/error_macros.h') diff --git a/core/error_macros.h b/core/error_macros.h index 4d6dedb654..afbf76c47d 100644 --- a/core/error_macros.h +++ b/core/error_macros.h @@ -412,11 +412,6 @@ void _err_print_index_error(const char *p_function, const char *p_file, int p_li _err_print_error(FUNCTION_STR, __FILE__, __LINE__, DEBUG_STR(m_msg), ERR_HANDLER_WARNING); \ } -#define WARN_PRINTS(m_msg) \ - { \ - _err_print_error(FUNCTION_STR, __FILE__, __LINE__, DEBUG_STR(m_msg), ERR_HANDLER_WARNING); \ - } - // Only prints the warning message once. #define WARN_PRINT_ONCE(m_msg) \ -- cgit v1.2.3 From 6d69cd40bd43c744fd402507a02d42d328266dc8 Mon Sep 17 00:00:00 2001 From: Marcel Admiraal Date: Thu, 7 Nov 2019 10:37:44 +0100 Subject: Add do..while(0) wrappers to macros without one. - Add do..while(0) wrapper to ERR_FAIL_NULL macros. - Add do..while(0) wrapper to ERR_FAIL_COND macros. - Add do..while(0) wrapper to ERR_CONTINUE macros. - Add do..while(0) wrapper to ERR_BREAK macros. - Add do..while(0) wrapper to CRASH_COND macros. - Add do..while(0) wrapper to ERR_FAIL macros. - Add do..while(0) wrapper to ERR_PRINT macros. - Add do..while(0) wrapper to WARN_PRINT macros. - Add do..while(0) wrapper to WARN_DEPRECATED macros. - Add do..while(0) wrapper to CRASH_NOW macros. --- core/error_macros.h | 158 ++++++++++++++++++++++++++-------------------------- 1 file changed, 79 insertions(+), 79 deletions(-) (limited to 'core/error_macros.h') diff --git a/core/error_macros.h b/core/error_macros.h index afbf76c47d..0fe3a5d796 100644 --- a/core/error_macros.h +++ b/core/error_macros.h @@ -230,38 +230,38 @@ void _err_print_index_error(const char *p_function, const char *p_file, int p_li // The current function returns. #define ERR_FAIL_NULL(m_param) \ - { \ + do { \ if (unlikely(!m_param)) { \ _err_print_error(FUNCTION_STR, __FILE__, __LINE__, "Parameter \"" _STR(m_param) "\" is null."); \ return; \ } \ - } + } while (0) #define ERR_FAIL_NULL_MSG(m_param, m_msg) \ - { \ + do { \ if (unlikely(!m_param)) { \ _err_print_error(FUNCTION_STR, __FILE__, __LINE__, "Parameter \"" _STR(m_param) "\" is null.", DEBUG_STR(m_msg)); \ return; \ } \ - } + } while (0) // The current function returns m_retval. #define ERR_FAIL_NULL_V(m_param, m_retval) \ - { \ + do { \ if (unlikely(!m_param)) { \ _err_print_error(FUNCTION_STR, __FILE__, __LINE__, "Parameter \"" _STR(m_param) "\" is null."); \ return m_retval; \ } \ - } + } while (0) #define ERR_FAIL_NULL_V_MSG(m_param, m_retval, m_msg) \ - { \ + do { \ if (unlikely(!m_param)) { \ _err_print_error(FUNCTION_STR, __FILE__, __LINE__, "Parameter \"" _STR(m_param) "\" is null.", DEBUG_STR(m_msg)); \ return m_retval; \ } \ - } + } while (0) // Error condition macros. // Ensures that `m_cond` is not true. @@ -269,193 +269,193 @@ void _err_print_index_error(const char *p_function, const char *p_file, int p_li // The current function returns. #define ERR_FAIL_COND(m_cond) \ - { \ + do { \ if (unlikely(m_cond)) { \ _err_print_error(FUNCTION_STR, __FILE__, __LINE__, "Condition \"" _STR(m_cond) "\" is true."); \ return; \ } \ - } + } while (0) #define ERR_FAIL_COND_MSG(m_cond, m_msg) \ - { \ + do { \ if (unlikely(m_cond)) { \ _err_print_error(FUNCTION_STR, __FILE__, __LINE__, "Condition \"" _STR(m_cond) "\" is true.", DEBUG_STR(m_msg)); \ return; \ } \ - } + } while (0) // The current function returns m_retval. #define ERR_FAIL_COND_V(m_cond, m_retval) \ - { \ + do { \ if (unlikely(m_cond)) { \ _err_print_error(FUNCTION_STR, __FILE__, __LINE__, "Condition \"" _STR(m_cond) "\" is true. returned: " _STR(m_retval)); \ return m_retval; \ } \ - } + } while (0) #define ERR_FAIL_COND_V_MSG(m_cond, m_retval, m_msg) \ - { \ + do { \ if (unlikely(m_cond)) { \ _err_print_error(FUNCTION_STR, __FILE__, __LINE__, "Condition \"" _STR(m_cond) "\" is true. returned: " _STR(m_retval), DEBUG_STR(m_msg)); \ return m_retval; \ } \ - } + } while (0) // The current loop continues. -#define ERR_CONTINUE(m_cond) \ - { \ - if (unlikely(m_cond)) { \ +#define ERR_CONTINUE(m_cond) \ + do { \ + if (unlikely(m_cond)) { \ _err_print_error(FUNCTION_STR, __FILE__, __LINE__, "Condition \"" _STR(m_cond) "\" is true. Continuing."); \ - continue; \ - } \ - } + continue; \ + } \ + } while (0) -#define ERR_CONTINUE_MSG(m_cond, m_msg) \ - { \ - if (unlikely(m_cond)) { \ +#define ERR_CONTINUE_MSG(m_cond, m_msg) \ + do { \ + if (unlikely(m_cond)) { \ _err_print_error(FUNCTION_STR, __FILE__, __LINE__, "Condition \"" _STR(m_cond) "\" is true. Continuing.", DEBUG_STR(m_msg)); \ - continue; \ - } \ - } + continue; \ + } \ + } while (0) // The current loop breaks. -#define ERR_BREAK(m_cond) \ - { \ - if (unlikely(m_cond)) { \ +#define ERR_BREAK(m_cond) \ + do { \ + if (unlikely(m_cond)) { \ _err_print_error(FUNCTION_STR, __FILE__, __LINE__, "Condition \"" _STR(m_cond) "\" is true. Breaking."); \ - break; \ - } \ - } + break; \ + } \ + } while (0) -#define ERR_BREAK_MSG(m_cond, m_msg) \ - { \ - if (unlikely(m_cond)) { \ +#define ERR_BREAK_MSG(m_cond, m_msg) \ + do { \ + if (unlikely(m_cond)) { \ _err_print_error(FUNCTION_STR, __FILE__, __LINE__, "Condition \"" _STR(m_cond) "\" is true. Breaking.", DEBUG_STR(m_msg)); \ - break; \ - } \ - } + break; \ + } \ + } while (0) // Only use CRASH macros if there is no sensible fallback, that is, the error is unrecoverable. #define CRASH_COND(m_cond) \ - { \ + do { \ if (unlikely(m_cond)) { \ _err_print_error(FUNCTION_STR, __FILE__, __LINE__, "FATAL: Condition \"" _STR(m_cond) "\" is true."); \ GENERATE_TRAP(); \ } \ - } + } while (0) #define CRASH_COND_MSG(m_cond, m_msg) \ - { \ + do { \ if (unlikely(m_cond)) { \ _err_print_error(FUNCTION_STR, __FILE__, __LINE__, "FATAL: Condition \"" _STR(m_cond) "\" is true.", DEBUG_STR(m_msg)); \ GENERATE_TRAP(); \ } \ - } + } while (0) // Generic error macros. // The current function returns. #define ERR_FAIL() \ - { \ + do { \ _err_print_error(FUNCTION_STR, __FILE__, __LINE__, "Method/Function Failed."); \ return; \ - } + } while (0) #define ERR_FAIL_MSG(m_msg) \ - { \ + do { \ _err_print_error(FUNCTION_STR, __FILE__, __LINE__, "Method/Function Failed.", DEBUG_STR(m_msg)); \ return; \ - } + } while (0) // The current function returns m_retval. #define ERR_FAIL_V(m_retval) \ - { \ + do { \ _err_print_error(FUNCTION_STR, __FILE__, __LINE__, "Method/Function Failed, returning: " __STR(m_value)); \ return m_retval; \ - } + } while (0) #define ERR_FAIL_V_MSG(m_value, m_msg) \ - { \ + do { \ _err_print_error(FUNCTION_STR, __FILE__, __LINE__, "Method/Function Failed, returning: " __STR(m_value), DEBUG_STR(m_msg)); \ return m_value; \ - } + } while (0) // Print error message macros. #define ERR_PRINT(m_msg) \ - { \ + do { \ _err_print_error(FUNCTION_STR, __FILE__, __LINE__, DEBUG_STR(m_msg)); \ - } + } while (0) // Only prints the error message once. #define ERR_PRINT_ONCE(m_msg) \ - { \ + do { \ static bool first_print = true; \ if (first_print) { \ _err_print_error(FUNCTION_STR, __FILE__, __LINE__, DEBUG_STR(m_msg)); \ first_print = false; \ } \ - } + } while (0) // Print warning message macros. // To warn about deprecated usage, use `WARN_DEPRECATED` or `WARN_DEPRECATED_MSG` instead. #define WARN_PRINT(m_msg) \ - { \ + do { \ _err_print_error(FUNCTION_STR, __FILE__, __LINE__, DEBUG_STR(m_msg), ERR_HANDLER_WARNING); \ - } + } while (0) // Only prints the warning message once. #define WARN_PRINT_ONCE(m_msg) \ - { \ + do { \ static bool first_print = true; \ if (first_print) { \ _err_print_error(FUNCTION_STR, __FILE__, __LINE__, DEBUG_STR(m_msg), ERR_HANDLER_WARNING); \ first_print = false; \ } \ - } + } while (0) // Print deprecated warning message macros. // Only prints the warning message once. -#define WARN_DEPRECATED \ - { \ - static volatile bool warning_shown = false; \ - if (!warning_shown) { \ +#define WARN_DEPRECATED \ + do { \ + static volatile bool warning_shown = false; \ + if (!warning_shown) { \ _err_print_error(FUNCTION_STR, __FILE__, __LINE__, "This method has been deprecated and will be removed in the future.", ERR_HANDLER_WARNING); \ - warning_shown = true; \ - } \ - } - -#define WARN_DEPRECATED_MSG(m_msg) \ - { \ - static volatile bool warning_shown = false; \ - if (!warning_shown) { \ + warning_shown = true; \ + } \ + } while (0) + +#define WARN_DEPRECATED_MSG(m_msg) \ + do { \ + static volatile bool warning_shown = false; \ + if (!warning_shown) { \ _err_print_error(FUNCTION_STR, __FILE__, __LINE__, "This method has been deprecated and will be removed in the future.", DEBUG_STR(m_msg), ERR_HANDLER_WARNING); \ - warning_shown = true; \ - } \ - } + warning_shown = true; \ + } \ + } while (0) // Only use CRASH macros if there is no sensible fallback, that is, the error is unrecoverable. #define CRASH_NOW() \ - { \ + do { \ _err_print_error(FUNCTION_STR, __FILE__, __LINE__, "FATAL: Method/Function Failed."); \ GENERATE_TRAP(); \ - } + } while (0) #define CRASH_NOW_MSG(m_msg) \ - { \ + do { \ _err_print_error(FUNCTION_STR, __FILE__, __LINE__, "FATAL: Method/Function Failed.", DEBUG_STR(m_msg)); \ GENERATE_TRAP(); \ - } + } while (0) #endif -- cgit v1.2.3 From 110f4f2dc5c27dd9b6cb9607d141389944f7c4cc Mon Sep 17 00:00:00 2001 From: Marcel Admiraal Date: Fri, 8 Nov 2019 09:08:51 +0100 Subject: Remove trailing semicolons from do..while wrappers. - Remove trailing semicolons from ERR_FAIL_INDEX macros. - Remove trailing semicolons from ERR_FAIL_UNSIGNED_INDEX macros. - Remove trailing semicolons from CRASH_BAD_INDEX macros. - Remove trailing semicolons from CRASH_BAD_UNSIGNED_INDEX macros. --- core/error_macros.h | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) (limited to 'core/error_macros.h') diff --git a/core/error_macros.h b/core/error_macros.h index 0fe3a5d796..664bff244f 100644 --- a/core/error_macros.h +++ b/core/error_macros.h @@ -121,7 +121,7 @@ void _err_print_index_error(const char *p_function, const char *p_file, int p_li _err_print_index_error(FUNCTION_STR, __FILE__, __LINE__, m_index, m_size, _STR(m_index), _STR(m_size)); \ return; \ } \ - } while (0); + } while (0) #define ERR_FAIL_INDEX_MSG(m_index, m_size, m_msg) \ do { \ @@ -129,7 +129,7 @@ void _err_print_index_error(const char *p_function, const char *p_file, int p_li _err_print_index_error(FUNCTION_STR, __FILE__, __LINE__, m_index, m_size, _STR(m_index), _STR(m_size), DEBUG_STR(m_msg)); \ return; \ } \ - } while (0); + } while (0) // The current function returns m_retval. @@ -139,7 +139,7 @@ void _err_print_index_error(const char *p_function, const char *p_file, int p_li _err_print_index_error(FUNCTION_STR, __FILE__, __LINE__, m_index, m_size, _STR(m_index), _STR(m_size)); \ return m_retval; \ } \ - } while (0); + } while (0) #define ERR_FAIL_INDEX_V_MSG(m_index, m_size, m_retval, m_msg) \ do { \ @@ -147,7 +147,7 @@ void _err_print_index_error(const char *p_function, const char *p_file, int p_li _err_print_index_error(FUNCTION_STR, __FILE__, __LINE__, m_index, m_size, _STR(m_index), _STR(m_size), DEBUG_STR(m_msg)); \ return m_retval; \ } \ - } while (0); + } while (0) // Only use CRASH macros if there is no sensible fallback, that is, the error is unrecoverable. @@ -157,7 +157,7 @@ void _err_print_index_error(const char *p_function, const char *p_file, int p_li _err_print_index_error(FUNCTION_STR, __FILE__, __LINE__, m_index, m_size, _STR(m_index), _STR(m_size), "", true); \ GENERATE_TRAP(); \ } \ - } while (0); + } while (0) #define CRASH_BAD_INDEX_MSG(m_index, m_size, m_msg) \ do { \ @@ -165,7 +165,7 @@ void _err_print_index_error(const char *p_function, const char *p_file, int p_li _err_print_index_error(FUNCTION_STR, __FILE__, __LINE__, m_index, m_size, _STR(m_index), _STR(m_size), DEBUG_STR(m_msg), true); \ GENERATE_TRAP(); \ } \ - } while (0); + } while (0) // Unsigned integer index out of bounds error macros. // Ensures an unsigned integer index `m_index` is less than `m_size` @@ -178,7 +178,7 @@ void _err_print_index_error(const char *p_function, const char *p_file, int p_li _err_print_index_error(FUNCTION_STR, __FILE__, __LINE__, m_index, m_size, _STR(m_index), _STR(m_size)); \ return; \ } \ - } while (0); + } while (0) #define ERR_FAIL_UNSIGNED_INDEX_MSG(m_index, m_size, m_msg) \ do { \ @@ -186,7 +186,7 @@ void _err_print_index_error(const char *p_function, const char *p_file, int p_li _err_print_index_error(FUNCTION_STR, __FILE__, __LINE__, m_index, m_size, _STR(m_index), _STR(m_size), DEBUG_STR(m_msg)); \ return; \ } \ - } while (0); + } while (0) // The current function returns m_retval. @@ -196,7 +196,7 @@ void _err_print_index_error(const char *p_function, const char *p_file, int p_li _err_print_index_error(FUNCTION_STR, __FILE__, __LINE__, m_index, m_size, _STR(m_index), _STR(m_size)); \ return m_retval; \ } \ - } while (0); + } while (0) #define ERR_FAIL_UNSIGNED_INDEX_V_MSG(m_index, m_size, m_retval, m_msg) \ do { \ @@ -204,7 +204,7 @@ void _err_print_index_error(const char *p_function, const char *p_file, int p_li _err_print_index_error(FUNCTION_STR, __FILE__, __LINE__, m_index, m_size, _STR(m_index), _STR(m_size), DEBUG_STR(m_msg)); \ return m_retval; \ } \ - } while (0); + } while (0) // Only use CRASH macros if there is no sensible fallback, that is, the error is unrecoverable. @@ -214,7 +214,7 @@ void _err_print_index_error(const char *p_function, const char *p_file, int p_li _err_print_index_error(FUNCTION_STR, __FILE__, __LINE__, m_index, m_size, _STR(m_index), _STR(m_size), "", true); \ GENERATE_TRAP(); \ } \ - } while (0); + } while (0) #define CRASH_BAD_UNSIGNED_INDEX_MSG(m_index, m_size, m_msg) \ do { \ @@ -222,7 +222,7 @@ void _err_print_index_error(const char *p_function, const char *p_file, int p_li _err_print_index_error(FUNCTION_STR, __FILE__, __LINE__, m_index, m_size, _STR(m_index), _STR(m_size), DEBUG_STR(m_msg), true); \ GENERATE_TRAP(); \ } \ - } while (0); + } while (0) // Null reference error macros. // Ensures a pointer `m_param` is not null. -- cgit v1.2.3 From 677604685dd2292f44fedb1b9a5b08b22137219a Mon Sep 17 00:00:00 2001 From: Marcel Admiraal Date: Wed, 5 Feb 2020 14:39:12 +0100 Subject: Apply macro documentation from #35521. --- core/error_macros.h | 349 ++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 268 insertions(+), 81 deletions(-) (limited to 'core/error_macros.h') diff --git a/core/error_macros.h b/core/error_macros.h index 664bff244f..80ceede043 100644 --- a/core/error_macros.h +++ b/core/error_macros.h @@ -80,10 +80,15 @@ void _err_print_index_error(const char *p_function, const char *p_file, int p_li #define FUNCTION_STR __FUNCTION__ #endif -// Don't use this directly; instead, use any of the CRASH_* macros #ifdef _MSC_VER +/** + * Don't use GENERATE_TRAP() directly, should only be used be the macros below. + */ #define GENERATE_TRAP() __debugbreak() #else +/** + * Don't use GENERATE_TRAP() directly, should only be used be the macros below. + */ #define GENERATE_TRAP() __builtin_trap() #endif @@ -111,10 +116,14 @@ void _err_print_index_error(const char *p_function, const char *p_file, int p_li // These macros should be used instead of `ERR_FAIL_COND` for bounds checking. // Integer index out of bounds error macros. -// Ensures an integer index `m_index` is less than `m_size` and greater than or equal to 0. - -// The current function returns. +/** + * Try using `ERR_FAIL_INDEX_MSG`. + * Only use this macro if there is no sensible error message. + * + * Ensures an integer index `m_index` is less than `m_size` and greater than or equal to 0. + * If not, the current function returns. + */ #define ERR_FAIL_INDEX(m_index, m_size) \ do { \ if (unlikely((m_index) < 0 || (m_index) >= (m_size))) { \ @@ -123,6 +132,10 @@ void _err_print_index_error(const char *p_function, const char *p_file, int p_li } \ } while (0) +/** + * Ensures an integer index `m_index` is less than `m_size` and greater than or equal to 0. + * If not, prints `m_msg` and the current function returns. + */ #define ERR_FAIL_INDEX_MSG(m_index, m_size, m_msg) \ do { \ if (unlikely((m_index) < 0 || (m_index) >= (m_size))) { \ @@ -131,8 +144,13 @@ void _err_print_index_error(const char *p_function, const char *p_file, int p_li } \ } while (0) -// The current function returns m_retval. - +/** + * Try using `ERR_FAIL_INDEX_V_MSG`. + * Only use this macro if there is no sensible error message. + * + * Ensures an integer index `m_index` is less than `m_size` and greater than or equal to 0. + * If not, the current function returns `m_retval`. + */ #define ERR_FAIL_INDEX_V(m_index, m_size, m_retval) \ do { \ if (unlikely((m_index) < 0 || (m_index) >= (m_size))) { \ @@ -141,6 +159,10 @@ void _err_print_index_error(const char *p_function, const char *p_file, int p_li } \ } while (0) +/** + * Ensures an integer index `m_index` is less than `m_size` and greater than or equal to 0. + * If not, prints `m_msg` and the current function returns `m_retval`. + */ #define ERR_FAIL_INDEX_V_MSG(m_index, m_size, m_retval, m_msg) \ do { \ if (unlikely((m_index) < 0 || (m_index) >= (m_size))) { \ @@ -149,8 +171,14 @@ void _err_print_index_error(const char *p_function, const char *p_file, int p_li } \ } while (0) -// Only use CRASH macros if there is no sensible fallback, that is, the error is unrecoverable. - +/** + * Try using `ERR_FAIL_INDEX_MSG` or `ERR_FAIL_INDEX_V_MSG`. + * Only use this macro if there is no sensible fallback i.e. the error is unrecoverable, and + * there is no sensible error message. + * + * Ensures an integer index `m_index` is less than `m_size` and greater than or equal to 0. + * If not, the application crashes. + */ #define CRASH_BAD_INDEX(m_index, m_size) \ do { \ if (unlikely((m_index) < 0 || (m_index) >= (m_size))) { \ @@ -159,6 +187,13 @@ void _err_print_index_error(const char *p_function, const char *p_file, int p_li } \ } while (0) +/** + * Try using `ERR_FAIL_INDEX_MSG` or `ERR_FAIL_INDEX_V_MSG`. + * Only use this macro if there is no sensible fallback i.e. the error is unrecoverable. + * + * Ensures an integer index `m_index` is less than `m_size` and greater than or equal to 0. + * If not, prints `m_msg` and the application crashes. + */ #define CRASH_BAD_INDEX_MSG(m_index, m_size, m_msg) \ do { \ if (unlikely((m_index) < 0 || (m_index) >= (m_size))) { \ @@ -168,10 +203,14 @@ void _err_print_index_error(const char *p_function, const char *p_file, int p_li } while (0) // Unsigned integer index out of bounds error macros. -// Ensures an unsigned integer index `m_index` is less than `m_size` - -// The current function returns. +/** + * Try using `ERR_FAIL_UNSIGNED_INDEX_MSG`. + * Only use this macro if there is no sensible error message. + * + * Ensures an unsigned integer index `m_index` is less than `m_size`. + * If not, the current function returns. + */ #define ERR_FAIL_UNSIGNED_INDEX(m_index, m_size) \ do { \ if (unlikely((m_index) >= (m_size))) { \ @@ -180,6 +219,10 @@ void _err_print_index_error(const char *p_function, const char *p_file, int p_li } \ } while (0) +/** + * Ensures an unsigned integer index `m_index` is less than `m_size`. + * If not, prints `m_msg` and the current function returns. + */ #define ERR_FAIL_UNSIGNED_INDEX_MSG(m_index, m_size, m_msg) \ do { \ if (unlikely((m_index) >= (m_size))) { \ @@ -188,8 +231,13 @@ void _err_print_index_error(const char *p_function, const char *p_file, int p_li } \ } while (0) -// The current function returns m_retval. - +/** + * Try using `ERR_FAIL_UNSIGNED_INDEX_V_MSG`. + * Only use this macro if there is no sensible error message. + * + * Ensures an unsigned integer index `m_index` is less than `m_size`. + * If not, the current function returns `m_retval`. + */ #define ERR_FAIL_UNSIGNED_INDEX_V(m_index, m_size, m_retval) \ do { \ if (unlikely((m_index) >= (m_size))) { \ @@ -198,6 +246,10 @@ void _err_print_index_error(const char *p_function, const char *p_file, int p_li } \ } while (0) +/** + * Ensures an unsigned integer index `m_index` is less than `m_size`. + * If not, prints `m_msg` and the current function returns `m_retval`. + */ #define ERR_FAIL_UNSIGNED_INDEX_V_MSG(m_index, m_size, m_retval, m_msg) \ do { \ if (unlikely((m_index) >= (m_size))) { \ @@ -206,8 +258,14 @@ void _err_print_index_error(const char *p_function, const char *p_file, int p_li } \ } while (0) -// Only use CRASH macros if there is no sensible fallback, that is, the error is unrecoverable. - +/** + * Try using `ERR_FAIL_UNSIGNED_INDEX_MSG` or `ERR_FAIL_UNSIGNED_INDEX_V_MSG`. + * Only use this macro if there is no sensible fallback i.e. the error is unrecoverable, and + * there is no sensible error message. + * + * Ensures an unsigned integer index `m_index` is less than `m_size`. + * If not, the application crashes. + */ #define CRASH_BAD_UNSIGNED_INDEX(m_index, m_size) \ do { \ if (unlikely((m_index) >= (m_size))) { \ @@ -216,6 +274,13 @@ void _err_print_index_error(const char *p_function, const char *p_file, int p_li } \ } while (0) +/** + * Try using `ERR_FAIL_UNSIGNED_INDEX_MSG` or `ERR_FAIL_UNSIGNED_INDEX_V_MSG`. + * Only use this macro if there is no sensible fallback i.e. the error is unrecoverable. + * + * Ensures an unsigned integer index `m_index` is less than `m_size`. + * If not, prints `m_msg` and the application crashes. + */ #define CRASH_BAD_UNSIGNED_INDEX_MSG(m_index, m_size, m_msg) \ do { \ if (unlikely((m_index) >= (m_size))) { \ @@ -225,10 +290,14 @@ void _err_print_index_error(const char *p_function, const char *p_file, int p_li } while (0) // Null reference error macros. -// Ensures a pointer `m_param` is not null. - -// The current function returns. +/** + * Try using `ERR_FAIL_NULL_MSG`. + * Only use this macro if there is no sensible error message. + * + * Ensures a pointer `m_param` is not null. + * If it is null, the current function returns. + */ #define ERR_FAIL_NULL(m_param) \ do { \ if (unlikely(!m_param)) { \ @@ -237,6 +306,10 @@ void _err_print_index_error(const char *p_function, const char *p_file, int p_li } \ } while (0) +/** + * Ensures a pointer `m_param` is not null. + * If it is null, prints `m_msg` and the current function returns. + */ #define ERR_FAIL_NULL_MSG(m_param, m_msg) \ do { \ if (unlikely(!m_param)) { \ @@ -245,8 +318,13 @@ void _err_print_index_error(const char *p_function, const char *p_file, int p_li } \ } while (0) -// The current function returns m_retval. - +/** + * Try using `ERR_FAIL_NULL_V_MSG`. + * Only use this macro if there is no sensible error message. + * + * Ensures a pointer `m_param` is not null. + * If it is null, the current function returns `m_retval`. + */ #define ERR_FAIL_NULL_V(m_param, m_retval) \ do { \ if (unlikely(!m_param)) { \ @@ -255,6 +333,10 @@ void _err_print_index_error(const char *p_function, const char *p_file, int p_li } \ } while (0) +/** + * Ensures a pointer `m_param` is not null. + * If it is null, prints `m_msg` and the current function returns `m_retval`. + */ #define ERR_FAIL_NULL_V_MSG(m_param, m_retval, m_msg) \ do { \ if (unlikely(!m_param)) { \ @@ -263,11 +345,15 @@ void _err_print_index_error(const char *p_function, const char *p_file, int p_li } \ } while (0) -// Error condition macros. -// Ensures that `m_cond` is not true. - -// The current function returns. - +/** + * Try using `ERR_FAIL_COND_MSG`. + * Only use this macro if there is no sensible error message. + * If checking for null use ERR_FAIL_NULL_MSG instead. + * If checking index bounds use ERR_FAIL_INDEX_MSG instead. + * + * Ensures `m_cond` is false. + * If `m_cond` is true, the current function returns. + */ #define ERR_FAIL_COND(m_cond) \ do { \ if (unlikely(m_cond)) { \ @@ -276,6 +362,13 @@ void _err_print_index_error(const char *p_function, const char *p_file, int p_li } \ } while (0) +/** + * Ensures `m_cond` is false. + * If `m_cond` is true, prints `m_msg` and the current function returns. + * + * If checking for null use ERR_FAIL_NULL_MSG instead. + * If checking index bounds use ERR_FAIL_INDEX_MSG instead. + */ #define ERR_FAIL_COND_MSG(m_cond, m_msg) \ do { \ if (unlikely(m_cond)) { \ @@ -284,8 +377,15 @@ void _err_print_index_error(const char *p_function, const char *p_file, int p_li } \ } while (0) -// The current function returns m_retval. - +/** + * Try using `ERR_FAIL_COND_V_MSG`. + * Only use this macro if there is no sensible error message. + * If checking for null use ERR_FAIL_NULL_V_MSG instead. + * If checking index bounds use ERR_FAIL_INDEX_V_MSG instead. + * + * Ensures `m_cond` is false. + * If `m_cond` is true, the current function returns `m_retval`. + */ #define ERR_FAIL_COND_V(m_cond, m_retval) \ do { \ if (unlikely(m_cond)) { \ @@ -294,6 +394,13 @@ void _err_print_index_error(const char *p_function, const char *p_file, int p_li } \ } while (0) +/** + * Ensures `m_cond` is false. + * If `m_cond` is true, prints `m_msg` and the current function returns `m_retval`. + * + * If checking for null use ERR_FAIL_NULL_V_MSG instead. + * If checking index bounds use ERR_FAIL_INDEX_V_MSG instead. + */ #define ERR_FAIL_COND_V_MSG(m_cond, m_retval, m_msg) \ do { \ if (unlikely(m_cond)) { \ @@ -302,44 +409,68 @@ void _err_print_index_error(const char *p_function, const char *p_file, int p_li } \ } while (0) -// The current loop continues. - -#define ERR_CONTINUE(m_cond) \ - do { \ - if (unlikely(m_cond)) { \ +/** + * Try using `ERR_CONTINUE_MSG`. + * Only use this macro if there is no sensible error message. + * + * Ensures `m_cond` is false. + * If `m_cond` is true, the current loop continues. + */ +#define ERR_CONTINUE(m_cond) \ + do { \ + if (unlikely(m_cond)) { \ _err_print_error(FUNCTION_STR, __FILE__, __LINE__, "Condition \"" _STR(m_cond) "\" is true. Continuing."); \ - continue; \ - } \ + continue; \ + } \ } while (0) -#define ERR_CONTINUE_MSG(m_cond, m_msg) \ - do { \ - if (unlikely(m_cond)) { \ +/** + * Ensures `m_cond` is false. + * If `m_cond` is true, prints `m_msg` and the current loop continues. + */ +#define ERR_CONTINUE_MSG(m_cond, m_msg) \ + do { \ + if (unlikely(m_cond)) { \ _err_print_error(FUNCTION_STR, __FILE__, __LINE__, "Condition \"" _STR(m_cond) "\" is true. Continuing.", DEBUG_STR(m_msg)); \ - continue; \ - } \ + continue; \ + } \ } while (0) -// The current loop breaks. - -#define ERR_BREAK(m_cond) \ - do { \ - if (unlikely(m_cond)) { \ +/** + * Try using `ERR_BREAK_MSG`. + * Only use this macro if there is no sensible error message. + * + * Ensures `m_cond` is false. + * If `m_cond` is true, the current loop breaks. + */ +#define ERR_BREAK(m_cond) \ + do { \ + if (unlikely(m_cond)) { \ _err_print_error(FUNCTION_STR, __FILE__, __LINE__, "Condition \"" _STR(m_cond) "\" is true. Breaking."); \ - break; \ - } \ + break; \ + } \ } while (0) -#define ERR_BREAK_MSG(m_cond, m_msg) \ - do { \ - if (unlikely(m_cond)) { \ +/** + * Ensures `m_cond` is false. + * If `m_cond` is true, prints `m_msg` and the current loop breaks. + */ +#define ERR_BREAK_MSG(m_cond, m_msg) \ + do { \ + if (unlikely(m_cond)) { \ _err_print_error(FUNCTION_STR, __FILE__, __LINE__, "Condition \"" _STR(m_cond) "\" is true. Breaking.", DEBUG_STR(m_msg)); \ - break; \ - } \ + break; \ + } \ } while (0) -// Only use CRASH macros if there is no sensible fallback, that is, the error is unrecoverable. - +/** + * Try using `ERR_FAIL_COND_MSG` or `ERR_FAIL_COND_V_MSG`. + * Only use this macro if there is no sensible fallback i.e. the error is unrecoverable, and + * there is no sensible error message. + * + * Ensures `m_cond` is false. + * If `m_cond` is true, the application crashes. + */ #define CRASH_COND(m_cond) \ do { \ if (unlikely(m_cond)) { \ @@ -348,6 +479,13 @@ void _err_print_index_error(const char *p_function, const char *p_file, int p_li } \ } while (0) +/** + * Try using `ERR_FAIL_COND_MSG` or `ERR_FAIL_COND_V_MSG`. + * Only use this macro if there is no sensible fallback i.e. the error is unrecoverable. + * + * Ensures `m_cond` is false. + * If `m_cond` is true, prints `m_msg` and the application crashes. + */ #define CRASH_COND_MSG(m_cond, m_msg) \ do { \ if (unlikely(m_cond)) { \ @@ -358,43 +496,71 @@ void _err_print_index_error(const char *p_function, const char *p_file, int p_li // Generic error macros. -// The current function returns. - +/** + * Try using `ERR_FAIL_COND_MSG` or `ERR_FAIL_MSG`. + * Only use this macro if more complex error detection or recovery is required, and + * there is no sensible error message. + * + * The current function returns. + */ #define ERR_FAIL() \ do { \ _err_print_error(FUNCTION_STR, __FILE__, __LINE__, "Method/Function Failed."); \ return; \ } while (0) +/** + * Try using `ERR_FAIL_COND_MSG`. + * Only use this macro if more complex error detection or recovery is required. + * + * Prints `m_msg`, and the current function returns. + */ #define ERR_FAIL_MSG(m_msg) \ do { \ _err_print_error(FUNCTION_STR, __FILE__, __LINE__, "Method/Function Failed.", DEBUG_STR(m_msg)); \ return; \ } while (0) -// The current function returns m_retval. - +/** + * Try using `ERR_FAIL_COND_V_MSG` or `ERR_FAIL_V_MSG`. + * Only use this macro if more complex error detection or recovery is required, and + * there is no sensible error message. + * + * The current function returns `m_retval`. + */ #define ERR_FAIL_V(m_retval) \ do { \ _err_print_error(FUNCTION_STR, __FILE__, __LINE__, "Method/Function Failed, returning: " __STR(m_value)); \ return m_retval; \ } while (0) -#define ERR_FAIL_V_MSG(m_value, m_msg) \ +/** + * Try using `ERR_FAIL_COND_V_MSG`. + * Only use this macro if more complex error detection or recovery is required. + * + * Prints `m_msg`, and the current function returns `m_retval`. + */ +#define ERR_FAIL_V_MSG(m_retval, m_msg) \ do { \ _err_print_error(FUNCTION_STR, __FILE__, __LINE__, "Method/Function Failed, returning: " __STR(m_value), DEBUG_STR(m_msg)); \ - return m_value; \ + return m_retval; \ } while (0) -// Print error message macros. - +/** + * Try using `ERR_FAIL_COND_MSG`, `ERR_FAIL_COND_V_MSG`, `ERR_CONTINUE_MSG` or ERR_BREAK_MSG. + * Only use this macro at the start of a function that has not been implemented yet, or + * if more complex error detection or recovery is required. + * + * Prints `m_msg`. + */ #define ERR_PRINT(m_msg) \ do { \ _err_print_error(FUNCTION_STR, __FILE__, __LINE__, DEBUG_STR(m_msg)); \ } while (0) -// Only prints the error message once. - +/** + * Prints `m_msg` once during the application lifetime. + */ #define ERR_PRINT_ONCE(m_msg) \ do { \ static bool first_print = true; \ @@ -405,15 +571,22 @@ void _err_print_index_error(const char *p_function, const char *p_file, int p_li } while (0) // Print warning message macros. -// To warn about deprecated usage, use `WARN_DEPRECATED` or `WARN_DEPRECATED_MSG` instead. +/** + * Prints `m_msg`. + * + * If warning about deprecated usage, use `WARN_DEPRECATED` or `WARN_DEPRECATED_MSG` instead. + */ #define WARN_PRINT(m_msg) \ do { \ _err_print_error(FUNCTION_STR, __FILE__, __LINE__, DEBUG_STR(m_msg), ERR_HANDLER_WARNING); \ } while (0) -// Only prints the warning message once. - +/** + * Prints `m_msg` once during the application lifetime. + * + * If warning about deprecated usage, use `WARN_DEPRECATED` or `WARN_DEPRECATED_MSG` instead. + */ #define WARN_PRINT_ONCE(m_msg) \ do { \ static bool first_print = true; \ @@ -424,34 +597,48 @@ void _err_print_index_error(const char *p_function, const char *p_file, int p_li } while (0) // Print deprecated warning message macros. -// Only prints the warning message once. -#define WARN_DEPRECATED \ - do { \ - static volatile bool warning_shown = false; \ - if (!warning_shown) { \ +/** + * Warns that the current function is deprecated. + */ +#define WARN_DEPRECATED \ + do { \ + static volatile bool warning_shown = false; \ + if (!warning_shown) { \ _err_print_error(FUNCTION_STR, __FILE__, __LINE__, "This method has been deprecated and will be removed in the future.", ERR_HANDLER_WARNING); \ - warning_shown = true; \ - } \ + warning_shown = true; \ + } \ } while (0) -#define WARN_DEPRECATED_MSG(m_msg) \ - do { \ - static volatile bool warning_shown = false; \ - if (!warning_shown) { \ +/** + * Warns that the current function is deprecated and prints `m_msg`. + */ +#define WARN_DEPRECATED_MSG(m_msg) \ + do { \ + static volatile bool warning_shown = false; \ + if (!warning_shown) { \ _err_print_error(FUNCTION_STR, __FILE__, __LINE__, "This method has been deprecated and will be removed in the future.", DEBUG_STR(m_msg), ERR_HANDLER_WARNING); \ - warning_shown = true; \ - } \ + warning_shown = true; \ + } \ } while (0) -// Only use CRASH macros if there is no sensible fallback, that is, the error is unrecoverable. - +/** + * Do not use. + * If the application should never reach this point use CRASH_NOW_MSG(m_msg) to explain why. + * + * The application crashes. + */ #define CRASH_NOW() \ do { \ _err_print_error(FUNCTION_STR, __FILE__, __LINE__, "FATAL: Method/Function Failed."); \ GENERATE_TRAP(); \ } while (0) +/** + * Only use if the application should never reach this point. + * + * Prints `m_msg`, and then the application crashes. + */ #define CRASH_NOW_MSG(m_msg) \ do { \ _err_print_error(FUNCTION_STR, __FILE__, __LINE__, "FATAL: Method/Function Failed.", DEBUG_STR(m_msg)); \ -- cgit v1.2.3