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/stdTypes.h"
  22 #include "sjme/error.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 /**
 111  * Hex dumps the given data.
 112  *
 113  * @param inData The data to dump.
 114  * @param inLen The data length.
 115  * @since 2024/08/17
 116  */
 117 void sjme_message_hexDump(
 118         sjme_attrInNullable sjme_buffer inData,
 119         sjme_attrInPositive sjme_jint inLen);
 120
 121 #if defined(SJME_CONFIG_DEBUG)
 122 /**
 123  * Prints a debug message.
 124  *
 125  * @param file The file printing from.
 126  * @param line The line printing from.
 127  * @param func The function printing from.
 128  * @param isBlank Is this blank?
 129  * @param message The @c printf style message.
 130  * @param args Any @c printf style arguments.
 131  * @since 2023/11/11
 132  */
 133 void sjme_messageV(SJME_DEBUG_DECL_FILE_LINE_FUNC,
 134         sjme_attrInValue sjme_jboolean isBlank,
 135         sjme_attrInNullable sjme_attrFormatArg sjme_lpcstr message,
 136         va_list args);
 137 #endif
 138
 139 /**
 140  * Prints a debug message
 141  *
 142  * @param message The @c printf style message.
 143  * @param ... Any @c printf style arguments.
 144  * @since 2021/10/31
 145  */
 146 #define sjme_message(...) SJME_ONLY_IN_DEBUG_EXPR( \
 147         sjme_messageR(SJME_DEBUG_FILE_LINE_FUNC, SJME_JNI_FALSE, __VA_ARGS__))
 148
 149 /**
 150  * Indicates a fatal error and exits the program.
 151  *
 152  * @param file The file printing from.
 153  * @param line The line printing from.
 154  * @param func The function printing from.
 155  * @param message The @c printf style message.
 156  * @param ... Any @c printf style arguments.
 157  * @return Never returns.
 158  * @since 2023/11/11
 159  */
 160 sjme_errorCode sjme_dieR(SJME_DEBUG_DECL_FILE_LINE_FUNC,
 161         sjme_attrInNullable sjme_attrFormatArg sjme_lpcstr message, ...)
 162         sjme_attrReturnNever sjme_attrFormatOuter(3, 4);
 163
 164 /**
 165  * Indicates a fatal error and exits the program.
 166  *
 167  * @param message The @c printf style message.
 168  * @param ... Any @c printf style arguments.
 169  * @return Never returns.
 170  * @since 2023/11/11
 171  */
 172 #define sjme_die(...) sjme_dieR(SJME_DEBUG_FILE_LINE_FUNC, __VA_ARGS__)
 173
 174 /**
 175  * Indicates a fatal error and exits the program.
 176  *
 177  * @param message The @c printf style message.
 178  * @param ... Any @c printf style arguments.
 179  * @return Never returns.
 180  * @since 2023/11/11
 181  */
 182 #define sjme_dieP(...) ((sjme_pointer)((intptr_t)sjme_dieR(\
 183         SJME_DEBUG_FILE_LINE_FUNC, __VA_ARGS__)))
 184
 185 /**
 186  * Indicates a To-Do and then terminates the program.
 187  *
 188  * @param file The file printing from.
 189  * @param line The line printing from.
 190  * @param func The function printing from.
 191  * @param message The @c printf style message.
 192  * @param ... Any @c printf style arguments.
 193  * @return Never returns.
 194  * @since 2021/02/28
 195  */
 196 void sjme_todoR(SJME_DEBUG_DECL_FILE_LINE_FUNC,
 197         sjme_attrInNullable sjme_attrFormatArg sjme_lpcstr message, ...)
 198         sjme_attrReturnNever sjme_attrFormatOuter(3, 4);
 199
 200 /**
 201  * Indicates a To-Do and then terminates the program.
 202  *
 203  * @param message The @c printf style message.
 204  * @param ... Any @c printf style arguments.
 205  * @return Never returns.
 206  * @since 2021/02/28
 207  */
 208 #define sjme_todo(...) sjme_todoR(SJME_DEBUG_FILE_LINE_FUNC_ALWAYS, \
 209         __VA_ARGS__)
 210
 211 /**
 212  * Potentially debug aborts.
 213  *
 214  * @since 2023/12/21
 215  */
 216 void sjme_debug_abort(void);
 217
 218 /**
 219  * Shorted the path of the specified file for debug printing purposes.
 220  *
 221  * @param file The file to shorten.
 222  * @return The resultant shortened file.
 223  * @since 2024/02/08
 224  */
 225 sjme_lpcstr sjme_debug_shortenFile(sjme_lpcstr file);
 226
 227 /**
 228  * Allows for optional debug abort when a fatal error is hit.
 229  *
 230  * @param error The error to return.
 231  * @return The @c error value.
 232  * @since 2024/07/31
 233  */
 234 sjme_errorCode sjme_error_fatalR(SJME_DEBUG_DECL_FILE_LINE_FUNC,
 235         sjme_attrInValue sjme_errorCode error);
 236
 237 /**
 238  * Allows for optional debug abort when a fatal error is hit.
 239  *
 240  * @param error The error to return.
 241  * @return The @c error value.
 242  * @since 2024/07/31
 243  */
 244 #define sjme_error_fatal(error) \
 245         sjme_error_fatalR(SJME_DEBUG_FILE_LINE_FUNC_ALWAYS, error)
 246
 247 /**
 248  * Allows for optional debug abort when unimplemented code is hit.
 249  *
 250  * @param context Any value.
 251  * @return Always @c SJME_ERROR_NOT_IMPLEMENTED .
 252  * @since 2024/07/30
 253  */
 254 sjme_errorCode sjme_error_notImplementedR(SJME_DEBUG_DECL_FILE_LINE_FUNC,
 255         sjme_attrInValue sjme_intPointer context);
 256
 257 /**
 258  * Allows for optional debug abort when unimplemented code is hit.
 259  *
 260  * @param context Any value.
 261  * @return Always @c SJME_ERROR_NOT_IMPLEMENTED .
 262  * @since 2024/07/30
 263  */
 264 #define sjme_error_notImplemented(context) \
 265         sjme_error_notImplementedR(SJME_DEBUG_FILE_LINE_FUNC_ALWAYS, \
 266         (sjme_intPointer)(context))
 267
 268 /**
 269  * Allows for optional debug abort when out of memory is hit.
 270  *
 271  * @param inPool The pool the allocation was within, if applicable.
 272  * @param context Any value.
 273  * @return Always @c SJME_ERROR_OUT_OF_MEMORY .
 274  * @since 2024/08/15
 275  */
 276 sjme_errorCode sjme_error_outOfMemoryR(SJME_DEBUG_DECL_FILE_LINE_FUNC,
 277         sjme_attrInNullable sjme_alloc_pool* inPool,
 278         sjme_attrInValue sjme_intPointer context);
 279
 280 /**
 281  * Allows for optional debug abort when out of memory is hit.
 282  *
 283  * @param inPool The pool the allocation was within, if applicable.
 284  * @param context Any value.
 285  * @return Always @c SJME_ERROR_OUT_OF_MEMORY .
 286  * @since 2024/08/15
 287  */
 288 #define sjme_error_outOfMemory(inPool, context) \
 289         sjme_error_outOfMemoryR(SJME_DEBUG_FILE_LINE_FUNC_ALWAYS, \
 290         (inPool), (sjme_intPointer)(context))
 291
 292 /**
 293  * Handles specific debug abort scenarios.
 294  *
 295  * @return Return @c SJME_JNI_TRUE if it was handled and abort should be
 296  * cancelled, otherwise @c SJME_JNI_FALSE will continue aborting.
 297  * @since 2023/12/21
 298  */
 299 typedef sjme_jboolean (*sjme_debug_abortHandlerFunc)(void);
 300
 301 /**
 302  * Handler for specific debug exit scenarios.
 303  *
 304  * @param exitCode The exit code.
 305  * @return Return @c SJME_JNI_TRUE if it was handled.
 306  * @since 2023/12/21
 307  */
 308 typedef sjme_jboolean (*sjme_debug_exitHandlerFunc)(int exitCode);
 309
 310 /**
 311  * Emits a dangling reference message.
 312  *
 313  * @param fullMessage The message to emit.
 314  * @param partMessage Partial message, without any prepend.
 315  * @return Return @c SJME_JNI_TRUE if the message is handled, otherwise
 316  * a standard @c fprintf to @c stderr will be used.
 317  * @since 2023/12/05
 318  */
 319 typedef sjme_jboolean (*sjme_debug_messageHandlerFunc)(sjme_lpcstr fullMessage,
 320         sjme_lpcstr partMessage);
 321
 322 /**
 323  * The set of functions to use for debugging functions.
 324  *
 325  * @since 2024/06/13
 326  */
 327 typedef struct sjme_debug_handlerFunctions
 328 {
 329         /** The handler for debug aborts. */
 330         sjme_debug_abortHandlerFunc abort;
 331
 332         /** The handler for debug exits. */
 333         sjme_debug_exitHandlerFunc exit;
 334
 335         /** The dangling message implementation to use. */
 336         sjme_debug_messageHandlerFunc message;
 337 } sjme_debug_handlerFunctions;
 338
 339 /*--------------------------------------------------------------------------*/
 340
 341 /* Anti-C++. */
 342 #ifdef __cplusplus
 343         #ifdef SJME_CXX_SQUIRRELJME_DEBUG_H
 344 }
 345                 #undef SJME_CXX_SQUIRRELJME_DEBUG_H
 346                 #undef SJME_CXX_IS_EXTERNED
 347         #endif /* #ifdef SJME_CXX_SQUIRRELJME_DEBUG_H */
 348 #endif     /* #ifdef __cplusplus */
 349
 350 #endif /* SQUIRRELJME_DEBUG_H */