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 88 of file report.hpp.

#include <report.hpp>

Collaboration diagram for Report:

[legend]

Public Type Index:
enum class	Types { Error , Warning , Message }

Public Static Method Index:
static Report &	GetDefault ()

Public Method Index:
ALIB_API	Report ()

ALIB_API	~Report ()

template<typename... Boxes>
void	DoReport (const NCString &file, int line, const NCString &func, const Enum &type, Boxes &&... msgs)

ALIB_API void	DoReport (Message &message)

ALIB_API ReportWriter *	PeekWriter ()

ALIB_API void	PopHaltFlags ()

ALIB_API void	PopWriter (ReportWriter *checkWriter)

ALIB_API void	PushHaltFlags (bool haltOnErrors, bool haltOnWarnings)

ALIB_API void	PushWriter (ReportWriter *newWriter)

Enumeration Details:

◆ Types

enum class Types

strong

Types of reports

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

Definition at line 98 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 110 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 136 of file report.hpp.

◆ lock

threads::ThreadLock lock

protected

A Lock to protect against multithreaded calls.

Definition at line 127 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 123 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 116 of file report.hpp.

Constructor(s) / Destructor Details::

◆ Report()

Report ( )

Constructor.

Definition at line 53 of file report.cpp.

Here is the call graph for this function:

◆ ~Report()

~Report ( )

Destructor.

Definition at line 59 of file report.cpp.

Here is the call graph for this function:

Method Details:

◆ DoReport() [1/2]

template<typename... Boxes>

void DoReport	(	const NCString &	file,
		int	line,
		const NCString &	func,
		const Enum &	type,
		Boxes &&...	msgs )

inline

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

Parameters

file	Information about the scope of invocation.
line	Information about the scope of invocation.
func	Information about the scope of invocation.
type	The report type.
msgs	Variadic list of boxes.

Definition at line 187 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 119 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 157 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 113 of file report.cpp.

◆ PopHaltFlags()

void PopHaltFlags ( )

Restores the previous values after an invocation to PushHaltFlags.

Definition at line 71 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 102 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 65 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 93 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:

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()