ALib C++ Library
Library Version: 2402 R1
Documentation generated by doxygen
Loading...
Searching...
No Matches
Report Class Reference

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

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 ReportWriterPeekWriter ()
 
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
fileInformation about the scope of invocation.
lineInformation about the scope of invocation.
funcInformation about the scope of invocation.
typeThe report type.
msgsVariadic 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
messageThe 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
checkWriterThe 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
haltOnErrorsSpecifies if halting on errors is wanted.
haltOnWarningsSpecifies 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
newWriterThe 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: