Description:

This class provides a simple facility to collect what is called a 'report'. Reports are maintenance messages, mostly error and warning messages, but is not aiming to replace any sort of error handling. (In ALib itself, sending a 'report' usually precedes raising an error.)

While a process can create different objects of this class, usually, the default instance available by inheriting from class Singleton. is sufficient and all ALib internal warnings and errors will be directed to this one. Software built on ALib should do the same with internal warnings and errors. An own instance might be created to collect other types of reports.

This class uses a member of type * ReportWriter to actually write the reports. By default, an object of type ReportWriterStdIO is attached.

The reporting method, DoReport will check the flags provided with PushHaltFlags for message types 0 (errors) and 1 (warnings), and may invoke assert(). Such assertions are effective only in the debug-builds of the library/executable. Custom 'ReportWriters' might take action (e.g., for security reasons) and e.g., terminate the application also in release compilations.

To simplify things, a set of macros is defined which are pruned in release versions of the compilation unit. These are:

In fact, these macros exist in alib/alib.hpp already, but with the inclusion of header alib/lang/message/report.hpp, these macros become redefined to use this class.

For convenience, with debug-builds of the library, these macros provide the file name, line number and method name of the invocation source, which can be used by more sophisticated versions of currently attached ReportWriter.

Note: For debug output statements, it is advised to rather use the module ALox instead of ALib reports and corresponding macros.
In addition, ALox itself replaces the standard report writer given with this class by an instance of type ALoxReportWriter, which uses the ALox standard debug logger.

Definition at line 84 of file report.hpp.

#include <report.hpp>

Collaboration diagram for Report:

[legend]

Public Type Index:
enum class	Types { Error , Warning , Message }
	Types of reports. More...

Public Static Method Index:
static Report &	GetDefault ()

Public Method Index:
ALIB_API	Report ()
	Constructor.

ALIB_API	~Report ()
	Destructor.

template<typename... Boxes>
void	DoReport (const CallerInfo &ci, const Enum &type, Boxes &&... msgs)

ALIB_API void	DoReport (Message &message)

ALIB_API ReportWriter *	PeekWriter ()

ALIB_API void	PopHaltFlags ()
	Restores the previous values after an invocation to PushHaltFlags.

ALIB_API void	PopWriter (ReportWriter *checkWriter)

ALIB_API void	PushHaltFlags (bool haltOnErrors, bool haltOnWarnings)

ALIB_API void	PushWriter (ReportWriter *newWriter)

Protected Static Field Index:
static ALIB_API Report *	defaultReport = nullptr
	The default Report used internally by ALib and usually by processes that rely on ALib.

Protected Field Index:
std::stack< int >	haltAfterReport

threads::RecursiveLock	lock
	A Lock to protect against multithreaded calls.

bool	recursionBlocker = false

std::stack< ReportWriter * >	writers

Enumeration Details:

◆ Types

enum class Types

strong

Types of reports.

Enumerator
Error	An assertion.
Warning	A warning.
Message	A report message.

Definition at line 92 of file report.hpp.

Field Details:

◆ defaultReport

Report * defaultReport = nullptr

staticprotected

The default Report used internally by ALib and usually by processes that rely on ALib.

Definition at line 104 of file report.hpp.

◆ haltAfterReport

std::stack<int> haltAfterReport

protected

A stack of integers. The topmost value is used to decide, whether program execution is halted on message of type 'error' (type 0, bit 0) or of type 'warning' (type 1, bit 1). Can be set at run-time using methods PushHaltFlags and PopHaltFlags.

Definition at line 125 of file report.hpp.

◆ lock

threads::RecursiveLock lock

protected

A Lock to protect against multithreaded calls.

Definition at line 118 of file report.hpp.

◆ recursionBlocker

bool recursionBlocker = false

protected

This is a flag that avoids recursion. Recursion might occur when a more sophisticated report writer sends a report (e.g., an ALIB Error or Warning). Recursive calls are rejected without further notice.

Definition at line 114 of file report.hpp.

◆ writers

std::stack<ReportWriter*> writers

protected

A stack of writers. The topmost one is the actual. Can be set at run-time using methods PushWriter and PopWriter.

Definition at line 108 of file report.hpp.

Constructor(s) / Destructor Details:

◆ Report()

Report ( )

Constructor.

Definition at line 37 of file report.cpp.

Here is the call graph for this function:

◆ ~Report()

~Report ( )

Destructor.

Definition at line 45 of file report.cpp.

Here is the call graph for this function:

Method Details:

◆ DoReport() [1/2]

template<typename... Boxes>

void DoReport	(	const CallerInfo &	ci,
		const Enum &	type,
		Boxes &&...	msgs )

inline

Overloaded method that fetches all arguments needed to construct a Message object to pass to DoReport.

Parameters

ci	Information about the scope of invocation.
type	The report type.
msgs	Variadic list of boxes.

Definition at line 174 of file report.hpp.

◆ DoReport() [2/2]

void DoReport ( Message & message )

Reports the given message to the current ReportWriter in place. The default ReportWriter will print the message on the process console. Furthermore, in debug execution the flags provided with PushHaltFlags is checked. If this is set in respect to type of message (field Message::Type), the program halts or suspends into the debugger (platform and language specific).

Parameters

message The message to report.

Definition at line 105 of file report.cpp.

Here is the call graph for this function:

◆ GetDefault()

static Report & GetDefault ( )

inlinestatic

Receives the default report object used by ALib and processes that rely on ALib.

Returns: The default Report.

Definition at line 146 of file report.hpp.

◆ PeekWriter()

ReportWriter * PeekWriter ( )

Retrieves the actual report writer.

Note: This method should not be used to retrieve the writer and use it. It should be used only to test the installation.

Returns: The actual report writer in place.

Definition at line 99 of file report.cpp.

◆ PopHaltFlags()

void PopHaltFlags ( )

Restores the previous values after an invocation to PushHaltFlags.

Definition at line 57 of file report.cpp.

Here is the call graph for this function:

◆ PopWriter()

void PopWriter ( ReportWriter * checkWriter )

Restores the previous writer after setting a new one using PushWriter. It is important to keep the right order when pushing and popping writers, as there lifetime is externally managed. (In standard use-cases, only one, app-specific writer should be pushed anyhow). To give a little assurance, this method PopWriter takes the same parameter as PushWriter does, to verify if the one to be removed is really the topmost.

Parameters

checkWriter The previously pushed writer (for checking of call order).

Definition at line 88 of file report.cpp.

◆ PushHaltFlags()

void PushHaltFlags	(	bool	haltOnErrors,
		bool	haltOnWarnings )

Writes new values to the internal flags that decide if calls to DoReport with report type '0' (errors), respectively report type '>0' (warnings) cause to halt program execution by calling assert(false). The previous values can be restored using PopHaltFlags.

Parameters

haltOnErrors	Specifies if halting on errors is wanted.
haltOnWarnings	Specifies if halting on warnings is wanted.

Definition at line 51 of file report.cpp.

◆ PushWriter()

void PushWriter ( ReportWriter * newWriter )

Sets a new writer. The actual writer is implemented as a stack. It is important to keep the right order when pushing and popping writers, as there lifetime is externally managed. (In standard use-cases, only one, app-specific writer should be pushed anyhow). To give a little assurance, method PopWriter takes the same parameter as this method does, to verify if if the one to be removed is really the topmost.

Parameters

newWriter The writer to use.

Definition at line 79 of file report.cpp.

Here is the call graph for this function:

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

Description:

Public Type Index:

Public Static Method Index:

Public Method Index:

Protected Static Field Index:

Protected Field Index:

Enumeration Details:

◆ Types

Field Details:

◆ defaultReport

◆ haltAfterReport

◆ lock

◆ recursionBlocker

◆ writers

Constructor(s) / Destructor Details:

◆ Report()

◆ ~Report()

Method Details:

◆ DoReport() [1/2]

◆ DoReport() [2/2]

◆ GetDefault()

◆ PeekWriter()

◆ PopHaltFlags()

◆ PopWriter()

◆ PushHaltFlags()

◆ PushWriter()