LogIO.h
Classes
- LogIO -- ostream-like interface to creating log messages. (full description)
- Global Functions -- Functions to send commands to a LogIO object. (full description)
- Global Functions -- Functions to accumulate text in the output message. (full description)
Types
- 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.
- DEBUGGING
-
Change the message priority to DEBUGGING.
Interface
- Public Members
- LogIO()
- LogIO(LogSink &sink)
- LogIO(const LogOrigin &OR)
- LogIO(const LogOrigin &OR, LogSink &sink)
- LogIO(const LogIO &other)
- LogIO &operator=(const LogIO &other)
- ~LogIO()
- void post()
- void postLocally()
- void postThenThrow()
- void priority(LogMessage::Priority which)
- void sourceLocation(const SourceLocation *where)
- void origin(const LogOrigin &origin)
- ostream& output()
- LogSinkInterface &localSink()
- const LogSinkInterface &localSink() const
Review Status
- Date Reviewed:
- yyyy/mm/dd
- Programs:
- Demos:
- Tests:
Prerequisite
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:
- LogIO::post() is called
- You send the LogIO::POST or LogIO::EXCEPTION
commands to the LogIO with the shift ( << ) command.
- 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;
Here, os is attached to the global log sink, and no origin
information is set.
TableLogSink tab(...);
LogIO os(tab);
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));
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
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;
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;
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?
Member Description
Special commands to the LogIO object
Attach this LogIO object to the global sink with no origin information.
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.
Attach this LogIO object to the supplied origin and global sink.
Attach this LogIO object to the supplied origin and sink.
LogIO(const LogIO &other)
LogIO &operator=(const LogIO &other)
Copying uses reference semantics, i.e. the same sink will be shared
by both copies.
The destructor will post any accumulated message that has not already
been posted.
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 the accumulated message locally.
After the post the priority is reset to NORMAL.
Post the accumulated message at SEVERE priority and then throw an
exception.
After the post the priority is reset to NORMAL.
Change the priority of the message. It does NOT post the accumulated
message at the old priority first.
void sourceLocation(const SourceLocation *where)
Change the location in the origin. Almost always this is called with the
macro WHERE as its argument.
Change the origin of the accumulated message.
Acumulate output in this ostream.
LogSinkInterface &localSink()
Occasionally it is useful to interrogate the local log sink.
const LogSinkInterface &localSink() const
Interface
Private Members
- LogIO &operator<<(LogIO &os, LogIO::Command item)
- LogIO &operator<<(LogIO &os, const SourceLocation *item)
- LogIO &operator<<(LogIO &os, const LogOrigin &OR)
The following commands don't change the accumulated message, rather they
send commands to the LogIO object, either to:
- post the current message: os << "message" << LogIO::POST;
- post the current message and then throw an exception:
os << "error" << LogIO::EXCEPTION;
- Change the priority of the current message:
os << LogIO::DEBUGGING;
- Change the origin of the message:
os << LogOrigin(...);
os << WHERE; // Changes only source file/line number
Member Description
Interface
- LogIO &operator<<(LogIO &os, const String &item)
- LogIO &operator<<(LogIO &os, const char *item)
- LogIO &operator<<(LogIO &os, Double item)
- LogIO &operator<<(LogIO &os, Complex item)
- LogIO &operator<<(LogIO &os, DComplex item)
- LogIO &operator<<(LogIO &os, Int item)
- LogIO &operator<<(LogIO &os, uInt item)
- LogIO &operator<<(LogIO &os, uLong item)
- LogIO &operator<<(LogIO &os, Long item)
- LogIO &operator<<(LogIO &os, Bool item)
- LogIO &operator<<(LogIO &os, ostream &(*item)(ostream &))
Accumulate text in the output message. The last entry is for things like
endl.
Member Description