LogSink.h
Classes
- LogSink -- Distribute LogMessages to their destination(s) (full description)
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
Review Status
- Reviewed By:
- wbrouw
- Date Reviewed:
- 1996/08/21
- Programs:
- Demos:
- Tests:
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
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)
Send message to both the local and global sink. Return
True if it passes either of them.
Send message to the global sink only. Returns True
if it passes the filter.
Send message to the local sink only. Returns True
if it passes the filter.
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.
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.
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).
Returns the id for this class...
Returns the id of the LogSink in use...