ROSE  0.11.96.11
Public Member Functions | Protected Member Functions | List of all members
Sawyer::Message::Stream Class Reference

Description

Converts text to messages.

A message stream is a subclass of std::ostream and therefore allows all the usual stream insertion operators (<<). A stream converts each line of output text to a single message, creating the message with properties defined for the stream and sending the results to a specified destination. Streams typically impart a facility name and importance level to each message via the stream's properties.

Definition at line 1396 of file Message.h.

#include <Message.h>

Inheritance diagram for Sawyer::Message::Stream:
Inheritance graph
[legend]
Collaboration diagram for Sawyer::Message::Stream:
Collaboration graph
[legend]

Public Member Functions

 Stream (const std::string facilityName, Importance imp, const DestinationPtr &destination)
 Construct a stream and initialize its name and importance properties.
 
 Stream (const MesgProps &props, const DestinationPtr &destination)
 Construct a stream and initialize its properties as specified.
 
 Stream (const Stream &other)
 Construct a new stream from an existing stream. More...
 
Streamoperator= (const Stream &other)
 Initialize this stream from another stream. More...
 
 Stream (const std::ostream &other_)
 Copy constructor with dynamic cast. More...
 
Streamoperator= (const std::ostream &other_)
 Assignment with dynamic cast. More...
 
void incrementRefCount ()
 
size_t decrementRefCount ()
 
SProxy dup () const
 Used for partial messages when std::move is missing. More...
 
bool enabled () const
 Returns true if a stream is enabled. More...
 
bool operator! () const
 Returns false if this stream is enabled.
 
MesgProps properties () const
 Return the default properties for this stream. More...
 
 operator void * () const
 Returns true if this stream is enabled. More...
 
 operator bool () const
 Returns true if this stream is enabled. More...
 
void enable (bool b=true)
 Enable or disable a stream. More...
 
void disable ()
 Enable or disable a stream. More...
 
void completionString (const std::string &s, bool asDefault=true)
 Set message or stream property. More...
 
void interruptionString (const std::string &s, bool asDefault=true)
 Set message or stream property. More...
 
void cancelationString (const std::string &s, bool asDefault=true)
 Set message or stream property. More...
 
void facilityName (const std::string &s, bool asDefault=true)
 Set message or stream property. More...
 
DestinationPtr destination () const
 Property: message destination. More...
 
Streamdestination (const DestinationPtr &d)
 Property: message destination. More...
 

Protected Member Functions

void initFromNS (const Stream &other)
 Initiaize this stream from other. More...
 

Constructor & Destructor Documentation

◆ Stream() [1/2]

Sawyer::Message::Stream::Stream ( const Stream other)

Construct a new stream from an existing stream.

If other has a pending message then ownership of that message is moved to this new stream.

Thread safety: This method is thread-safe.

◆ Stream() [2/2]

Sawyer::Message::Stream::Stream ( const std::ostream &  other_)

Copy constructor with dynamic cast.

Same as Stream(const Stream&) but declared so we can do things like this:

Stream m1(mlog[INFO] <<"first part of the message");
m1 <<"; finalize message\n";

Thread safety: This method is thread-safe.

Member Function Documentation

◆ operator=() [1/2]

Stream& Sawyer::Message::Stream::operator= ( const Stream other)

Initialize this stream from another stream.

If other has a pending message then ownership of that message is moved to this stream.

Thread safety: This method is thread-safe.

◆ operator=() [2/2]

Stream& Sawyer::Message::Stream::operator= ( const std::ostream &  other_)

Assignment with dynamic cast.

Same as operator=(const Stream&) but declared so we can do things like this:

Stream m1 = mlog[INFO] <<"first part of the message");
m1 <<"; finalize message\n";

Thread safety: This method is thread-safe.

◆ dup()

SProxy Sawyer::Message::Stream::dup ( ) const

Used for partial messages when std::move is missing.

Thread safety: This method is thread-safe.

◆ initFromNS()

void Sawyer::Message::Stream::initFromNS ( const Stream other)
protected

Initiaize this stream from other.

This stream will get its own StreamBuf (if it doesn't have one already), and any pending message from other will be moved (not copied) to this stream.

Thread safety: This method is not thread-safe–the caller is expected to obtain the necessary locks.

◆ enabled()

bool Sawyer::Message::Stream::enabled ( ) const

Returns true if a stream is enabled.

Thread safety: This method is thread-safe.

◆ operator void *()

Sawyer::Message::Stream::operator void * ( ) const
inline

Returns true if this stream is enabled.

This implicit conversion to bool can be used to conveniently avoid expensive insertion operations when a stream is disabled. For example, if printing MemoryMap is an expensive operation then the logging can be written any of these ways to avoid formatting memorymap when logging is disabled:

if (mlog[DEBUG])
mlog[DEBUG] <<"the memory map is: " <<memoryMap <<"\n";
mlog[DEBUG] && mlog[DEBUG] <<"the memory map is: " <<memoryMap <<"\n";
SAWYER_MESG(mlog[DEBUG]) <<"the memory map is: " <<memoryMap <<"\n";

The SAWYER_MESG_FIRST macro is similar in that it short circuits, but it prints to the first stream that's enabled For example, these two are equivalent:

if (mlog[TRACE] || mlog[DEBUG])
(mlog[TRACE] ? mlog[TRACE] : mlog[DEBUG]) <<"got here\n";
SAWYER_MESG_FIRST(mlog[TRACE], mlog[DEBUG]) <<"got here\n";

Thread safety: This method is thread-safe.

Definition at line 1506 of file Message.h.

◆ operator bool()

Sawyer::Message::Stream::operator bool ( ) const
inline

Returns true if this stream is enabled.

This implicit conversion to bool can be used to conveniently avoid expensive insertion operations when a stream is disabled. For example, if printing MemoryMap is an expensive operation then the logging can be written any of these ways to avoid formatting memorymap when logging is disabled:

if (mlog[DEBUG])
mlog[DEBUG] <<"the memory map is: " <<memoryMap <<"\n";
mlog[DEBUG] && mlog[DEBUG] <<"the memory map is: " <<memoryMap <<"\n";
SAWYER_MESG(mlog[DEBUG]) <<"the memory map is: " <<memoryMap <<"\n";

The SAWYER_MESG_FIRST macro is similar in that it short circuits, but it prints to the first stream that's enabled For example, these two are equivalent:

if (mlog[TRACE] || mlog[DEBUG])
(mlog[TRACE] ? mlog[TRACE] : mlog[DEBUG]) <<"got here\n";
SAWYER_MESG_FIRST(mlog[TRACE], mlog[DEBUG]) <<"got here\n";

Thread safety: This method is thread-safe.

Definition at line 1515 of file Message.h.

◆ enable()

void Sawyer::Message::Stream::enable ( bool  b = true)

Enable or disable a stream.

A disabled stream buffers the latest partial message and enabling the stream will cause the entire accumulated message to be emitted–whether the partial message immediately appears on the output is up to the message sinks.

Thread safety: This method is thread-safe.

◆ disable()

void Sawyer::Message::Stream::disable ( )
inline

Enable or disable a stream.

A disabled stream buffers the latest partial message and enabling the stream will cause the entire accumulated message to be emitted–whether the partial message immediately appears on the output is up to the message sinks.

Thread safety: This method is thread-safe.

Definition at line 1541 of file Message.h.

◆ completionString()

void Sawyer::Message::Stream::completionString ( const std::string &  s,
bool  asDefault = true 
)

Set message or stream property.

If asDefault is false then the property is set only in the current message and the message must be empty (e.g., just after the previous message was completed). When asDefault is true the new value becomes the default for all future messages. The default also affects the current message if the current message is empty.

Thread safety: This method is thread-safe.

◆ interruptionString()

void Sawyer::Message::Stream::interruptionString ( const std::string &  s,
bool  asDefault = true 
)

Set message or stream property.

If asDefault is false then the property is set only in the current message and the message must be empty (e.g., just after the previous message was completed). When asDefault is true the new value becomes the default for all future messages. The default also affects the current message if the current message is empty.

Thread safety: This method is thread-safe.

◆ cancelationString()

void Sawyer::Message::Stream::cancelationString ( const std::string &  s,
bool  asDefault = true 
)

Set message or stream property.

If asDefault is false then the property is set only in the current message and the message must be empty (e.g., just after the previous message was completed). When asDefault is true the new value becomes the default for all future messages. The default also affects the current message if the current message is empty.

Thread safety: This method is thread-safe.

◆ facilityName()

void Sawyer::Message::Stream::facilityName ( const std::string &  s,
bool  asDefault = true 
)

Set message or stream property.

If asDefault is false then the property is set only in the current message and the message must be empty (e.g., just after the previous message was completed). When asDefault is true the new value becomes the default for all future messages. The default also affects the current message if the current message is empty.

Thread safety: This method is thread-safe.

◆ destination() [1/2]

DestinationPtr Sawyer::Message::Stream::destination ( ) const

Property: message destination.

This is the pointer to the top of the plumbing lattice.

Thread safety: This method is thread-safe.

◆ destination() [2/2]

Stream& Sawyer::Message::Stream::destination ( const DestinationPtr d)

Property: message destination.

This is the pointer to the top of the plumbing lattice.

Thread safety: This method is thread-safe.

◆ properties()

MesgProps Sawyer::Message::Stream::properties ( ) const

Return the default properties for this stream.

These are the properties of the stream itself before they are adjusted by the destination lattice. The default properties are used each time the stream creates a message.

Thread safety: This method is thread-safe.


The documentation for this class was generated from the following file:
Sawyer::Message::mlog
Facility mlog
Facility used by Sawyer components.
Sawyer::Message::DEBUG
@ DEBUG
Messages intended to be useful primarily to the author of the code.
Definition: Message.h:314
Sawyer::Message::TRACE
@ TRACE
Detailed tracing information useful to end-users that are trying to understand program internals.
Definition: Message.h:317
Sawyer::Message::INFO
@ INFO
Informative messages.
Definition: Message.h:326
Sawyer::Message::Stream::Stream
Stream(const std::string facilityName, Importance imp, const DestinationPtr &destination)
Construct a stream and initialize its name and importance properties.