ROSE  0.9.10.103
Public Member Functions | Protected Member Functions | Protected Attributes | List of all members
Sawyer::Message::UnformattedSink Class Reference

Description

Base class for final destinations that are free-format.

These are destinations that emit messages as strings.

Definition at line 1157 of file Message.h.

#include <Message.h>

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

Public Member Functions

virtual std::string maybeTerminatePrior (const Mesg &, const MesgProps &)
 Support function for emitting a message. More...
 
virtual std::string maybePrefix (const Mesg &, const MesgProps &)
 Support function for emitting a message. More...
 
virtual std::string maybeBody (const Mesg &, const MesgProps &)
 Support function for emitting a message. More...
 
virtual std::string maybeFinal (const Mesg &, const MesgProps &)
 Support function for emitting a message. More...
 
virtual std::string render (const Mesg &, const MesgProps &)
 Support function for emitting a message. More...
 
GangPtr gang () const
 Property: sink gang. More...
 
UnformattedSinkPtr gang (const GangPtr &g)
 Property: sink gang. More...
 
bool partialMessagesAllowed () const
 Property: allow partial message output. More...
 
UnformattedSinkPtr partialMessagesAllowed (bool)
 Property: allow partial message output. More...
 
PrefixPtr prefix () const
 Property: how to generate message prefixes. More...
 
UnformattedSinkPtr prefix (const PrefixPtr &p)
 Property: how to generate message prefixes. More...
 
- Public Member Functions inherited from Sawyer::Message::Destination
virtual void bakeDestinations (const MesgProps &, BakedDestinations &baked)
 Bakes message properties according to the plumbing lattice. More...
 
virtual void post (const Mesg &, const MesgProps &bakedProperties)=0
 Causes a message to be emitted. More...
 
MesgProps mergePropertiesNS (const MesgProps &props)
 Merge properties of this lattice node into the specified properties. More...
 
const MesgPropsdefaultPropertiesNS () const
 Default values for message properties. More...
 
MesgPropsdefaultPropertiesNS ()
 Default values for message properties. More...
 
const MesgPropsoverridePropertiesNS () const
 Overrides message properties. More...
 
MesgPropsoverridePropertiesNS ()
 Overrides message properties. More...
 
- Public Member Functions inherited from Sawyer::SharedObject
 SharedObject ()
 Default constructor. More...
 
 SharedObject (const SharedObject &)
 Copy constructor. More...
 
virtual ~SharedObject ()
 Virtual destructor. More...
 
SharedObjectoperator= (const SharedObject &)
 Assignment. More...
 
- Public Member Functions inherited from Sawyer::SharedFromThis< Destination >
SharedPointer< Destination > sharedFromThis ()
 Create a shared pointer from this. More...
 
SharedPointer< const Destination > sharedFromThis () const
 Create a shared pointer from this. More...
 

Protected Member Functions

 UnformattedSink (const PrefixPtr &prefix)
 Constructor for derived classes. More...
 
void gangInternal (const GangPtr &g)
 Cause this sink to be coordinated with others. More...
 

Protected Attributes

bool partialMessagesAllowed_
 
- Protected Attributes inherited from Sawyer::Message::Destination
Sawyer::SynchronizationTraits< Sawyer::SingleThreadedTag >::RecursiveMutex mutex_
 Mutex protecting data members here and in subclasses. More...
 
MesgProps dflts_
 Default properties merged into each incoming message. More...
 
MesgProps overrides_
 Override properties applied to incoming message. More...
 

Constructor & Destructor Documentation

Sawyer::Message::UnformattedSink::UnformattedSink ( const PrefixPtr prefix)
inlineexplicitprotected

Constructor for derived classes.

Non-subclass users should use instance factory methods instead.

Definition at line 1168 of file Message.h.

References Sawyer::Message::Gang::instance(), and Sawyer::Message::Prefix::instance().

Member Function Documentation

GangPtr Sawyer::Message::UnformattedSink::gang ( ) const

Property: sink gang.

Message sinks use a gang to coordinate their output. For instance, two sinks that both write to the same file should share the same gang. A shared gang can also be used for sinks that write to two different locations that both happen to be visible collectively, such as when writing to standard error and standard output when both are writing to the terminal or when both have been redirected to the same file. Not all sinks support automatically choosing the correct gang (e.g., C++ std::ofstream doesn't have the necessary capabilities), so it must be chosen manually sometimes for the output to be coordinated. See Gang::instanceForId() and Gang::instanceForTty().

Thread safety: This method is thread-safe.

UnformattedSinkPtr Sawyer::Message::UnformattedSink::gang ( const GangPtr g)

Property: sink gang.

Message sinks use a gang to coordinate their output. For instance, two sinks that both write to the same file should share the same gang. A shared gang can also be used for sinks that write to two different locations that both happen to be visible collectively, such as when writing to standard error and standard output when both are writing to the terminal or when both have been redirected to the same file. Not all sinks support automatically choosing the correct gang (e.g., C++ std::ofstream doesn't have the necessary capabilities), so it must be chosen manually sometimes for the output to be coordinated. See Gang::instanceForId() and Gang::instanceForTty().

Thread safety: This method is thread-safe.

bool Sawyer::Message::UnformattedSink::partialMessagesAllowed ( ) const

Property: allow partial message output.

If partial messages are not allowed, then a message is emitted only when its terminating linefeed is encountered. The default for unformatted sinks is to allow partial message output. Disabling partial message output is sometimes useful in multi-threaded applications to prevent two threads from competing with each other when they both try to output a complete message at the same time: one thread might interrupt the other midway through the other's message, in which case the other thread would have emitted a partial message. I.e., disabling partial messages works like this:

concurrently {
mlog0[INFO] <<"message from first thread\n";
mlog1[INFO] <<"message from second thread\n";
}

If mlog0 and mlog1 are both emitting to standard error then the output might look like this (sans prefixes):

mlog0[INFO]: message from fir...
mlog1[INFO]: message from second thread
mlog0[INFO]: message from first thread

Disabling partial message output would have prevented the first partial message.

UnformattedSinkPtr Sawyer::Message::UnformattedSink::partialMessagesAllowed ( bool  )

Property: allow partial message output.

If partial messages are not allowed, then a message is emitted only when its terminating linefeed is encountered. The default for unformatted sinks is to allow partial message output. Disabling partial message output is sometimes useful in multi-threaded applications to prevent two threads from competing with each other when they both try to output a complete message at the same time: one thread might interrupt the other midway through the other's message, in which case the other thread would have emitted a partial message. I.e., disabling partial messages works like this:

concurrently {
mlog0[INFO] <<"message from first thread\n";
mlog1[INFO] <<"message from second thread\n";
}

If mlog0 and mlog1 are both emitting to standard error then the output might look like this (sans prefixes):

mlog0[INFO]: message from fir...
mlog1[INFO]: message from second thread
mlog0[INFO]: message from first thread

Disabling partial message output would have prevented the first partial message.

PrefixPtr Sawyer::Message::UnformattedSink::prefix ( ) const

Property: how to generate message prefixes.

This is a pointer to the object that is responsible for generating the string that appears at the beginning of each line and usually contains such things as the program and importance level.

Thread safety: This method is thread-safe.

UnformattedSinkPtr Sawyer::Message::UnformattedSink::prefix ( const PrefixPtr p)

Property: how to generate message prefixes.

This is a pointer to the object that is responsible for generating the string that appears at the beginning of each line and usually contains such things as the program and importance level.

Thread safety: This method is thread-safe.

virtual std::string Sawyer::Message::UnformattedSink::maybeTerminatePrior ( const Mesg ,
const MesgProps  
)
virtual

Support function for emitting a message.

This string terminates the previous partial message from the same gang. This method must be called exactly once during render for its possible side effects, although the return value doesn't have to be used.

Thread safety: not thread-safe. However, it is usually only called from inside render after locks for this object and the gang have been obtained.

virtual std::string Sawyer::Message::UnformattedSink::maybePrefix ( const Mesg ,
const MesgProps  
)
virtual

Support function for emitting a message.

This string is the prefix generated by calling Prefix::toString if a prefix is necessary. This method must be called exactly once during render for its possible side effects, although the return value doesn't have to be used.

Thread safety: not thread-safe. However, it is usually only called from inside render after locks for this object and the gang have been obtained.

virtual std::string Sawyer::Message::UnformattedSink::maybeBody ( const Mesg ,
const MesgProps  
)
virtual

Support function for emitting a message.

This string is the message body, or at least the part of the body that hasn't been emitted yet. This method must be called exactly once during render for its possible side effects, although the return value doesn't have to be used.

Thread safety: not thread-safe. However, it is usually only called from inside render after locks for this object and the gang have been obtained.

virtual std::string Sawyer::Message::UnformattedSink::maybeFinal ( const Mesg ,
const MesgProps  
)
virtual

Support function for emitting a message.

This string is the message termination, interruption, or cancelation and the following line termination as necessary. This method must be called exactly once during render for its possible side effects, although the return value doesn't have to be used.

Thread safety: not thread-safe. However, it is usually only called from inside render after locks for this object and the gang have been obtained.

virtual std::string Sawyer::Message::UnformattedSink::render ( const Mesg ,
const MesgProps  
)
virtual

Support function for emitting a message.

The return string is constructed by calling maybeTerminatePrior, maybePrefix, maybeBody, and maybeFinal one time each (because some of them have side effects).

Thread safety: This method is thread safe. It obtains and holds locks for this object and the gang across all the calls to maybeTerminatePrior, maybePrefix, maybeBody, and maybeFinal.

void Sawyer::Message::UnformattedSink::gangInternal ( const GangPtr g)
protected

Cause this sink to be coordinated with others.

Thread safety: This method is thread-safe.


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