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.