casacore
Classes | Public Member Functions | Static Public Member Functions | Private Member Functions | Static Private Member Functions | Private Attributes | Static Private Attributes | List of all members
casacore::LogSink Class Reference

More...

#include <LogSink.h>

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...
 
LogSinkoperator= (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 LogFilterInterfacefilter () const
 Get or set the filter of this particular LogSink. More...
 
virtual LogSinkInterfacefilter (const LogFilterInterface &filter)
 
const LogSinkInterfacelocalSink () const
 Change the sink that this LogSink actually uses. More...
 
LogSinkInterfacelocalSink ()
 
LogSinklocalSink (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...
 
LogSinkInterfaceoperator= (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 LogSinkInterfaceglobalSink ()
 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< LogSinkInterfacelocal_sink_p
 
CountedPtr< LsiIntermediatelocal_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

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

  1. A global destination, which is shared by all LogSinks. The global destination will typically be a GUI window or standard output.
  2. 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:

  1. a NullLogSink which merely discards the logging messages.
  2. a StreamLogSink which sends the log messages to an ostream (typically cerr)
  3. 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
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 m...

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

Definition at line 142 of file LogSink.h.

Constructor & Destructor Documentation

◆ LogSink() [1/10]

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.

◆ LogSink() [2/10]

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

◆ LogSink() [3/10]

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.

◆ LogSink() [4/10]

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

◆ LogSink() [5/10]

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

Log to the given sink.

It is primarily intended to log to a TableLogSink.

◆ LogSink() [6/10]

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

◆ LogSink() [7/10]

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.

◆ LogSink() [8/10]

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

◆ LogSink() [9/10]

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

◆ LogSink() [10/10]

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

◆ ~LogSink()

casacore::LogSink::~LogSink ( )

Member Function Documentation

◆ clearLocally()

virtual void casacore::LogSink::clearLocally ( )
virtual

Clear the local sink (i.e.

remove all messages from it).

Reimplemented from casacore::LogSinkInterface.

◆ createGlobalSink()

static void casacore::LogSink::createGlobalSink ( )
staticprivate

Create the global sink (attached to cerr).

Always called using theirCallOnce.

◆ filter() [1/2]

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

Get or set the filter of this particular LogSink.

Reimplemented from casacore::LogSinkInterface.

◆ filter() [2/2]

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

Reimplemented from casacore::LogSinkInterface.

◆ flush()

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

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

Reimplemented from casacore::LogSinkInterface.

◆ getLocation()

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

◆ getMessage()

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

◆ getObjectID()

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

◆ getPriority()

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

◆ getTime()

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().

◆ globalSink() [1/2]

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.

◆ globalSink() [2/2]

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

◆ id()

String casacore::LogSink::id ( ) const
virtual

Returns the id of the LogSink in use...

Implements casacore::LogSinkInterface.

◆ localId()

static String casacore::LogSink::localId ( )
static

Returns the id for this class...

◆ localSink() [1/3]

LogSinkInterface& casacore::LogSink::localSink ( )

◆ localSink() [2/3]

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

Change the sink that this LogSink actually uses.

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

◆ localSink() [3/3]

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

◆ nelements()

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

Get number of messages in local sink.

Reimplemented from casacore::LogSinkInterface.

◆ nullGlobalSink()

static Bool casacore::LogSink::nullGlobalSink ( )
static

◆ operator=()

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

◆ post()

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

Send message to both the local and global sink.

Return True if it passes either of them.

◆ postGlobally()

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

Send message to the global sink only.

Returns True if it passes the filter.

◆ postGloballyThenThrow()

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

◆ postLocally()

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.

◆ postThenThrow()

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().

◆ preparePostThenThrow()

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

Prepare for postThenThrow function.

Referenced by postThenThrow().

◆ writeLocally()

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

◆ global_sink_p

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

Definition at line 309 of file LogSink.h.

◆ local_ref_to_global_p

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.

◆ local_sink_p

CountedPtr<LogSinkInterface> casacore::LogSink::local_sink_p
private

Definition at line 308 of file LogSink.h.

◆ theirCallOnceFlag

std::once_flag casacore::LogSink::theirCallOnceFlag
staticprivate

Definition at line 310 of file LogSink.h.

◆ useGlobalSink_p

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: