VTK-m  1.8
Namespaces | Macros | Enumerations | Functions
Logging.h File Reference

Logging utilities. More...

#include <vtkm/internal/Configure.h>
#include <vtkm/internal/ExportMacros.h>
#include <vtkm/Types.h>
#include <vtkm/cont/vtkm_cont_export.h>
#include <iostream>
#include <sstream>
#include <string>
#include <typeindex>
#include <typeinfo>

Go to the source code of this file.

Namespaces

 vtkm
 VTKM_NO_DEPRECATED_VIRTUAL.
 
 vtkm::cont
 VTK-m Control Environment.
 

Macros

#define VTKM_LOG_S(level, ...)
 Writes a message using stream syntax to the indicated log level. More...
 
#define VTKM_LOG_F(level, ...)
 Writes a message using printf syntax to the indicated log level. More...
 
#define VTKM_LOG_IF_S(level, cond, ...)
 
#define VTKM_LOG_IF_F(level, cond, ...)
 
#define VTKM_LOG_SCOPE(level, ...)
 
#define VTKM_LOG_SCOPE_FUNCTION(level)
 
#define VTKM_LOG_ERROR_CONTEXT(desc, data)
 
#define VTKM_LOG_CAST_SUCC(inObj, outObj)
 Convenience macro for logging the successful cast of dynamic object. More...
 
#define VTKM_LOG_CAST_FAIL(inObj, outType)
 Convenience macro for logging a failed cast of dynamic object. More...
 
#define VTKM_DEFINE_USER_LOG_LEVEL(name, offset)
 Convenience macro for creating a custom log level that is usable in the other macros. If logging is disabled this macro does nothing. More...
 
#define VTKM_LOG_ALWAYS_S(level, ...)
 
#define VTKM_LOG_TRYEXECUTE_FAIL(errorMessage, functorName, deviceId)
 Convenience macro for logging a TryExecute failure to the Error level. If logging is disabled, a message is still printed to stderr. More...
 
#define VTKM_LOG_TRYEXECUTE_DISABLE(errorMessage, functorName, deviceId)
 Similar to VTKM_LOG_TRYEXECUTE_FAIL, but also informs the user that the device has been disable for future TryExecute calls. More...
 

Enumerations

enum  vtkm::cont::LogLevel {
  vtkm::cont::LogLevel::Off = -9, vtkm::cont::LogLevel::Fatal = -3, vtkm::cont::LogLevel::Error = -2, vtkm::cont::LogLevel::Warn = -1,
  vtkm::cont::LogLevel::Info = 0, vtkm::cont::LogLevel::UserFirst = 1, vtkm::cont::LogLevel::UserLast = 255, vtkm::cont::LogLevel::DevicesEnabled,
  vtkm::cont::LogLevel::Perf, vtkm::cont::LogLevel::MemCont, vtkm::cont::LogLevel::MemExec, vtkm::cont::LogLevel::MemTransfer,
  vtkm::cont::LogLevel::KernelLaunches, vtkm::cont::LogLevel::Cast, vtkm::cont::LogLevel::UserVerboseFirst = 1024, vtkm::cont::LogLevel::UserVerboseLast = 2047
}
 Log levels for use with the logging macros. More...
 

Functions

VTKM_CONT_EXPORT VTKM_CONT vtkm::cont::LogLevel vtkm::cont::GetStderrLogLevel ()
 Get the active highest log level that will be printed to stderr. More...
 
VTKM_CONT_EXPORT VTKM_CONT void vtkm::cont::SetLogLevelName (vtkm::cont::LogLevel level, const std::string &name)
 Register a custom name to identify a log level. More...
 
VTKM_CONT_EXPORT VTKM_CONT std::string vtkm::cont::GetLogLevelName (vtkm::cont::LogLevel level)
 Get a human readable name for the log level. More...
 
VTKM_CONT_EXPORT VTKM_CONT std::string vtkm::cont::GetLogErrorContext ()
 
VTKM_CONT_EXPORT VTKM_CONT std::string vtkm::cont::GetStackTrace (vtkm::Int32 skip=0)
 Returns a stacktrace on supported platforms. More...
 
VTKM_CONT_EXPORT VTKM_CONT std::string vtkm::cont::GetHumanReadableSize (vtkm::UInt64 bytes, int prec=2)
 Convert a size in bytes to a human readable string (e.g. More...
 
template<typename T >
VTKM_CONT std::string vtkm::cont::GetHumanReadableSize (T &&bytes, int prec=2)
 
VTKM_CONT_EXPORT VTKM_CONT std::string vtkm::cont::GetSizeString (vtkm::UInt64 bytes, int prec=2)
 Returns "%1 (%2 bytes)" where %1 is the result from GetHumanReadableSize and two is the exact number of bytes. More...
 
template<typename T >
VTKM_CONT std::string vtkm::cont::GetSizeString (T &&bytes, int prec=2)
 
VTKM_CONT_EXPORT VTKM_CONT void vtkm::cont::InitLogging (int &argc, char *argv[], const std::string &loggingFlag="--vtkm-log-level")
 This shouldn't be called directly – prefer calling vtkm::cont::Initialize, which takes care of logging as well as other initializations. More...
 
VTKM_CONT_EXPORT VTKM_CONT void vtkm::cont::InitLogging ()
 This shouldn't be called directly – prefer calling vtkm::cont::Initialize, which takes care of logging as well as other initializations. More...
 
VTKM_CONT_EXPORT VTKM_CONT void vtkm::cont::SetStderrLogLevel (const char *verbosity)
 Set the range of log levels that will be printed to stderr. More...
 
VTKM_CONT_EXPORT VTKM_CONT void vtkm::cont::SetStderrLogLevel (vtkm::cont::LogLevel level)
 Set the range of log levels that will be printed to stderr. More...
 
VTKM_CONT_EXPORT VTKM_CONT void vtkm::cont::SetLogThreadName (const std::string &name)
 The name to identify the current thread in the log output. More...
 
VTKM_CONT_EXPORT VTKM_CONT std::string vtkm::cont::GetLogThreadName ()
 The name to identify the current thread in the log output. More...
 
VTKM_CONT_EXPORT VTKM_CONT std::string vtkm::cont::TypeToString (const std::type_info &t)
 Use RTTI information to retrieve the name of the type T. More...
 
VTKM_CONT_EXPORT VTKM_CONT std::string vtkm::cont::TypeToString (const std::type_index &t)
 Use RTTI information to retrieve the name of the type T. More...
 
template<typename T >
VTKM_CONT std::string vtkm::cont::TypeToString ()
 Use RTTI information to retrieve the name of the type T. More...
 
template<typename T >
VTKM_CONT std::string vtkm::cont::TypeToString (const T &)
 Use RTTI information to retrieve the name of the type T. More...
 
VTKM_CONT_EXPORT VTKM_CONT void vtkm::cont::InitLogging (int &argc, char *argv[], const std::string &loggingFlag="--vtkm-log-level")
 This shouldn't be called directly – prefer calling vtkm::cont::Initialize, which takes care of logging as well as other initializations. More...
 
VTKM_CONT_EXPORT VTKM_CONT void vtkm::cont::InitLogging ()
 This shouldn't be called directly – prefer calling vtkm::cont::Initialize, which takes care of logging as well as other initializations. More...
 
VTKM_CONT_EXPORT VTKM_CONT void vtkm::cont::SetStderrLogLevel (const char *verbosity)
 Set the range of log levels that will be printed to stderr. More...
 
VTKM_CONT_EXPORT VTKM_CONT void vtkm::cont::SetStderrLogLevel (vtkm::cont::LogLevel level)
 Set the range of log levels that will be printed to stderr. More...
 
VTKM_CONT_EXPORT VTKM_CONT void vtkm::cont::SetLogThreadName (const std::string &name)
 The name to identify the current thread in the log output. More...
 
VTKM_CONT_EXPORT VTKM_CONT std::string vtkm::cont::GetLogThreadName ()
 The name to identify the current thread in the log output. More...
 
VTKM_CONT_EXPORT VTKM_CONT std::string vtkm::cont::TypeToString (const std::type_info &t)
 Use RTTI information to retrieve the name of the type T. More...
 
VTKM_CONT_EXPORT VTKM_CONT std::string vtkm::cont::TypeToString (const std::type_index &t)
 Use RTTI information to retrieve the name of the type T. More...
 
template<typename T >
VTKM_CONT std::string vtkm::cont::TypeToString ()
 Use RTTI information to retrieve the name of the type T. More...
 
template<typename T >
VTKM_CONT std::string vtkm::cont::TypeToString (const T &)
 Use RTTI information to retrieve the name of the type T. More...
 

Detailed Description

Logging utilities.

This file includes the logging system for VTK-m. There are a variety of macros to print log messages using C++ stream or printf syntax. Nested scopes may be created in the log output, and there are several helper functions to help format common types of log data such as byte counts and type names.

Logging is enabled via the CMake option VTKm_ENABLE_LOGGING by default. The default log level is set to only log Warn and Error messages; Fatal levels are printed to stderr by default. The logging system will need to be initialized through a call to either vtkm::cont::Initialize or vtkm::cont::InitLogging.

Additional logging features are enabled by calling vtkm::cont::InitLogging (or preferably, vtkm::cont::Initialize) in an executable. This will:

The main logging entry points are the macros VTKM_LOG_S and VTKM_LOG_F, which using C++ stream and printf syntax, repectively. Other variants exist, including conditional logging and special-purpose logs for writing specific events, such as DynamicObject cast results and TryExecute failures.

The logging backend supports the concept of "Scopes". By creating a new scope with the macros VTKM_LOG_SCOPE or VTKM_LOG_SCOPE_FUNCTION, a new "logging scope" is opened within the C++ scope the macro is called from. New messages will be indented in the log until the scope ends, at which point a message is logged with the elapsed time that the scope was active. Scopes may be nested to arbitrary depths.

The logging implementation is thread-safe. When working in a multithreaded environment, each thread may be assigned a human-readable name using vtkm::cont::SetThreadName. This will appear in the log output so that per-thread messages can be easily tracked.

By default, only Warn, Error, and Fatal messages are printed to stderr. This can be changed at runtime by passing the '–vtkm-log-level' flag to an executable that calls vtkm::cont::InitLogging. Alternatively, the application can explicitly call vtkm::cont::SetStderrLogLevel to change the verbosity. When specifying a verbosity, all log levels with enum values less-than-or-equal-to the requested level are printed. vtkm::cont::LogLevel::Off (or "--vtkm-log-level Off") may be used to silence the log completely.

The helper functions vtkm::cont::GetHumanReadableSize and vtkm::cont::GetSizeString assist in formating byte sizes to a more readable format. Similarly, the vtkm::cont::TypeToString template functions provide RTTI based type-name information. When logging is enabled, these use the logging backend to demangle symbol names on supported platforms.

The more verbose VTK-m log levels are:

The log may be shared and extended by applications that use VTK-m. There are two log level ranges left available for applications: User and UserVerbose. The User levels may be enabled without showing any of the verbose VTK-m levels, while UserVerbose levels will also enable all VTK-m levels.

Macro Definition Documentation

◆ VTKM_DEFINE_USER_LOG_LEVEL

#define VTKM_DEFINE_USER_LOG_LEVEL (   name,
  offset 
)

Convenience macro for creating a custom log level that is usable in the other macros. If logging is disabled this macro does nothing.

Parameters
nameThe name to give the new log level
offsetThe offset from the vtkm::cont::LogLevel::UserFirst value from the LogLevel enum. Additionally moduloed against the vtkm::cont::LogLevel::UserLast value
Note
This macro is to be used for quickly setting log levels. For a more maintainable solution it is recommended to create a custom enum class and then cast appropriately, as described here: https://gitlab.kitware.com/vtk/vtk-m/-/issues/358#note_550157

◆ VTKM_LOG_ALWAYS_S

#define VTKM_LOG_ALWAYS_S (   level,
  ... 
)
Value:
(static_cast<int>(level) < 0 ? std::cerr : std::cout) \
<< vtkm::cont::GetLogLevelName(level) << ": " << __VA_ARGS__ << "\n"

This ostream-style log message is always emitted, even when logging is disabled at compile time.

◆ VTKM_LOG_CAST_FAIL

#define VTKM_LOG_CAST_FAIL (   inObj,
  outType 
)

Convenience macro for logging a failed cast of dynamic object.

Parameters
inObjThe dynamic object.
outTypeThe candidate type (or typelist) that was unsuccessful.

◆ VTKM_LOG_CAST_SUCC

#define VTKM_LOG_CAST_SUCC (   inObj,
  outObj 
)

Convenience macro for logging the successful cast of dynamic object.

Parameters
inObjThe dynamic object.
outObjThe resulting downcasted object.

◆ VTKM_LOG_ERROR_CONTEXT

#define VTKM_LOG_ERROR_CONTEXT (   desc,
  data 
)

◆ VTKM_LOG_F

#define VTKM_LOG_F (   level,
  ... 
)

Writes a message using printf syntax to the indicated log level.

The ellipsis may be replaced with the log message as if constructing a printf call, e.g:

"Executed functor %s on device %s",
vtkm::cont::TypeToString(functor).c_str(),
deviceId.GetName().c_str());

◆ VTKM_LOG_IF_F

#define VTKM_LOG_IF_F (   level,
  cond,
  ... 
)

Same as VTKM_LOG_F, but only logs if cond is true.

◆ VTKM_LOG_IF_S

#define VTKM_LOG_IF_S (   level,
  cond,
  ... 
)

Same as VTKM_LOG_S, but only logs if cond is true.

◆ VTKM_LOG_S

#define VTKM_LOG_S (   level,
  ... 
)

Writes a message using stream syntax to the indicated log level.

The ellipsis may be replaced with the log message as if constructing a C++ stream, e.g:

"Executed functor " << vtkm::cont::TypeToString(functor)
<< " on device " << deviceId.GetName());

◆ VTKM_LOG_SCOPE

#define VTKM_LOG_SCOPE (   level,
  ... 
)

Creates a new scope at the requested level. The log scope ends when the code scope ends. The ellipses form the scope name using printf syntax.

{
"Executing filter %s",
vtkm::cont::TypeToString(myFilter).c_str());
myFilter.Execute();
}

◆ VTKM_LOG_SCOPE_FUNCTION

#define VTKM_LOG_SCOPE_FUNCTION (   level)

Equivalent to VTKM_LOG_SCOPE(func);

◆ VTKM_LOG_TRYEXECUTE_DISABLE

#define VTKM_LOG_TRYEXECUTE_DISABLE (   errorMessage,
  functorName,
  deviceId 
)
Value:
std::cerr << "Error: TryExecute encountered an error: " << errorMessage << "\n" \
<< "\t- Failing functor: " << functorName << "\n" \
<< "\t- Failing device: " << deviceId.GetName() << "\n" \
<< "The failing device has been disabled.\n\n"

Similar to VTKM_LOG_TRYEXECUTE_FAIL, but also informs the user that the device has been disable for future TryExecute calls.

Parameters
errorMessageThe error message detailing the failure.
functorNameThe name of the functor (see vtkm::cont::TypeToString)
deviceIdThe device tag / id for the device on which the functor failed.

◆ VTKM_LOG_TRYEXECUTE_FAIL

#define VTKM_LOG_TRYEXECUTE_FAIL (   errorMessage,
  functorName,
  deviceId 
)
Value:
std::cerr << "Error: TryExecute encountered an error: " << errorMessage << "\n" \
<< "\t- Failing functor: " << functorName << "\n" \
<< "\t- Failing device: " << deviceId.GetName() << "\n\n"

Convenience macro for logging a TryExecute failure to the Error level. If logging is disabled, a message is still printed to stderr.

Parameters
errorMessageThe error message detailing the failure.
functorNameThe name of the functor (see vtkm::cont::TypeToString)
deviceIdThe device tag / id for the device on which the functor failed.
VTKM_LOG_SCOPE
#define VTKM_LOG_SCOPE(level,...)
Definition: Logging.h:257
VTKM_LOG_F
#define VTKM_LOG_F(level,...)
Writes a message using printf syntax to the indicated log level.
Definition: Logging.h:254
VTKM_LOG_S
#define VTKM_LOG_S(level,...)
Writes a message using stream syntax to the indicated log level.
Definition: Logging.h:253
vtkm::cont::GetLogLevelName
VTKM_CONT_EXPORT VTKM_CONT std::string GetLogLevelName(vtkm::cont::LogLevel level)
Get a human readable name for the log level.
vtkm::cont::TypeToString
VTKM_CONT_EXPORT VTKM_CONT std::string TypeToString(const std::type_info &t)
Use RTTI information to retrieve the name of the type T.
vtkm::cont::LogLevel::Perf
@ Perf
General timing data and algorithm flow information, such as filter execution, worklet dispatches,...