nanocoat/include/sjme/debug.h

   1 /* -*- Mode: C; indent-tabs-mode: t; tab-width: 4 -*-
   2 // ---------------------------------------------------------------------------
   3 // SquirrelJME
   4 //     Copyright (C) Stephanie Gawroriski <xer@multiphasicapps.net>
   5 // ---------------------------------------------------------------------------
   6 // SquirrelJME is under the Mozilla Public License Version 2.0.
   7 // See license.mkd for licensing and copyright information.
   8 // -------------------------------------------------------------------------*/
   9
  10 /**
  11  * Debugging helpers.
  12  *
  13  * @since 2023/07/27
  14  */
  15
  16 #ifndef SQUIRRELJME_DEBUG_H
  17 #define SQUIRRELJME_DEBUG_H
  18
  19 #include <stdarg.h>
  20
  21 #include "sjme/nvm.h"
  22 #include "sjme/dylib.h"
  23
  24 /* Anti-C++. */
  25 #ifdef __cplusplus
  26         #ifndef SJME_CXX_IS_EXTERNED
  27                 #define SJME_CXX_IS_EXTERNED
  28                 #define SJME_CXX_SQUIRRELJME_DEBUG_H
  29 extern "C" {
  30         #endif /* #ifdef SJME_CXX_IS_EXTERNED */
  31 #endif     /* #ifdef __cplusplus */
  32
  33 /*--------------------------------------------------------------------------*/
  34
  35 #define SJME_DEBUG_DECL_FILE_LINE_FUNC \
  36         sjme_attrInNullable sjme_lpcstr file, \
  37         sjme_attrInValue int line, \
  38         sjme_attrInNullable sjme_lpcstr func
  39
  40 /** File, line, and function. */
  41 #define SJME_DEBUG_FILE_LINE_FUNC_ALWAYS __FILE__, __LINE__, __func__
  42
  43 #if defined(SJME_CONFIG_RELEASE)
  44         /** Debug comma. */
  45         #define SJME_DEBUG_ONLY_COMMA
  46
  47         /** Optional declaration for debugging. */
  48         #define SJME_DEBUG_DECL_FILE_LINE_FUNC_OPTIONAL
  49
  50         /** File, line, and function. */
  51         #define SJME_DEBUG_FILE_LINE_FUNC NULL, -1, NULL
  52
  53         /** Copy of file line and function. */
  54         #define SJME_DEBUG_FILE_LINE_COPY
  55
  56         /** Only emitted in debugging. */
  57         #define SJME_ONLY_IN_DEBUG_EXPR(expr) do {} while(0)
  58
  59         /** Only emitted in debugging. */
  60         #define SJME_ONLY_IN_DEBUG_PP(expr)
  61
  62         /** Release/Debug ternary. */
  63         #define SJME_DEBUG_TERNARY(debug, release) release
  64
  65         /** Debug identifier. */
  66         #define SJME_DEBUG_IDENTIFIER(ident) ident
  67 #else
  68         /** Debug comma. */
  69         #define SJME_DEBUG_ONLY_COMMA ,
  70
  71         /** Optional declaration for debugging. */
  72         #define SJME_DEBUG_DECL_FILE_LINE_FUNC_OPTIONAL \
  73                 SJME_DEBUG_DECL_FILE_LINE_FUNC
  74
  75         /** File, line, and function. */
  76         #define SJME_DEBUG_FILE_LINE_FUNC SJME_DEBUG_FILE_LINE_FUNC_ALWAYS
  77
  78         /** Copy of file line and function. */
  79         #define SJME_DEBUG_FILE_LINE_COPY file, line, func
  80
  81         /** Only emitted in debugging. */
  82         #define SJME_ONLY_IN_DEBUG_EXPR(expr) expr
  83
  84         /** Only emitted in debugging. */
  85         #define SJME_ONLY_IN_DEBUG_PP(expr) expr
  86
  87         /** Release/Debug ternary. */
  88         #define SJME_DEBUG_TERNARY(debug, release) debug
  89
  90         /** Debug identifier. */
  91         #define SJME_DEBUG_IDENTIFIER(ident) ident##R
  92 #endif
  93
  94 /**
  95  * Prints a debug message.
  96  *
  97  * @param file The file printing from.
  98  * @param line The line printing from.
  99  * @param func The function printing from.
 100  * @param isBlank Is this blank?
 101  * @param message The @c printf style message.
 102  * @param ... Any @c printf style arguments.
 103  * @since 2021/10/31
 104  */
 105 void sjme_messageR(SJME_DEBUG_DECL_FILE_LINE_FUNC,
 106         sjme_attrInValue sjme_jboolean isBlank,
 107         sjme_attrInNullable sjme_attrFormatArg sjme_lpcstr message, ...)
 108         sjme_attrFormatOuter(4, 5);
 109
 110 #if defined(SJME_CONFIG_DEBUG)
 111 /**
 112  * Prints a debug message.
 113  *
 114  * @param file The file printing from.
 115  * @param line The line printing from.
 116  * @param func The function printing from.
 117  * @param isBlank Is this blank?
 118  * @param message The @c printf style message.
 119  * @param args Any @c printf style arguments.
 120  * @since 2023/11/11
 121  */
 122 void sjme_messageV(SJME_DEBUG_DECL_FILE_LINE_FUNC,
 123         sjme_attrInValue sjme_jboolean isBlank,
 124         sjme_attrInNullable sjme_attrFormatArg sjme_lpcstr message,
 125         va_list args);
 126 #endif
 127
 128 /**
 129  * Prints a debug message
 130  *
 131  * @param message The @c printf style message.
 132  * @param ... Any @c printf style arguments.
 133  * @since 2021/10/31
 134  */
 135 #define sjme_message(...) SJME_ONLY_IN_DEBUG_EXPR( \
 136         sjme_messageR(SJME_DEBUG_FILE_LINE_FUNC, SJME_JNI_FALSE, __VA_ARGS__))
 137
 138 /**
 139  * Indicates a fatal error and exits the program.
 140  *
 141  * @param file The file printing from.
 142  * @param line The line printing from.
 143  * @param func The function printing from.
 144  * @param message The @c printf style message.
 145  * @param ... Any @c printf style arguments.
 146  * @return Never returns.
 147  * @since 2023/11/11
 148  */
 149 sjme_errorCode sjme_dieR(SJME_DEBUG_DECL_FILE_LINE_FUNC,
 150         sjme_attrInNullable sjme_attrFormatArg sjme_lpcstr message, ...)
 151         sjme_attrReturnNever sjme_attrFormatOuter(3, 4);
 152
 153 /**
 154  * Indicates a fatal error and exits the program.
 155  *
 156  * @param message The @c printf style message.
 157  * @param ... Any @c printf style arguments.
 158  * @return Never returns.
 159  * @since 2023/11/11
 160  */
 161 #define sjme_die(...) sjme_dieR(SJME_DEBUG_FILE_LINE_FUNC, __VA_ARGS__)
 162
 163 /**
 164  * Indicates a fatal error and exits the program.
 165  *
 166  * @param message The @c printf style message.
 167  * @param ... Any @c printf style arguments.
 168  * @return Never returns.
 169  * @since 2023/11/11
 170  */
 171 #define sjme_dieP(...) ((sjme_pointer)((intptr_t)sjme_dieR(\
 172         SJME_DEBUG_FILE_LINE_FUNC, __VA_ARGS__)))
 173
 174 /**
 175  * Indicates a To-Do and then terminates the program.
 176  *
 177  * @param file The file printing from.
 178  * @param line The line printing from.
 179  * @param func The function printing from.
 180  * @param message The @c printf style message.
 181  * @param ... Any @c printf style arguments.
 182  * @return Never returns.
 183  * @since 2021/02/28
 184  */
 185 void sjme_todoR(SJME_DEBUG_DECL_FILE_LINE_FUNC,
 186         sjme_attrInNullable sjme_attrFormatArg sjme_lpcstr message, ...)
 187         sjme_attrReturnNever sjme_attrFormatOuter(3, 4);
 188
 189 /**
 190  * Indicates a To-Do and then terminates the program.
 191  *
 192  * @param message The @c printf style message.
 193  * @param ... Any @c printf style arguments.
 194  * @return Never returns.
 195  * @since 2021/02/28
 196  */
 197 #define sjme_todo(...) sjme_todoR(SJME_DEBUG_FILE_LINE_FUNC_ALWAYS, \
 198         __VA_ARGS__)
 199
 200 /**
 201  * Potentially debug aborts.
 202  *
 203  * @since 2023/12/21
 204  */
 205 void sjme_debug_abort(void);
 206
 207 /**
 208  * Shorted the path of the specified file for debug printing purposes.
 209  *
 210  * @param file The file to shorten.
 211  * @return The resultant shortened file.
 212  * @since 2024/02/08
 213  */
 214 sjme_lpcstr sjme_debug_shortenFile(sjme_lpcstr file);
 215
 216 /**
 217  * Allows for optional debug abort when a fatal error is hit.
 218  *
 219  * @param error The error to return.
 220  * @return The @c error value.
 221  * @since 2024/07/31
 222  */
 223 sjme_errorCode sjme_error_fatalR(SJME_DEBUG_DECL_FILE_LINE_FUNC,
 224         sjme_attrInValue sjme_errorCode error);
 225
 226 /**
 227  * Allows for optional debug abort when a fatal error is hit.
 228  *
 229  * @param error The error to return.
 230  * @return The @c error value.
 231  * @since 2024/07/31
 232  */
 233 #define sjme_error_fatal(error) \
 234         sjme_error_fatalR(SJME_DEBUG_FILE_LINE_FUNC_ALWAYS, error)
 235
 236 /**
 237  * Allows for optional debug abort when unimplemented code is hit.
 238  *
 239  * @param context Any value.
 240  * @return Always @c SJME_ERROR_NOT_IMPLEMENTED .
 241  * @since 2024/07/30
 242  */
 243 sjme_errorCode sjme_error_notImplementedR(SJME_DEBUG_DECL_FILE_LINE_FUNC,
 244         sjme_attrInValue sjme_intPointer context);
 245
 246 /**
 247  * Allows for optional debug abort when unimplemented code is hit.
 248  *
 249  * @param context Any value.
 250  * @return Always @c SJME_ERROR_NOT_IMPLEMENTED .
 251  * @since 2024/07/30
 252  */
 253 #define sjme_error_notImplemented(context) \
 254         sjme_error_notImplementedR(SJME_DEBUG_FILE_LINE_FUNC_ALWAYS, \
 255         (sjme_intPointer)(context))
 256
 257 /**
 258  * Allows for optional debug abort when out of memory is hit.
 259  *
 260  * @param inPool The pool the allocation was within, if applicable.
 261  * @param context Any value.
 262  * @return Always @c SJME_ERROR_OUT_OF_MEMORY .
 263  * @since 2024/08/15
 264  */
 265 sjme_errorCode sjme_error_outOfMemoryR(SJME_DEBUG_DECL_FILE_LINE_FUNC,
 266         sjme_attrInNullable sjme_alloc_pool* inPool,
 267         sjme_attrInValue sjme_intPointer context);
 268
 269 /**
 270  * Allows for optional debug abort when out of memory is hit.
 271  *
 272  * @param inPool The pool the allocation was within, if applicable.
 273  * @param context Any value.
 274  * @return Always @c SJME_ERROR_OUT_OF_MEMORY .
 275  * @since 2024/08/15
 276  */
 277 #define sjme_error_outOfMemory(inPool, context) \
 278         sjme_error_outOfMemoryR(SJME_DEBUG_FILE_LINE_FUNC_ALWAYS, \
 279         (inPool), (sjme_intPointer)(context))
 280
 281 /**
 282  * Handles specific debug abort scenarios.
 283  *
 284  * @return Return @c SJME_JNI_TRUE if it was handled and abort should be
 285  * cancelled, otherwise @c SJME_JNI_FALSE will continue aborting.
 286  * @since 2023/12/21
 287  */
 288 typedef sjme_jboolean (*sjme_debug_abortHandlerFunc)(void);
 289
 290 /**
 291  * Handler for specific debug exit scenarios.
 292  *
 293  * @param exitCode The exit code.
 294  * @return Return @c SJME_JNI_TRUE if it was handled.
 295  * @since 2023/12/21
 296  */
 297 typedef sjme_jboolean (*sjme_debug_exitHandlerFunc)(int exitCode);
 298
 299 /**
 300  * Emits a dangling reference message.
 301  *
 302  * @param fullMessage The message to emit.
 303  * @param partMessage Partial message, without any prepend.
 304  * @return Return @c SJME_JNI_TRUE if the message is handled, otherwise
 305  * a standard @c fprintf to @c stderr will be used.
 306  * @since 2023/12/05
 307  */
 308 typedef sjme_jboolean (*sjme_debug_messageHandlerFunc)(sjme_lpcstr fullMessage,
 309         sjme_lpcstr partMessage);
 310
 311 /**
 312  * The set of functions to use for debugging functions.
 313  *
 314  * @since 2024/06/13
 315  */
 316 typedef struct sjme_debug_handlerFunctions
 317 {
 318         /** The handler for debug aborts. */
 319         sjme_debug_abortHandlerFunc abort;
 320
 321         /** The handler for debug exits. */
 322         sjme_debug_exitHandlerFunc exit;
 323
 324         /** The dangling message implementation to use. */
 325         sjme_debug_messageHandlerFunc message;
 326 } sjme_debug_handlerFunctions;
 327
 328 /** The debug handlers to use. */
 329 extern SJME_DYLIB_EXPORT
 330         sjme_debug_handlerFunctions* sjme_debug_handlers;
 331
 332 /*--------------------------------------------------------------------------*/
 333
 334 /* Anti-C++. */
 335 #ifdef __cplusplus
 336         #ifdef SJME_CXX_SQUIRRELJME_DEBUG_H
 337 }
 338                 #undef SJME_CXX_SQUIRRELJME_DEBUG_H
 339                 #undef SJME_CXX_IS_EXTERNED
 340         #endif /* #ifdef SJME_CXX_SQUIRRELJME_DEBUG_H */
 341 #endif     /* #ifdef __cplusplus */
 342
 343 #endif /* SQUIRRELJME_DEBUG_H */