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:

Table 14 SLIC macro availability and collective behavior

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 SLIC_DEBUG_PRINT_CONTAINER SLIC_DEBUG_ONCE SLIC_DEBUG_IF_ONCE SLIC_DEBUG_ROOT_ONCE SLIC_DEBUG_ROOT_IF_ONCE SLIC_DEBUG_PRINT_CONTAINER_ONCE

  • 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 SLIC_INFO_ONCE SLIC_INFO_IF_ONCE SLIC_INFO_ROOT_ONCE SLIC_INFO_ROOT_IF_ONCE SLIC_INFO_TAGGED_ONCE

  • 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 SLIC_WARNING_ONCE SLIC_WARNING_IF_ONCE SLIC_WARNING_ROOT_ONCE SLIC_WARNING_ROOT_IF_ONCE

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

  • The SLIC_*_ONCE variants can help reduce logging verbosity when only the first invocation at a call-site is necessary.