Loading...
Searching...
No Matches
casacore::LogSink Class Reference
casa package (libcasa_casa) » Logging_module

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.
| 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 std::shared_ptr< 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...
Public Member Functions inherited from casacore::LogSinkInterface
| LogSinkInterface ()
| Create with a NORMAL filter.
| LogSinkInterface (const LogFilterInterface &filter)
| Create with the supplied filter.
| LogSinkInterface (const LogSinkInterface &other)
| Copy semantics - copy the filter from other to this.
LogSinkInterface & | operator= (const LogSinkInterface &)
virtual | ~LogSinkInterface ()
virtual void | cerrToo (bool cerr2)
| Write to cerr too.
void | setTaskName (const String &theTask)

## 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...
Static Public Member Functions inherited from casacore::LogSinkInterface
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

std::shared_ptr< LogSinkInterface > | local_sink_p
std::shared_ptr< LsiIntermediate > | local_ref_to_global_p
| The following is a reference to the global sink.
Bool | useGlobalSink_p

## Static Private Attributes

static std::shared_ptr< 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

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
casacore::LogMessage
Definition LogMessage.h:98
casacore::LogMessage::NORMAL
@ NORMAL
Definition LogMessage.h:116
casacore::LogSink::LogSink
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

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

Definition at line 137 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.

References filter(), casacore::LogMessage::NORMAL, and casacore::True.

Referenced by localSink(), LogSink(), and operator=().

## LogSink() [2/10]

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

explicit

References filter(), and casacore::True.

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

References filter(), and casacore::True.

## LogSink() [4/10]

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

References filter(), and casacore::True.

## LogSink() [5/10]

casacore::LogSink::LogSink | ( | const LogFilterInterface & | filter,
|  | const std::shared_ptr< LogSinkInterface > & | )

Log to the given sink.

It is primarily intended to log to a TableLogSink.

References filter().

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

References LogSink().

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

References filter().

## LogSink() [8/10]

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

References filter().

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

void casacore::LogSink::createGlobalSink | ( |  | ) |

static private

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.

Referenced by filter(), LogSink(), LogSink(), LogSink(), LogSink(), LogSink(), LogSink(), and LogSink().

## filter() [2/2]

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

virtual

Reimplemented from casacore::LogSinkInterface.

References filter(), and casacore::LogSinkInterface::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.

References casacore::True.

## getLocation()

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

virtual

Reimplemented from casacore::LogSinkInterface.

## getMessage()

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

virtual

Reimplemented from casacore::LogSinkInterface.

## getObjectID()

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

virtual

Reimplemented from casacore::LogSinkInterface.

## getPriority()

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

virtual

Reimplemented from casacore::LogSinkInterface.

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

## globalSink() [1/2]

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.

References casacore::LogSinkInterface::LogSinkInterface().

## globalSink() [2/2]

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

static

References casacore::LogSinkInterface::LogSinkInterface().

## id()

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

virtual

Returns the id of the LogSink in use...

Implements casacore::LogSinkInterface.

## localId()

String casacore::LogSink::localId | ( |  | ) |

static

Returns the id for this class...

## localSink() [1/3]

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

References casacore::LogSinkInterface::LogSinkInterface().

## localSink() [2/3]

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

Change the sink that this LogSink actually uses.

References casacore::LogSinkInterface::LogSinkInterface().

## localSink() [3/3]

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

References LogSink(), and casacore::LogSinkInterface::LogSinkInterface().

## nelements()

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

virtual

Get number of messages in local sink.

Reimplemented from casacore::LogSinkInterface.

## nullGlobalSink()

Bool casacore::LogSink::nullGlobalSink | ( |  | ) |

static

## operator=()

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

References LogSink().

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

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

static

Send message to the global sink only.

Returns True if it passes the filter.

## postGloballyThenThrow()

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 202 of file LogSink.h.

References preparePostThenThrow().

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

References casacore::time().

## Member Data Documentation

## global_sink_p

std::shared_ptr<LsiIntermediate> casacore::LogSink::global_sink_p

static private

Definition at line 304 of file LogSink.h.

## local_ref_to_global_p

std::shared_ptr<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 reference to it is destroyed. This can happen if you have a static LogSink (or LogIO).

Definition at line 311 of file LogSink.h.

## local_sink_p

std::shared_ptr<LogSinkInterface> casacore::LogSink::local_sink_p

private

Definition at line 303 of file LogSink.h.

## theirCallOnceFlag

std::once_flag casacore::LogSink::theirCallOnceFlag

static private

Definition at line 305 of file LogSink.h.

## useGlobalSink_p

Bool casacore::LogSink::useGlobalSink_p

private

Definition at line 312 of file LogSink.h.

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

- casa/Logging/LogSink.h