Wrapping Slic in Macros

The recommended way of integrating Slic into an application is to wrap the Slic API for logging messages into a set of convenience application macros that are used throughout the application code.

This allows the application code to:

  • Centralize all use of Slic behind a thin macro layer,

  • Insulate the application from API changes in Slic,

  • Customize and augment the behavior of logging messages if needed, e.g., provide macros that are only active when the code is compiled with debug symbols etc.

The primary function used to log messages is slic::logMessage(), which in its most basic form takes the following arguments:

  1. The Log Message Level associated with the message

  2. A string corresponding to the user-supplied message

  3. The name of the file where the message was emitted

  4. The corresponding line number within the file where the message was emitted

There are additional variants of the slic::logMessage() function that allow an application to specify a TAG for different types of messages, etc. Consult the Slic Doxygen API Documentation for more details.

For example, an application, MYAPP, may want to define macros to log DEBUG, INFO, WARNING and ERROR messages as illustrated below

 1#define MYAPP_LOGMSG( LEVEL, msg )                                         \
 2{                                                                          \
 3  std::ostringstream oss;                                                  \
 4  oss << msg;                                                              \
 5  slic::logMessage( LEVEL, oss.str(), __FILE__, __LINE__ );                \
 6}
 7
 8#define MYAPP_ERROR( msg ) MYAPP_LOGMSG( slic::message::Error, msg )
 9#define MYAPP_WARNING( msg ) MYAPP_LOGMSG( slic::message::Warning, msg )
10#define MYAPP_INFO( msg ) MYAPP_LOGMSG( slic::message::Info, msg )
11#define MYAPP_DEBUG( msg ) MYAPP_LOGMSG( slic::message::Debug, msg )

These macros can then be used in the application code as follows:

MYAPP_INFO( "this is an info message")
MYAPP_ERROR( "this is an error message" );
...

Note

Another advantage of encapsulating the Slic API calls in macros is that this approach alleviates the burden from application developers to have to pass the __FILE__ and __LINE__ to the logMessage() function each time.

Macros that use slic::logMessage() with a Log Message Level of WARNING or ERROR are collective operations when used with MPI-aware Log Stream instances. Consult Collective Slic Macros for a list of collective Axom macros.

The Slic Macros Used in Axom provide a good resource for the type of macros that an application may want to adopt and extend. Although these macros are tailored for use within the Axom Toolkit, these are also callable by application code.

Slic Macros Used in Axom

Slic provides a set of convenience macros that can be used to streamline logging within an application, as summarized in the table below.

Note

The Slic Macros Used in Axom are not the only interface to log messages with Slic. They are used within Axom Toolkit for convenience. Applications or libraries that adopt Slic, typically, use the C++ API directly, e.g., call slic::logMessage() and wrap the functionality in application specific macros to better suit the requirements of the application.

Collective Slic Macros

A subset of SLIC macros are collective operations when used with MPI-aware Log Stream instances such as Synchronized Stream or Lumberjack Stream.

Additionally, macros such as SLIC_WARNING and SLIC_CHECK become collective operations when certain flags are toggled on or functions are called. Other macros such as SLIC_ERROR and SLIC_ASSERT can be made not collective when certain functions are called.

The table below details the built-in SLIC macros as well as some notes about when they are collective calls:

Macro

Availability

Collective status
SLIC_ASSERT
SLIC_ASSERT_MSG
Only available in debug configurations
(i.e. when AXOM_DEBUG is defined).
Not available in device code.
Collective by default.
Collective after calling slic::enableAbortOnError().
No longer collective after calling slic::disableAbortOnError().
SLIC_CHECK
SLIC_CHECK_MSG
Only available in debug configurations
(i.e. when AXOM_DEBUG is defined).
Not available in device code.
Not collective by default.
Collective after slic::debug::checksAreErrors is set to true,
defaults to false.
SLIC_DEBUG
SLIC_DEBUG_IF
SLIC_DEBUG_ROOT
SLIC_DEBUG_ROOT_IF
Only available in debug configurations
(i.e. when AXOM_DEBUG is defined)
Never
SLIC_INFO
SLIC_INFO_IF
SLIC_INFO_ROOT
SLIC_INFO_ROOT_IF
SLIC_INFO_TAGGED
Always
Never
SLIC_ERROR
SLIC_ERROR_IF
SLIC_ERROR_ROOT
SLIC_ERROR_ROOT_IF
Always
Collective by default.
Collective after calling slic::enableAbortOnError().
No longer collective after calling slic::disableAbortOnError()
SLIC_WARNING
SLIC_WARNING_IF
SLIC_WARNING_ROOT
SLIC_WARNING_ROOT_IF
Always
Not collective by default.
Collective after calling slic::enableAbortOnWarning().
No longer collective after calling slic::disableAbortOnWarning()

Doxygen generated API documentation on Macros can be found here: SLIC Macros

Consider the following rules of thumb when choosing from the above logging macros:

  • The SLIC_ABORT and SLIC_CHECK macros are typically used to check preconditions/postconditions of functions and help catch developer errors. They are only available in debug configurations (i.e. when AXOM_DEBUG is available).

  • SLIC_WARNING and SLIC_ERROR are available in all configurations and can be used to check for conditions that might affect the results. They are also useful for validating user inputs.

  • SLIC_INFO and SLIC_DEBUG macros are typically used to provide information about the state of an application. The SLIC_*_IF variants can be used to conditionally log messages. SLIC_DEBUG macros are compiled out in non-debug configurations (i.e. their messages will not get logged), while SLIC_INFO macros are always available.

  • The SLIC_*_ROOT variants can help reduce logging verbosity when called in an MPI application, especially if all MPI ranks are expected to have the same data (for example, if a value was broadcast from one rank to all the other ranks).