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

#include <LogSink.h>

Inheritance diagram for casacore::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. More...

	LogSink (const LogFilterInterface &filter, Bool nullSink=True)

	LogSink (LogMessage::Priority filter, ostream *os, Bool useGlobalSink=True)
	Log to an ostream. More...

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

	LogSink (const LogFilterInterface &filter, const CountedPtr< LogSinkInterface > &)
	Log to the given sink. More...

	LogSink (const LogSink &other)
	Make a referencing copy of `other`. More...

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. More...

	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. More...

virtual Bool	postLocally (const LogMessage &message)
	Send `message` to the local sink only. More...

template<typename EXC >
void	postThenThrow (const LogMessage &message, const EXC &exc)
	Post `message` and then throw an `AipsError` exception containing `message.toString()`. More...

virtual uInt	nelements () const
	Get number of messages in local sink. More...

virtual Double	getTime (uInt i) const
	Get given part of the i-th message from the local sink. More...

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. More...

virtual void	clearLocally ()
	Clear the local sink (i.e. More...

virtual const LogFilterInterface &	filter () const
	Get or set the filter of this particular `LogSink`. More...

virtual LogSinkInterface &	filter (const LogFilterInterface &filter)

const LogSinkInterface &	localSink () const
	Change the sink that this `LogSink` actually uses. More...

LogSinkInterface &	localSink ()

LogSink &	localSink (LogSinkInterface *&fromNew)

virtual void	flush (Bool global=True)
	Write any pending output (by default also the global sink). More...

String	id () const
	Returns the id of the LogSink in use... More...

Public Member Functions inherited from casacore::LogSinkInterface
	LogSinkInterface ()
	Create with a `NORMAL` filter. More...

	LogSinkInterface (const LogFilterInterface &filter)
	Create with the supplied `filter`. More...

	LogSinkInterface (const LogSinkInterface &other)
	Copy semantics - copy the filter from `other` to `this` More...

LogSinkInterface &	operator= (const LogSinkInterface &)

virtual	~LogSinkInterface ()

virtual void	cerrToo (bool cerr2)
	Write to cerr too. More...

void	setTaskName (const String &theTask)

Static Public Member Functions
static Bool	postGlobally (const LogMessage &message)
	Send `message` to the global sink only. More...

static void	postGloballyThenThrow (const LogMessage &message)

static LogSinkInterface &	globalSink ()
	Get/set the global sink or check if the global sink is null. More...

static void	globalSink (LogSinkInterface *&fromNew)

static Bool	nullGlobalSink ()

static String	localId ()
	Returns the id for this class... More...

Static Public Member Functions inherited from casacore::LogSinkInterface
static String	localId ()
	Returns the id for this class... More...

Private Member Functions
void	preparePostThenThrow (const LogMessage &message, const AipsError &x)
	Prepare for postThenThrow function. More...

Static Private Member Functions
static void	createGlobalSink ()
	Create the global sink (attached to cerr). More...

Private Attributes
CountedPtr< LogSinkInterface >	local_sink_p

CountedPtr< LsiIntermediate >	local_ref_to_global_p
	The following is a reference to the global sink. More...

Bool	useGlobalSink_p

Static Private Attributes
static CountedPtr < LsiIntermediate > *	global_sink_p

static std::once_flag	theirCallOnceFlag

Additional Inherited Members
Protected Attributes inherited from casacore::LogSinkInterface
String	taskName

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 a Casacore 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 a Casacore 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 142 of file LogSink.h.

Constructor & Destructor Documentation

casacore::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.

casacore::LogSink::LogSink	(	const LogFilterInterface &	filter,
		Bool	nullSink = `True`
	)

explicit

casacore::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.

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

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

Log to the given sink.

It is primarily intended to log to a TableLogSink.

casacore::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).

casacore::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.

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

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

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

casacore::LogSink::~LogSink ( )

Member Function Documentation

virtual void casacore::LogSink::clearLocally ( )

virtual

Clear the local sink (i.e.

remove all messages from it).

Reimplemented from casacore::LogSinkInterface.

static void casacore::LogSink::createGlobalSink ( )

staticprivate

Create the global sink (attached to cerr).

Always called using theirCallOnce.

virtual const LogFilterInterface& casacore::LogSink::filter ( ) const

virtual

Get or set the filter of this particular LogSink.

Reimplemented from casacore::LogSinkInterface.

virtual LogSinkInterface& casacore::LogSink::filter ( const LogFilterInterface & filter )

virtual

Reimplemented from casacore::LogSinkInterface.

virtual void casacore::LogSink::flush ( Bool global = True )

virtual

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

Reimplemented from casacore::LogSinkInterface.

virtual String casacore::LogSink::getLocation ( uInt i ) const

virtual

Reimplemented from casacore::LogSinkInterface.

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

virtual String casacore::LogSink::getMessage ( uInt i ) const

virtual

Reimplemented from casacore::LogSinkInterface.

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

virtual String casacore::LogSink::getObjectID ( uInt i ) const

virtual

Reimplemented from casacore::LogSinkInterface.

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

virtual String casacore::LogSink::getPriority ( uInt i ) const

virtual

Reimplemented from casacore::LogSinkInterface.

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

virtual Double casacore::LogSink::getTime ( uInt i ) const

virtual

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

Reimplemented from casacore::LogSinkInterface.

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

static LogSinkInterface& casacore::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. More so, calling globalSink(fromNew) while using the global sink is not thread-safe. And fromNew is set to 0.

static void casacore::LogSink::globalSink ( LogSinkInterface *& fromNew )

static

String casacore::LogSink::id ( ) const

virtual

Returns the id of the LogSink in use...

Implements casacore::LogSinkInterface.

static String casacore::LogSink::localId ( )

static

Returns the id for this class...

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

Change the sink that this LogSink actually uses.

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

LogSinkInterface& casacore::LogSink::localSink ( )

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

virtual uInt casacore::LogSink::nelements ( ) const

virtual

Get number of messages in local sink.

Reimplemented from casacore::LogSinkInterface.

static Bool casacore::LogSink::nullGlobalSink ( )

static

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

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

Send message to both the local and global sink.

Return True if it passes either of them.

static Bool casacore::LogSink::postGlobally ( const LogMessage & message )

static

Send message to the global sink only.

Returns True if it passes the filter.

static void casacore::LogSink::postGloballyThenThrow ( const LogMessage & message )

static

virtual Bool casacore::LogSink::postLocally ( const LogMessage & message )

virtual

Send message to the local sink only.

Returns True if it passes the filter.

Implements casacore::LogSinkInterface.

template<typename EXC >

void casacore::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 207 of file LogSink.h.

References preparePostThenThrow().

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

void casacore::LogSink::preparePostThenThrow	(	const LogMessage &	message,
		const AipsError &	x
	)

private

Prepare for postThenThrow function.

Referenced by postThenThrow().

virtual void casacore::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 casacore::LogSinkInterface.

Member Data Documentation

CountedPtr<LsiIntermediate>* casacore::LogSink::global_sink_p

staticprivate

Definition at line 309 of file LogSink.h.

CountedPtr<LsiIntermediate> casacore::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 316 of file LogSink.h.

CountedPtr<LogSinkInterface> casacore::LogSink::local_sink_p

private

Definition at line 308 of file LogSink.h.

std::once_flag casacore::LogSink::theirCallOnceFlag

staticprivate

Definition at line 310 of file LogSink.h.

Bool casacore::LogSink::useGlobalSink_p

private

Definition at line 317 of file LogSink.h.

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

casa/Logging/LogSink.h

Classes

Public Member Functions

Static Public Member Functions

Private Member Functions

Static Private Member Functions

Private Attributes

Static Private Attributes

Additional Inherited Members

Detailed Description

Intended use:

Review Status

Prerequisite

Etymology

Synopsis

Example

Advanced topics

Motivation

To Do

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation