Cogs::Logging Namespace Reference

Contains logging functionality for the Cogs native library. More...

Classes
struct	BacktraceState
class	ConsoleLogger
	Console logger that supports splitting log lines between stdout and stderr according to severity. More...
class	Consumer
	Consumer is the base class for objects that want to consume log messages through the LogManager. More...
class	FileLogger
class	Log
	Log implementation class. More...
class	RedirectedLogger
	RedirectedLogger is a message consumer that forwards any incoming message to the callback functions registered with it. More...
class	StructuredLogger
class	ThrottledConsumer
	ThrottledConsumer is a log message consumer that attempts to throttle messages to reduce log spam. More...

Typedefs
using	LoggerCallback = void(const char *message, const char *source, int category)
	Definition of logging callback.
using	FileLineLoggerCallback = void(const char *file, int line, const char *message, const char *source, int category)
	Definition of logging callback including file and line information.

Enumerations
enum class	Category {   Trace = 0 , Debug , Info , Warning ,   Error , Fatal }
	Logging categories used to filter log messages. More...
enum	ErrorGroup : uint32_t {   Unspecified , FirstFoundation = 0x00100000 , FoundationIO = 0x00110000 , FoundationModule = 0x00120000 ,   FoundationNetwork = 0x00130000 , FirstRendering = 0x01000000 , FirstCore = 0x10000000 , FirstDesktop = 0x20000000 ,   FirstTerrain = 0x30000000 , FirstCoreExtension = 0x40000000 , FirstExternalExtension = 0x90000000 , FirstThirdParty = 0xB0000000 ,   NvidiaCUDA = 0xB0010000 , NvidiaNvEnc = 0xB0020000 , FirstApplication = 0xC0000000 }
	ErrorGroup values define the top 16-bits of module specific error numbers. More...

Functions
void	consumeMessage (const char *source, Category category, uint32_t errorNumber, const char *filename, int lineNumber, _Printf_format_string_ const char *fmt, va_list argptr)
	Forwards the incoming log message to all interested consumers.
_Unwind_Reason_Code	unwindCallback (struct _Unwind_Context *context, void *arg)
void	printFrame (void *address)
void	signalHandler (int sig)
void COGSFOUNDATION_API	setLoggerCategory (Category category)
	Sets the default category level for loggers created after this call.
void COGSFOUNDATION_API	updateLoggerCategory (Category category)
void	updateMinimumCategory ()
	Internal.
void COGSFOUNDATION_API	enableUnhandledExceptionLogging ()
	Enable catching and logging of hardware exceptions (crashes) before exiting. (Windows only - for now.)
void COGSFOUNDATION_API	registerConsumer (Consumer *consumer)
	Registers the specified consumer with the LogManager.
void COGSFOUNDATION_API	unregisterConsumer (Consumer *consumer)
	Removes the specified consumer from the LogManager.
void COGSFOUNDATION_API	log (const char *message, const char *source, const Category category, uint32_t errorNumber)
	Logs the given message with source and category.
void COGSFOUNDATION_API	log (const char *source, const Category category, uint32_t errorNumber, _Printf_format_string_ const char *fmt,...) VALIDATE_ARGS(4)
	Logs the given formatted string (using printf formatting rules) with source and category.
void COGSFOUNDATION_API	logFileLine (const char *file, const int line, const char *source, const Category category, uint32_t errorNumber, _Printf_format_string_ const char *fmt,...) VALIDATE_ARGS(6)
	Logs the given formatted string (using printf formatting rules) with file/line information and source and category.
void COGSFOUNDATION_API	logArgs (const char *source, const Category category, uint32_t errorNumber, const char *fmt, va_list args)
	Log the given formatted string with argument list.
void COGSFOUNDATION_API	logFileLineArgs (const char *file, const int line, const char *source, const Category category, uint32_t errorNumber, const char *fmt, va_list args)
	Log the given formatted string with argument list and file/line information.
Category COGSFOUNDATION_API	parseCategoryString (const StringView category)
	Utility function that takes a loglevel name as a string and returns the corresponding log level enum value.
bool COGSFOUNDATION_API	isErrorGroup (uint32_t errorNumber, ErrorGroup group)
	Tests whether the specified error number is from the given group.
template<size_t LEN>
constexpr Log	getLogger (const char(&name)[LEN]) noexcept
std::string COGSFOUNDATION_API	getOsNameAndVersion ()

Detailed Description

Contains logging functionality for the Cogs native library.

Typedef Documentation

FileLineLoggerCallback

using Cogs::Logging::FileLineLoggerCallback = typedef void(const char* file, int line, const char* message, const char* source, int category)

Definition of logging callback including file and line information.

LoggerCallback

using Cogs::Logging::LoggerCallback = typedef void(const char* message, const char* source, int category)

Definition of logging callback.

Enumeration Type Documentation

Category

enum class Cogs::Logging::Category

strong

Logging categories used to filter log messages.

Enumerator
Trace
Debug
Info
Warning
Error
Fatal

ErrorGroup

enum Cogs::Logging::ErrorGroup : uint32_t

ErrorGroup values define the top 16-bits of module specific error numbers.

Subsystems should add their own group value below (in the appropriate section) and define their own error number enums with the value from below used to initialise their first value. These can then be registered with the type system for inclusion in generated code. Error numbers can be passed directly to log functions, or as the second argument to the LOG_WARNING_ERRNO, LOG_ERROR_ERRNO, and LOG_FATAL_ERRNO macros.

Enumerator
Unspecified	The default error number for legacy logger usage.
FirstFoundation
FoundationIO
FoundationModule
FoundationNetwork
FirstRendering
FirstCore
FirstDesktop
FirstTerrain
FirstCoreExtension
FirstExternalExtension
FirstThirdParty
NvidiaCUDA	CUDA errors are wrapped in this group. (ORed with this value.)
NvidiaNvEnc	Error values from NvEnc are in this group. (ORed with this value.)
FirstApplication

Function Documentation

consumeMessage()

void Cogs::Logging::consumeMessage	(	const char *	source,
		Category	category,
		uint32_t	errorNumber,
		const char *	filename,
		int	lineNumber,
		_Printf_format_string_ const char *	fmt,
		va_list	argptr
	)

Forwards the incoming log message to all interested consumers.

*============================================================================================

Referenced by log(), logArgs(), logFileLine(), and logFileLineArgs().

enableUnhandledExceptionLogging()

void Cogs::Logging::enableUnhandledExceptionLogging

(

)

Enable catching and logging of hardware exceptions (crashes) before exiting. (Windows only - for now.)

On Windows, enable unhandled hardware exceptions to be included in the log.

*============================================================================================

References signalHandler().

getLogger()

template<size_t LEN>

constexpr Log Cogs::Logging::getLogger ( const char(&)  name[LEN] )

constexprnoexcept

Get a logger with the given name. The name must be a string literal and is used as "source" in log messages.

getOsNameAndVersion()

std::string Cogs::Logging::getOsNameAndVersion

(

)

isErrorGroup()

bool Cogs::Logging::isErrorGroup	(	uint32_t	errorNumber,
		ErrorGroup	group
	)

Tests whether the specified error number is from the given group.

log() [1/2]

void Cogs::Logging::log	(	const char *	message,
		const char *	source,
		const Category	category,
		uint32_t	errorNumber
	)

Logs the given message with source and category.

References consumeMessage().

log() [2/2]

void Cogs::Logging::log	(	const char *	source,
		const Category	category,
		uint32_t	errorNumber,
		_Printf_format_string_ const char *	fmt,
			...
	)

Logs the given formatted string (using printf formatting rules) with source and category.

References consumeMessage().

logArgs()

void Cogs::Logging::logArgs	(	const char *	source,
		const Category	category,
		uint32_t	errorNumber,
		const char *	fmt,
		va_list	args
	)

Log the given formatted string with argument list.

References consumeMessage().

Referenced by Cogs::Logging::Log::log().

logFileLine()

void Cogs::Logging::logFileLine	(	const char *	file,
		const int	line,
		const char *	source,
		const Category	category,
		uint32_t	errorNumber,
		_Printf_format_string_ const char *	fmt,
			...
	)

Logs the given formatted string (using printf formatting rules) with file/line information and source and category.

References consumeMessage().

logFileLineArgs()

void Cogs::Logging::logFileLineArgs	(	const char *	file,
		const int	line,
		const char *	source,
		const Category	category,
		uint32_t	errorNumber,
		const char *	fmt,
		va_list	args
	)

Log the given formatted string with argument list and file/line information.

References consumeMessage().

Referenced by Cogs::Logging::Log::logFileLine().

parseCategoryString()

Cogs::Logging::Category Cogs::Logging::parseCategoryString

(

const StringView

category

)

Utility function that takes a loglevel name as a string and returns the corresponding log level enum value.

Converts a category string into a Category value.

*============================================================================================

References Cogs::hash(), and Cogs::hashLowercase().

printFrame()

void Cogs::Logging::printFrame

(

void *

address

)

Referenced by signalHandler().

registerConsumer()

void Cogs::Logging::registerConsumer

(

Consumer *

consumer

)

Registers the specified consumer with the LogManager.

Once registered a consumer will receive all log messages with a category value above its currently set minimum.

Consumers register themselves automatically with the system from their constructors.

Referenced by Cogs::Logging::Consumer::Consumer().

setLoggerCategory()

void Cogs::Logging::setLoggerCategory

(

Category

category

)

Sets the default category level for loggers created after this call.

Sets the default category level for all future consumers.

This function exists merely for API compatibility with the older single-consumer LogManager. *============================================================================================

signalHandler()

void Cogs::Logging::signalHandler

(

int

sig

)

References Cogs::Logging::BacktraceState::current, printFrame(), and unwindCallback().

Referenced by enableUnhandledExceptionLogging().

unregisterConsumer()

void Cogs::Logging::unregisterConsumer

(

Consumer *

consumer

)

Removes the specified consumer from the LogManager.

Consumers unregister themseves automatically during destruction.

Referenced by Cogs::Logging::Consumer::~Consumer().

unwindCallback()

_Unwind_Reason_Code Cogs::Logging::unwindCallback	(	struct _Unwind_Context *	context,
		void *	arg
	)

References Cogs::Logging::BacktraceState::current, and Cogs::Logging::BacktraceState::end.

Referenced by signalHandler().

updateLoggerCategory()

void Cogs::Logging::updateLoggerCategory

(

Category

category

)

Change logging category for existing and future loggers. Call from main thread. Typical usage to reduce catagory after initializing Cogs. Skip init spam, but keep later logs.

updateMinimumCategory()

void Cogs::Logging::updateMinimumCategory

(

)

Internal.

Updates the minimum category level of the LogManager.

This is a calculated minimum from all currently registered consumers and is used to quickly filter incoming messages if no consumer is interested in them. *============================================================================================

Referenced by Cogs::Logging::Consumer::setMinimumCategory(), and Cogs::Logging::Consumer::~Consumer().