This class implements a messenger for information, warning or error messages. More...

Inheritance diagram for Ocean::Messenger:

Public Types
enum	MessageType : uint32_t { TYPE_UNDEFINED = 0u , TYPE_DEBUG , TYPE_INFORMATION , TYPE_WARNING , TYPE_ERROR }
	Definition of different message types. More...

enum	MessageOutput : uint32_t { OUTPUT_DISCARDED = 0u , OUTPUT_STANDARD = 1u << 0u , OUTPUT_QUEUED = 1u << 1u , OUTPUT_DEBUG_WINDOW = 1u << 2u , OUTPUT_FILE = 1u << 3u , OUTPUT_STREAM = 1u << 4u , OUTPUT_MAINTENANCE = 1u << 5u }
	Definition of different message output types. More...

Public Member Functions
void	push (const MessageType type, std::string &&location, std::string &&message)
	Pushes a new message into the message queue. More...

bool	popDebug (std::string &location, std::string &message, bool *isNew=nullptr)
	Pops the first debug message from the message queue. More...

bool	popInformation (std::string &location, std::string &message, bool *isNew=nullptr)
	Pops the first information message from the message queue. More...

bool	popWarning (std::string &location, std::string &message, bool *isNew=nullptr)
	Pops the first warning message from the message queue. More...

bool	popError (std::string &location, std::string &message, bool *isNew=nullptr)
	Pops the first error message from the message queue. More...

bool	popMessage (MessageType &type, std::string &location, std::string &message, bool *isNew=nullptr)
	Pops any first message available of a given type or of any type. More...

std::string	popMessage (const MessageType type=TYPE_UNDEFINED, bool *isNew=nullptr)
	Pops the oldest message available of a specified type. More...

bool	setOutputType (const MessageOutput type)
	Sets the output type of the messenger. More...

bool	setFileOutput (const std::string &filename)
	Sets the message output to a file. More...

bool	setOutputStream (std::ostream &stream)
	Sets the message output to an output stream. More...

void	setIntegrateDateTime (const bool state)
	Enables or disables the integration of local date/time information into the location information of messages. More...

void	flush (std::ostream &stream)
	Flushes the current message stack to a given output stream, the output type is unchanged. More...

void	clear ()
	Clears all message queues. More...

void	clearInformations ()
	Clears the information message queue. More...

void	clearWarnings ()
	Clears the warning message queue. More...

void	clearErrors ()
	Clears the error message queue. More...

MessageOutput	outputType () const
	Returns the output type of the messenger. More...

size_t	informations () const
	Returns the number of waiting information messages. More...

size_t	warnings () const
	Returns the number of waiting information messages. More...

size_t	errors () const
	Returns the number of waiting information messages. More...

bool	integrateDateTime () const
	Returns whether the date/time integration is activated. More...

bool	empty () const
	Returns whether no message exists. More...

Static Public Member Functions
static void	writeToDebugOutput (const std::string &message)
	Writes a message to the most suitable debug output of the current platform. More...

static constexpr bool	isActive ()
	Returns whether the messenger is active on this build. More...

static constexpr bool	isDebugBuild ()
	Returns whether the messenger is used on a debug build. More...

Static Public Member Functions inherited from Ocean::Singleton< Messenger >
static Messenger &	get ()
	Returns a reference to the unique object. More...

Protected Types
typedef std::pair< std::string, std::string >	Message
	Definition of a message. More...

typedef std::queue< Message >	MessageQueue
	Definition of a message queue. More...

Protected Member Functions
	Messenger ()
	Creates a new messenger object queuing all messages as default. More...

	~Messenger ()
	Destructs a messenger object. More...

Protected Member Functions inherited from Ocean::Singleton< Messenger >
	Singleton ()=default
	Default constructor. More...

Static Protected Member Functions
static void	writeMessageToDebugWindowApple (const std::string &message)
	Write message to Apple-specific log facility. More...

Protected Attributes
MessageOutput	outputType_ = OUTPUT_STANDARD
	Message output type. More...

MessageQueue	debugMessageQueue_
	Debug message queue. More...

std::string	lastDebugMessage_
	Last debug message. More...

MessageQueue	informationMessageQueue_
	Information message queue. More...

MessageQueue	warningMessageQueue_
	Warning message queue. More...

MessageQueue	errorMessageQueue_
	Error message queue. More...

std::string	lastInformationMessage_
	Last information message. More...

std::string	lastWarningMessage_
	Last warning message. More...

std::string	lastErrorMessage_
	Last error message. More...

std::ofstream	fileOutputStream_
	File output stream. More...

std::ostream *	outputStream_ = nullptr
	Explicit output stream, if any. More...

bool	integrateDateTime_ = false
	Date and time integration state. More...

Lock	lock_
	Messenger lock. More...

Static Protected Attributes
static constexpr unsigned int	maxMessages_ = 5000u
	Maximum number of messages. More...

Friends
class	Singleton< Messenger >
	Friend class. More...

Detailed Description

This class implements a messenger for information, warning or error messages.

Posted messages are stored in internal message queues or referred to a specified output file.
Therefore, applications interested in live messaging have to pop the queued messages recurrently.

There different message types are supported dividing all messages related to their magnitude: Error messages hold critical informations which influence the major program progress directly.
Warning messages hold informations which can influence minor program progresses, however they are not critical.
Information messages hold interesting informations for the user only.
Meaning that error messages should be informed to the user immediately, instead information messages can be informed to the user.
Additionally, each message can provide a location specifying e.g. the sender module.

Applications interested in messages use the Messenger object implemented as singleton to receive messages. Modules use the MessageObject objects to post new messages.
Three basic message types are defined: error, warning and info.

See also: SpecificMessenger.

Tutorial explaining the usage on application side:

#include "ocean/base/Messenger.h"
 
// Function called by e.g. a timer recurrently.
void timer()
{
    if (Messenger::get().empty() == false)
    {
        // Strings which will receive the popped informations
        std::string message, location;
 
        // Boolean which will receive whether the information has been posted more than one time.
        bool isNew;
 
        // Pop all error messages
        while (Messenger::get().popError(location, message, isNew))
        {
            // Writes the error message to any application output window.
            writeToErrorOutputWindow(location, message);
        }
 
        // Pop all warning messages
        while (Messenger::get().popWarning(location, message, isNew))
        {
            // Writes the warning message to any application output window.
            writeToWarningOutputWindow(location, message);
        }
    }
}

Tutorial explaining the usage on module side:

#include "ocean/base/Messenger.h"
 
// Any function which will post a message.
void anyFunction()
{
    // A function calculating something
    int value = calculate();
 
    // suppose a resulting value of '0' is a failure
    if (value == 0)
        Log::error() << "The calculation failed.";
    else
        Log::info() << "The calculation returned \"" << value << \" which is great!";
}

Member Typedef Documentation

◆ Message

typedef std::pair<std::string, std::string> Ocean::Messenger::Message

protected

Definition of a message.

◆ MessageQueue

typedef std::queue<Message> Ocean::Messenger::MessageQueue

protected

Definition of a message queue.

Member Enumeration Documentation

◆ MessageOutput

enum Ocean::Messenger::MessageOutput : uint32_t

Definition of different message output types.

Enumerator
OUTPUT_DISCARDED	All messages will be discarded.
OUTPUT_STANDARD	All messages are directed to the standard output immediately.
OUTPUT_QUEUED	All messages are queued and must be popped from the message stack explicitly.
OUTPUT_DEBUG_WINDOW	All messages are directed to a debug window.
OUTPUT_FILE	All messages are directed to a file immediately.
OUTPUT_STREAM	All messages are directed to an arbitrary stream immediately.
OUTPUT_MAINTENANCE	All messages are directed to the maintenance manager.

◆ MessageType

enum Ocean::Messenger::MessageType : uint32_t

Definition of different message types.

Enumerator
TYPE_UNDEFINED	Invalid message type.
TYPE_DEBUG	Debug message, which are not used on release builds (optimized out of the code).
TYPE_INFORMATION	Information message.
TYPE_WARNING	Warning message.
TYPE_ERROR	Error message.

Constructor & Destructor Documentation

◆ Messenger()

Ocean::Messenger::Messenger ( )

protected

Creates a new messenger object queuing all messages as default.

◆ ~Messenger()

Ocean::Messenger::~Messenger ( )

protected

Destructs a messenger object.

Member Function Documentation

◆ clear()

void Ocean::Messenger::clear ( )

Clears all message queues.

◆ clearErrors()

void Ocean::Messenger::clearErrors ( )

Clears the error message queue.

◆ clearInformations()

void Ocean::Messenger::clearInformations ( )

Clears the information message queue.

◆ clearWarnings()

void Ocean::Messenger::clearWarnings ( )

Clears the warning message queue.

◆ empty()

bool Ocean::Messenger::empty ( ) const

inline

Returns whether no message exists.

Returns: True, if so

◆ errors()

size_t Ocean::Messenger::errors ( ) const

inline

Returns the number of waiting information messages.

Returns: Number of messages

◆ flush()

void Ocean::Messenger::flush ( std::ostream & stream )

Flushes the current message stack to a given output stream, the output type is unchanged.

Parameters

stream Output stream

◆ informations()

size_t Ocean::Messenger::informations ( ) const

inline

Returns the number of waiting information messages.

Returns: Number of messages

◆ integrateDateTime()

bool Ocean::Messenger::integrateDateTime ( ) const

inline

Returns whether the date/time integration is activated.

By default the date time integration is deactivated.

Returns: True, if so

See also: setIntegrateDateTime().

◆ isActive()

constexpr bool Ocean::Messenger::isActive ( )

staticconstexpr

Returns whether the messenger is active on this build.

Returns: True, if so; False, to strip away every message related information in the binary

◆ isDebugBuild()

constexpr bool Ocean::Messenger::isDebugBuild ( )

staticconstexpr

Returns whether the messenger is used on a debug build.

Returns: True, if so

◆ outputType()

Messenger::MessageOutput Ocean::Messenger::outputType ( ) const

inline

Returns the output type of the messenger.

Returns: Current output type

◆ popDebug()

bool Ocean::Messenger::popDebug	(	std::string &	location,
		std::string &	message,
		bool *	isNew = `nullptr`
	)

Pops the first debug message from the message queue.

Parameters

location	The resulting location of the message
message	The resulting text message
isNew	Optional returning flag determining whether this message is not identical to the last one

Returns: True, if a message could be popped

◆ popError()

bool Ocean::Messenger::popError	(	std::string &	location,
		std::string &	message,
		bool *	isNew = `nullptr`
	)

Pops the first error message from the message queue.

Parameters

location	The resulting location of the message
message	The resulting text message
isNew	Returning flag determining whether this message is not identical to the last one

Returns: True, if a message could be popped

◆ popInformation()

bool Ocean::Messenger::popInformation	(	std::string &	location,
		std::string &	message,
		bool *	isNew = `nullptr`
	)

Pops the first information message from the message queue.

Parameters

location	The resulting location of the message
message	The resulting text message
isNew	Optional returning flag determining whether this message is not identical to the last one

Returns: True, if a message could be popped

◆ popMessage() [1/2]

std::string Ocean::Messenger::popMessage	(	const MessageType	type = `TYPE_UNDEFINED`,
		bool *	isNew = `nullptr`
	)

Pops the oldest message available of a specified type.

Parameters

type	The type of the message to return, TYPE_UNDEFINED to return a message with any type
isNew	Optional resulting state determining whether the message is not identical to the previous one

Returns: The resulting message with format "Type: Location, Message", an empty string if no message is available

◆ popMessage() [2/2]

bool Ocean::Messenger::popMessage	(	MessageType &	type,
		std::string &	location,
		std::string &	message,
		bool *	isNew = `nullptr`
	)

Pops any first message available of a given type or of any type.

If several messages with different types are available and an undefined type is defined the pop order is: errors, warnings, informations.

Parameters

type	The type of the message to pop, may be TYPE_UNDEFINED to return any message while 'type' will be set to the type of the message which is returned
location	The resulting location of the message
message	The resulting text message
isNew	Optional returning flag determining whether this message is not identical to the previous one

Returns: True, if a message existed

◆ popWarning()

bool Ocean::Messenger::popWarning	(	std::string &	location,
		std::string &	message,
		bool *	isNew = `nullptr`
	)

Pops the first warning message from the message queue.

Parameters

location	The resulting location of the message
message	The resulting test message
isNew	Returning flag determining whether this message is not identical to the last one

Returns: True, if a message could be popped

◆ push()

void Ocean::Messenger::push	(	const MessageType	type,
		std::string &&	location,
		std::string &&	message
	)

Pushes a new message into the message queue.

Parameters

type	The type of the message
location	The location of the message
message	The text message

◆ setFileOutput()

bool Ocean::Messenger::setFileOutput ( const std::string & filename )

Sets the message output to a file.

All messages will be redirected to the specified file instead of inserted into the message queue.

Parameters

filename Name of the output file, use an empty filename to disable file output

Returns: True, if succeeded

See also: setOutputType().

◆ setIntegrateDateTime()

void Ocean::Messenger::setIntegrateDateTime ( const bool state )

Enables or disables the integration of local date/time information into the location information of messages.

Parameters

state True, to enable the integration of the date/time information

See also: integrateDateTime().

◆ setOutputStream()

bool Ocean::Messenger::setOutputStream ( std::ostream & stream )

Sets the message output to an output stream.

All messages will be redirected to the specified output stream instead of inserted into the message queue.

Parameters

stream Output stream

Returns: True, if succeeded

See also: setOutputType().

◆ setOutputType()

bool Ocean::Messenger::setOutputType ( const MessageOutput type )

Sets the output type of the messenger.

Parameters

type	Output type to set

Returns: True, if succeeded

See also: setFileOutput(), setOutputStream().

◆ warnings()

size_t Ocean::Messenger::warnings ( ) const

inline

Returns the number of waiting information messages.

Returns: Number of messages

◆ writeMessageToDebugWindowApple()

static void Ocean::Messenger::writeMessageToDebugWindowApple ( const std::string & message )

staticprotected

Write message to Apple-specific log facility.

See also: push()

Parameters

message The message to be written into NSLog

◆ writeToDebugOutput()

static void Ocean::Messenger::writeToDebugOutput ( const std::string & message )

static

Writes a message to the most suitable debug output of the current platform.

This function is just a simple way to create a debug message without needing to configure the Messenger.

Parameters

message The message to write

Friends And Related Function Documentation

◆ Singleton< Messenger >

friend class Singleton< Messenger >

friend

Friend class.

Field Documentation

◆ debugMessageQueue_

MessageQueue Ocean::Messenger::debugMessageQueue_

protected

Debug message queue.

◆ errorMessageQueue_

MessageQueue Ocean::Messenger::errorMessageQueue_

protected

Error message queue.

◆ fileOutputStream_

std::ofstream Ocean::Messenger::fileOutputStream_

protected

File output stream.

◆ informationMessageQueue_

MessageQueue Ocean::Messenger::informationMessageQueue_

protected

Information message queue.

◆ integrateDateTime_

bool Ocean::Messenger::integrateDateTime_ = false

protected

Date and time integration state.

◆ lastDebugMessage_

std::string Ocean::Messenger::lastDebugMessage_

protected

Last debug message.

◆ lastErrorMessage_

std::string Ocean::Messenger::lastErrorMessage_

protected

Last error message.

◆ lastInformationMessage_

std::string Ocean::Messenger::lastInformationMessage_

protected

Last information message.

◆ lastWarningMessage_

std::string Ocean::Messenger::lastWarningMessage_

protected

Last warning message.

◆ lock_

Lock Ocean::Messenger::lock_

mutableprotected

Messenger lock.

◆ maxMessages_

constexpr unsigned int Ocean::Messenger::maxMessages_ = 5000u

staticconstexprprotected

Maximum number of messages.

◆ outputStream_

std::ostream* Ocean::Messenger::outputStream_ = nullptr

protected

Explicit output stream, if any.

◆ outputType_

MessageOutput Ocean::Messenger::outputType_ = OUTPUT_STANDARD

protected

Message output type.

◆ warningMessageQueue_

MessageQueue Ocean::Messenger::warningMessageQueue_

protected

Warning message queue.

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

Messenger.h

Public Types

Public Member Functions

Static Public Member Functions

Protected Types

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Static Protected Attributes

Friends

Detailed Description

Member Typedef Documentation

◆ Message

◆ MessageQueue

Member Enumeration Documentation

◆ MessageOutput

◆ MessageType

Constructor & Destructor Documentation

◆ Messenger()

◆ ~Messenger()

Member Function Documentation

◆ clear()

◆ clearErrors()

◆ clearInformations()

◆ clearWarnings()

◆ empty()

◆ errors()

◆ flush()

◆ informations()

◆ integrateDateTime()

◆ isActive()

◆ isDebugBuild()

◆ outputType()

◆ popDebug()

◆ popError()

◆ popInformation()

◆ popMessage() [1/2]

◆ popMessage() [2/2]

◆ popWarning()

◆ push()

◆ setFileOutput()

◆ setIntegrateDateTime()

◆ setOutputStream()

◆ setOutputType()

◆ warnings()

◆ writeMessageToDebugWindowApple()

◆ writeToDebugOutput()

Friends And Related Function Documentation

◆ Singleton< Messenger >

Field Documentation

◆ debugMessageQueue_

◆ errorMessageQueue_

◆ fileOutputStream_

◆ informationMessageQueue_

◆ integrateDateTime_

◆ lastDebugMessage_

◆ lastErrorMessage_

◆ lastInformationMessage_

◆ lastWarningMessage_

◆ lock_

◆ maxMessages_

◆ outputStream_

◆ outputType_

◆ warningMessageQueue_