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 plLog::SetCustomPrintFunction.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

static void	BroadcastLoggingEvent (plLogInterface *pInterface, plLogMsgType::Enum type, plStringView 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 plLog::Print.

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

static void	GenerateFormattedTimestamp (TimestampMode mode, plStringBuilder &ref_sTimestampOut)

Friends
class	plLogBlock

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 plLog::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 timplone indicator) is added. Ex: [13:40:30.345] Log message.

Member Function Documentation

◆ Debug() [1/2]

static void plLog::Debug	(	plLogInterface *	pInterface,
		const plFormatString &	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 plLog::Debug	(	plStringView	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 plLog::Dev	(	plLogInterface *	pInterface,
		const plFormatString &	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 plLog::Dev	(	plStringView	sFormat,
		ARGS &&...	args )

inlinestatic

Status information that is nice to have during development.

This function is compiled out in non-development builds.

◆ Flush()

bool plLog::Flush	(	plUInt32	uiNumNewMsgThreshold = 0,
		plTime	timeIntervalThreshold = plTime::MakeFromSeconds(10),
		plLogInterface *	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 plLogInterface 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 plLog::OsMessageBox ( const plFormatString & 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 plLog::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 plLog::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 plFormatString syntax.

See also: plLog::Print

◆ SetThreadLocalLogSystem()

void plLog::SetThreadLocalLogSystem ( plLogInterface * pInterface )

static

Allows to change which logging system is used by default on the current thread. If nothing is set, plGlobalLog 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:

Code/Engine/Foundation/Logging/Log.h
Code/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()