A concrete instance of LogStream that dumps messages to a C++ std::ostream object. More...

#include </home/docs/checkouts/readthedocs.org/user_builds/axom/checkouts/main/src/axom/slic/streams/SynchronizedStream.hpp>

Inheritance diagram for axom::slic::SynchronizedStream:

[legend]

Public Member Functions
	SynchronizedStream (std::ostream *stream, MPI_Comm comm)
	Constructs a SynchronizedStream instance with the given stream and MPI communicator. More...

	SynchronizedStream (std::ostream *stream, MPI_Comm comm, const std::string &format)
	Constructs a SynchronizedStream instance with the given stream, MPI communicator, and message formatting. More...

	SynchronizedStream (std::string stream, MPI_Comm comm)
	Constructs a SynchronizedStream instance specified by the given string, and MPI communicator. The string input determines the stream as follows: More...

	SynchronizedStream (std::string stream, MPI_Comm comm, const std::string &format)
	Constructs a SynchronizedStream instance specified by the given string, MPI communicator, and message formatting. The string input determines the stream as follows: More...

virtual	~SynchronizedStream ()

virtual void	append (message::Level msgLevel, const std::string &message, const std::string &tagName, const std::string &fileName, int line, bool filter_duplicates, bool tag_stream_only) override
	Appends the given message to the stream. More...

virtual void	outputLocal () override
	Dumps the messages from the current rank directly to the console (non-collectively). More...

virtual void	flush () override
	Dumps the messages to the console in rank-order for all ranks. More...

virtual bool	hasPendingMessages () override
	Tests whether there are any pending messages that need to be flushed. More...

virtual bool	isUsingMPI () override
	Tests whether this class relies on MPI. More...

virtual MPI_Comm	comm () override
	Get the communicator. More...

void	setFormatString (const std::string &format)
	Sets the format string. More...

virtual void	push ()
	Pushes messages incrementally up the log stream. NO-OP by default. More...

Protected Member Functions
std::string	getFormatedMessage (const std::string &msgLevel, const std::string &message, const std::string &tagName, const std::string &rank, const std::string &rank_count, const std::string &fileName, int line)
	Get the communicator. More...

std::string	getTimeStamp ()
	Returns a time-stamp. More...

Detailed Description

A concrete instance of LogStream that dumps messages to a C++ std::ostream object.

Note: The intent of this class is to illustrate how to using the Logging facility within an MPI distributed environment and provide a utility that could be useful for debugging problems at small scales.

Warning: Do not use this for large-scale production runs.; The intent of this class is to be used primarily with std::cout, std::cerr, etc. It is suggested that applications do not use this class with an std::ofstream object.

Constructor & Destructor Documentation

◆ SynchronizedStream() [1/4]

axom::slic::SynchronizedStream::SynchronizedStream	(	std::ostream *	stream,
		MPI_Comm	comm
	)

Constructs a SynchronizedStream instance with the given stream and MPI communicator.

Parameters

[in]	os	pointer to a user-supplied ostream instance.
[in]	comm	MPI communicator

Precondition: stream != NULL

◆ SynchronizedStream() [2/4]

axom::slic::SynchronizedStream::SynchronizedStream	(	std::ostream *	stream,
		MPI_Comm	comm,
		const std::string &	format
	)

Constructs a SynchronizedStream instance with the given stream, MPI communicator, and message formatting.

Parameters

[in]	os	pointer to a user-supplied ostream instance.
[in]	comm	MPI communicator
[in]	format	the format string.

Precondition: stream != NULL

See also: LogStream::setFormatString for the format string.

◆ SynchronizedStream() [3/4]

axom::slic::SynchronizedStream::SynchronizedStream	(	std::string	stream,
		MPI_Comm	comm
	)

Constructs a SynchronizedStream instance specified by the given string, and MPI communicator. The string input determines the stream as follows:

"cout" makes std::cout the output stream
"cerr" makes std::cerr the output stream
Any other input will construct a std::ofstream associated with input
Parameters

[in] stream the string to control type of stream created

[in] comm MPI communicator

Precondition
stream != NULL

See also
LogStream::setFormatString for the format string.

Note
This constructor avoids creating an empty file if this SynchronizedStream never flushes a message.

◆ SynchronizedStream() [4/4]

axom::slic::SynchronizedStream::SynchronizedStream	(	std::string	stream,
		MPI_Comm	comm,
		const std::string &	format
	)

Constructs a SynchronizedStream instance specified by the given string, MPI communicator, and message formatting. The string input determines the stream as follows:

"cout" makes std::cout the output stream
"cerr" makes std::cerr the output stream
Any other input will construct a std::ofstream associated with input
Parameters

[in] stream the string to control type of stream created

[in] comm MPI communicator

[in] format the format string.

Precondition
stream != NULL

See also
LogStream::setFormatString for the format string.

Note
This constructor avoids creating an empty file if this SynchronizedStream never flushes a message.

◆ ~SynchronizedStream()

virtual axom::slic::SynchronizedStream::~SynchronizedStream ( )

virtual

Member Function Documentation

◆ append()

virtual void axom::slic::SynchronizedStream::append	(	message::Level	msgLevel,
		const std::string &	message,
		const std::string &	tagName,
		const std::string &	fileName,
		int	line,
		bool	filter_duplicates,
		bool	tag_stream_only
	)

overridevirtual

Appends the given message to the stream.

Parameters

[in]	msgLevel	the level of the message.
[in]	message	the user-supplied message.
[in]	tagName	user-supplied tag to associate with the given message.
[in]	fileName	the file where this message is appended
[in]	line	the line within the file at which the message is appended.
[in]	filter_duplicates	optional parameter that indicates whether duplicate messages resulting from running in parallel will be filtered out. /param [in] tag_stream_only optional parameter that indicates whether the message will go only to streams bound to tagName.

Note: This method doesn't put anything to the console. Instead the messages are cached locally to each ranks and are dumped to the console in rank order when flush is called.

Implements axom::slic::LogStream.

◆ outputLocal()

virtual void axom::slic::SynchronizedStream::outputLocal ( )

overridevirtual

Dumps the messages from the current rank directly to the console (non-collectively).

Warning: This method is being called before slic aborts.

Reimplemented from axom::slic::LogStream.

◆ flush()

virtual void axom::slic::SynchronizedStream::flush ( )

overridevirtual

Dumps the messages to the console in rank-order for all ranks.

Note: This method is a collective operation intended for a synchronization checkpoint.

Reimplemented from axom::slic::LogStream.

◆ hasPendingMessages()

virtual bool axom::slic::SynchronizedStream::hasPendingMessages ( )

overridevirtual

Tests whether there are any pending messages that need to be flushed.

Returns: Returns true if there are pending messages that need to be flushed

Reimplemented from axom::slic::LogStream.

◆ isUsingMPI()

virtual bool axom::slic::SynchronizedStream::isUsingMPI ( )

overridevirtual

Tests whether this class relies on MPI.

Returns: Returns true if this class relies on MPI

Reimplemented from axom::slic::LogStream.

◆ comm()

virtual MPI_Comm axom::slic::SynchronizedStream::comm ( )

overridevirtual

Get the communicator.

Returns: Returns the communicator if it exists, or MPI_COMM_NULL otherwise

◆ setFormatString()

void axom::slic::LogStream::setFormatString ( const std::string & format )

inlineinherited

Sets the format string.

Parameters

format a format string

Note

The following keywords in the format string are replaced:

<LEVEL> with the message type, e.g, ERROR, FATAL, etc.
<MESSAGE> with the user-supplied message
<TAG> user-supplied tag
<FILE> with the filename
<LINE> with the line number
<RANK> with the MPI rank(s)
<RANK_COUNT> with the number of MPI ranks
<TIMESTAMP> date/time the message is logged

An example illustrating how an application can setup the format string is shown below:

std::string format =
       std::string( "***********************************\n" )+
       std::string( "* <TIMESTAMP>\n\n" ) +
       std::string( "* LEVEL=<LEVEL>\n" ) +
       std::string( "* MESSAGE=<MESSAGE>\n" ) +
       std::string( "* FILE=<FILE>\n" ) +
       std::string( "* LINE=<LINE>\n" ) +
       std::string( "* RANK=<RANK>\n" ) +
       std::string( "* RANK_COUNT=<RANK_COUNT>\n" ) +
       std::string( "***********************************\n" );

◆ push()

virtual void axom::slic::LogStream::push ( )

inlinevirtualinherited

Pushes messages incrementally up the log stream. NO-OP by default.

Note: The intent of this method is to be overridden by concrete implementations that need to be incrementally advanced. This is primarily useful for applications running in a distributed MPI environment, where the push is a collective operation intended for a incrementally advancing messages through the log stream.

Reimplemented in axom::slic::LumberjackStream.

◆ getFormatedMessage()

std::string axom::slic::LogStream::getFormatedMessage	(	const std::string &	msgLevel,
		const std::string &	message,
		const std::string &	tagName,
		const std::string &	rank,
		const std::string &	rank_count,
		const std::string &	fileName,
		int	line
	)

protectedinherited

Get the communicator.

Returns: Returns the communicator if it exists, or MPI_COMM_NULL otherwise

Returns the formatted message as a single string.

Parameters

[in]	msgLevel	the level of the given message.
[in]	message	the user-supplied message.
[in]	tagName	user-supplied tag, may be MSG_IGNORE_TAG
[in]	fileName	filename where this message is logged, may be MSG_IGNORE_FILE to ignore this field.
[in]	rank	The MPI rank(s) that emitted this message
[in]	rank_count	the number of MPI ranks that emitted this message
[in]	line	the line number within the file where the message is logged. Likewise, may be set to MSG_IGNORE_LINE to ignore this field.

Returns: str the formatted message string.

Postcondition: str != "".

◆ getTimeStamp()

std::string axom::slic::LogStream::getTimeStamp ( )

protectedinherited

Returns a time-stamp.

Returns: str a textual representation of the current time.

The documentation for this class was generated from the following file:

/home/docs/checkouts/readthedocs.org/user_builds/axom/checkouts/main/src/axom/slic/streams/SynchronizedStream.hpp

[in]	stream	the string to control type of stream created
[in]	comm	MPI communicator

Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ SynchronizedStream() [1/4]

◆ SynchronizedStream() [2/4]

◆ SynchronizedStream() [3/4]

◆ SynchronizedStream() [4/4]

◆ ~SynchronizedStream()

Member Function Documentation

◆ append()

◆ outputLocal()

◆ flush()

◆ hasPendingMessages()

◆ isUsingMPI()

◆ comm()

◆ setFormatString()

◆ push()

◆ getFormatedMessage()

◆ getTimeStamp()