Logger¶

The logger class.

Inherited by the following classes: SparkyStudios::Audio::Amplitude::ConsoleLogger, SparkyStudios::Audio::Amplitude::FileLogger, SparkyStudios::Audio::Amplitude::LogcatLogger, SparkyStudios::Audio::Amplitude::NSLogger, SparkyStudios::Audio::Amplitude::NullLogger

Detailed Description¶

Base class used to perform logging. Implementations of this class can display or store log messages wherever they are needed.

Messages logged from the audio thread (see Logger::ScopedAudioThread) are never written there: they are copied into a lock-free queue, and written by the next Flush(), which the engine calls once per frame. Messages logged from any other thread are written at once, after the ones still queued, so the order is kept.

Warning:

The global logger is meant to be installed once during engine setup. It is not meant to be swapped, or destroyed while the engine runs. The installed logger must be kept alive until the engine is deinitialized.

Classes¶

Type	Name
class	ScopedAudioThread Marks the calling thread as an audio thread while it is alive.

Public Static Attributes¶

Type	Name
AmSize	kMaxQueuedMessageLength = `256` The longest message, in characters, kept when it is logged from an audio thread. A longer one is cut, and ends with "..." to show it.

Public Functions¶

Type	Name
void	Critical (const char * file, int line, const AmString & message) Logs a critical message.
void	Debug (const char * file, int line, const AmString & message) Logs a debug message.
void	Error (const char * file, int line, const AmString & message) Logs an error message.
void	Flush () Writes the messages queued from the audio thread.
void	Info (const char * file, int line, const AmString & message) Logs an informational message.
	Logger () Creates the logger.
void	Success (const char * file, int line, const AmString & message) Logs a success message.
void	Warning (const char * file, int line, const AmString & message) Logs a warning message.
void	Write (eLogMessageLevel level, const char * file, int line, const char * message, AmSize length) Logs a message with this logger.
virtual	~Logger () Destroys the logger, and unregisters it if it is the global one.

Public Static Functions¶

Type	Name
void	Emit (eLogMessageLevel level, const char * file, int line, const char * message, AmSize length) Logs a message with the global logger, if there is one.
Logger *	GetLogger () Gets the logger instance to use when calling `amLogger` .
void	SetLogger (Logger * loggerInstance) Sets the logger instance to use when calling `amLogger` .

Protected Functions¶

Type	Name
virtual void	Log (eLogMessageLevel level, const char * file, int line, const AmString & message) = 0 Logs a message with the given level.

Public Static Attributes Documentation¶

kMaxQueuedMessageLength

The longest message, in characters, kept when it is logged from an audio thread. A longer one is cut, and ends with "..." to show it.

AmSize SparkyStudios::Audio::Amplitude::Logger::kMaxQueuedMessageLength;

Public Functions Documentation¶

Critical

Logs a critical message.

void Amplitude::Logger::Critical (
    const char * file,
    int line,
    const AmString & message
)

Parameters:

file The file where the message was logged.
line The line where the message was logged.
message The message to log.

Debug

Logs a debug message.

void Amplitude::Logger::Debug (
    const char * file,
    int line,
    const AmString & message
)

Parameters:

file The file where the message was logged.
line The line where the message was logged.
message The message to log.

Error

Logs an error message.

void Amplitude::Logger::Error (
    const char * file,
    int line,
    const AmString & message
)

Parameters:

file The file where the message was logged.
line The line where the message was logged.
message The message to log.

Flush

Writes the messages queued from the audio thread.

void Amplitude::Logger::Flush ()

Safe to call from any thread but an audio thread, and from several at once: writes are serialized. If the queue overflowed, one warning reports how many messages were dropped.

Info

Logs an informational message.

void Amplitude::Logger::Info (
    const char * file,
    int line,
    const AmString & message
)

Parameters:

file The file where the message was logged.
line The line where the message was logged.
message The message to log.

Logger

Creates the logger.

Amplitude::Logger::Logger ()

Success

Logs a success message.

void Amplitude::Logger::Success (
    const char * file,
    int line,
    const AmString & message
)

Parameters:

file The file where the message was logged.
line The line where the message was logged.
message The message to log.

Warning

Logs a warning message.

void Amplitude::Logger::Warning (
    const char * file,
    int line,
    const AmString & message
)

Parameters:

file The file where the message was logged.
line The line where the message was logged.
message The message to log.

Write

Logs a message with this logger.

void Amplitude::Logger::Write (
    eLogMessageLevel level,
    const char * file,
    int line,
    const char * message,
    AmSize length
)

Prefer the amLog macros. From an audio thread, the message is queued (and cut to kMaxQueuedMessageLength characters, ending with "..."); from any other thread, it is written at once.

Parameters:

level The level of the log message.
file The file where the message was logged.
line The line where the message was logged.
message The message, not necessarily null-terminated.
length The length of message.

~Logger

Destroys the logger, and unregisters it if it is the global one.

virtual Amplitude::Logger::~Logger ()

Messages still queued are lost: a logger that writes somewhere should call Flush() in its own destructor, while it can still write.

Public Static Functions Documentation¶

Emit

Logs a message with the global logger, if there is one.

static void Amplitude::Logger::Emit (
    eLogMessageLevel level,
    const char * file,
    int line,
    const char * message,
    AmSize length
)

This is what the amLog macros call: the global logger is read once, so it cannot go away between the test and the call.

Parameters:

level The level of the log message.
file The file where the message was logged.
line The line where the message was logged.
message The message, not necessarily null-terminated.
length The length of message.

GetLogger

Gets the logger instance to use when calling amLogger .

static Logger * Amplitude::Logger::GetLogger ()

Returns:

The logger instance.

SetLogger

Sets the logger instance to use when calling amLogger .

static void Amplitude::Logger::SetLogger (
    Logger * loggerInstance
)

Messages still queued on the logger being replaced are written first.

Call it before initializing the engine, and again (with the previous logger, or nullptr) only after the engine is deinitialized.

Parameters:

loggerInstance The logger instance.

Protected Functions Documentation¶

Log

Logs a message with the given level.

virtual void Amplitude::Logger::Log (
    eLogMessageLevel level,
    const char * file,
    int line,
    const AmString & message
) = 0

Parameters:

level The level of the log message.
file The file where the message was logged.
line The line where the message was logged.
message The message to log.

The documentation for this class was generated from the following file: include/SparkyStudios/Audio/Amplitude/IO/Log.h