nx_metadata_sdk 1.0 Metadata SDK

Classes | Macros | Typedefs | Functions
debug.h File Reference
`#include <iostream>`
`#include <stdint.h>`
`#include <functional>`
`#include <sstream>`
`#include <memory>`
`#include <nx/kit/utils.h>`

Go to the source code of this file.

## Classes
class | nx::kit::debug::detail::Timer
class | nx::kit::debug::detail::Fps

## Macros
#define | NX_KIT_API /*empty*/
#define | NX_DEBUG_INI ini().
#define | NX_DEBUG_ENABLE_OUTPUT NX_DEBUG_INI enableOutput
#define | NX_PRINT_PREFIX ::nx::kit::debug::detail::printPrefix(__FILE__)
#define | NX_DEBUG_STREAM *::nx::kit::debug::stream()
#define | NX_DEBUG_ENDL << std::endl
#define | NX_PRINT
#define | NX_OUTPUT
#define | NX_KIT_ASSERT(...)
#define | LL
#define | NX_PRINT_VALUE(VALUE) NX_PRINT << "####### " #VALUE ": " + ::nx::kit::utils::toString(VALUE)
#define | NX_PRINT_HEX_DUMP(CAPTION, BYTES, SIZE)
#define | NX_DEBUG_SAVE_DIR ::nx::kit::IniConfig::iniFilesDir()
#define | NX_SAVE_STR(FILENAME, STR)
#define | NX_SAVE_BIN(FILENAME, BYTES, SIZE)
#define | NX_DEBUG_ENABLE_TIME NX_DEBUG_INI enableTime
#define | NX_TIME_BEGIN(TAG)
#define | NX_TIME_MARK(TAG, MARK)
#define | NX_TIME_END(TAG)
#define | NX_DEBUG_ENABLE_FPS NX_DEBUG_INI enableFps
#define | NX_FPS(TAG, ...)
#define | NX_KIT_DEBUG_DETAIL_PRINT_FUNC ([&](const char* message) { NX_PRINT << message; })
#define | NX_KIT_DEBUG_DETAIL_MSVC_EXPAND(ARG) ARG
#define | NX_KIT_DEBUG_DETAIL_GET_3RD_ARG(ARG1, ARG2, ARG3, ...) ARG3
#define | NX_KIT_DEBUG_DETAIL_ASSERT1(CONDITION)
#define | NX_KIT_DEBUG_DETAIL_ASSERT2(CONDITION, MESSAGE)
#define | NX_KIT_DEBUG_DETAIL_CONCAT(X, Y) NX_KIT_DEBUG_DETAIL_CONCAT2(X, Y)
#define | NX_KIT_DEBUG_DETAIL_CONCAT2(X, Y) X##Y
#define | NX_KIT_DEBUG_DETAIL_THREAD_ID ""

## Typedefs
typedef std::function< void(const char *)> | nx::kit::debug::detail::PrintFunc

## Functions
std::string | nx::kit::debug::srcFileRelativePath (const std::string &file)
std::string | nx::kit::debug::srcFileBaseNameWithoutExt (const std::string &file)
std::ostream *& | nx::kit::debug::stream ()
void | nx::kit::debug::intentionallyCrash (const char *message)
std::string | nx::kit::debug::hexDumpLine (const char *bytes, int size, int bytesPerLine)
void | nx::kit::debug::detail::assertionFailed (PrintFunc printFunc, const char *conditionStr, const std::string &message, const char *file, int line)
bool | nx::kit::debug::detail::doAssert (bool condition, PrintFunc printFunc, const char *conditionStr, const std::string &message, const char *file, int line)
std::string | nx::kit::debug::detail::printPrefix (const char *file)
void | nx::kit::debug::detail::printHexDump (PrintFunc printFunc, const char *caption, const char *const bytes, int size)
void | nx::kit::debug::detail::saveStr (PrintFunc printFunc, const char *originDir, const char *filename, const char *strCaption, const std::string &str)
void | nx::kit::debug::detail::saveBin (PrintFunc printFunc, const char *originDir, const char *filename, const char *bytes, int size)

## Detailed Description

Utilities for debugging: measuring execution time and FPS, working with strings, logging values and messages.

This unit can be compiled in the context of any C++ project.

## Macro Definition Documentation

## ◆ LL

#define LL

Value:
NX_PRINT << "####### LL line " + ::nx::kit::utils::toString(__LINE__) \
+ NX_KIT_DEBUG_DETAIL_THREAD_ID \
+ ", " + ::nx::kit::debug::srcFileRelativePath(__FILE__) \
/* The final semicolon allows to use this macro as a line prefix. */;
NX_PRINT
#define NX_PRINT
Definition: debug.h:90

Logs execution of a line - to use, write LL at the beginning of the line.

## ◆ NX_DEBUG_ENABLE_FPS

#define NX_DEBUG_ENABLE_FPS NX_DEBUG_INI enableFps

Redefine if needed. Will be suffixed with Fps TAG values.

## ◆ NX_DEBUG_ENABLE_OUTPUT

#define NX_DEBUG_ENABLE_OUTPUT NX_DEBUG_INI enableOutput

Redefine if needed.

## ◆ NX_DEBUG_ENABLE_TIME

#define NX_DEBUG_ENABLE_TIME NX_DEBUG_INI enableTime

Redefine if needed.

## ◆ NX_DEBUG_ENDL

#define NX_DEBUG_ENDL << std::endl

Redefine if needed; used after NX_DEBUG_STREAM by other macros.

## ◆ NX_DEBUG_INI

#define NX_DEBUG_INI ini().

Define if needed to redirect NX_PRINT... to qDebug(). If needed, redefine to form a prefix for NX_DEBUG_ENABLE_... macros.

## ◆ NX_DEBUG_SAVE_DIR

#define NX_DEBUG_SAVE_DIR ::nx::kit::IniConfig::iniFilesDir()

If needed, redefine to provide a relative path origin for NX_SAVE_... macros.

## ◆ NX_DEBUG_STREAM

#define NX_DEBUG_STREAM *::nx::kit::debug::stream()

Redefine if needed; used for all output by other macros.

## ◆ NX_FPS

#define NX_FPS | ( |  | TAG,
|  |  | ...
| ) |  |

Value:
do \
{ \
if (NX_KIT_DEBUG_DETAIL_CONCAT(NX_DEBUG_ENABLE_FPS, TAG)) \
{ \
static ::nx::kit::debug::detail::Fps fps( \
NX_KIT_DEBUG_DETAIL_PRINT_FUNC, #TAG); \
fps.mark(__VA_ARGS__); \
} \
} while (0)
NX_DEBUG_ENABLE_FPS
#define NX_DEBUG_ENABLE_FPS
Definition: debug.h:226

Measures and prints with NX_PRINT each period between executions of the point of call; does nothing if !NX_DEBUG_ENABLE_FPS##TAG.

## ◆ NX_KIT_ASSERT

#define NX_KIT_ASSERT | ( |  | ... | ) |

Value:
NX_KIT_DEBUG_DETAIL_MSVC_EXPAND(NX_KIT_DEBUG_DETAIL_GET_3RD_ARG( \
__VA_ARGS__, NX_KIT_DEBUG_DETAIL_ASSERT2, NX_KIT_DEBUG_DETAIL_ASSERT1, \
/* Helps to generate a reasonable compiler error. */ args_required)(__VA_ARGS__))
NX_KIT_DEBUG_DETAIL_MSVC_EXPAND
#define NX_KIT_DEBUG_DETAIL_MSVC_EXPAND(ARG)
Definition: debug.h:256
NX_KIT_DEBUG_DETAIL_GET_3RD_ARG
#define NX_KIT_DEBUG_DETAIL_GET_3RD_ARG(ARG1, ARG2, ARG3,...)
Definition: debug.h:259

If the condition is false, logs the failure with NX_PRINT, and in debug build (i.e. NDEBUG is not defined), crashes the process to let a dump/core be generated.

ATTENTION: Unlike std library assert(), the condition is checked even in Release build to log the failure.

Additionally, allows to handle the failure (because the application must keep going):

if (!NX_KIT_ASSERT(objectPointer))
return false;

Returns
  Condition evaluation result.

## ◆ NX_KIT_DEBUG_DETAIL_ASSERT1

#define NX_KIT_DEBUG_DETAIL_ASSERT1 | ( |  | CONDITION | ) |

Value:
::nx::kit::debug::detail::doAssert( \
!!(CONDITION), NX_KIT_DEBUG_DETAIL_PRINT_FUNC, #CONDITION, "", __FILE__, __LINE__)

## ◆ NX_KIT_DEBUG_DETAIL_ASSERT2

#define NX_KIT_DEBUG_DETAIL_ASSERT2 | ( |  | CONDITION,
|  |  | MESSAGE
| ) |  |

Value:
::nx::kit::debug::detail::doAssert( \
!!(CONDITION), NX_KIT_DEBUG_DETAIL_PRINT_FUNC, #CONDITION, MESSAGE, __FILE__, __LINE__)

## ◆ NX_KIT_DEBUG_DETAIL_GET_3RD_ARG

#define NX_KIT_DEBUG_DETAIL_GET_3RD_ARG | ( |  | ARG1,
|  |  | ARG2,
|  |  | ARG3,
|  |  | ...
| ) |  | ARG3

Needed to make an "overloaded" macro which can accept either one or two args.

## ◆ NX_KIT_DEBUG_DETAIL_MSVC_EXPAND

#define NX_KIT_DEBUG_DETAIL_MSVC_EXPAND | ( |  | ARG | ) | ARG

Needed as a workaround for an MSVC issue: if VA_ARGS is used as an argument to another macro, it forms a single macro argument even if contains commas.

## ◆ NX_OUTPUT

#define NX_OUTPUT

Value:
/* << args... */ \
for (/* Executed either once or never; `for` instead of `if` gives no warnings. */ \
int NX_KIT_DEBUG_DETAIL_CONCAT(nxOutput_, __line__) = 0; \
NX_KIT_DEBUG_DETAIL_CONCAT(nxOutput_, __line__) != 1 && (NX_DEBUG_ENABLE_OUTPUT); \
++NX_KIT_DEBUG_DETAIL_CONCAT(nxOutput_, __line__) \
) NX_PRINT
NX_PRINT
#define NX_PRINT
Definition: debug.h:90
NX_DEBUG_ENABLE_OUTPUT
#define NX_DEBUG_ENABLE_OUTPUT
Definition: debug.h:61

Prints the args like NX_PRINT; does nothing if !NX_DEBUG_ENABLE_OUTPUT.

## ◆ NX_PRINT

#define NX_PRINT

Value:
/* << args... */ \
/* Allocate a temp value, which prints endl in its destructor, in the "<<" expression. */ \
( []() { struct Endl { ~Endl() { NX_DEBUG_STREAM NX_DEBUG_ENDL; } }; \
return std::make_shared<Endl>(); }() ) /*operator,*/, \
NX_DEBUG_STREAM << NX_PRINT_PREFIX
NX_DEBUG_STREAM
#define NX_DEBUG_STREAM
Definition: debug.h:71
NX_PRINT_PREFIX
#define NX_PRINT_PREFIX
Definition: debug.h:66
NX_DEBUG_ENDL
#define NX_DEBUG_ENDL
Definition: debug.h:76

Print the args to NX_DEBUG_STREAM, starting with NX_PRINT_PREFIX and ending with NX_DEBUG_ENDL. Redefine if needed.

## ◆ NX_PRINT_HEX_DUMP

#define NX_PRINT_HEX_DUMP | ( |  | CAPTION,
|  |  | BYTES,
|  |  | SIZE
| ) |  |

Value:
::nx::kit::debug::detail::printHexDump( \
NX_KIT_DEBUG_DETAIL_PRINT_FUNC, (CAPTION), (const char*) (BYTES), (int) (SIZE))

Hex-dumps binary data using NX_PRINT.

## ◆ NX_PRINT_PREFIX

#define NX_PRINT_PREFIX ::nx::kit::debug::detail::printPrefix(__FILE__)

Redefine if needed; used as the first item in NX_PRINT and NX_OUTPUT.

## ◆ NX_PRINT_VALUE

#define NX_PRINT_VALUE | ( |  | VALUE | ) | NX_PRINT << "####### " #VALUE ": " + ::nx::kit::utils::toString(VALUE)

Prints the expression text and its value via toString().

## ◆ NX_SAVE_BIN

#define NX_SAVE_BIN | ( |  | FILENAME,
|  |  | BYTES,
|  |  | SIZE
| ) |  |

Value:
::nx::kit::debug::detail::saveBin( \
NX_KIT_DEBUG_DETAIL_PRINT_FUNC, (NX_DEBUG_SAVE_DIR), (FILENAME), (BYTES), (SIZE))
NX_DEBUG_SAVE_DIR
#define NX_DEBUG_SAVE_DIR
Definition: debug.h:168

Saves the bytes to a binary file. If the path is relative, use NX_DEBUG_SAVE_DIR as the origin.

## ◆ NX_SAVE_STR

#define NX_SAVE_STR | ( |  | FILENAME,
|  |  | STR
| ) |  |

Value:
::nx::kit::debug::detail::saveStr( \
NX_KIT_DEBUG_DETAIL_PRINT_FUNC, (NX_DEBUG_SAVE_DIR), (FILENAME), #STR, (STR))
NX_DEBUG_SAVE_DIR
#define NX_DEBUG_SAVE_DIR
Definition: debug.h:168

Saves the string to a file. All bytes of the string are saved in binary form as-is, including newlines (so `\n` produces a Unix-style `LF` even on Windows) and zero bytes (if any). If the path is relative, use NX_DEBUG_SAVE_DIR as the origin.

## ◆ NX_TIME_BEGIN

#define NX_TIME_BEGIN | ( |  | TAG | ) |

Value:
::nx::kit::debug::detail::Timer nxTimer_##TAG( \
(NX_DEBUG_ENABLE_TIME), NX_KIT_DEBUG_DETAIL_PRINT_FUNC, #TAG)
NX_DEBUG_ENABLE_TIME
#define NX_DEBUG_ENABLE_TIME
Definition: debug.h:192
nx::kit::debug::detail::Timer
Definition: debug.h:288

Starts measuring time - saves current time in a variable; does nothing if !NX_DEBUG_ENABLE_TIME.

## ◆ NX_TIME_END

#define NX_TIME_END | ( |  | TAG | ) |

Value:
do \
{ \
if (NX_DEBUG_ENABLE_TIME) \
nxTimer_##TAG.finish(); \
} while (0)
NX_DEBUG_ENABLE_TIME
#define NX_DEBUG_ENABLE_TIME
Definition: debug.h:192

Prints the totals of this time measurement with NX_PRINT; does nothing if !NX_DEBUG_ENABLE_TIME.

## ◆ NX_TIME_MARK

#define NX_TIME_MARK | ( |  | TAG,
|  |  | MARK
| ) |  |

Value:
do \
{ \
if (NX_DEBUG_ENABLE_TIME) \
nxTimer_##TAG.mark((MARK)); \
} while (0)
NX_DEBUG_ENABLE_TIME
#define NX_DEBUG_ENABLE_TIME
Definition: debug.h:192

Measures the time in the intermediate point, to be printed at the end; does nothing if !NX_DEBUG_ENABLE_TIME. If called at least once, forces "ms" instead of "us" for the totals.

## Function Documentation

## ◆ hexDumpLine()

NX_KIT_API std::string nx::kit::debug::hexDumpLine | ( | const char * | bytes,
|  | int | size,
|  | int | bytesPerLine = `0`
| ) |  |

Parameters

  bytesPerLine | Used to calculate space padding, 0 means no padding.

## ◆ intentionallyCrash()

NX_KIT_API void nx::kit::debug::intentionallyCrash | ( | const char * | message | ) |

Debug feature. Crashes the process. On Windows, copies message to a local variable on the stack, so that it is included into the mini-dump.

## ◆ printPrefix()

NX_KIT_API std::string nx::kit::debug::detail::printPrefix | ( | const char * | file | ) |

Parameters

  file | Supply FILE.

## ◆ srcFileBaseNameWithoutExt()

NX_KIT_API std::string nx::kit::debug::srcFileBaseNameWithoutExt | ( | const std::string & | file | ) |

Extracts the basa name without extension from the supplied FILE.

## ◆ srcFileRelativePath()

NX_KIT_API std::string nx::kit::debug::srcFileRelativePath | ( | const std::string & | file | ) |

Extracts the part of the supplied FILE which follows the uninteresting common part.

## ◆ stream()

NX_KIT_API std::ostream *& nx::kit::debug::stream | ( |  | ) |

Allows to override the stream used by NX_PRINT via NX_DEBUG_STREAM, initially std::cerr.

Returns
  Reference to the static variable which stores the stream pointer.