LogStream Class Reference

Log Stream Class. More...

#include <OpenMS/CONCEPT/LogStream.h>

Inheritance diagram for LogStream:

Classes
struct	GuardedRemoval
	A destination that LogSinkGuard removed from a global stream (see removeForGuard_()), restored with its prefix and id. More...

Public Member Functions
Constructors and Destructors
	LogStream (LogStreamBuf *buf=nullptr, bool delete_buf=true, std::ostream *stream=nullptr)
	~LogStream () override
	Clears all message buffers.
Stream Methods
LogStreamBuf *	rdbuf ()
LogStreamBuf *	operator-> ()
	Arrow operator.
Level methods
void	setLevel (std::string level)
std::string	getLevel ()

Associating Streams
A thread-local LogStream (see getThreadLocalLog*()) writes to the destinations of the corresponding global LogStream, including later changes to them. Its own changes apply on top of these, to the calling thread only: a stream inserted into it belongs to it and is not affected by later changes to the global LogStream; a global destination removed from it stays hidden until it is inserted into it again. A destination that the global LogStream inserts later, also the same stream again, is not hidden; a LogSinkGuard on the global LogStream restores its destination as it was, so it stays hidden. setPrefix() on it applies to its own destinations only; the prefix of a global destination is set on the global LogStream. Do not insert a LogStream as a destination of another one: writing to it would block. When the destinations change, pending repeat counts ("<message> occurred N times") are written to the destinations that got the repeated messages and remain (with insert(), remove() and removeAllStreams() on this stream: to all destinations before the change), and the earlier messages no longer count as repeated: a new destination gets every message from then on.
typedef std::list< LogStreamBuf::StreamStruct >::iterator	StreamIterator
struct	ThreadLocalLogAccess
	Lets the thread-local accessors (getThreadLocalLog*()) call followParent_() on each use.
class	LogSinkGuard
bool	delete_buffer_
void	insert (std::ostream &s)
void	remove (std::ostream &s)
void	removeAllStreams ()
void	setPrefix (const std::ostream &s, const std::string &prefix)
void	setPrefix (const std::string &prefix)
	Set prefix of all output streams, details see setPrefix method with ostream.
void	flush ()
void	flushIncomplete ()
	Flush any incomplete line (text not terminated by newline) to all streams.
bool	hasStream (std::ostream &stream)
	Is stream currently one of this LogStream's output destinations?
StreamIterator	findStream_ (const std::ostream &stream)
bool	hasStream_ (std::ostream &stream)
bool	bound_ () const
GuardedRemoval	removeForGuard_ (std::ostream &s)
void	restoreForGuard_ (std::ostream &s, const GuardedRemoval &removal)
GuardedRemoval	detachLocked_ (std::ostream &s)
	Removes s from the destinations (for a thread-local stream: hides inherited ones) and returns what it removed. The caller holds the sink mutex.
LogStream *	threadLocalFollower_ ()
	For a global stream: the calling thread's thread-local stream of the same level, or nullptr.
void	drain_ ()
	Writes pending text (also an incomplete line) and repeat counts to the current destinations.
void	followParent_ ()
	For a thread-local stream: applies changes of the global destinations made since the last call, see updateState_()
void	updateState_ ()

Detailed Description

Log Stream Class.

Defines a log stream which features a cache and some formatting. For the developer, however, only some macros are of interest which will push the message that follows them into the appropriate stream:

Macros:

• OPENMS_LOG_FATAL_ERROR
• OPENMS_LOG_ERROR (non-fatal error are reported (processing continues))
• OPENMS_LOG_WARN (warning, a piece of information which should be read by the user, should be logged)
• OPENMS_LOG_INFO (information, e.g. a status should be reported)
• OPENMS_LOG_DEBUG (general debugging information - output be written to cout if debug_level > 0)

To use a specific logger of a log level simply use it as cerr or cout:
OPENMS_LOG_ERROR << " A bad error occurred ..."
Which produces an error message in the log.

Note

The OPENMS_LOG_* macros are thread-safe: each thread logs through its own thread-local LogStream/LogStreamBuf (see getThreadLocalLog*()), so the per-stream buffers and caches are never shared. The final writes to the shared sink(s) (e.g. std::cerr / std::cout) and to the shared Colorizer are serialized by a global mutex inside LogStreamBuf::distribute_(). The global LogStream objects returned by getGlobalLog*() are NOT thread-safe for direct logging. Configure them from one thread at a time; every thread-local stream follows their destinations from its next message on.

---

Class Documentation

OpenMS::Logger::LogStream::GuardedRemoval

struct OpenMS::Logger::LogStream::GuardedRemoval

A destination that LogSinkGuard removed from a global stream (see removeForGuard_()), restored with its prefix and id.

Class Members
Size	id = 0
string	prefix
bool	reinsert = false

Member Typedef Documentation

StreamIterator

typedef std::list<LogStreamBuf::StreamStruct>::iterator StreamIterator

private

Constructor & Destructor Documentation

LogStream()

LogStream	(	LogStreamBuf *	buf = nullptr,
		bool	delete_buf = true,
		std::ostream *	stream = nullptr
	)

Creates a new LogStream object that is not associated with any stream. If the argument stream is set to an output stream (e.g. cout) all output is send to that stream.

Parameters

[in]	buf
[in]	delete_buf
[in]	stream

~LogStream()

~LogStream ( )

override

Clears all message buffers.

Member Function Documentation

bound_()

bool bound_ ( ) const

private

detachLocked_()

GuardedRemoval detachLocked_ ( std::ostream &  s )

private

Removes s from the destinations (for a thread-local stream: hides inherited ones) and returns what it removed. The caller holds the sink mutex.

drain_()

void drain_ ( )

private

Writes pending text (also an incomplete line) and repeat counts to the current destinations.

findStream_()

StreamIterator findStream_ ( const std::ostream &  stream )

private

flush()

void flush

(

)

flushIncomplete()

void flushIncomplete

(

)

Flush any incomplete line (text not terminated by newline) to all streams.

This is useful for thread-local logging where the buffer needs to be flushed before streams are reconfigured globally.

followParent_()

void followParent_ ( )

private

For a thread-local stream: applies changes of the global destinations made since the last call, see updateState_()

getLevel()

std::string getLevel

(

)

Returns the LogLevel of this LogStream

hasStream()

bool hasStream

(

std::ostream &

stream

)

Is stream currently one of this LogStream's output destinations?

hasStream_()

bool hasStream_ ( std::ostream &  stream )

private

insert()

void insert

(

std::ostream &

s

)

Associate a new stream with this logstream. This method inserts a new stream into the list of associated streams and sets the corresponding minimum and maximum log levels. Any message that is subsequently logged, will be copied to this stream if its log level is between min_level and max_level. If min_level and max_level are omitted, all messages are copied to this stream. If min_level and max_level are equal, this function can be used to listen to a specified channel.

Parameters

[in]

s

a reference to the stream to be associated

operator->()

LogStreamBuf * operator->

(

)

Arrow operator.

rdbuf()

LogStreamBuf * rdbuf

(

)

rdbuf method of ostream. This method is needed to access the LogStreamBuf object.

See also

std::ostream::rdbuf for more details.

remove()

void remove

(

std::ostream &

s

)

Remove an association with a stream.

Remove a stream from the stream list and avoid the copying of new messages to this stream.

If the stream was not in the list of associated streams nothing will happen.

Parameters

[in]

s

the stream to be removed

removeAllStreams()

void removeAllStreams

(

)

Remove all streams associated to this LogStream, effectively silencing it.

Flushes all buffers to ensure any pending log messages are written to their respective streams before they are removed.

removeForGuard_()

GuardedRemoval removeForGuard_ ( std::ostream &  s )

private

For LogSinkGuard: on a thread-local stream, suppresses s until restoreForGuard_(); on a global stream, removes it. Pending text and repeat counts go to the current destinations first; for a global stream also those of the calling thread's thread-local stream of the same level, which follows it.

restoreForGuard_()

void restoreForGuard_ ( std::ostream &  s, const GuardedRemoval &  removal  )

private

Undoes removeForGuard_(). Text pending since then goes to the destinations without s first. A thread-local stream then has the destinations it would have without the guard; a global stream gets s back unless it was inserted again.

setLevel()

void setLevel

(

std::string

level

)

Set the level of the LogStream

Parameters

[in]

level

The new LogLevel

setPrefix() [1/2]

void setPrefix	(	const std::ostream &	s,
		const std::string &	prefix
	)

Set prefix for output to this stream. Each line written to the stream will be prefixed by this string. The string may also contain trivial format specifiers to include loglevel and time/date of the logged message.

The following format tags are recognized:

• y message type ("Error", "Warning", "Information", "-")
• T time (HH:MM:SS)
• t time in short format (HH:MM)
• D date (YYYY/MM/DD)
• d date in short format (MM/DD)
• S time and date (YYYY/MM/DD, HH:MM:SS)
• s time and date in short format (MM/DD, HH:MM)
• %% percent sign (escape sequence)

Parameters

[in]	s	The stream that will be prefixed.
[in]	prefix	The prefix used for the stream.

setPrefix() [2/2]

void setPrefix

(

const std::string &

prefix

)

Set prefix of all output streams, details see setPrefix method with ostream.

threadLocalFollower_()

LogStream * threadLocalFollower_ ( )

private

For a global stream: the calling thread's thread-local stream of the same level, or nullptr.

updateState_()

void updateState_ ( )

private

For a thread-local stream: sets badbit while it has no destination, so that operator<< does not format messages that would be discarded anyway, and clears the state once it has a destination again. Global streams are left as they are; a thread-local stream is used by its own thread only.

Friends And Related Symbol Documentation

LogSinkGuard

friend class LogSinkGuard

friend

ThreadLocalLogAccess

friend struct ThreadLocalLogAccess

friend

Lets the thread-local accessors (getThreadLocalLog*()) call followParent_() on each use.

Member Data Documentation

delete_buffer_

bool delete_buffer_

private

flag needed by the destructor to decide whether the streambuf has to be deleted. If the default ctor is used to create the LogStreamBuf, delete_buffer_ is set to true and the ctor also deletes the buffer.