JeVois  1.20
JeVois Smart Embedded Machine Vision Toolkit
Share this page:
Debugging helper classes, functions and macros

Classes

class  jevois::Log< Level >
 Logger class. More...
 
class  jevois::trace::TraceObject
 Helper class for tracing, issues one message on construction, and another on destruction. More...
 
class  jevois::timed_lock_guard
 Acquire a lock object on a std::timed_mutex, or LFATAL after 1 second of waiting. More...
 
class  jevois::Profiler
 Simple profiler class. More...
 
class  jevois::Timer
 Simple timer class. More...
 
class  jevois::TimerOne
 Simple one-shot timer class. More...
 
class  jevois::Watchdog
 Simple watchdog class. More...
 

Macros

#define LDEBUG(msg)
 Convenience macro for users to print out console or syslog messages, DEBUG level. More...
 
#define PLDEBUG(msg)
 Like LDEBUG but appends errno and strerror(errno), to be used when some system call fails. More...
 
#define LINFO(msg)
 Convenience macro for users to print out console or syslog messages, INFO level. More...
 
#define PLINFO(msg)
 Like LINFO but appends errno and strerror(errno), to be used when some system call fails. More...
 
#define LERROR(msg)
 Convenience macro for users to print out console or syslog messages, ERROR level. More...
 
#define PLERROR(msg)
 Like LERROR but appends errno and strerror(errno), to be used when some system call fails. More...
 
#define LFATAL(msg)
 Convenience macro for users to print out console or syslog messages, FATAL level. More...
 
#define PLFATAL(msg)
 Like LDEBUG but appends errno and strerror(errno), to be used when some system call fails. More...
 
#define JEVOIS_ASSERT(cond)
 Test whether something is true and issue an LFATAL if not. More...
 
#define JEVOIS_TRACE(level)
 Trace object. More...
 
#define JEVOIS_TIMED_LOCK(mtx)
 Helper macro to create a timed_lock_guard object. More...
 

Functions

void jevois::warnAndRethrowException (std::string const &prefix="")
 Convenience function to catch an exception, issue some LERROR (depending on type), and rethrow it. More...
 
std::string jevois::warnAndIgnoreException (std::string const &prefix="")
 Convenience function to catch an exception, issue some LERROR (depending on type), and ignore it. More...
 
void jevois::warnAndRethrowParamCallbackException (std::string const &descriptor, std::string const &strval)
 Convenience function for parameter callback exceptions. More...
 
void jevois::logSetEngine (Engine *e)
 Set an Engine so that all log messages will be forwarded to its serial ports. More...
 
std::string jevois::getPythonExceptionString (boost::python::error_already_set &)
 Python exception translation to string so we can print the traceback to our serlog stream. More...
 
std::string jevois::getSysInfoCPU ()
 Get CPU info: frequency, thermal, load. More...
 
std::string jevois::getSysInfoMem ()
 Get memory info. More...
 
std::string jevois::getSysInfoVersion ()
 Get O.S. version info. More...
 

Variables

int jevois::logLevel = LOG_INFO
 Current log level. More...
 
int jevois::traceLevel = 0
 Current trace level. More...
 

Macro Definition Documentation

◆ JEVOIS_ASSERT

#define JEVOIS_ASSERT (   cond)

Test whether something is true and issue an LFATAL if not.

Definition at line 257 of file Log.H.

◆ JEVOIS_TIMED_LOCK

#define JEVOIS_TIMED_LOCK (   mtx)

Helper macro to create a timed_lock_guard object.

Creates a timed_lock_guard over std::timed_mutex mtx, which will throw if mtx cannot be locked before timeout. The guard will unlock the mutex upon destruction.

Definition at line 328 of file Log.H.

◆ JEVOIS_TRACE

#define JEVOIS_TRACE (   level)

Trace object.

Use this as you do with, e.g., std::lock_guard. Issues one LDEBUG() message on construction, and one on destruction. Typically, you would hence invoke JEVOIS_TRACE as the first command in each of the functions you want to trace.

Definition at line 296 of file Log.H.

◆ LDEBUG

#define LDEBUG (   msg)

Convenience macro for users to print out console or syslog messages, DEBUG level.

This macro is intended to be used with a stream-oriented syntax for everything that is passed as argument to the macro. The syntax is a bit strange at first but you will rapidly get used to it. This allows any datatype that has an operator<< defined to be printed out in a log (contrary to printf-style syntax). For example:

int x = 3; std::string str = "hello"; jevois::StepRange<int> rng(0, 5, 100);
LDEBUG("x=" << x << " and str=" << str << " and rng=" << rng);
Note
This is the preferred way to issue messages. Do not use printf, do not use cout<<"blah", etc.
Warning
No line breaks ('
' and similar) are allowed in LDEBUG(), LINFO(), and LERROR(), as these may be sent out over serial ports to simple processors like Arduino, with just one prefix ("DBG ", "INF ", "ERR ") followed by the message, for easy parsing. JeVois-Inventor will likely not be able to function if you send multiline messages. Line breaks are allowed in exception error messages and in LFATAL() and LTHROW(), and the multiple lines will be sent as several consecutive messages.

By design, your log message will not be evaluated if the current log level is below (stronger than) the debug level. This means that you should not be afraid of wasting CPU computing messages that will not be output; for example:

LINFO("CPU-intensive function says: " << cpu_intensive_function());

will not run the cpu-intensive function if the current log level is LOG_ERR (it will still run one "if" statement to check the current log level). This also means that you should never assume that your log message will be evaluated. For example:

int x = 42;
LDEBUG("x = " << (x++) ); // x may now be 43 or 42 depending on current log level...
Note
Because LDEBUG() may be used for debugging of many fast loops, including through the use of JEVOIS_TRACE(level), it will be compiled in only if JEVOIS_LDEBUG_ENABLE is defined during build (typicaly, this is done as an option passed to cmake), otherwise it will simply be commented out so that no CPU is wasted.

Definition at line 173 of file Log.H.

◆ LERROR

#define LERROR (   msg)

Convenience macro for users to print out console or syslog messages, ERROR level.

Usage syntax is the same as for LDEBUG(msg)

Definition at line 211 of file Log.H.

◆ LFATAL

#define LFATAL (   msg)

Convenience macro for users to print out console or syslog messages, FATAL level.

Convenience macro for users to throw std::runtime_error with convenient message formatting.

Usage syntax is the same as for LDEBUG(msg)

Note
After printing the message, this also throws std::runtime_error

Usage syntax is the same as for LDEBUG(msg). Nothing is added by this function to the user-provided error message. So this is mainly useful for situations where the exception will be caught and a consolidated error message will then be issued via LFATAL() (maybe adding some more context details).

Note
This throws std::runtime_error

◆ LINFO

#define LINFO (   msg)

Convenience macro for users to print out console or syslog messages, INFO level.

Usage syntax is the same as for LDEBUG(msg)

Definition at line 194 of file Log.H.

◆ PLDEBUG

#define PLDEBUG (   msg)

Like LDEBUG but appends errno and strerror(errno), to be used when some system call fails.

Usage syntax is the same as for LDEBUG(msg)

Definition at line 181 of file Log.H.

◆ PLERROR

#define PLERROR (   msg)

Like LERROR but appends errno and strerror(errno), to be used when some system call fails.

Usage syntax is the same as for LDEBUG(msg)

Definition at line 219 of file Log.H.

◆ PLFATAL

#define PLFATAL (   msg)

Like LDEBUG but appends errno and strerror(errno), to be used when some system call fails.

Usage syntax is the same as for LDEBUG(msg)

Note
After printing the message, this also throws std::runtime_error

Definition at line 239 of file Log.H.

◆ PLINFO

#define PLINFO (   msg)

Like LINFO but appends errno and strerror(errno), to be used when some system call fails.

Usage syntax is the same as for LDEBUG(msg)

Definition at line 202 of file Log.H.

Function Documentation

◆ getPythonExceptionString()

std::string jevois::getPythonExceptionString ( boost::python::error_already_set &  )

Python exception translation to string so we can print the traceback to our serlog stream.

This code inspired from: https://github.com/abingham/boost_python_exception/tree/master/src/boost_python_exception/auto_translation

You would usually use this from inside a catch(boost::python::error_already_set & e) { ... } block.

Definition at line 146 of file PythonException.C.

Referenced by jevois::PythonWrapper::pythonload(), jevois::GUIhelper::reportAndIgnoreException(), jevois::warnAndIgnoreException(), jevois::warnAndRethrowException(), and jevois::warnAndRethrowParamCallbackException().

◆ getSysInfoCPU()

std::string jevois::getSysInfoCPU ( )

Get CPU info: frequency, thermal, load.

Definition at line 24 of file SysInfo.C.

References jevois::getFileString(), and jevois::to_string().

Referenced by jevois::GUIhelper::drawSystem(), and jevois::Engine::parseCommand().

◆ getSysInfoMem()

std::string jevois::getSysInfoMem ( )

Get memory info.

Definition at line 66 of file SysInfo.C.

References jevois::getFileString().

Referenced by jevois::GUIhelper::drawSystem(), and jevois::Engine::parseCommand().

◆ getSysInfoVersion()

std::string jevois::getSysInfoVersion ( )

Get O.S. version info.

Definition at line 74 of file SysInfo.C.

References jevois::getFileString().

Referenced by jevois::GUIhelper::drawSystem(), and jevois::Engine::parseCommand().

◆ logSetEngine()

void jevois::logSetEngine ( Engine e)

Set an Engine so that all log messages will be forwarded to its serial ports.

This function is not intended for general use, Engine uses it internally when users set one of its parameters to enable forwarding of log messages to serial ports.

Definition at line 124 of file Log.C.

Referenced by jevois::logEnd(), jevois::Engine::postInit(), and jevois::Engine::~Engine().

◆ warnAndIgnoreException()

std::string jevois::warnAndIgnoreException ( std::string const &  prefix = "")

Convenience function to catch an exception, issue some LERROR (depending on type), and ignore it.

User code can use this function as follows, to log some trace of the exception that was thrown, and then swallow (ignore) the exception. Use this sparingly, swallowing exceptions often defeats the whole logic of using exceptions in the first place. Example use:

try { do_something_risky_and_we_dont_care_if_it_fails(); } catch (...) { jevois::warnAndIgnoreException(); }

Note that the message that is logged to console is also returned as a string, in case one wants to report it in some other way (e.g., in a GUI or in a video frame using drawErrorImage()).

Definition at line 236 of file Log.C.

References jevois::getPythonExceptionString(), LERROR, and jevois::split().

Referenced by jevois::Camera::abortStream(), jevois::GUIhelper::compileCommand(), jevois::GUIhelper::drawConsole(), jevois::Engine::foreachVideoMapping(), jevois::GUIhelper::headlessDisplay(), jevois::ImGuiBackendMALI::init(), jevois::GPUshader::load(), jevois::Engine::mainLoop(), jevois::Engine::postInit(), TutorialEdgeDetectionX4::process(), jevois::dnn::Pipeline::process(), jevois::Engine::runScriptFromFile(), jevois::Engine::sendSerial(), jevois::GUIhelper::setparstr(), jevois::CameraDevice::streamOff(), jevois::Camera::streamOff(), jevois::Camera::streamOn(), jevois::Camera::~Camera(), jevois::CameraDevice::~CameraDevice(), jevois::Engine::~Engine(), jevois::Gadget::~Gadget(), jevois::ImGuiBackendMALI::~ImGuiBackendMALI(), and jevois::MovieOutput::~MovieOutput().

◆ warnAndRethrowException()

void jevois::warnAndRethrowException ( std::string const &  prefix = "")

Convenience function to catch an exception, issue some LERROR (depending on type), and rethrow it.

User code that is not going to swallow exceptions can use this function as follows, to log some trace of the exception that was thrown:

try { do_something_risky(); } catch (...) { jevois::warnAndRethrowException(); }
Note
This function throws! So obviously it only makes sense to use it inside a catch block.

Definition at line 203 of file Log.C.

References jevois::getPythonExceptionString(), LERROR, and jevois::split().

Referenced by jevois::dnn::NetworkNPU::doprocess(), and jevois::dnn::Network::ready().

◆ warnAndRethrowParamCallbackException()

void jevois::warnAndRethrowParamCallbackException ( std::string const &  descriptor,
std::string const &  strval 
)

Convenience function for parameter callback exceptions.

Used internally by Parameter, likely not so useful to others, included in the jevois namespace to avoid having to pull boost::python into Parameter, which would pull it into pretty much everything and increase compile time a lot.

Note
This function throws! So obviously it only makes sense to use it inside a catch block.

Definition at line 274 of file Log.C.

References jevois::getPythonExceptionString(), and LERROR.

Variable Documentation

◆ logLevel

int jevois::logLevel = LOG_INFO

Current log level.

The log level is set by changing the value of this global variable. The default value is LOG_INFO.

The possible log values are defined in sys/syslog.h and here we only handle the following with different amounts of messages: LOG_CRIT, LOG_ERR, LOG_INFO, LOG_DEBUG.

Definition at line 29 of file Log.C.

Referenced by main().

◆ traceLevel

int jevois::traceLevel = 0

Current trace level.

Higher levels yield more verbosity in tracing. Note that this has effect only if JEVOIS_TRACE_ENABLE is specified as a compile option, and the trace messages are issued at the LDEBUG log level, so JEVOIS_LDEBUG_ENABLE must also be specified at compile time.

Definition at line 30 of file Log.C.

Referenced by jevois::trace::TraceObject::TraceObject(), and jevois::trace::TraceObject::~TraceObject().

LDEBUG
#define LDEBUG(msg)
Convenience macro for users to print out console or syslog messages, DEBUG level.
Definition: Log.H:173
jevois::warnAndRethrowException
void warnAndRethrowException(std::string const &prefix="")
Convenience function to catch an exception, issue some LERROR (depending on type),...
Definition: Log.C:203
jevois::StepRange
A generic range class with a step.
Definition: StepRange.H:69
jevois::warnAndIgnoreException
std::string warnAndIgnoreException(std::string const &prefix="")
Convenience function to catch an exception, issue some LERROR (depending on type),...
Definition: Log.C:236
LINFO
#define LINFO(msg)
Convenience macro for users to print out console or syslog messages, INFO level.
Definition: Log.H:194