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

More...

`#include <LogIO.h>`

## Public Types

enum | Command { POST , EXCEPTION , SEVERE , WARN , NORMAL , NORMAL1 , NORMAL2 , NORMAL3 , NORMAL4 , NORMAL5 , DEBUG1 , DEBUG2 , DEBUGGING }
| Special commands to the LogIO object. More...

## Public Member Functions

| LogIO ()
| Attach this LogIO object to the global sink with no origin information.
| LogIO (LogSink &sink)
| Attach this LogIO object to the supplied sink.
| LogIO (const LogOrigin &OR)
| Attach this LogIO object to the supplied origin and global sink.
| LogIO (const LogOrigin &OR, LogSink &sink)
| Attach this LogIO object to the supplied origin and sink.
| LogIO (const LogIO &other)
| Copying uses reference semantics, i.e.
LogIO & | operator= (const LogIO &other)
| ~LogIO ()
| The destructor will post any accumulated message that has not already been posted.
void | post ()
| Post the accumulated message.
void | post (LogMessage &amess)
void | postLocally ()
| Post the accumulated message locally.
template<typename EXC>
void | postThenThrow (const EXC &exc)
| Post the accumulated message at SEVERE priority and then throw an exception.
void | priority (LogMessage::Priority which)
| Change the priority of the message.
LogMessage::Priority | priority ()
void | sourceLocation (const SourceLocation *where)
| Change the location in the origin.
void | origin (const LogOrigin &origin)
| Change the origin of the accumulated message.
ostream & | output ()
| Acumulate output in this ostream.
LogSinkInterface & | localSink ()
| Occasionally it is useful to interrogate the local log sink.
const LogSinkInterface & | localSink () const

## Private Member Functions

void | preparePostThenThrow (const AipsError &x)
| Prepare message stream for postThenThrow function.

## Private Attributes

LogSink | sink_p
LogMessage | msg_p
ostringstream * | text_p

## Detailed Description

ostream-like interface to creating log messages.

### Intended use:

Public interface

### Review Status

Reviewed By:
  UNKNOWN
Date Reviewed:
  before2004/08/25
Test programs:
  tLogIO
Demo programs:
  dLogging

### Prerequisite

- LogSink class
- LogMessage class
- LogOrigin class

### Etymology

Log message, Input/Output.

### Synopsis

LogIO is intended to be used in a way similar to the ostream class. However, rather than sending it's output to a file or stdout, it bundles its output up into LogMessage objects and posts them to a LogSink.

When you use the "<<" operator on a LogIO, you are building up a log message inside the LogIO object. The message is posted when:

1. LogIO::POST() is called
2. You send the LogIO::POST or LogIO::EXCEPTION commands to the LogIO with the shift ( << ) command.
3. The LogIO object is destructed.

Note that log messages may span multiple lines, so sending the LogIO a newline (via "\n" or endl) does not force the message to be emitted.

### Example

A LogIO may be created in the following ways:

LogIO os;
casacore::LogIO::LogIO
LogIO()
Attach this LogIO object to the global sink with no origin information.

Here, os is attached to the global log sink, and no origin information is set.

TableLogSink tab(...);
LogIO os(tab);
casacore::TableLogSink
Definition TableLogSink.h:90

Here, os is attached to tab (and also to the global log sink since every sink's post also calls the global sink's post).

LogIO os(LogOrigin("class", "func(args)", WHERE));
WHERE
#define WHERE
Definition LogOrigin.h:212
casacore::LogOrigin
Definition LogOrigin.h:92

Here, os is attached to the global sink and the origin information is set to class::func(args) and the line number and source file information is set (with WHERE).

TableLogSink tab(...);
LogIO os(LogOrigin("class", "func(args)", WHERE), tab);

Here all the above information is set.

Once you have a LogIO, using it is pretty simple:

os << "Every good boy deserves" << 5 << " pieces of fudge!";

This accumulates the message but does not send it. If you want to force it to be sent you can do so with either of the following methods:

os << LogIO::POST; // From the Commands enum
os.post(); // Member function
casacore::LogIO::POST
@ POST
Post the accumulated message.
Definition LogIO.h:170
casacore::LogIO::post
void post()
Post the accumulated message.

Note that after a post the priority is reset to NORMAL.

If you want to change the level of the message you can also do so with the shift operator:

os << LogIO::DEBUGGING << "Boring message" <<
LogIO::SEVERE << "Error!" << LogIO::POST;
casacore::LogIO::SEVERE
@ SEVERE
Change the message priority to SEVERE.
Definition LogIO.h:176
casacore::LogIO::DEBUGGING
@ DEBUGGING
Definition LogIO.h:189

Note that changing the priority changes the priority of the entire message. The message does not get posted until the POST is done. So in the above example the DEBUGGING priority does not do anything because the priority is overwritten by the SEVERE one.

You can also change the origin information with the << operator:

os << LogOrigin("class", "func(args)");
os << WHERE;

A class which has an operator<< to std::ostream but not LogIO can be handled as follows:

os << LogIO::SEVERE << " at ";
os.output() << MEpoch::Convert(time_p, MEpoch::Ref(MEpoch::UTC))();
os << LogIO::POST;
casacore::LogIO::output
ostream & output()
Acumulate output in this ostream.
casacore::MEpoch::UTC
@ UTC
Definition MEpoch.h:125
casacore::MEpoch::Ref
MeasRef< MEpoch > Ref
Measure reference (i.e.
Definition MEpoch.h:153
casacore::MEpoch::Convert
MeasConvert< MEpoch > Convert
Measure Convert (i.e.
Definition MEpoch.h:155

### Motivation

The earlier method of creating log messages solely through LogSink and LogMessage required the programmer to type in more lines of code than this solution. Also, this interface makes it easy to drop log messages into existing code that uses ostreams.

### To Do

- Add << operators for all classes that have ostream<< defined. (We could probably do it with a template, but might result in ambiguity).
- Have a function for changing the LogSink only? (You can get much the same effect with operator=). them?

Definition at line 164 of file LogIO.h.

## Member Enumeration Documentation

## Command

enum casacore::LogIO::Command

Special commands to the LogIO object.

Enumerator
POST | Post the accumulated message. Equivalent to calling LogIO::post().
EXCEPTION | Post the accumulated message then throw an exception. Always posts the message at SEVERE priority. Equivalent to calling LogIO::postThenThrow().
SEVERE | Change the message priority to SEVERE.
WARN | Change the message priority to WARN.
NORMAL | Change the message priority to NORMAL.
NORMAL1 |
NORMAL2 |
NORMAL3 |
NORMAL4 |
NORMAL5 |
DEBUG1 | Change the message priority to DEBUGGING.
DEBUG2 |
DEBUGGING |

Definition at line 168 of file LogIO.h.

## Constructor & Destructor Documentation

## LogIO() [1/5]

casacore::LogIO::LogIO | ( |  | ) |

Attach this LogIO object to the global sink with no origin information.

Referenced by LogIO(), and operator=().

## LogIO() [2/5]

casacore::LogIO::LogIO | ( | LogSink & | sink | ) |

Attach this LogIO object to the supplied sink.

A referencing copy of the sink is made inside the LogIO object, so you do not need to worry about memory management.

## LogIO() [3/5]

casacore::LogIO::LogIO | ( | const LogOrigin & | OR | ) |

Attach this LogIO object to the supplied origin and global sink.

## LogIO() [4/5]

casacore::LogIO::LogIO | ( | const LogOrigin & | OR,
|  | LogSink & | sink )

Attach this LogIO object to the supplied origin and sink.

## LogIO() [5/5]

casacore::LogIO::LogIO | ( | const LogIO & | other | ) |

Copying uses reference semantics, i.e.

the same sink will be shared by both copies.

References LogIO().

## ~LogIO()

casacore::LogIO::~LogIO | ( |  | ) |

The destructor will post any accumulated message that has not already been posted.

## Member Function Documentation

## localSink() [1/2]

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

inline

Occasionally it is useful to interrogate the local log sink.

Definition at line 300 of file LogIO.h.

References sink_p.

## localSink() [2/2]

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

inline

Definition at line 305 of file LogIO.h.

References sink_p.

## operator=()

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

References LogIO().

## origin()

void casacore::LogIO::origin | ( | const LogOrigin & | origin | ) |

Change the origin of the accumulated message.

References origin().

Referenced by origin().

## output()

ostream & casacore::LogIO::output | ( |  | ) |

Acumulate output in this ostream.

Referenced by casacore::STLIO_global_functions_Container_IO::operator<<(), casacore::STLIO_global_functions_Container_IO::operator<<(), casacore::STLIO_global_functions_Container_IO::operator<<(), and casacore::STLIO_global_functions_Container_IO::operator<<().

## post() [1/2]

void casacore::LogIO::post | ( |  | ) |

Post the accumulated message.

If you wish, you can post the messages only locally to the sink. After the post the priority is reset to NORMAL.

## post() [2/2]

void casacore::LogIO::post | ( | LogMessage & | amess | ) |

## postLocally()

void casacore::LogIO::postLocally | ( |  | ) |

Post the accumulated message locally.

After the post the priority is reset to NORMAL.

## postThenThrow()

template<typename EXC>

void casacore::LogIO::postThenThrow | ( | const EXC & | exc | ) |

inline

Post the accumulated message at SEVERE priority and then throw an exception.

After the post the priority is reset to NORMAL.

Definition at line 226 of file LogIO.h.

References msg_p, preparePostThenThrow(), and sink_p.

## preparePostThenThrow()

void casacore::LogIO::preparePostThenThrow | ( | const AipsError & | x | ) |

private

Prepare message stream for postThenThrow function.

Referenced by postThenThrow().

## priority() [1/2]

LogMessage::Priority casacore::LogIO::priority | ( |  | ) |

## priority() [2/2]

void casacore::LogIO::priority | ( | LogMessage::Priority | which | ) |

Change the priority of the message.

It does NOT post the accumulated message at the old priority first.

## sourceLocation()

void casacore::LogIO::sourceLocation | ( | const SourceLocation * | where | ) |

Change the location in the origin.

Almost always this is called with the macro WHERE as its argument.

## Member Data Documentation

## msg_p

LogMessage casacore::LogIO::msg_p

private

Definition at line 251 of file LogIO.h.

Referenced by postThenThrow().

## sink_p

LogSink casacore::LogIO::sink_p

private

Definition at line 250 of file LogIO.h.

Referenced by localSink(), localSink(), and postThenThrow().

## text_p

ostringstream* casacore::LogIO::text_p

private

Definition at line 252 of file LogIO.h.

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

- casa/Logging/LogIO.h