Base class for message reporting and monitoring. More...

#include <tsReport.h>

Inheritance diagram for ts::Report:

[legend]

Public Member Functions
	Report ()=default
	Default constructor.

	Report (int max_severity, const UString &prefix=UString(), Report *report=nullptr)
	Constructor with initial report level, prefix and delegation.

virtual	~Report ()
	Destructor.

bool	debug () const
	Check if debugging is active.

template<class... Args>
void	debug (const UChar *fmt, Args &&... args)
	Report a debug message with a printf-like interface.

void	debug (const UChar *msg)
	Report a debug message.

template<class... Args>
void	debug (const UString &fmt, Args &&... args)
	Report a debug message with a printf-like interface.

void	debug (const UString &msg)
	Report a debug message.

Report *	delegateReport (Report *report)
	Delegate message logging to another report object.

template<class... Args>
void	error (const UChar *fmt, Args &&... args)
	Report an error message with a printf-like interface.

void	error (const UChar *msg)
	Report an error message.

template<class... Args>
void	error (const UString &fmt, Args &&... args)
	Report an error message with a printf-like interface.

void	error (const UString &msg)
	Report an error message.

template<class... Args>
void	fatal (const UChar *fmt, Args &&... args)
	Report a fatal error message with a printf-like interface.

void	fatal (const UChar *msg)
	Report a fatal error message.

template<class... Args>
void	fatal (const UString &fmt, Args &&... args)
	Report a fatal error message with a printf-like interface.

void	fatal (const UString &msg)
	Report a fatal error message.

bool	gotErrors () const
	Check if errors (or worse) were reported through this object.

template<class... Args>
void	info (const UChar *fmt, Args &&... args)
	Report an informational message with a printf-like interface.

void	info (const UChar *msg)
	Report an informational message.

template<class... Args>
void	info (const UString &fmt, Args &&... args)
	Report an informational message with a printf-like interface.

void	info (const UString &msg)
	Report an informational message.

template<class... Args>
void	log (int severity, const UChar *fmt, Args &&... args)
	Report a message with an explicit severity and a printf-like interface.

template<class... Args>
void	log (int severity, const UString &fmt, Args &&... args)
	Report a message with an explicit severity and a printf-like interface.

void	log (int severity, const UString &msg)
	Report a message with an explicit severity.

int	maxSeverity () const
	Get maximum severity level.

void	raiseMaxSeverity (int level)
	Raise maximum severity level.

UString	reportPrefix () const
	Get the current prefix to display.

void	resetErrors ()
	Reset the error indicator.

void	setMaxSeverity (int level)
	Set maximum severity level.

void	setReportPrefix (const UString &prefix)
	Set the prefix to display before each message.

template<class... Args>
void	severe (const UChar *fmt, Args &&... args)
	Report a severe error message with a printf-like interface.

void	severe (const UChar *msg)
	Report a severe error message.

template<class... Args>
void	severe (const UString &fmt, Args &&... args)
	Report a severe error message with a printf-like interface.

void	severe (const UString &msg)
	Report a severe error message.

bool	verbose () const
	Check if verbose reporting is active.

template<class... Args>
void	verbose (const UChar *fmt, Args &&... args)
	Report a verbose message with a printf-like interface.

void	verbose (const UChar *msg)
	Report a verbose message.

template<class... Args>
void	verbose (const UString &fmt, Args &&... args)
	Report a verbose message with a printf-like interface.

void	verbose (const UString &msg)
	Report a verbose message.

template<class... Args>
void	warning (const UChar *fmt, Args &&... args)
	Report a warning message with a printf-like interface.

void	warning (const UChar *msg)
	Report a warning error message.

template<class... Args>
void	warning (const UString &fmt, Args &&... args)
	Report a warning message with a printf-like interface.

void	warning (const UString &msg)
	Report a warning error message.

Protected Member Functions
virtual void	writeLog (int severity, const UString &msg)
	Actual message reporting method.

Detailed Description

Base class for message reporting and monitoring.

Maximum severity: Each Report instance has an adjustable "maximum severity". All messages with a higher severity are dropped without reporting. The initial default severity is Info, meaning that Verbose and Debug messages are dropped by default.

Report delegation: A Report can delegate its message reporting to another Report. Each Report has at most one delegate and several delagators (other Reports which delegate to this object). Therefore, there is a tree of Reports which ultimately ends to one Report which does the actual message logging. All Reports in that tree share the same maximum severity. When the maximum severity is changed in one Report, it is updated in all Reports in the tree.

Delegation and thread synchronization: We tried to find the right balance between performances and synchronization.

We assume that messages are extremely frequently emitted and should be logged without locking. Accesses to the current maximum severity and to the delegate are unchecked are done using local capies in this object. Problems occur when we log to the delegate at the same time the delegate is destructed, because there is no lock during the logging functions. We accept the race condition since getting the lock each time we log a message whould be too costly. To avoid this race condition, never delegate to a report which may be destructed before this object.
Setting or removing delegation is rare and needs synchronization. Because modifications can be done upward or downward, it is difficult to find a fine-grained hierarchy of locks without risking a deadlock. Similarly, it is difficult to locate one mutex per tree of Reports because trees can be split (when a delegation is removed) or merged (when a delegation is created). Therefore, a global mutex is used for all Reports, when delegations are added or removed. This is why this must be a rare operation.
Adjusting the maximum severity is far less frequent than logging a message. However, since we assume that many or most Reports do not have any delegate or delegators, we want to safely update their maximum severity without locking the global mutex. We do this using atomic counters. For Reports which are part of a delegation tree, we lock the global mutex and update the local copy of the maximum severity in each Report in the tree.

Constructor & Destructor Documentation

◆ Report() [1/2]

ts::Report::Report ( )

default

Default constructor.

The default initial report level is Info.

◆ Report() [2/2]

ts::Report::Report	(	int	max_severity,
		const UString &	prefix = `UString()`,
		Report *	report = `nullptr`
	)

Constructor with initial report level, prefix and delegation.

Parameters

[in]	max_severity	Initial maximum severity of reported messages.
[in]	prefix	The prefix to prepend to all messages.
[in]	report	New report object to which messages are delegated.

◆ ~Report()

virtual ts::Report::~Report ( )

virtual

Destructor.

It is unsafe to delete a Report when it has delegators (i.e. when other Reports delegate to this object). Race conditions exist when a delegator logs a message at the same time its delegate is destructed.

Member Function Documentation

◆ setMaxSeverity()

void ts::Report::setMaxSeverity ( int level )

Set maximum severity level.

Messages with higher severities are not reported.

Parameters

[in] level Set report to that level.

◆ raiseMaxSeverity()

void ts::Report::raiseMaxSeverity ( int level )

Raise maximum severity level.

The severity can only be increased (more verbose, more debug), never decreased.

Parameters

[in] level Set report at least to that level.

◆ maxSeverity()

int ts::Report::maxSeverity ( ) const

inline

Get maximum severity level.

Returns: Current maximum debug level.

◆ gotErrors()

bool ts::Report::gotErrors ( ) const

inline

Check if errors (or worse) were reported through this object.

Errors which were reported through delegated reports are ignored.

Returns: True if errors (or worse) were reported through this object.

◆ resetErrors()

void ts::Report::resetErrors ( )

inline

Reset the error indicator.

See also: gotErrors()

◆ setReportPrefix()

void ts::Report::setReportPrefix ( const UString & prefix )

inline

Set the prefix to display before each message.

Parameters

[in] prefix The prefix to prepend to all messages.

◆ reportPrefix()

UString ts::Report::reportPrefix ( ) const

inline

Get the current prefix to display.

Returns: The current prefix to display.

◆ delegateReport()

Report * ts::Report::delegateReport ( Report * report )

Delegate message logging to another report object.

Parameters

[in] report New report object to which messages are delegated. Use nullptr to remove the delegation and return to normal logging.

Returns: Previous delegate report, return a null pointer if there was no previous delegate.

◆ debug() [1/5]

bool ts::Report::debug ( ) const

inline

Check if debugging is active.

Returns: True if current reporting level is Debug or higher.

◆ verbose() [1/5]

bool ts::Report::verbose ( ) const

inline

Check if verbose reporting is active.

Returns: True if current reporting level is Verbose or higher.

◆ log() [1/3]

void ts::Report::log	(	int	severity,
		const UString &	msg
	)

Report a message with an explicit severity.

Parameters

[in]	severity	Message severity.
[in]	msg	Message line.

◆ log() [2/3]

template<class... Args>

void ts::Report::log	(	int	severity,
		const UChar *	fmt,
		Args &&...	args
	)

inline

Report a message with an explicit severity and a printf-like interface.

Parameters

[in]	severity	Message severity.
[in]	fmt	Format string with embedded '%' sequences.
[in]	args	List of arguments to substitute in the format string.

See also: UString::format()

◆ log() [3/3]

template<class... Args>

void ts::Report::log	(	int	severity,
		const UString &	fmt,
		Args &&...	args
	)

inline

Report a message with an explicit severity and a printf-like interface.

Parameters

[in]	severity	Message severity.
[in]	fmt	Format string with embedded '%' sequences.
[in]	args	List of arguments to substitute in the format string.

See also: UString::format()

◆ fatal() [1/4]

void ts::Report::fatal ( const UChar * msg )

inline

Report a fatal error message.

Parameters

[in] msg Message line.

◆ fatal() [2/4]

void ts::Report::fatal ( const UString & msg )

inline

Report a fatal error message.

Parameters

[in] msg Message line.

◆ fatal() [3/4]

template<class... Args>

void ts::Report::fatal	(	const UChar *	fmt,
		Args &&...	args
	)

inline

Report a fatal error message with a printf-like interface.

Parameters

[in]	fmt	Format string with embedded '%' sequences.
[in]	args	List of arguments to substitute in the format string.

See also: UString::format()

◆ fatal() [4/4]

template<class... Args>

void ts::Report::fatal	(	const UString &	fmt,
		Args &&...	args
	)

inline

Report a fatal error message with a printf-like interface.

Parameters

[in]	fmt	Format string with embedded '%' sequences.
[in]	args	List of arguments to substitute in the format string.

See also: UString::format()

◆ severe() [1/4]

void ts::Report::severe ( const UChar * msg )

inline

Report a severe error message.

Parameters

[in] msg Message line.

◆ severe() [2/4]

void ts::Report::severe ( const UString & msg )

inline

Report a severe error message.

Parameters

[in] msg Message line.

◆ severe() [3/4]

template<class... Args>

void ts::Report::severe	(	const UChar *	fmt,
		Args &&...	args
	)

inline

Report a severe error message with a printf-like interface.

Parameters

[in]	fmt	Format string with embedded '%' sequences.
[in]	args	List of arguments to substitute in the format string.

See also: UString::format()

◆ severe() [4/4]

template<class... Args>

void ts::Report::severe	(	const UString &	fmt,
		Args &&...	args
	)

inline

Report a severe error message with a printf-like interface.

Parameters

[in]	fmt	Format string with embedded '%' sequences.
[in]	args	List of arguments to substitute in the format string.

See also: UString::format()

◆ error() [1/4]

void ts::Report::error ( const UChar * msg )

inline

Report an error message.

Parameters

[in] msg Message line.

◆ error() [2/4]

void ts::Report::error ( const UString & msg )

inline

Report an error message.

Parameters

[in] msg Message line.

◆ error() [3/4]

template<class... Args>

void ts::Report::error	(	const UChar *	fmt,
		Args &&...	args
	)

inline

Report an error message with a printf-like interface.

Parameters

[in]	fmt	Format string with embedded '%' sequences.
[in]	args	List of arguments to substitute in the format string.

See also: UString::format()

◆ error() [4/4]

template<class... Args>

void ts::Report::error	(	const UString &	fmt,
		Args &&...	args
	)

inline

Report an error message with a printf-like interface.

Parameters

[in]	fmt	Format string with embedded '%' sequences.
[in]	args	List of arguments to substitute in the format string.

See also: UString::format()

◆ warning() [1/4]

void ts::Report::warning ( const UChar * msg )

inline

Report a warning error message.

Parameters

[in] msg Message line.

◆ warning() [2/4]

void ts::Report::warning ( const UString & msg )

inline

Report a warning error message.

Parameters

[in] msg Message line.

◆ warning() [3/4]

template<class... Args>

void ts::Report::warning	(	const UChar *	fmt,
		Args &&...	args
	)

inline

Report a warning message with a printf-like interface.

Parameters

[in]	fmt	Format string with embedded '%' sequences.
[in]	args	List of arguments to substitute in the format string.

See also: UString::format()

◆ warning() [4/4]

template<class... Args>

void ts::Report::warning	(	const UString &	fmt,
		Args &&...	args
	)

inline

Report a warning message with a printf-like interface.

Parameters

[in]	fmt	Format string with embedded '%' sequences.
[in]	args	List of arguments to substitute in the format string.

See also: UString::format()

◆ info() [1/4]

void ts::Report::info ( const UChar * msg )

inline

Report an informational message.

Parameters

[in] msg Message line.

◆ info() [2/4]

void ts::Report::info ( const UString & msg )

inline

Report an informational message.

Parameters

[in] msg Message line.

◆ info() [3/4]

template<class... Args>

void ts::Report::info	(	const UChar *	fmt,
		Args &&...	args
	)

inline

Report an informational message with a printf-like interface.

Parameters

[in]	fmt	Format string with embedded '%' sequences.
[in]	args	List of arguments to substitute in the format string.

See also: UString::format()

◆ info() [4/4]

template<class... Args>

void ts::Report::info	(	const UString &	fmt,
		Args &&...	args
	)

inline

Report an informational message with a printf-like interface.

Parameters

[in]	fmt	Format string with embedded '%' sequences.
[in]	args	List of arguments to substitute in the format string.

See also: UString::format()

◆ verbose() [2/5]

void ts::Report::verbose ( const UChar * msg )

inline

Report a verbose message.

Parameters

[in] msg Message line.

◆ verbose() [3/5]

void ts::Report::verbose ( const UString & msg )

inline

Report a verbose message.

Parameters

[in] msg Message line.

◆ verbose() [4/5]

template<class... Args>

void ts::Report::verbose	(	const UChar *	fmt,
		Args &&...	args
	)

inline

Report a verbose message with a printf-like interface.

Parameters

[in]	fmt	Format string with embedded '%' sequences.
[in]	args	List of arguments to substitute in the format string.

See also: UString::format()

◆ verbose() [5/5]

template<class... Args>

void ts::Report::verbose	(	const UString &	fmt,
		Args &&...	args
	)

inline

Report a verbose message with a printf-like interface.

Parameters

[in]	fmt	Format string with embedded '%' sequences.
[in]	args	List of arguments to substitute in the format string.

See also: UString::format()

◆ debug() [2/5]

void ts::Report::debug ( const UChar * msg )

inline

Report a debug message.

Parameters

[in] msg Message line.

◆ debug() [3/5]

void ts::Report::debug ( const UString & msg )

inline

Report a debug message.

Parameters

[in] msg Message line.

◆ debug() [4/5]

template<class... Args>

void ts::Report::debug	(	const UChar *	fmt,
		Args &&...	args
	)

inline

Report a debug message with a printf-like interface.

Parameters

[in]	fmt	Format string with embedded '%' sequences.
[in]	args	List of arguments to substitute in the format string.

See also: UString::format()

◆ debug() [5/5]

template<class... Args>

void ts::Report::debug	(	const UString &	fmt,
		Args &&...	args
	)

inline

Report a debug message with a printf-like interface.

Parameters

[in]	fmt	Format string with embedded '%' sequences.
[in]	args	List of arguments to substitute in the format string.

See also: UString::format()

◆ writeLog()

virtual void ts::Report::writeLog	(	int	severity,
		const UString &	msg
	)

protectedvirtual

Actual message reporting method.

The method is called only when a message passed the severity filter. It is not necessary to recheck the maximum severity inside the method. By default, does nothing.

Parameters

[in]	severity	Message severity.
[in]	msg	Message text.

Reimplemented in ts::Args, ts::ReportBuffer< SAFETY >, ts::ReportFile< SAFETY >, ts::TelnetConnection, ts::CerrReport, and ts::NullReport.

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

tsReport.h

Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ Report() [1/2]

◆ Report() [2/2]

◆ ~Report()

Member Function Documentation

◆ setMaxSeverity()

◆ raiseMaxSeverity()

◆ maxSeverity()

◆ gotErrors()

◆ resetErrors()

◆ setReportPrefix()

◆ reportPrefix()

◆ delegateReport()

◆ debug() [1/5]

◆ verbose() [1/5]

◆ log() [1/3]

◆ log() [2/3]

◆ log() [3/3]

◆ fatal() [1/4]

◆ fatal() [2/4]

◆ fatal() [3/4]

◆ fatal() [4/4]

◆ severe() [1/4]

◆ severe() [2/4]

◆ severe() [3/4]

◆ severe() [4/4]

◆ error() [1/4]

◆ error() [2/4]

◆ error() [3/4]

◆ error() [4/4]

◆ warning() [1/4]

◆ warning() [2/4]

◆ warning() [3/4]

◆ warning() [4/4]

◆ info() [1/4]

◆ info() [2/4]

◆ info() [3/4]

◆ info() [4/4]

◆ verbose() [2/5]

◆ verbose() [3/5]

◆ verbose() [4/5]

◆ verbose() [5/5]

◆ debug() [2/5]

◆ debug() [3/5]

◆ debug() [4/5]

◆ debug() [5/5]

◆ writeLog()