Home

C-Bits Package Documentation

Main Page Namespace List Compound List File List Namespace Members Compound Members File Members

cbits::LogStream Class Reference

From the client perspective, a LogStream instance represents a logging destination such as a disk file. More...

#include <LogStream.h>

Collaboration diagram for cbits::LogStream:

Public Methods
	LogStream (const std::string &path, const LogLevel::Level level, const bool appnd=true) throw ( LogStreamException )
	Constructor that binds a log stream to a file. More...
	LogStream (std::ostream *os, const LogLevel::Level level) throw ( LogStreamException )
	Constructor that associates a log stream with an existing output stream. More...
	LogStream ()
	Default Constructor: creates a LogStream that eats all log records written to it.. More...
const char *	get_file_path () const
	Get the path to the file (if any) that the log stream is bound to. More...
const LogLevel::Level	get_max_level () const
	Get the max log level for the stream. More...
LogLevel::Level	reset_max_level (LogLevel::Level new_level)
	Set the log stream's maximum log level to a new value. More...
void	increaseLevel ()
	Increase threshold level by one step. More...
void	decreaseLevel ()
	decrease threshold level by one step. More...
void	setTrace (const bool on)
	Enable or disable trace logging. More...
const bool	isTraceOn () const
	Check if trace statements are enabled. More...
virtual	~LogStream (void)
	Destructor. More...
std::ostream *	replace_stream (std::ostream *) throw ( LogStreamException)
	Replace the underlying output stream. More...
std::ostream *	get_logstream () const
	Get the underying output stream that log records are being written to or a 'null' output stream if this LogStream instance was default constructed. More...
std::ostream *	get_nullstream () const
	Get a NULL output output stream that silently drops all records written to it. More...
std::ostream *	get_ostream () const
	Get the underlying output stream that log records are being written to. More...
void	lock ()
	Lock the stream. More...
void	unlock ()
	Un Lock the stream. More...
Private Methods
	LogStream (const LogStream &)
LogStream &	operator= (const LogStream &)
Private Attributes
std::string *	_path
	path to log file, if any. More...
LogLevel::Level	_max_level
	this LogStream's threshold. More...
std::ostream *	_ostream
	the underlying ostream. More...
bool	_own_stream
	true if stream opened internally. More...
NullStream	_nullstream
	used to ignore records. More...
bool	_trace
	if on, trace stmts will be logged. More...
pthread_mutex_t	_lock
	protect against concurrent access. More...

Detailed Description

From the client perspective, a LogStream instance represents a logging destination such as a disk file.

However, the LogStream is really just a 'decorator' (a la Decorator design pattern) for a standard library std::ostream or derivative.

Use of cbits::LogStream for application logging is very simple. The application code simply creates one (or more) instance(s) of LogStream, specifying either a file or output stream as the logging destination, and a threshold log level. For instance:

     // Create logger that writes log records to a 
     // file in the temp directory.  All log records
     // except 'trace' records are written.
     LogStream logger( "/tmp/server.log", LogLevel::MAX );

     // Create a logger that writes log records to 
     // STDERR.  Only 'error' log records are written.
     LogStream logger( &std::cerr, LogLevel::ERR );

The LogLevel class defines the following levels which act as stream manipulators when written to a LogStream stream.

Each application log statement will just use the logger object like an ordinary stream object. However, a LogLevel manipulator must be the first object written to the stream:

      // The 'logger' object's threshold must be set to at least
      // LogLevel::DBG2 in order for the following log message
      // to be written to the log stream.
 	logger << LogLevel::DBG2 << "This is a level 2 debug msg"<<std::endl;

A LogStream instance's threshold can be adjusted dynamically after it has been constructed, perhaps in response to a technician command to increase the debug logging during the investigation of a problem:

 	if( got_inclvl_command ) {
		logger.increaseLevel(); // e.g. DBG1 -> DBG2
	}

Of course the level can be reset explicitly:

 	if( got_inclvl_command ) {
		logger.reset_max_level( LogLevel::MAX );
 	}

It's often useful to include ubiquitous 'trace' log statements in code while it's under development and then remove or disable them later. The LogLevel::TRACE level accomodates this.

However, application log statements that use the TRACE level are not subject to the threshold filtering that levels ERR, DBG1, DBG2, and DBG3 are.

TRACE log statements are turned on using the LogStream::setTrace method with an argument of true. By default, tracing is disabled so that all log statements with LogLevel::TRACE are ignored unless explicitly enabled from application code by a statement such as the following:

 	logger.setTrace( true );

They can similarly be disabled:

 	logger.setTrace( false );

In most cases, a LogStream will simply be constructed with the name of a disk file to write the log data to. But since it can also be used to wrap (decorate) an arbitrary std::ostream, other options exist. For instance, the cbits::Socket class, used to connect to remote applications over a network, also supports std::ostream semantics. Wrapping a LogStream object around a output stream from a cbits::Socket would allow remote logging with little effort.

Multithreaded access The LogStream object supports lock() and unlock() methods to allow client code to protect against concurrent access in a multithreaded environment. Moreover, the cbits::TempLock template class is useful for automatically locking log statement only within the scope of a particular log statement. for instance, the followin is thread safe:

 // In the Main thread
 LogStream log ("/tmp/server.log", LogLevel::ERR );

 // 'log' is shared by multiple application threads
 

 // In a particular thread:
 TempLock<LogStream>(log) << LogLevel::ERR 
      << "Thread [" << getMyThreadID() <<"]:  "Help! ..." << std::endl;

During the execution of this log statement, other threads would block trying to write to the log object (assuming they similarly used TempLock) until the current statement has executed.

Constructor & Destructor Documentation

LogStream::LogStream ( const std::string & path,

const LogLevel::Level level,

const bool appnd = true

) throw ( LogStreamException )

Constructor that binds a log stream to a file.

Exceptions:

LogStreamException raised if the log file can not be opened.

Parameters:

path The path to the log file. The file will be created if it doesn't exist.

mxlevel The threshold log level for the log stream. Records written at a higher log level will be silently dropped.

appnd If true, an existing log file will be appended to rather than overwritten.

LogStream::LogStream ( std::ostream * os,

const LogLevel::Level level

) throw ( LogStreamException )

Constructor that associates a log stream with an existing output stream.

Exceptions:

LogStreamException raised if the specified output stream is invalid.

Parameters:

os The stream to send log output to.

mxlevel The threshold log level for the log stream. Records written at a higher log level will be silently dropped.

LogStream::LogStream ( )

Default Constructor: creates a LogStream that eats all log records written to it..
Define default construcor.

LogStream::~LogStream ( void ) [virtual]

Destructor.
If the LogStream was bound to a 'path', then the underlying file is closed. If the LogStream was bound to a pre-existing std::ostream object, the latter is not affected by the LogStream desctruction.

cbits::LogStream::LogStream ( const LogStream & ) [private]

Member Function Documentation

void LogStream::decreaseLevel ( )

decrease threshold level by one step.

const char* cbits::LogStream::get_file_path ( ) const [inline]

Get the path to the file (if any) that the log stream is bound to.

Returns:
a const pointer to a string holding the path or 0 if the stream was either default constructed or is wrapping an anonymous output stream.

std::ostream * LogStream::get_logstream ( ) const

Get the underying output stream that log records are being written to or a 'null' output stream if this LogStream instance was default constructed.

const LogLevel::Level cbits::LogStream::get_max_level ( ) const [inline]

Get the max log level for the stream.

Returns:
one of: LogLevel::ERR LogLevel::DBG1 LogLevel::DBG2 LogLevel::DBG3

std::ostream* cbits::LogStream::get_nullstream ( ) const [inline]

Get a NULL output output stream that silently drops all records written to it.

std::ostream* cbits::LogStream::get_ostream ( ) const [inline]

Get the underlying output stream that log records are being written to.

Returns:
the std::ostream instance that records are being written to or 0 if the LogStream was default constructed.

void LogStream::increaseLevel ( )

Increase threshold level by one step.

const bool cbits::LogStream::isTraceOn ( ) const [inline]

Check if trace statements are enabled.

Returns:
true if trace statements will be logged.

void cbits::LogStream::lock ( ) [inline]

Lock the stream.

LogStream& cbits::LogStream::operator= ( const LogStream & ) [private]

std::ostream * LogStream::replace_stream ( std::ostream * ) throw ( LogStreamException)

Replace the underlying output stream.

Returns:
old stream.
Exceptions:

LogStreamException if this LogStream instance was constructed with a file path instead of an existing output stream.

Parameters:

new_os New output stream

LogLevel::Level LogStream::reset_max_level ( LogLevel::Level new_level )

Set the log stream's maximum log level to a new value.

Returns:
the old maximum log level. Default constructed LogStream objects always return LogLevel::MAX.
Parameters:

new_level The new logging threshold. Must be one of: LogLevel::MIN (:=LogLevel::ERR) LogLevel::ERR LogLevel::DBG1 LogLevel::DBG2 LogLevel::DBG3 LogLevel::MAX

void cbits::LogStream::setTrace ( const bool on ) [inline]

Enable or disable trace logging.
Log statements with LogLevel::TRACE will be logged.
Parameters:

on log trace statements if true

void cbits::LogStream::unlock ( ) [inline]

Un Lock the stream.

Member Data Documentation

pthread_mutex_t cbits::LogStream::_lock [private]

protect against concurrent access.

LogLevel::Level cbits::LogStream::_max_level [private]

this LogStream's threshold.

NullStream cbits::LogStream::_nullstream [private]

used to ignore records.

std::ostream* cbits::LogStream::_ostream [private]

the underlying ostream.

bool cbits::LogStream::_own_stream [private]

true if stream opened internally.

std::string* cbits::LogStream::_path [private]

path to log file, if any.

bool cbits::LogStream::_trace [private]

if on, trace stmts will be logged.

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

Generated by

Hosted by

cbits::LogStream Class Reference

Public Methods

Private Methods

Private Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation