AXOM
Axom provides a robust, flexible software infrastructure for the development of multi-physics applications and computational tools.
axom::slic Namespace Reference

Namespaces

 detail
 
 inherit
 
 message
 

Classes

class  Logger
 A singleton class for logging error, debug and warning messages. More...
 
class  LogStream
 Abstract base class defining the interface of all LogStreams. More...
 
class  SimpleLogger
 SimpleLogger is a simple wrapper around the initialization and finalize operations of the slic::Logger class that is helpful for unit tests and simple applications in axom. More...
 
struct  debug
 
class  GenericOutputStream
 Concrete instance of LogStream, which implements functionality for logging messages to a C++ ostream object, e.g., std::cout, std::cerr, a std::ofstream, std::ostringstream, etc. More...
 
class  LumberjackStream
 A concrete instance of LogStream that utilizes Lumberjack to filter and pass messages between MPI nodes. More...
 
class  SynchronizedStream
 A concrete instance of LogStream that dumps messages to a C++ std::ostream object. More...
 

Typedefs

using AbortFunctionPtr = void(*)()
 

Functions

void initialize (bool is_root=true)
 Initializes the SLIC logging environment and allows setting which ranks write messages (root nodes). This defaults to all ranks writing unless selectively set by the user and can be set afterwards via slic::setIsRoot(). More...
 
bool isInitialized ()
 Checks if the SLIC logging environment is initialized. More...
 
bool isRoot ()
 Checks if we are on the root rank. Used for selective logging on root nodes. More...
 
void setIsRoot (bool is_root)
 Marks this node as root and enables the selective root logging filtering used in the SLIC_*_ROOT_* macros. More...
 
void ensureInitialized ()
 Ensures the SLIC logging environment is initialized. More...
 
void createLogger (const std::string &name, char imask=inherit::nothing)
 Creates a new logger associated with the given name. More...
 
bool activateLogger (const std::string &name)
 Activates the logger associated with the given name. More...
 
std::string getActiveLoggerName ()
 Returns the name of the active logger. More...
 
void setLoggingMsgLevel (message::Level level)
 Sets desired logging level. More...
 
message::Level getLoggingMsgLevel ()
 Gets the current logging level. More...
 
void setAbortOnError (bool status)
 Toggles the abort behavior for errors on the current active logger. More...
 
void enableAbortOnError ()
 Enables aborts on error messages for the current active logger. More...
 
void disableAbortOnError ()
 Disables aborts on error messages for the current active logger. More...
 
bool isAbortOnErrorsEnabled ()
 Checks whether aborts on errors are enabled for the current logger. More...
 
void setAbortOnWarning (bool status)
 Toggles the abort behavior for warnings on the current active logger. More...
 
void enableAbortOnWarning ()
 Enables aborts on warnings messages for the current active logger. More...
 
void disableAbortOnWarning ()
 Disables aborts on warnings messages for the current active logger. More...
 
bool isAbortOnWarningsEnabled ()
 Checks whether aborts on warnings are enabled for the current logger. More...
 
void setAbortFunction (AbortFunctionPtr abort_func)
 Sets the function to call when program abort is requested. More...
 
void addStreamToMsgLevel (LogStream *ls, message::Level level)
 Adds the given stream to the given level. More...
 
void addStreamToMsgLevel (GenericOutputStream *ls, message::Level level)
 Adds the given GenericOutputStream to the given level. More...
 
void addStreamToAllMsgLevels (LogStream *ls)
 Adds the given stream to all levels. More...
 
void addStreamToAllMsgLevels (GenericOutputStream *ls)
 Adds the given GenericOutputStream to all levels. More...
 
void addStreamToTag (LogStream *ls, const std::string &tag)
 Binds the given stream to the given tag. More...
 
void addStreamToTag (GenericOutputStream *ls, const std::string &tag)
 Binds the given GenericOutputStream to the given tag. More...
 
void addStreamToAllTags (LogStream *ls)
 Binds the given stream to all the tags. More...
 
void addStreamToAllTags (GenericOutputStream *ls)
 Binds the given GenericOutputStream to all the tags. More...
 
int getNumStreamsWithTag (const std::string &tag)
 Returns the number of streams for a given tag. Returns 0 if the tag does not exist. More...
 
void logMessage (message::Level level, const std::string &message, bool filter_duplicates=false)
 Logs the given message to all registered streams. More...
 
void logMessage (message::Level level, const std::string &message, const std::string &tag, bool filter_duplicates=false, bool tag_stream_only=false)
 Logs the given message to all registered streams. More...
 
void logMessage (message::Level level, const std::string &message, const std::string &fileName, int line, bool filter_duplicates=false)
 Logs the given message to all registered streams. More...
 
void logMessage (message::Level level, const std::string &message, const std::string &tag, const std::string &fileName, int line, bool filter_duplicates=false, bool tag_stream_only=false)
 Logs the given message to all registered streams. More...
 
void logErrorMessage (const std::string &message, const std::string &fileName, int line)
 Convenience method to log an error message. More...
 
void logWarningMessage (const std::string &message, const std::string &fileName, int line)
 Convenience method to log warning messages. More...
 
void outputLocalMessages ()
 For the current rank, outputs messages from all streams to the console. More...
 
std::string stacktrace ()
 Uses glibc's backtrace() functionality to return a stacktrace. More...
 
Collective Methods
Attention
These methods are collective operations. All ranks in the user-supplied communicator must call the method when used within an MPI distributed environment.
void abort ()
 Calls abort function. Default is abort() or MPI_Abort() in a MPI distributed environment. More...
 
void flushStreams ()
 Flushes all streams for all ranks. More...
 
void pushStreams ()
 Pushes all streams. More...
 
void finalize ()
 Finalizes the slic logging environment. More...
 

Typedef Documentation

◆ AbortFunctionPtr

using axom::slic::AbortFunctionPtr = typedef void (*)()

Function Documentation

◆ initialize()

void axom::slic::initialize ( bool  is_root = true)

Initializes the SLIC logging environment and allows setting which ranks write messages (root nodes). This defaults to all ranks writing unless selectively set by the user and can be set afterwards via slic::setIsRoot().

See also
slic::setIsRoot()
Parameters
[in]is_rootEnables selective logging macros based on root.

◆ isInitialized()

bool axom::slic::isInitialized ( )

Checks if the SLIC logging environment is initialized.

Returns
status true if initialized, else, false.

◆ isRoot()

bool axom::slic::isRoot ( )

Checks if we are on the root rank. Used for selective logging on root nodes.

See also
slic::initialize()
slic::setIsRoot()
Returns
status true if on root, else, false.

◆ setIsRoot()

void axom::slic::setIsRoot ( bool  is_root)

Marks this node as root and enables the selective root logging filtering used in the SLIC_*_ROOT_* macros.

Parameters
[in]is_rootEnables selective logging macros based on root.

◆ ensureInitialized()

void axom::slic::ensureInitialized ( )

Ensures the SLIC logging environment is initialized.

If SLIC is not initialized when this method is called, initialize SLIC to print all messages to std::cout and log a warning that prompts developers to properly call slic::initialize() and slic::finalize().

◆ createLogger()

void axom::slic::createLogger ( const std::string &  name,
char  imask = inherit::nothing 
)

Creates a new logger associated with the given name.

Parameters
[in]namethe name to associate with the new logger.
[in]imaskinheritance mask, indicates the log level streams that

will be inherited from the "root" logger. By default, nothing is inherited.

◆ activateLogger()

bool axom::slic::activateLogger ( const std::string &  name)

Activates the logger associated with the given name.

Parameters
[in]namethe name of the logger to activate.
Returns
True if the named logger was activated, False otherwise

◆ getActiveLoggerName()

std::string axom::slic::getActiveLoggerName ( )

Returns the name of the active logger.

Returns
s a string corresponding to the name of the active logger.

◆ setLoggingMsgLevel()

void axom::slic::setLoggingMsgLevel ( message::Level  level)

Sets desired logging level.

Parameters
[in]leveluser-supplied level to log.

◆ getLoggingMsgLevel()

message::Level axom::slic::getLoggingMsgLevel ( )

Gets the current logging level.

◆ setAbortOnError()

void axom::slic::setAbortOnError ( bool  status)

Toggles the abort behavior for errors on the current active logger.

Parameters
[in]statususer-supplied flag.

◆ enableAbortOnError()

void axom::slic::enableAbortOnError ( )

Enables aborts on error messages for the current active logger.

Note
This is equivalent to calling slic::setAbortOnError( true )
Postcondition
slic::isAbortOnErrorsEnabled() == true.
Precondition
slic::isInitialized() == true

◆ disableAbortOnError()

void axom::slic::disableAbortOnError ( )

Disables aborts on error messages for the current active logger.

Note
this is equivalent to calling slic::setAbortOnError( false )
Postcondition
slic::isAbortOnErrorsEnabled() == false.
Precondition
slic::isInitialized() == true

◆ isAbortOnErrorsEnabled()

bool axom::slic::isAbortOnErrorsEnabled ( )

Checks whether aborts on errors are enabled for the current logger.

Returns
status true if aborts on errors are enabled, otherwise, false.
Precondition
slic::isInitialized() == true.

◆ setAbortOnWarning()

void axom::slic::setAbortOnWarning ( bool  status)

Toggles the abort behavior for warnings on the current active logger.

Parameters
[in]statususer-supplied flag.

◆ enableAbortOnWarning()

void axom::slic::enableAbortOnWarning ( )

Enables aborts on warnings messages for the current active logger.

Note
This is equivalent to calling slic::setAbortOnWarning( true )
Postcondition
slic::isAbortOnWarningsEnabled() == true.
Precondition
slic::isInitialized() == true.

◆ disableAbortOnWarning()

void axom::slic::disableAbortOnWarning ( )

Disables aborts on warnings messages for the current active logger.

Note
This is equivalent to calling slic::setAbortOnWarnings( false )
Postcondition
slic::isAbortOnWarnigsEnabled() == true.
Precondition
slic::isInitialized() == true.

◆ isAbortOnWarningsEnabled()

bool axom::slic::isAbortOnWarningsEnabled ( )

Checks whether aborts on warnings are enabled for the current logger.

Returns
status true if aborts on warnings are enabled, otherwise, false.
Precondition
slic::isInitialized() == true.

◆ setAbortFunction()

void axom::slic::setAbortFunction ( AbortFunctionPtr  abort_func)

Sets the function to call when program abort is requested.

Parameters
[in]abort_funcThe user-specified function to call
Precondition
slic::isInitialized() == true.
Warning
No collective calls should be made in the given function. Collective calls may cause the program to hang on abort.

◆ addStreamToMsgLevel() [1/2]

void axom::slic::addStreamToMsgLevel ( LogStream ls,
message::Level  level 
)

Adds the given stream to the given level.

Parameters
[in]lspointer to the log stream.
[in]levelthe level to log.
Precondition
ls != nullptr

◆ addStreamToMsgLevel() [2/2]

void axom::slic::addStreamToMsgLevel ( GenericOutputStream ls,
message::Level  level 
)

Adds the given GenericOutputStream to the given level.

Parameters
[in]lspointer to the GenericOutputStream.
[in]levelthe level to log.
Precondition
ls != nullptr

◆ addStreamToAllMsgLevels() [1/2]

void axom::slic::addStreamToAllMsgLevels ( LogStream ls)

Adds the given stream to all levels.

Parameters
[in]lspointer to the log stream.
Precondition
ls != nullptr.

◆ addStreamToAllMsgLevels() [2/2]

void axom::slic::addStreamToAllMsgLevels ( GenericOutputStream ls)

Adds the given GenericOutputStream to all levels.

Parameters
[in]lspointer to the GenericOutputStream.
Precondition
ls != nullptr.

◆ addStreamToTag() [1/2]

void axom::slic::addStreamToTag ( LogStream ls,
const std::string &  tag 
)

Binds the given stream to the given tag.

Parameters
[in]lspointer to the user-supplied LogStream object.
[in]tagthe tag that this stream will be associated with.
Precondition
ls != nullptr.

◆ addStreamToTag() [2/2]

void axom::slic::addStreamToTag ( GenericOutputStream ls,
const std::string &  tag 
)

Binds the given GenericOutputStream to the given tag.

Parameters
[in]lspointer to the user-supplied GenericOutputStream.
[in]tagthe tag that this stream will be associated with.
Precondition
ls != nullptr.

◆ addStreamToAllTags() [1/2]

void axom::slic::addStreamToAllTags ( LogStream ls)

Binds the given stream to all the tags.

Parameters
[in]lspointer to the user-supplied LogStream object.
Precondition
ls != nullptr.

◆ addStreamToAllTags() [2/2]

void axom::slic::addStreamToAllTags ( GenericOutputStream ls)

Binds the given GenericOutputStream to all the tags.

Parameters
[in]lspointer to the user-supplied GenericOutputStream.
Precondition
ls != nullptr.

◆ getNumStreamsWithTag()

int axom::slic::getNumStreamsWithTag ( const std::string &  tag)

Returns the number of streams for a given tag. Returns 0 if the tag does not exist.

Parameters
[in]tagthe tag in query.
Returns
N the number of streams for the given tag.
Postcondition
N >= 0

◆ logMessage() [1/4]

void axom::slic::logMessage ( message::Level  level,
const std::string &  message,
bool  filter_duplicates = false 
)

Logs the given message to all registered streams.

Parameters
[in]levelthe level of the message being logged.
[in]messageuser-supplied message.
[in]filter_duplicatesoptional parameter that indicates whether duplicate messages resulting from running in parallel will be filtered out. Default is false.

◆ logMessage() [2/4]

void axom::slic::logMessage ( message::Level  level,
const std::string &  message,
const std::string &  tag,
bool  filter_duplicates = false,
bool  tag_stream_only = false 
)

Logs the given message to all registered streams.

Parameters
[in]levelthe level of the message being logged.
[in]messageuser-supplied message.
[in]taguser-supplied associated with this message.
[in]filter_duplicatesoptional parameter that indicates whether duplicate messages resulting from running in parallel will be filtered out. Default is false. /param [in] tag_stream_only optional parameter that indicates whether the message will go only to streams bound to tagName. Default is false.

◆ logMessage() [3/4]

void axom::slic::logMessage ( message::Level  level,
const std::string &  message,
const std::string &  fileName,
int  line,
bool  filter_duplicates = false 
)

Logs the given message to all registered streams.

Parameters
[in]levelthe level of the message being logged.
[in]messageuser-supplied message.
[in]fileNamethe name of the file this message is logged from.
[in]linethe line number within the file this message is logged.
[in]filter_duplicatesoptional parameter that indicates whether duplicate messages resulting from running in parallel will be filtered out. Default is false.

◆ logMessage() [4/4]

void axom::slic::logMessage ( message::Level  level,
const std::string &  message,
const std::string &  tag,
const std::string &  fileName,
int  line,
bool  filter_duplicates = false,
bool  tag_stream_only = false 
)

Logs the given message to all registered streams.

Parameters
[in]levelthe level of the message being logged.
[in]messageuser-supplied message.
[in]taguser-supplied tag associated with the message.
[in]fileNamethe name of the file this message is logged from.
[in]linethe line number within the file this message is logged.
[in]filter_duplicatesoptional parameter that indicates whether duplicate messages resulting from running in parallel will be filtered out. Default is false. /param [in] tag_stream_only optional parameter that indicates whether the message will go only to streams bound to tagName. Default is false.

◆ logErrorMessage()

void axom::slic::logErrorMessage ( const std::string &  message,
const std::string &  fileName,
int  line 
)

Convenience method to log an error message.

Parameters
[in]messageuser-supplied message.
[in]fileNamethe name of the file this message is logged from.
[in]linethe line number within the file that the message is logged.

◆ logWarningMessage()

void axom::slic::logWarningMessage ( const std::string &  message,
const std::string &  fileName,
int  line 
)

Convenience method to log warning messages.

Parameters
[in]messageuser-supplied message.
[in]fileNamethe name of the file this message is logged from.
[in]linethe line number within the file that the message is logged.

◆ outputLocalMessages()

void axom::slic::outputLocalMessages ( )

For the current rank, outputs messages from all streams to the console.

Warning
outputLocalMessages() is used before a rank aborts. flushStreams() is preferred over this function, as outputLocalMessages() may put LogStreams in an undesirable state. This call is not collective.

◆ abort()

void axom::slic::abort ( )

Calls abort function. Default is abort() or MPI_Abort() in a MPI distributed environment.

◆ flushStreams()

void axom::slic::flushStreams ( )

Flushes all streams for all ranks.

See also
Logger::flushStreams.
Note
When used within an MPI distributed environment, flushStreams is a collective operation. All ranks in the user-supplied communicator must call this method.

◆ pushStreams()

void axom::slic::pushStreams ( )

Pushes all streams.

See also
Logger::pushStreams.
Note
When used within an MPI distributed environment, pushStreams is a collective operation. All ranks in the user-supplied communicator must call this method.

◆ finalize()

void axom::slic::finalize ( )

Finalizes the slic logging environment.

◆ stacktrace()

std::string axom::slic::stacktrace ( )

Uses glibc's backtrace() functionality to return a stacktrace.

Returns
a string corresponding to the stacktrace.