A journalling class for debugging applications. More...

#include <journaller.h>

Public Member Functions
void	cleanupThread ()
	Removes stored information on the current thread after flushing all data. More...

JournalLogLevel	debugLevel () const

const XsString	filename () const
	Returns the filename of the used journal file. More...

void	flush ()
	Flush any data to disk. More...

JournalLogLevel	flushLevel () const

	Journaller (const XsString &pathfile, bool purge=true, JournalLogLevel initialLogLevel=JLL_Alert)
	Constructor. More...

void	log (JournalLogLevel level, const std::string &msg)
	Write a log message to the file if level is at least equal to the current log level. More...

JournalLogLevel	logLevel () const

bool	logLevel (JournalLogLevel level) const
	Compares a log/debug level with a set one. More...

void	moveLogFile (const XsString &pathfile, bool purge=true, bool eraseOld=true)
	Move the log file to the supplied path, keeping current contents intact. More...

void	moveLogs (Journaller *target, bool eraseOld=true)
	Copy the contents of the current log file to target. More...

void	setDebugLevel (JournalLogLevel level, bool writeLogLine=true)
	Set the log level for logging to debug output. More...

void	setFlushLevel (JournalLogLevel level, bool writeLogLine=true)
	Set level threshold for automatically flushing lines to disk. More...

void	setLogLevel (JournalLogLevel level, bool writeLogLine=true)
	Set the log level for logging to file. More...

void	setTag (const std::string &tag)
	Set a tag to be added before the log level tag in each log file. More...

void	setUseDateTime (bool yes)
	When setting the Date Time to yes, the timestamps are translated from unix timestamp into a redable date/time. More...

std::string	tag () const

void	writeCallstack (JournalLogLevel level)
	Write the current callstack to the file if level is at least equal to the current log level. More...

void	writeFileHeader (const std::string &appName)
	Write a header for the log file including some meta-data about the journaller. More...

void	writeLevel (JournalLogLevel level)
	Write the supplied log level to the file. More...

void	writeMessage (const std::string &msg)
	Write msg to the file without decoration or added newline. More...

void	writeTag ()
	Write the tag to the file. More...

void	writeThread ()
	Write the current time to the file. More...

void	writeTime ()
	Write the current time to the file. More...

	~Journaller ()
	Destructor, detaches from the logfile and closes it if this was the last reference. More...

Static Public Member Functions
static AbstractAdditionalLogger *	additionalLogger ()

static bool	hasAdditionalLogger ()

static void	setAdditionalLogger (AbstractAdditionalLogger *additionalLogger)
	Sets the additional logger. More...

static std::string	tagFromFilename (const std::string &fn)

Private Member Functions
void	flushLine ()
	Flush any data currently queued for logging to the file buffer. More...

void	init (XsString const &pathfile, bool purge)
	Initialize the Journaller by (re-)creating the internal journal file. More...

	Journaller (Journaller const &)=delete

Journaller &	operator= (Journaller const &)=delete

Private Attributes
std::string	m_appName

JournalLogLevel	m_debugLevel

std::shared_ptr< JournalFile >	m_file

JournalLogLevel	m_flushLevel

JournalLogLevel	m_level

std::string	m_tag

std::shared_ptr< JournalThreader >	m_threader

bool	m_useDateTime

Static Private Attributes
static AbstractAdditionalLogger *	m_additionalLogger = nullptr
	The optional additional logger. More...

Detailed Description

A journalling class for debugging applications.

Create a Journaller object in your application or dll main and share it among the source files of your application (ie by adding "extern Journaller* journal;" in the xscommon_config.h) Use the supplied logging macros if you want to be able to remove the logging lines at compile-time.

Multiple Journaller objects can use the same file

Definition at line 79 of file journaller.h.

Constructor & Destructor Documentation

◆ Journaller() [1/2]

Journaller::Journaller	(	const XsString &	pathfile,
		bool	purge = `true`,
		JournalLogLevel	initialLogLevel = `JLL_Alert`
	)

Constructor.

The constructor configures the object to use the specified file. If it is already open by another Journaller object, the existing file is reused and it will not be purged.

Parameters

pathfile	The (path+) filename of the logfile to use
purge	Whether to clear the logfile or append when opening the file (default true)
initialLogLevel	The initial log level to use (default JLL_Alert)

Definition at line 121 of file journaller.cpp.

◆ ~Journaller()

Journaller::~Journaller ( )

Destructor, detaches from the logfile and closes it if this was the last reference.

Definition at line 133 of file journaller.cpp.

◆ Journaller() [2/2]

Journaller::Journaller ( Journaller const & )

privatedelete

Member Function Documentation

◆ additionalLogger()

static AbstractAdditionalLogger* Journaller::additionalLogger ( )

inlinestatic

Returns: The additional logger

Definition at line 146 of file journaller.h.

◆ cleanupThread()

void Journaller::cleanupThread ( )

Removes stored information on the current thread after flushing all data.

Note: It is recommended to call this in the DllMain DLL_THREAD_DETACH section

Definition at line 491 of file journaller.cpp.

◆ debugLevel()

JournalLogLevel Journaller::debugLevel ( ) const

inline

Returns: The log level for logging to debug output

Definition at line 108 of file journaller.h.

◆ filename()

const XsString Journaller::filename ( ) const

Returns the filename of the used journal file.

Definition at line 363 of file journaller.cpp.

◆ flush()

void Journaller::flush ( )

Flush any data to disk.

Definition at line 308 of file journaller.cpp.

◆ flushLevel()

JournalLogLevel Journaller::flushLevel ( ) const

inline

Returns: The flush level

Definition at line 116 of file journaller.h.

◆ flushLine()

void Journaller::flushLine ( )

private

Flush any data currently queued for logging to the file buffer.

Definition at line 292 of file journaller.cpp.

◆ hasAdditionalLogger()

static bool Journaller::hasAdditionalLogger ( )

inlinestatic

Returns: True if it has an additional logger

Definition at line 140 of file journaller.h.

◆ init()

void Journaller::init	(	XsString const &	pathfile,
		bool	purge
	)

private

Initialize the Journaller by (re-)creating the internal journal file.

Definition at line 138 of file journaller.cpp.

◆ log()

void Journaller::log	(	JournalLogLevel	level,
		const std::string &	msg
	)

Write a log message to the file if level is at least equal to the current log level.

Parameters

level	The log level to use
msg	The message to log

This function decorates msg with the time and log level and appends a newline

Definition at line 201 of file journaller.cpp.

◆ logLevel() [1/2]

JournalLogLevel Journaller::logLevel ( ) const

inline

Returns: The log level for logging to file

Definition at line 91 of file journaller.h.

◆ logLevel() [2/2]

bool Journaller::logLevel ( JournalLogLevel level ) const

inline

Compares a log/debug level with a set one.

Parameters

level The log level to compare with

Returns: True if a set log/debug level is equal or higher than the compared one

Definition at line 100 of file journaller.h.

◆ moveLogFile()

void Journaller::moveLogFile	(	const XsString &	pathfile,
		bool	purge = `true`,
		bool	eraseOld = `true`
	)

Move the log file to the supplied path, keeping current contents intact.

Parameters

pathfile	The path of a file to change to
purge	If set to true (default) then it clears the log file that we changed to
eraseOld	If set to true (default) then the old log file will be removed

Definition at line 398 of file journaller.cpp.

◆ moveLogs()

void Journaller::moveLogs	(	Journaller *	target,
		bool	eraseOld = `true`
	)

Copy the contents of the current log file to target.

After copying the contents, the current log file is closed.

Parameters

target	The destination Journaller to write to
eraseOld	When true (default), the old log file is deleted

Definition at line 451 of file journaller.cpp.

◆ operator=()

Journaller& Journaller::operator= ( Journaller const & )

privatedelete

◆ setAdditionalLogger()

void Journaller::setAdditionalLogger ( AbstractAdditionalLogger * additionallogger )

static

Sets the additional logger.

Parameters

[in] additionallogger A pointer (may be null) to the additional logger. If additionalLogger is a null pointer, the current additionalLogger is removed.

Note: Journaller does NOT take ownership of the logger.

Definition at line 172 of file journaller.cpp.

◆ setDebugLevel()

void Journaller::setDebugLevel	(	JournalLogLevel	level,
		bool	writeLogLine = `true`
	)

Set the log level for logging to debug output.

Parameters

level	The log level to use
writeLogLine	If set to true then it writes a log line

Any log requests of a lower level will not be done

Definition at line 355 of file journaller.cpp.

◆ setFlushLevel()

void Journaller::setFlushLevel	(	JournalLogLevel	level,
		bool	writeLogLine = `true`
	)

Set level threshold for automatically flushing lines to disk.

Definition at line 318 of file journaller.cpp.

◆ setLogLevel()

void Journaller::setLogLevel	(	JournalLogLevel	level,
		bool	writeLogLine = `true`
	)

Set the log level for logging to file.

Parameters

level	The log level to use
writeLogLine	If set to true then it writes a log line

Any log requests of a lower level will not be done

Definition at line 343 of file journaller.cpp.

◆ setTag()

void Journaller::setTag ( const std::string & tag )

Set a tag to be added before the log level tag in each log file.

Definition at line 370 of file journaller.cpp.

◆ setUseDateTime()

void Journaller::setUseDateTime ( bool yes )

When setting the Date Time to yes, the timestamps are translated from unix timestamp into a redable date/time.

Parameters

yes	The boolean value to set

Note: the translation is not free, the recommended behaviour is to stick with the default unix timestamps

Definition at line 162 of file journaller.cpp.

◆ tag()

std::string Journaller::tag ( ) const

Returns: a tag that will be added before the log level tag in each log file.

On most platforms the default tag is an empty string, on Android it defaults to the filename without extension to be able to make full use of the logcat backend.

Override the tag using setTag, or overload this function.

Definition at line 382 of file journaller.cpp.

◆ tagFromFilename()

std::string Journaller::tagFromFilename ( const std::string & fn )

static

Returns: The tag string made from file name

This function is primarily useful on Android, where we always need a tag set.

Parameters

fn	The file name string

Definition at line 151 of file journaller.cpp.

◆ writeCallstack()

void Journaller::writeCallstack ( JournalLogLevel level )

Write the current callstack to the file if level is at least equal to the current log level.

Definition at line 327 of file journaller.cpp.

◆ writeFileHeader()

void Journaller::writeFileHeader ( const std::string & appName )

Write a header for the log file including some meta-data about the journaller.

Definition at line 190 of file journaller.cpp.

◆ writeLevel()

void Journaller::writeLevel ( JournalLogLevel level )

Write the supplied log level to the file.

Parameters

level The log level to set

Note: This does not actually CHANGE the log level of the line to the supplied value

Definition at line 265 of file journaller.cpp.

◆ writeMessage()

void Journaller::writeMessage ( const std::string & msg )

Write msg to the file without decoration or added newline.

Parameters

msg	The message to write

This function is also used to do the actual writing. It will only write the data to the outputs when the end of msg is a newline character, otherwise it will queue msg to be written later. If msg is empty, the currently queued data is written immediately

Definition at line 276 of file journaller.cpp.

◆ writeTag()

void Journaller::writeTag ( )

Write the tag to the file.

Definition at line 254 of file journaller.cpp.

◆ writeThread()

void Journaller::writeThread ( )

Write the current time to the file.

Definition at line 242 of file journaller.cpp.

◆ writeTime()

void Journaller::writeTime ( )

Write the current time to the file.

Definition at line 224 of file journaller.cpp.

Member Data Documentation

◆ m_additionalLogger

AbstractAdditionalLogger * Journaller::m_additionalLogger = nullptr

staticprivate

The optional additional logger.

Definition at line 169 of file journaller.h.

◆ m_appName

std::string Journaller::m_appName

private

Definition at line 161 of file journaller.h.

◆ m_debugLevel

JournalLogLevel Journaller::m_debugLevel

private

Definition at line 163 of file journaller.h.

◆ m_file

std::shared_ptr<JournalFile> Journaller::m_file

private

Definition at line 159 of file journaller.h.

◆ m_flushLevel

JournalLogLevel Journaller::m_flushLevel

private

Definition at line 164 of file journaller.h.

◆ m_level

JournalLogLevel Journaller::m_level

private

Definition at line 162 of file journaller.h.

◆ m_tag

std::string Journaller::m_tag

private

Definition at line 160 of file journaller.h.

◆ m_threader

std::shared_ptr<JournalThreader> Journaller::m_threader

private

Definition at line 165 of file journaller.h.

◆ m_useDateTime

bool Journaller::m_useDateTime

private

Definition at line 167 of file journaller.h.

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

Public Member Functions

Static Public Member Functions

Private Member Functions

Private Attributes

Static Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ Journaller() [1/2]

◆ ~Journaller()

◆ Journaller() [2/2]

Member Function Documentation

◆ additionalLogger()

◆ cleanupThread()

◆ debugLevel()

◆ filename()

◆ flush()

◆ flushLevel()

◆ flushLine()

◆ hasAdditionalLogger()

◆ init()

◆ log()

◆ logLevel() [1/2]

◆ logLevel() [2/2]

◆ moveLogFile()

◆ moveLogs()

◆ operator=()

◆ setAdditionalLogger()

◆ setDebugLevel()

◆ setFlushLevel()

◆ setLogLevel()

◆ setTag()

◆ setUseDateTime()

◆ tag()

◆ tagFromFilename()

◆ writeCallstack()

◆ writeFileHeader()

◆ writeLevel()

◆ writeMessage()

◆ writeTag()

◆ writeThread()

◆ writeTime()

Member Data Documentation

◆ m_additionalLogger

◆ m_appName

◆ m_debugLevel

◆ m_file

◆ m_flushLevel

◆ m_level

◆ m_tag

◆ m_threader

◆ m_useDateTime