Static class that allows to write out logging information. More...

#include <Log.h>

Public Types
enum class	TimestampMode { None = 0 , Numeric = 1 , Textual = 2 , TimeOnly = 3 }
	This enum is used in context of outputting timestamp information to indicate a formatting for said timestamps. More...

using	PrintFunction = void ()(const char szText)
	Signature of the custom print function used by xiiLog::SetCustomPrintFunction.

Static Public Member Functions
static void	SetThreadLocalLogSystem (xiiLogInterface *pInterface)
	Allows to change which logging system is used by default on the current thread. If nothing is set, xiiGlobalLog is used.

static xiiLogInterface *	GetThreadLocalLogSystem ()
	Returns the currently set default logging system, or a thread local instance of xiiGlobalLog, if nothing else was set.

static void	SetDefaultLogLevel (xiiLogMsgType::Enum logLevel)
	Sets the default log level which is used by all xiiLogInterface's that have their log level set to xiiLogMsgType::GlobalDefault.

static xiiLogMsgType::Enum	GetDefaultLogLevel ()
	Returns the currently set default log level.

static void	Error (xiiLogInterface *pInterface, const xiiFormatString &string)
	An error that needs to be fixed as soon as possible.

template<typename... ARGS>
static void	Error (xiiStringView sFormat, ARGS &&... args)
	An error that needs to be fixed as soon as possible.

template<typename... ARGS>
static void	Error (xiiLogInterface *pInterface, xiiStringView sFormat, ARGS &&... args)
	Overload of Error() to output messages to a specific log.

static void	SeriousWarning (xiiLogInterface *pInterface, const xiiFormatString &string)
	Not an error, but definitely a big problem, that should be looked into very soon.

template<typename... ARGS>
static void	SeriousWarning (xiiStringView sFormat, ARGS &&... args)
	Not an error, but definitely a big problem, that should be looked into very soon.

template<typename... ARGS>
static void	SeriousWarning (xiiLogInterface *pInterface, xiiStringView sFormat, ARGS &&... args)
	Overload of SeriousWarning() to output messages to a specific log.

static void	Warning (xiiLogInterface *pInterface, const xiiFormatString &string)
	A potential problem or a performance warning. Might be possible to ignore it.

template<typename... ARGS>
static void	Warning (xiiStringView sFormat, ARGS &&... args)
	A potential problem or a performance warning. Might be possible to ignore it.

template<typename... ARGS>
static void	Warning (xiiLogInterface *pInterface, xiiStringView sFormat, ARGS &&... args)
	Overload of Warning() to output messages to a specific log.

static void	Success (xiiLogInterface *pInterface, const xiiFormatString &string)
	Status information that something was completed successfully.

template<typename... ARGS>
static void	Success (xiiStringView sFormat, ARGS &&... args)
	Status information that something was completed successfully.

template<typename... ARGS>
static void	Success (xiiLogInterface *pInterface, xiiStringView sFormat, ARGS &&... args)
	Overload of Success() to output messages to a specific log.

static void	Info (xiiLogInterface *pInterface, const xiiFormatString &string)
	Status information that is important.

template<typename... ARGS>
static void	Info (xiiStringView sFormat, ARGS &&... args)
	Status information that is important.

template<typename... ARGS>
static void	Info (xiiLogInterface *pInterface, xiiStringView sFormat, ARGS &&... args)
	Overload of Info() to output messages to a specific log.

static void	Dev (xiiLogInterface *pInterface, const xiiFormatString &string)
	Status information that is nice to have during development.

template<typename... ARGS>
static void	Dev (xiiStringView sFormat, ARGS &&... args)
	Status information that is nice to have during development.

template<typename... ARGS>
static void	Dev (xiiLogInterface *pInterface, xiiStringView sFormat, ARGS &&... args)
	Overload of Dev() to output messages to a specific log.

static void	Debug (xiiLogInterface *pInterface, const xiiFormatString &string)
	Status information during debugging. Very verbose. Usually only temporarily added to the code.

template<typename... ARGS>
static void	Debug (xiiStringView sFormat, ARGS &&... args)
	Status information during debugging. Very verbose. Usually only temporarily added to the code.

template<typename... ARGS>
static void	Debug (xiiLogInterface *pInterface, xiiStringView sFormat, ARGS &&... args)
	Overload of Debug() to output messages to a specific log.

static bool	Flush (xiiUInt32 uiNumNewMsgThreshold=0, xiiTime timeIntervalThreshold=xiiTime::MakeFromSeconds(10), xiiLogInterface *pInterface=GetThreadLocalLogSystem())
	Instructs log writers to flush their caches, to ensure all log output (even non-critical information) is written.

static void	BroadcastLoggingEvent (xiiLogInterface *pInterface, xiiLogMsgType::Enum type, xiiStringView sString)
	Usually called internally by the other log functions, but can be called directly, if the message type is already known. pInterface must be != nullptr.

static void	Print (const char *szText)
	Calls low-level OS functionality to print a string to the typical outputs, e.g. printf and OutputDebugString.

static void	Printf (const char *szFormat,...)
	Calls low-level OS functionality to print a string to the typical outputs. Forwards to Print.

static void	SetCustomPrintFunction (PrintFunction func)
	Sets a custom function that is called in addition to the default behavior of xiiLog::Print.

static void	OsMessageBox (const xiiFormatString &text)
	Shows a simple message box using the OS functionality.

static void	GenerateFormattedTimestamp (TimestampMode mode, xiiStringBuilder &ref_sTimestampOut)

Friends
class	xiiLogBlock

Detailed Description

Static class that allows to write out logging information.

This class takes logging information, prepares it and then broadcasts it to all interested code via the event interface. It does not write anything on disk or somewhere else, itself. Instead it allows to register custom log writers that can then write it to disk, to console, send it over a network or pop up a message box. Whatever suits the current situation. Since event handlers can be registered only temporarily, it is also possible to just gather all errors that occur during some operation and then unregister the event handler again.

Member Enumeration Documentation

◆ TimestampMode

enum class xiiLog::TimestampMode

strong

This enum is used in context of outputting timestamp information to indicate a formatting for said timestamps.

Enumerator
None	No timestamp will be added at all.
Numeric	A purely numeric timestamp will be added. Ex.: [2019-08-16 13:40:30.345 (UTC)] Log message.
Textual	A timestamp with textual fields will be added. Ex.: [2019 Aug 16 (Fri) 13:40:30.345 (UTC)] Log message.
TimeOnly	A short timestamp (time only, no timezone indicator) is added. Ex: [13:40:30.345] Log message.

Member Function Documentation

◆ Debug() [1/2]

static void xiiLog::Debug	(	xiiLogInterface *	pInterface,
		const xiiFormatString &	string )

static

Status information during debugging. Very verbose. Usually only temporarily added to the code.

This function is compiled out in non-debug builds.

◆ Debug() [2/2]

template<typename... ARGS>

static void xiiLog::Debug	(	xiiStringView	sFormat,
		ARGS &&...	args )

inlinestatic

Status information during debugging. Very verbose. Usually only temporarily added to the code.

This function is compiled out in non-debug builds.

◆ Dev() [1/2]

static void xiiLog::Dev	(	xiiLogInterface *	pInterface,
		const xiiFormatString &	string )

static

Status information that is nice to have during development.

This function is compiled out in non-development builds.

◆ Dev() [2/2]

template<typename... ARGS>

static void xiiLog::Dev	(	xiiStringView	sFormat,
		ARGS &&...	args )

inlinestatic

Status information that is nice to have during development.

This function is compiled out in non-development builds.

◆ Flush()

bool xiiLog::Flush	(	xiiUInt32	uiNumNewMsgThreshold = 0,
		xiiTime	timeIntervalThreshold = xiiTime::MakeFromSeconds(10),
		xiiLogInterface *	pInterface = GetThreadLocalLogSystem() )

static

Instructs log writers to flush their caches, to ensure all log output (even non-critical information) is written.

On some log writers this has no effect. Do not call this too frequently as it incurs a performance penalty.

Parameters

uiNumNewMsgThreshold	If this is set to a number larger than zero, the flush may be ignored if the given xiiLogInterface has logged fewer than this many messages since the last flush.
timeIntervalThreshold	The flush may be ignored if less time has past than this, since the last flush.

If either enough messages have been logged, or the flush interval has been exceeded, the flush is executed. To force a flush, set uiNumNewMsgThreshold to zero. However, a flush is always ignored if not a single message was logged in between.

Returns: Returns true if the flush is executed.

◆ OsMessageBox()

void xiiLog::OsMessageBox ( const xiiFormatString & text )

static

Shows a simple message box using the OS functionality.

This should only be used for critical information that can't be conveyed in another way.

◆ Print()

void xiiLog::Print ( const char * szText )

static

Calls low-level OS functionality to print a string to the typical outputs, e.g. printf and OutputDebugString.

Use this function to log unrecoverable errors like asserts, crash handlers etc. This function is meant for short term debugging when actual printing to the console is desired. Code using it should be temporary. This function flushes the output immediately, to ensure output is never lost during a crash. Consequently it has a high performance overhead.

◆ Printf()

void xiiLog::Printf	(	const char *	szFormat,
			... )

static

Calls low-level OS functionality to print a string to the typical outputs. Forwards to Print.

Note: This function uses actual printf formatting, not xiiFormatString syntax.

See also: xiiLog::Print

◆ SetThreadLocalLogSystem()

void xiiLog::SetThreadLocalLogSystem ( xiiLogInterface * pInterface )

static

Allows to change which logging system is used by default on the current thread. If nothing is set, xiiGlobalLog is used.

Replacing the log system on a thread does not delete the previous system, so it can be reinstated later again. This can be used to temporarily route all logging to a custom system.

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

/home/runner/work/XII/XII/Source/Engine/Foundation/Logging/Log.h
/home/runner/work/XII/XII/Source/Engine/Foundation/Logging/Implementation/Log.cpp

Public Types

Static Public Member Functions

Friends

Detailed Description

Member Enumeration Documentation

◆ TimestampMode

Member Function Documentation

◆ Debug() [1/2]

◆ Debug() [2/2]

◆ Dev() [1/2]

◆ Dev() [2/2]

◆ Flush()

◆ OsMessageBox()

◆ Print()

◆ Printf()

◆ SetThreadLocalLogSystem()