LogSink.h

Classes

LogSink -- Distribute LogMessages to their destination(s) (full description)

class LogSink : public LogSinkInterface

Interface

Public Members

explicit LogSink (LogMessage::Priority filter = LogMessage::NORMAL, Bool nullSink = True)

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

LogSink (LogMessage::Priority filter, ostream *os)

LogSink (const LogFilterInterface &filter, ostream *os)

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

LogSink (const LogSink &other)

LogSink &operator= (const LogSink &other)

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

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)

static Bool postGlobally (const LogMessage &message)

virtual Bool postLocally (const LogMessage &message)

void postThenThrow (const LogMessage &message)

static void postGloballyThenThrow (const LogMessage &message)

virtual uInt nelements() const

virtual Double getTime (uInt i) const

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)

virtual void clearLocally()

virtual const LogFilterInterface &filter() const

virtual LogSinkInterface &filter (const LogFilterInterface &filter)

const LogSinkInterface &localSink() const

LogSinkInterface &localSink()

LogSink &localSink (LogSinkInterface *&fromNew)

static LogSinkInterface &globalSink()

static void globalSink (LogSinkInterface *&fromNew)

static Bool nullGlobalSink()

virtual void flush (Bool global=True)

static String localId( )

String id( ) const

Description

Review Status

Reviewed By:

wbrouw

Date Reviewed:

1996/08/21

Programs:

Demos:

dLogging.cc

Tests:

tLogging.cc

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

Member Description

explicit LogSink (LogMessage::Priority filter = LogMessage::NORMAL, Bool nullSink = True)
explicit LogSink (const LogFilterInterface &filter, 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. If a filter isn't defined, default to NORMAL.

LogSink (LogMessage::Priority filter, ostream os)
LogSink (const LogFilterInterface &filter, ostream os)

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 (const LogFilterInterface &filter, const CountedPtr<LogSinkInterface>&)

Log to the given sink. It is primarily intended to log to a TableLogSink.

LogSink (const LogSink &other)
LogSink &operator= (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 (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 (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. Return True if it passes either of them.

static Bool postGlobally (const LogMessage &message)

Send message to the global sink only. Returns True if it passes the filter.

virtual Bool postLocally (const LogMessage &message)

Send message to the local sink only. Returns True if it passes the filter.

void postThenThrow (const LogMessage &message)
static void postGloballyThenThrow (const LogMessage &message)

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.

virtual uInt nelements() const

Get number of messages in local sink.

virtual Double getTime (uInt i) const
virtual String getPriority (uInt i) const
virtual String getMessage (uInt i) const
virtual String getLocation (uInt i) const
virtual String getObjectID (uInt i) const

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

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. The default implementation does nothing.

virtual void clearLocally()

Clear the local sink (i.e. remove all messages from it).

virtual const LogFilterInterface &filter() const
virtual LogSinkInterface &filter (const LogFilterInterface &filter)

Get or set the filter of this particular LogSink.

const LogSinkInterface &localSink() const
LogSinkInterface &localSink()
LogSink &localSink (LogSinkInterface *&fromNew)

Change the sink that this LogSink actually uses.

static LogSinkInterface &globalSink()
static void globalSink (LogSinkInterface *&fromNew)
static Bool nullGlobalSink()

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.

virtual void flush (Bool global=True)

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

static String localId( )

Returns the id for this class...

String id( ) const

Returns the id of the LogSink in use...