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 <memory>
#include <sstream>
#include <string>
#include <typeindex>
#include <typeinfo>

Classes
struct	vtkm::cont::LogCondStream
	Conditionally logs a message with a stream-like interface. More...

Namespaces
	vtkm
	Groups connected points that have the same field value.

	vtkm::cont
	VTK-m Control Environment.

Macros
#define	VTKM_CONCAT_IMPL(s1, s2) s1##s2

#define	VTKM_CONCAT(s1, s2) VTKM_CONCAT_IMPL(s1, s2)

#define	VTKM_ANONYMOUS_VARIABLE VTKM_CONCAT(vtk_m_anonymous_, __LINE__)

#define	VTKM_LOG_IF_S(level, cond, ...) vtkm::cont::LogCondStream(level, cond, __FILE__, __LINE__) << __VA_ARGS__

#define	VTKM_LOG_IF_F(level, cond, ...) vtkm::cont::LogCond(level, cond, __FILE__, __LINE__, __VA_ARGS__)

#define	VTKM_LOG_S(level, ...) VTKM_LOG_IF_S(level, true, __VA_ARGS__)
	Writes a message using stream syntax to the indicated log level. More...

#define	VTKM_LOG_F(level, ...) VTKM_LOG_IF_F(level, true, __VA_ARGS__)
	Writes a message using printf syntax to the indicated log level. More...

#define	VTKM_LOG_SCOPE(level, ...) vtkm::cont::detail::LogScope VTKM_ANONYMOUS_VARIABLE { level, __FILE__, __LINE__, __VA_ARGS__ }

#define	VTKM_LOG_SCOPE_FUNCTION(level) VTKM_LOG_SCOPE(level, __func__)

#define	VTKM_LOG_ALWAYS_S(level, ...) VTKM_LOG_S(level, __VA_ARGS__)

#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_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...

#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...

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::LogLevel	vtkm::cont::GetStderrLogLevel ()
	Get the active highest log level that will be printed to stderr. More...

void	vtkm::cont::SetLogLevelName (vtkm::cont::LogLevel level, const std::string &name)
	Register a custom name to identify a log level. More...

std::string	vtkm::cont::GetLogLevelName (vtkm::cont::LogLevel level)
	Get a human readable name for the log level. More...

std::string	vtkm::cont::GetLogErrorContext ()

std::string	vtkm::cont::GetStackTrace (vtkm::Int32 skip=0)
	Returns a stacktrace on supported platforms. More...

std::string	vtkm::cont::GetHumanReadableSize (vtkm::UInt64 bytes, int prec=2)
	Convert a size in bytes to a human readable string (such as "64 bytes", "1.44 MiB", "128 GiB", etc). More...

template<typename T >
std::string	vtkm::cont::GetHumanReadableSize (T &&bytes, int prec=2)

std::string	vtkm::cont::GetSizeString (vtkm::UInt64 bytes, int prec=2)
	Returns "%1 (%2 bytes)" where %1 is the result from GetHumanReadableSize and %2 is the exact number of bytes. More...

template<typename T >
std::string	vtkm::cont::GetSizeString (T &&bytes, int prec=2)

void	vtkm::cont::LogCond (LogLevel level, bool cond, const char file, unsigned line, const char format...)
	Conditionally logs a message with a printf-like format. More...


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...

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...


void	vtkm::cont::SetStderrLogLevel (const char *verbosity)
	Set the range of log levels that will be printed to stderr. More...

void	vtkm::cont::SetStderrLogLevel (vtkm::cont::LogLevel level)
	Set the range of log levels that will be printed to stderr. More...


void	vtkm::cont::SetLogThreadName (const std::string &name)
	Specifies a humman-readable name to identify the current thread in the log output. More...

std::string	vtkm::cont::GetLogThreadName ()
	Specifies a humman-readable name to identify the current thread in the log output. More...


std::string	vtkm::cont::TypeToString (const std::type_info &t)
	Use RTTI information to retrieve the name of the type T. More...

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 >
std::string	vtkm::cont::TypeToString ()
	Use RTTI information to retrieve the name of the type T. More...

template<typename T >
std::string	vtkm::cont::TypeToString (const T &)
	Use RTTI information to retrieve the name of the type T. More...


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...

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...


void	vtkm::cont::SetStderrLogLevel (const char *verbosity)
	Set the range of log levels that will be printed to stderr. More...

void	vtkm::cont::SetStderrLogLevel (vtkm::cont::LogLevel level)
	Set the range of log levels that will be printed to stderr. More...


void	vtkm::cont::SetLogThreadName (const std::string &name)
	Specifies a humman-readable name to identify the current thread in the log output. More...

std::string	vtkm::cont::GetLogThreadName ()
	Specifies a humman-readable name to identify the current thread in the log output. More...


std::string	vtkm::cont::TypeToString (const std::type_info &t)
	Use RTTI information to retrieve the name of the type T. More...

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 >
std::string	vtkm::cont::TypeToString ()
	Use RTTI information to retrieve the name of the type T. More...

template<typename T >
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:

Set human-readable names for the log levels in the output.
Allow the stderr logging level to be set at runtime by passing a '–vtkm-log-level [level]' argument to the executable.
Name the main thread.
Print a preamble with details of the program's startup (args, etc).
Install signal handlers to automatically print stacktraces and error contexts (linux only) on crashes.

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:

Perf: Logs performance information, using the scopes feature to track execution time of filters, worklets, and device algorithms with microsecond resolution.
MemCont / MemExec: These levels log memory allocations in the control and execution environments, respectively.
MemTransfer: This level logs memory transfers between the control and host environments.
KernelLaunches: This level logs details about each device side kernel launch such as the CUDA PTX, Warps, and Grids used.
Cast: Logs details of dynamic object resolution.

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_ANONYMOUS_VARIABLE

#define VTKM_ANONYMOUS_VARIABLE VTKM_CONCAT(vtk_m_anonymous_, __LINE__)

◆ VTKM_CONCAT

#define VTKM_CONCAT	(	s1,
		s2
	)	VTKM_CONCAT_IMPL(s1, s2)

◆ VTKM_CONCAT_IMPL

#define VTKM_CONCAT_IMPL	(	s1,
		s2
	)	s1##s2

◆ VTKM_DEFINE_USER_LOG_LEVEL

#define VTKM_DEFINE_USER_LOG_LEVEL	(	name,
		offset
	)

Value:

  static constexpr vtkm::cont::LogLevel name = static_cast<vtkm::cont::LogLevel>( \
    static_cast<typename std::underlying_type<vtkm::cont::LogLevel>::type>(       \
      vtkm::cont::LogLevel::UserFirst) +                                          \
    offset %                                                                      \
      static_cast<typename std::underlying_type<vtkm::cont::LogLevel>::type>(     \
        vtkm::cont::LogLevel::UserLast))

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

Parameters

name	The name to give the new log level
offset	The 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,
		...
	)	VTKM_LOG_S(level, __VA_ARGS__)

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
	)

Value:

  VTKM_LOG_F(vtkm::cont::LogLevel::Cast,              \
             "Cast failed: %s (%p) --> %s",           \
             vtkm::cont::TypeToString(inObj).c_str(), \
             &inObj,                                  \
             vtkm::cont::TypeToString<outType>().c_str())

Convenience macro for logging a failed cast of dynamic object.

Parameters

inObj	The dynamic object.
outType	The candidate type (or typelist) that was unsuccessful.

◆ VTKM_LOG_CAST_SUCC

#define VTKM_LOG_CAST_SUCC	(	inObj,
		outObj
	)

Value:

  VTKM_LOG_F(vtkm::cont::LogLevel::Cast,               \
             "Cast succeeded: %s (%p) --> %s (%p)",    \
             vtkm::cont::TypeToString(inObj).c_str(),  \
             &inObj,                                   \
             vtkm::cont::TypeToString(outObj).c_str(), \
             &outObj)

Convenience macro for logging the successful cast of dynamic object.

Parameters

inObj	The dynamic object.
outObj	The resulting downcasted object.

◆ VTKM_LOG_F

#define VTKM_LOG_F	(	level,
		...
	)	VTKM_LOG_IF_F(level, true, __VA_ARGS__)

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:

VTKM_LOG_F(vtkm::cont::LogLevel::Perf,
           "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,
		...
	)	vtkm::cont::LogCond(level, cond, __FILE__, __LINE__, __VA_ARGS__)

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

◆ VTKM_LOG_IF_S

#define VTKM_LOG_IF_S	(	level,
		cond,
		...
	)	vtkm::cont::LogCondStream(level, cond, __FILE__, __LINE__) << __VA_ARGS__

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

◆ VTKM_LOG_S

#define VTKM_LOG_S	(	level,
		...
	)	VTKM_LOG_IF_S(level, true, __VA_ARGS__)

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:

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

◆ VTKM_LOG_SCOPE

#define VTKM_LOG_SCOPE	(	level,
		...
	)	vtkm::cont::detail::LogScope VTKM_ANONYMOUS_VARIABLE { level, __FILE__, __LINE__, __VA_ARGS__ }

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.

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

◆ VTKM_LOG_SCOPE_FUNCTION

#define VTKM_LOG_SCOPE_FUNCTION ( level ) VTKM_LOG_SCOPE(level, __func__)

Equivalent to VTKM_LOG_SCOPE(level, __func__)

◆ VTKM_LOG_TRYEXECUTE_DISABLE

#define VTKM_LOG_TRYEXECUTE_DISABLE	(	errorMessage,
		functorName,
		deviceId
	)

Value:

  VTKM_LOG_S(vtkm::cont::LogLevel::Error, "TryExecute encountered an error: " << errorMessage); \
  VTKM_LOG_S(vtkm::cont::LogLevel::Error, "Failing functor: " << functorName);                  \
  VTKM_LOG_S(vtkm::cont::LogLevel::Error, "Failing device: " << deviceId.GetName());            \
  VTKM_LOG_S(vtkm::cont::LogLevel::Error, "The failing device has been disabled.")

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

Parameters

errorMessage	The error message detailing the failure.
functorName	The name of the functor (see vtkm::cont::TypeToString)
deviceId	The device tag / id for the device on which the functor failed.

◆ VTKM_LOG_TRYEXECUTE_FAIL

#define VTKM_LOG_TRYEXECUTE_FAIL	(	errorMessage,
		functorName,
		deviceId
	)

Value:

  VTKM_LOG_S(vtkm::cont::LogLevel::Error, "TryExecute encountered an error: " << errorMessage); \
  VTKM_LOG_S(vtkm::cont::LogLevel::Error, "Failing functor: " << functorName);                  \
  VTKM_LOG_S(vtkm::cont::LogLevel::Error, "Failing device: " << deviceId.GetName())

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

Parameters

errorMessage	The error message detailing the failure.
functorName	The name of the functor (see vtkm::cont::TypeToString)
deviceId	The device tag / id for the device on which the functor failed.

Classes

Namespaces

Macros

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ VTKM_ANONYMOUS_VARIABLE

◆ VTKM_CONCAT

◆ VTKM_CONCAT_IMPL

◆ VTKM_DEFINE_USER_LOG_LEVEL

◆ VTKM_LOG_ALWAYS_S

◆ VTKM_LOG_CAST_FAIL

◆ VTKM_LOG_CAST_SUCC

◆ VTKM_LOG_F

◆ VTKM_LOG_IF_F

◆ VTKM_LOG_IF_S

◆ VTKM_LOG_S

◆ VTKM_LOG_SCOPE

◆ VTKM_LOG_SCOPE_FUNCTION

◆ VTKM_LOG_TRYEXECUTE_DISABLE

◆ VTKM_LOG_TRYEXECUTE_FAIL