GlobalLog Class Reference

#include <Log.h>

List of all members.

Public Types
typedef unsigned int	PreambleFlags
Public Member Functions
	GlobalLog (const wstring &programName, Mutex::GlobalData &globalData, size_t maxLineLength)
	~GlobalLog ()
void	registerPattern (const wstring &pattern)
void	unregisterPattern (const wstring &pattern)
void	clearPatterns ()
const vector< wstring > &	patterns () const
LogLevel	level () const
void	setLevel (const LogLevel level)
LogLevel	threshold () const
void	setThreshold (const LogLevel threshold)
void	setPreambleFlags (const PreambleFlags preambleFlags)
void	lock ()
void	unlock ()
bool	isEnabled (const LogLevel level)
bool	isEnabled (const wstring &category)
const wstring	levelName (const LogLevel level) const
	Return the name of the specified log level.
const wstring	levelColor (const LogLevel level) const
	Return the color string for the specified log level.
void	write (const wstring &category, const LogLevel level, wostringstream &wos)
void	setIndentationState (const bool useIndentation)
	Enable or disable the indentation mechanism.
void	setIndentationAmount (const size_t spaces)
void	registerIndentationLevelPlaceholder (int &indentationLevel)
void	unregisterIndentationLevelPlaceholder ()
const int &	indentationLevelPlaceholder () const
bool	outputToTTY () const
Protected Member Functions
const wstring	preamble (const wstring &category, const LogLevel level)
void	splitLine (const wstring &line, vector< wstring > &lines, wstring::size_type reserved)
void	splitMultiLine (const wstring &line, vector< wstring > &lines)
const wstring	indent (const int threadId) const
const int	indentationLevel (const int threadId) const
const wstring	fit (const wstring &text, const size_t limit)
Protected Attributes
wstring	m_programName
	argv[0].
LogLevel	m_level
	The current log level.
LogLevel	m_threshold
	The threshold below which messages are allowed unconditionally.
vector< wstring >	m_patterns
vector< pair< wstring, wstring > >	m_levelInfo
	A vector of strings containing the names of all the levels.
PreambleFlags	m_preambleFlags
size_t	m_maxLineLength
bool	m_useIndentation
	`true' if the indentation mechanism is enabled.
size_t	m_spaces
	The number of spaces per indentation level.
size_t	m_maxLogLevelNameLength
	The length of the longest level name.
hash_map< int, int * >	m_indentationLevels
bool	m_useColors
	`true' if the logging should use colors on ANSI terminals.
Mutex::GlobalData &	m_globalData
Mutex	m_mutex

---

Detailed Description

This class implements the logging mechanism. Only one instance of an object of this type should exist (the wrapper class "Log" uses a global pointer called g_log). This class logs a message if its level is <= to the current logging level an its pattern matches at least one pattern registered with this object. This class shouldn't be used directly - use the "Log" class instead.

---

Constructor & Destructor Documentation

GlobalLog::GlobalLog (  const wstring &  programName, Mutex::GlobalData &  globalData, size_t  maxLineLength )

Create a log object that can be shared among threads. When the log object is first created, it won't have any logging levels defined or patterns enabled and until that happens, no logging will be possible (outside of the Log object itself). Parameters: programName  the name of the program to be reported in the preamble of each log line. globalData  global data for synchronization among threads. maxLineLength  the maximum length a logged message can have without being split; if a message (together with the preamble) exceeds this length, it will be split into pieces of at most maxLineLength characters.

GlobalLog::~GlobalLog (   )  [inline]

Destroy the log object, releasing its mutex if held in the current thread.

---

Member Function Documentation

void GlobalLog::clearPatterns (   )  [inline]

Clear the pattern list. Note that the pattern matching the category used by the log object itself is re-added.

const wstring GlobalLog::fit (  const wstring &  text, const size_t  limit )  [protected]

Make a string fit into a certain number of characters. If the string is too short, pad it with spaces (in front). If it's too long, cut the excess + 3 characters, and replace the first 3 characters with "...". Parameters: text  the text to be processed. limit  the number of characters allowed. Returns: a string with the result.

const wstring GlobalLog::indent (  const int  threadId  )  const [protected]

Return a string containing a number of spaces reflecting the indentation level in the given thread. Parameters: threadId  the thread for which the indentation is to be calculated. Returns: a string made out of spaces.

const int GlobalLog::indentationLevel (  const int  threadId  )  const [protected]

Return the indentation level of the given thread, or -1 if a placeholder hasn't been set for it. Returns: the current thread's indentation level.

const int & GlobalLog::indentationLevelPlaceholder (   )  const

Get the indentation level placeholder or 0 if not set. Returns: the indentation level placeholder or 0 if not set.

bool GlobalLog::isEnabled (  const wstring &  category  )

Check whether a certain category is allowed to log messages, by matching it against registered patterns. Parameters: category  the name of the category. Returns: `true' if allowed, `false' otherwise.

bool GlobalLog::isEnabled (  const LogLevel  level  )  [inline]

Check that logging is allowed on a given level. Parameters: level  the level to check. Returns: true if logging is allowed, false otherwise.

LogLevel GlobalLog::level (   )  const [inline]

Return the current logging level. Logging happens only if the logging level is less than or equal to the value returned by this function. Returns: the current logging level.

void GlobalLog::lock (   )  [inline]

Lock the log, guaranteeing the current thread exclusive access. This call can block if the log is already locked.

bool GlobalLog::outputToTTY (   )  const [inline]

Check whether or not output goes to a terminal. Returns: `true' if the log outputs to a terminal, `false' otherwise.

const vector<wstring>& GlobalLog::patterns (   )  const [inline]

Return a vector containing all registered patterns. Returns: a vector containing all registered patterns.

const wstring GlobalLog::preamble (  const wstring &  category, const LogLevel  level )  [protected]

Prepare a string to be inserted at the beginning of every line in the log. The string can be customized via the `setPreambleFlags()' method. Parameters: category  the category of the current message. level  the level on which the current message is to be logged. Returns: the string to be logged at the beginning of each log line.

void GlobalLog::registerIndentationLevelPlaceholder (  int &  indentationLevel  )

Establish a placeholder for the thread's current indentation level. The log object will use the value of the integer at that location to properly indent the messages logged. It is the thread's responsability to properly update it. Parameters: indentationLevel  the placeholder.

void GlobalLog::registerPattern (  const wstring &  pattern  )

Turn on logging for categories matching a certain pattern. Parameters: pattern  a new pattern for categories to be checked against.

void GlobalLog::setIndentationAmount (  const size_t  spaces  )

Set the number of spaces per indentation level. This applies to all threads for now. Parameters: spaces  the number of spaces per indentation level.

void GlobalLog::setLevel (  const LogLevel  level  )

Set the logging level. Logging happens only if the logging level is less than or equal to the value set with this function. Parameters: level  the new logging level.

void GlobalLog::setPreambleFlags (  const PreambleFlags  preambleFlags  )  [inline]

Set the preamble flags, determining how to make up the preamble. Parameters: preambleFlags  a bitmask made up of values in the LogPreambleFlags enum or-ed together.

void GlobalLog::setThreshold (  const LogLevel  threshold  )

Set the threshold below which log messages are printed even if the category itself is disabled. Parameters: threshold  the threshold below which log messages are allowed unconditionally.

void GlobalLog::splitLine (  const wstring &  line, vector< wstring > &  lines, wstring::size_type  reserved )  [protected]

Split a long line into multiple lines, at most MaxLogLine characters long. Parameters: line  the long line to be split. lines  a vector of lines to store the result. reserved  the number of characters reserved at the beginning of the line (usually for the preamble).

void GlobalLog::splitMultiLine (  const wstring &  line, vector< wstring > &  lines )  [protected]

Split a multi-line message into multiple lines, using L' ' as the separator. Parameters: line  the multi-line to be split. lines  a vector of lines to store the result.

LogLevel GlobalLog::threshold (   )  const [inline]

Return the threshold below which log messages are allowed unconditionally. Returns: the threshold below which log messages are allowed unconditionally.

void GlobalLog::unlock (   )  [inline]

Unlock the log so that other threads can log messages. This should only be called if the current thread is the one who locked the log.

void GlobalLog::unregisterIndentationLevelPlaceholder (   )

Unregister the curent thread's indentation level placeholder.

void GlobalLog::unregisterPattern (  const wstring &  pattern  )

Turn off logging for categories matching a certain pattern. Parameters: pattern  the pattern to be removed.

void GlobalLog::write (  const wstring &  category, const LogLevel  level, wostringstream &  wos )

Log the content of a string stream. Parameters: category  the category of the message to be logged. level  the level of the message to be logged. wos  the output stream containing the message.

---

Member Data Documentation

Mutex::GlobalData& GlobalLog::m_globalData [protected]

Reference to the global data used for synchronization among threads.

hash_map<int, int*> GlobalLog::m_indentationLevels [protected]

A hash table storing one integer pointer per thread. That integer pointer is provided by the logging thread and it is the address/location where the thread updates its current indentation level. The updating is done without locking because that address/location is assumed thread specific.

size_t GlobalLog::m_maxLineLength [protected]

The maximum length that a log line can have. Lines longer than this will be split.

Mutex GlobalLog::m_mutex [protected]

Mutex used to gain exclusive access to the output stream from within a thread.

vector<wstring> GlobalLog::m_patterns [protected]

A vector of strings containing patterns. A log message's category must match at least one of these patterns in order to be logged. For now, matching means that the pattern must be the leading substring of the category.

PreambleFlags GlobalLog::m_preambleFlags [protected]

A bit mask containing flags to turn on/off certain parts of the preamble. See PreambleFlags for details.

---

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

• Log.h
• Log.cc

---