Distribute LogMessages to their destination(s) More...

#include <LogSink.h>

Inheritance diagram for casa::LogSink:

Classes
class	LsiIntermediate
	LsiIntermediate is a helper class to allow LogSinkInterface to implement semantics that allow causing all classes accessing the log sink to be aimed at a different sink object. More...
Public Member Functions
	LogSink (LogMessage::Priority filter=LogMessage::NORMAL, Bool nullSink=True)
	Create a null local sink that throws all messages away or create a memory local sink that holds the messages in memory.
	LogSink (const LogFilterInterface &filter, Bool nullSink=True)
	LogSink (LogMessage::Priority filter, ostream *os, Bool useGlobalSink=True)
	Log to an ostream.
	LogSink (const LogFilterInterface &filter, ostream *os, Bool useGlobalSink=True)
	LogSink (const LogFilterInterface &filter, const CountedPtr< LogSinkInterface > &)
	Log to the given sink.
	LogSink (const LogSink &other)
	Make a referencing copy of `other`.
LogSink &	operator= (const LogSink &other)
	LogSink (const LogFilterInterface &filter, const String &fileName, Int n=0)
	Temporary to avoid problem that the bool constructor is taken if a char* is passed.
	LogSink (const LogFilterInterface &filter, const Char *fileName, Int n=0)
	LogSink (LogMessage::Priority, const String &fileName, Int n=0)
	LogSink (LogMessage::Priority, const Char *fileName, Int n=0)
	~LogSink ()
Bool	post (const LogMessage &message)
	Send `message` to both the local and global sink.
virtual Bool	postLocally (const LogMessage &message)
	Send `message` to the local sink only.
template<typename EXC >
void	postThenThrow (const LogMessage &message, const EXC &exc)
	Post `message` and then throw an `AipsError` exception containing `message.toString()`.
virtual uInt	nelements () const
	Get number of messages in local sink.
virtual Double	getTime (uInt i) const
	Get given part of the i-th message from the local sink.
virtual String	getPriority (uInt i) const
virtual String	getMessage (uInt i) const
virtual String	getLocation (uInt i) const
virtual String	getObjectID (uInt i) const
virtual void	writeLocally (Double time, const String &message, const String &priority, const String &location, const String &objectID)
	Write a message (usually from another logsink) into the local one.
virtual void	clearLocally ()
	Clear the local sink (i.e.
virtual const LogFilterInterface &	filter () const
	Get or set the filter of this particular `LogSink`.
virtual LogSinkInterface &	filter (const LogFilterInterface &filter)
const LogSinkInterface &	localSink () const
	Change the sink that this `LogSink` actually uses.
LogSinkInterface &	localSink ()
LogSink &	localSink (LogSinkInterface *&fromNew)
virtual void	flush (Bool global=True)
	Write any pending output (by default also the global sink).
String	id () const
	Returns the id of the LogSink in use...
Static Public Member Functions
static Bool	postGlobally (const LogMessage &message)
	Send `message` to the global sink only.
static void	postGloballyThenThrow (const LogMessage &message)
static LogSinkInterface &	globalSink ()
	Get/set the global sink or check if the global sink is null.
static void	globalSink (LogSinkInterface *&fromNew)
static Bool	nullGlobalSink ()
static String	localId ()
	Returns the id for this class...
Private Member Functions
void	preparePostThenThrow (const LogMessage &message, const AipsError &x)
	Prepare for postThenThrow function.
Static Private Member Functions
static void	createGlobalSink ()
	Create the global sink (attached to cerr).
Private Attributes
CountedPtr< LogSinkInterface >	local_sink_p
CountedPtr< LsiIntermediate >	local_ref_to_global_p
	The following is a reference to the global sink.
Bool	useGlobalSink_p
Static Private Attributes
static CountedPtr < LsiIntermediate > *	global_sink_p
static Mutex	theirMutex

Detailed Description

Distribute LogMessages to their destination(s)

Intended use:

Public interface

Review Status

Reviewed By:: wbrouw
Date Reviewed:: 1996/08/21
Test programs:: tLogging
Demo programs:: dLogging

Prerequisite

LogMessage
LogSinkInterface , if you are interested in extending the set of destinations a LogMessage can be sent.

Etymology

Log as in "Log Book." Sink from its common usage ("source/sink") as a thing which can accept some substance or energy.

Synopsis

The LogSink class supplies the destination for LogMessage s. There are two destinations available through the LogSink

A global destination, which is shared by all LogSinks. The global destination will typically be a GUI window or standard output.
A local destination which is intended to log changes to particular dataset(s). The local destination will typically be an AIPS++ Table , but there is also a local sink for temporary storage in memory.

Normally the post() member function will be called which sends the message to both the global and local destinations, however one or the other may be chosen via LogSink::postGlobally() and postLocally() member functions.

The global sink will normally be set by system library code (it defaults to using cerr. The type of local sink is defined at construction time. Presently you can choose one of:

a NullLogSink which merely discards the logging messages.
a StreamLogSink which sends the log messages to an ostream (typically cerr)
a TableLogSink which sends the messages to an AIPS++ Table .

Every LogSink has an attached LogFilterInterface which is used to reject or pass messages. The local and global sinks have their own filters, so they can pass different message priorities (e.g., global DEBUGGING and local NORMAL). Generally applications code shouldn't change the global filter.

Example

    LogMessage logMessage(...);
    LogSink logger(LogMessage::NORMAL, "logtable");   // log locally to a 'logtable'
    logMessage.message("this is a message").line(__LINE__);
    logger.post(logMessage);                          // local and global

More complete examples are in (see (file=Logging.h))Logging.h .

Advanced topics

All possible sinks are derived from an abstract base class: LogSinkInterface . If you want to allow for logging to a different type of sink (i.e. different from a stream or Table) , you first need to derive a new class from LogSinkInterface, and then add a new constructor to LogSink.

LogSink itself contains a reference to the actual object that disposes of the messages. Several LogSink's can share the same actual sink via the copy constructor or assignment operator.

    LogSink logger1(LogMessage::NORMAL, "logtable");
    LogSink logger2(logger1);  // logger2 references logger1
    logger2.post(message);     // ends up in "logtable"

You can even have different LogFilterInterface's attached to the different LogSinks.

Motivation

Logging changes to data and informing users what the software is doing in detail.

To Do

More sink types - in particular to Glish.
A "tee" Sink type might be useful.

Definition at line 141 of file LogSink.h.

Constructor & Destructor Documentation

casa::LogSink::LogSink	(	LogMessage::Priority	filter = `LogMessage::NORMAL`,
		Bool	nullSink = `True`
	)		`[explicit]`

Create a null local sink that throws all messages away or create a memory local sink that holds the messages in memory.

If a filter isn't defined, default to NORMAL.

casa::LogSink::LogSink	(	const LogFilterInterface &	filter,
		Bool	nullSink = `True`
	)		`[explicit]`

casa::LogSink::LogSink	(	LogMessage::Priority	filter,
		ostream *	os,
		Bool	useGlobalSink = `True`
	)

Log to an ostream.

It is the responsiblity of the caller to ensure that os will last as long as the LogSinks that use it. Normally you would use &cerr as the argument.

casa::LogSink::LogSink	(	const LogFilterInterface &	filter,
		ostream *	os,
		Bool	useGlobalSink = `True`
	)

casa::LogSink::LogSink	(	const LogFilterInterface &	filter,
		const CountedPtr< LogSinkInterface > &
	)

Log to the given sink.

It is primarily intended to log to a TableLogSink .

casa::LogSink::LogSink ( const LogSink & other )

Make a referencing copy of other.

That is, if you post a message to the new object, it behaves as if you had posted it to the old one (so long as their filters are the same).

casa::LogSink::LogSink	(	const LogFilterInterface &	filter,
		const String &	fileName,
		Int	n = `0`
	)

Temporary to avoid problem that the bool constructor is taken if a char* is passed.

They are not implemented, so compiler should give warning. The 3rd argument is added to make it different from current version which is still in the system library.

casa::LogSink::LogSink	(	const LogFilterInterface &	filter,
		const Char *	fileName,
		Int	n = `0`
	)

casa::LogSink::LogSink	(	LogMessage::Priority	,
		const String &	fileName,
		Int	n = `0`
	)

casa::LogSink::LogSink	(	LogMessage::Priority	,
		const Char *	fileName,
		Int	n = `0`
	)

casa::LogSink::~LogSink ( )

Member Function Documentation

virtual void casa::LogSink::clearLocally ( ) [virtual]

Clear the local sink (i.e.

remove all messages from it).

Reimplemented from casa::LogSinkInterface.

static void casa::LogSink::createGlobalSink ( ) [static, private]

Create the global sink (attached to cerr).

virtual const LogFilterInterface& casa::LogSink::filter ( ) const [virtual]

Get or set the filter of this particular LogSink.

Reimplemented from casa::LogSinkInterface.

virtual LogSinkInterface& casa::LogSink::filter ( const LogFilterInterface & filter ) [virtual]

Reimplemented from casa::LogSinkInterface.

virtual void casa::LogSink::flush ( Bool global = True ) [virtual]

Write any pending output (by default also the global sink).

Reimplemented from casa::LogSinkInterface.

virtual String casa::LogSink::getLocation ( uInt i ) const [virtual]

Reimplemented from casa::LogSinkInterface.

Referenced by casa::LogHolderIterEntry::location().

virtual String casa::LogSink::getMessage ( uInt i ) const [virtual]

Reimplemented from casa::LogSinkInterface.

Referenced by casa::LogHolderIterEntry::message().

virtual String casa::LogSink::getObjectID ( uInt i ) const [virtual]

Reimplemented from casa::LogSinkInterface.

Referenced by casa::LogHolderIterEntry::objectID().

virtual String casa::LogSink::getPriority ( uInt i ) const [virtual]

Reimplemented from casa::LogSinkInterface.

Referenced by casa::LogHolderIterEntry::priority().

virtual Double casa::LogSink::getTime ( uInt i ) const [virtual]

Get given part of the i-th message from the local sink.

Reimplemented from casa::LogSinkInterface.

Referenced by casa::LogHolderIterEntry::time().

static LogSinkInterface& casa::LogSink::globalSink ( ) [static]

Get/set the global sink or check if the global sink is null.

The global sink defaults to using cerr. Generally applications code shouldn't change the global sink.

static void casa::LogSink::globalSink ( LogSinkInterface *& fromNew ) [static]

String casa::LogSink::id ( ) const [virtual]

Returns the id of the LogSink in use...

Implements casa::LogSinkInterface.

static String casa::LogSink::localId ( ) [static]

Returns the id for this class...

Reimplemented from casa::LogSinkInterface.

const LogSinkInterface& casa::LogSink::localSink ( ) const

Change the sink that this LogSink actually uses.

Referenced by casa::LogIO::localSink().

LogSinkInterface& casa::LogSink::localSink ( )

LogSink& casa::LogSink::localSink ( LogSinkInterface *& fromNew )

virtual uInt casa::LogSink::nelements ( ) const [virtual]

Get number of messages in local sink.

Reimplemented from casa::LogSinkInterface.

static Bool casa::LogSink::nullGlobalSink ( ) [static]

LogSink& casa::LogSink::operator= ( const LogSink & other )

Bool casa::LogSink::post ( const LogMessage & message )

Send message to both the local and global sink.

Return True if it passes either of them.

static Bool casa::LogSink::postGlobally ( const LogMessage & message ) [static]

Send message to the global sink only.

Returns True if it passes the filter.

static void casa::LogSink::postGloballyThenThrow ( const LogMessage & message ) [static]

virtual Bool casa::LogSink::postLocally ( const LogMessage & message ) [virtual]

Send message to the local sink only.

Returns True if it passes the filter.

Implements casa::LogSinkInterface.

template<typename EXC >

void casa::LogSink::postThenThrow	(	const LogMessage &	message,
		const EXC &	exc
	)		`[inline]`

Post message and then throw an AipsError exception containing message.toString().

It is always posted as a SEVERE priority message, no matter what message.priority() says.

Definition at line 206 of file LogSink.h.

References preparePostThenThrow().

Referenced by casa::LogIO::postThenThrow().

void casa::LogSink::preparePostThenThrow	(	const LogMessage &	message,
		const AipsError &	x
	)		`[private]`

Prepare for postThenThrow function.

Referenced by postThenThrow().

virtual void casa::LogSink::writeLocally	(	Double	time,
		const String &	message,
		const String &	priority,
		const String &	location,
		const String &	objectID
	)		`[virtual]`

Write a message (usually from another logsink) into the local one.

The default implementation does nothing.

Reimplemented from casa::LogSinkInterface.

Member Data Documentation

CountedPtr<LsiIntermediate>* casa::LogSink::global_sink_p [static, private]

Definition at line 307 of file LogSink.h.

CountedPtr<LsiIntermediate> casa::LogSink::local_ref_to_global_p [private]

The following is a reference to the global sink.

It is created to ensure that the global sink is not destroyed before the last local reference to it is destroyed. This can happen if you have a static LogSink (or LogIO).

Definition at line 314 of file LogSink.h.

CountedPtr<LogSinkInterface> casa::LogSink::local_sink_p [private]

Definition at line 306 of file LogSink.h.

Mutex casa::LogSink::theirMutex [static, private]

Definition at line 308 of file LogSink.h.

Bool casa::LogSink::useGlobalSink_p [private]

Definition at line 315 of file LogSink.h.

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

casacore/casa/Logging/LogSink.h

Classes

Public Member Functions

Static Public Member Functions

Private Member Functions

Static Private Member Functions

Private Attributes

Static Private Attributes

Detailed Description

Intended use:

Review Status

Prerequisite

Etymology

Synopsis

Example

Advanced topics

Motivation

To Do

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation