Appendix¶

Slic Application Code Example¶

Below is the complete Slic Application Code Example presented in the Getting Started with Slic section. The code can be found in the Axom source code under src/axom/slic/examples/basic/logging.cpp.

// SPHINX_SLIC_INCLUDES_BEGIN
// Slic includes
#include "axom/slic.hpp"
// SPHINX_SLIC_INCLUDES_END

using namespace axom;

//------------------------------------------------------------------------------
int main(int AXOM_NOT_USED(argc), char** AXOM_NOT_USED(argv))
{
  // SPHINX_SLIC_INIT_BEGIN

  slic::initialize();

  // SPHINX_SLIC_INIT_END

  slic::disableAbortOnError();

  // SPHINX_SLIC_FORMAT_MSG_BEGIN

  std::string format = std::string("<TIMESTAMP>\n") +
    std::string("[<LEVEL>]: <MESSAGE> \n") + std::string("FILE=<FILE>\n") +
    std::string("LINE=<LINE>\n\n");

  // SPHINX_SLIC_FORMAT_MSG_END

  // SPHINX_SLIC_SET_SEVERITY_BEGIN

  slic::setLoggingMsgLevel(slic::message::Debug);

  // SPHINX_SLIC_SET_SEVERITY_END

  // SPHINX_SLIC_SET_STREAM_BEGIN
  slic::addStreamToAllMsgLevels(new slic::GenericOutputStream(&std::cout, format));

  // SPHINX_SLIC_SET_STREAM_END

  // SPHINX_SLIC_LOG_MESSAGES_BEGIN

  SLIC_DEBUG("Here is a debug message!");
  SLIC_INFO("Here is an info mesage!");
  SLIC_WARNING("Here is a warning!");
  SLIC_ERROR("Here is an error message!");

  // SPHINX_SLIC_LOG_MESSAGES_END

  // SPHINX_SLIC_FINALIZE_BEGIN

  slic::finalize();

  // SPHINX_SLIC_FINALIZE_END

  return 0;
}

axom::utilities::processAbort()¶

The axom::utilities::processAbort() function gracefully aborts the application by:

Calling abort() if it is a serial application.
Calls MPI_Abort() if the Axom Toolkit is compiled with MPI and the application has initialized MPI, i.e., it’s a distributed MPI application.

Slic Macros Used in Axom¶

Slic provides a set of convenience macros that can be used to streamline logging within an application.

Note

The Slic Macros Used in Axom are not the only interface to log messages with Slic. They are used within the 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.

SLIC_INFO¶

The SLIC_INFO macro logs INFO messages that consist general information reported by an application.

The following code snippet illustrates the usage of the SLIC_INFO macro:

SLIC_INFO( "Total number of mesh cells:" <<  N );

SLIC_INFO_IF¶

The SLIC_INFO_IF macro provides the same functionality with the SLIC_INFO macro, however, it takes one additional argument, a boolean expression, that allows the application to conditionally log an INFO message depending on the value of the boolean expression.

For example, the following code snippet illustrates the usage of the SLIC_INFO_IF macro.

SLIC_INFO_IF( (myval >= 0), "[" << myval << "] is positive!" );

In this case, the INFO message is only logged when the boolean expression, (myval >=0) evaluates to true.

Note

The primary intent is to provide a convenience layer and facilitate in a cleaner and more compact code style by encapsulating the conditional branching logic within a macro.

SLIC_ERROR¶

The SLIC_ERROR macro logs ERROR messages that indicate that the application has encountered a critical error.

The following code snippet illustrates the basic usage of the SLIC_ERROR macro:

SLIC_ERROR( "jacobian is negative!" );

A stacktrace of the application is appended to all ERROR messages to facilitate debugging.

Note

By default, an ERROR message triggers a call to abort() the application. However, this behavior can be toggled by calling slic::enableAbortOnError() and slic::disableAbortOnError() accordingly. See the Slic Doxygen API Documentation for more information.

SLIC_ERROR_IF¶

The SLIC_ERROR_IF provides the same functionality with the SLIC_ERROR macro, however, it takes one additional argument, a boolean expression, that allows the application to conditionally log an ERROR message depending on the value of the boolean expression.

The following code snippet illustrates the usage of the SLIC_ERROR_IF macro.

SLIC_ERROR_IF( (jacobian < 0.0 + TOL), "jacobian is negative!" );

In this case, the ERROR message in only logged when the boolean expression, (jacobian < 0.0 + TOL) evaluates to true.

Note

The primary intent is to provide a convenience layer and facilitate in a cleaner and more compact code style by encapsulating the conditional branching logic within a macro.

SLIC_WARNING¶

The SLIC_WARNING macro logs WARNING messages that indicate that the application has encountered an error, however, the error is not critical and the application can proceed.

The following code snippet illustrates the basic usage of the SLIC_WARNING macro.

SLIC_WARNING( "Region [" << ir << "] defined but not used in the problem!" );

SLIC_WARNING_IF¶

Similarly, the SLIC_WARNING_IF macro provides the same functionality with the SLIC_WARNING macro, however, it takes one additional argument, a boolean expression, that allows the application to conditionally log a WARNING message depending on the value of the boolean expression.

The following code snippet illustrates the basic usage of the SLIC_WARNING_IF macro.

SLIC_WARNING_IF( (val < 1), "val cannot be less than 1. Forcing value to 1." );
val = 1;

In this case, the WARNING message is only logged when the boolean expression, (val < 1), evaluates to `` true``.

Note

The primary intent is to provide a convenience layer and facilitate in a cleaner and more compact code style by encapsulating the conditional branching logic within a macro.

SLIC_DEBUG¶

The SLIC_DEBUG macro logs DEBUG messages that are intended for debugging information intended for developers.

The following code snippet illustrates the basic usage of the SLIC_DEBUG macro

SLIC_DEBUG( "Application is running with " << N << " threads!" );

Warning

This macro will log messages only when the Axom Toolkit is configured and built with debug symbols. Consult the Axom Quick Start Guide for more information.

SLIC_DEBUG_IF¶

Similarly, the SLIC_DEBUG_IF macro provides the same functionality with the SLIC_DEBUG macro, however, it take one additional argument, a boolean expression, that allows the application to conditionally log a DEBUG message depending on the value of the supplied boolean expression.

The following code snippet illustrates the basic usage of the SLIC_DEBUG_IF macro.

SLIC_DEBUG_IF( (value < 0), "value is negative!" );

In this case, the DEBUG message is only logged when the boolean expression, (value <0), evaluates to true.

Note

The primary intent is to provide a convenience layer and facilitate in a cleaner and more compact code style by encapsulating the conditional branching logic within a macro.

Warning

This macro will log messages only when the Axom Toolkit is configured and built with debug symbols. Consult the Axom Quick Start Guide for more information.

SLIC_ASSERT¶

The SLIC_ASSERT macro is used in a similar manner to the C++ assert() function call. It evaluates the given expression and logs an ERROR message if the assertion is not true. The contents of the error message consist of the supplied expression.

The SLIC_ASSERT macro is typically used to capture programming errors and to ensure pre-conditions and post-conditions are satisfied.

The following code snippet illustrates the basic usage of the SLIC_ASSERT macro.

SLIC_ASSERT( data != nullptr );

Warning

This macro will log messages only when the Axom Toolkit is configured and built with debug symbols. Consult the Axom Quick Start Guide for more information.

SLIC_ASSERT_MSG¶

The SLIC_ASSERT_MSG macro provides the same functionality with the SLIC_ASSERT macro, however, it allows the application to supply a custom message in addition to the boolean expression that is evaluated.

The following code snippet illustrates the basic usage of the SLIC_ASSERT_MSG macro.

SLIC_ASSERT_MSG( data != nullptr, "supplied pointer is null!" );

Warning

This macro will log messages only when the Axom Toolkit is configured and built with debug symbols. Consult the Axom Quick Start Guide for more information.

SLIC_CHECK¶

The SLIC_CHECK macro evaluates a given boolean expression, similar to the SLIC_ASSERT macro. However, in contrast to the SLIC_ASSERT macro, when the boolean expression evaluates to false, the macro logs a WARNING instead of an ERROR.

The following code snippet illustrates the basic usage of the SLIC_CHECK macro.

SLIC_CHECK( data != nullptr );

Warning

This macro will log messages only when the Axom Toolkit is configured and built with debug symbols. Consult the Axom Quick Start Guide for more information.

SLIC_CHECK_MSG¶

The SLIC_CHECK_MSG macro provides the same functionality with the SLIC_CHECK macro, however, it allows for the application to supply a custom message in addition to the boolean expression that is evaluated.

The following code snippet illustrates the basic usage of the SLIC_CHECK_MSG macro.

SLIC_CHECK_MSG( data != nullptr, "supplied pointer is null!" );

Warning

This macro will log messages only when the Axom Toolkit is configured and built with debug symbols. Consult the Axom Quick Start Guide for more information.