Description
Base class for final destinations that are free-format.
These are destinations that emit messages as strings.
#include <Sawyer/Message.h>
Public Member Functions | |
| virtual std::string | maybeTerminatePrior (const Mesg &, const MesgProps &) |
| Support function for emitting a message. | |
| virtual std::string | maybePrefix (const Mesg &, const MesgProps &) |
| Support function for emitting a message. | |
| virtual std::string | maybeBody (const Mesg &, const MesgProps &) |
| Support function for emitting a message. | |
| virtual std::string | maybeFinal (const Mesg &, const MesgProps &) |
| Support function for emitting a message. | |
| virtual std::string | render (const Mesg &, const MesgProps &) |
| Support function for emitting a message. | |
| GangPtr | gang () const |
| Property: sink gang. | |
| UnformattedSinkPtr | gang (const GangPtr &g) |
| Property: sink gang. | |
| bool | partialMessagesAllowed () const |
| Property: allow partial message output. | |
| UnformattedSinkPtr | partialMessagesAllowed (bool) |
| Property: allow partial message output. | |
| PrefixPtr | prefix () const |
| Property: how to generate message prefixes. | |
| UnformattedSinkPtr | prefix (const PrefixPtr &p) |
| Property: how to generate message prefixes. | |
 Public Member Functions inherited from Sawyer::Message::Destination | |
| virtual void | bakeDestinations (const MesgProps &, BakedDestinations &baked) |
| Bakes message properties according to the plumbing lattice. | |
| virtual void | post (const Mesg &, const MesgProps &bakedProperties)=0 |
| Causes a message to be emitted. | |
| MesgProps | mergePropertiesNS (const MesgProps &props) |
| Merge properties of this lattice node into the specified properties. | |
| const MesgProps & | defaultPropertiesNS () const |
| Default values for message properties. | |
| MesgProps & | defaultPropertiesNS () |
| Default values for message properties. | |
| const MesgProps & | overridePropertiesNS () const |
| Overrides message properties. | |
| MesgProps & | overridePropertiesNS () |
| Overrides message properties. | |
| Public Member Functions inherited from Sawyer::SharedObject | |
| SharedObject () | |
| Default constructor. | |
| SharedObject (const SharedObject &) | |
| Copy constructor. | |
| virtual | ~SharedObject () |
| Virtual destructor. | |
| SharedObject & | operator= (const SharedObject &) |
| Assignment. | |
| Public Member Functions inherited from Sawyer::SharedFromThis< Destination > | |
| SharedPointer< Destination > | sharedFromThis () |
Create a shared pointer from this. | |
| SharedPointer< const Destination > | sharedFromThis () const |
Create a shared pointer from this. | |
Protected Member Functions | |
| UnformattedSink (const PrefixPtr &prefix) | |
| Constructor for derived classes. | |
| void | gangInternal (const GangPtr &g) |
| Cause this sink to be coordinated with others. | |
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. | |
| MesgProps | dflts_ |
| Default properties merged into each incoming message. | |
| MesgProps | overrides_ |
| Override properties applied to incoming message. | |
Constructor & Destructor Documentation
◆ UnformattedSink()
|
inlineexplicitprotected |
Member Function Documentation
◆ gang() [1/2]
| 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.
◆ gang() [2/2]
| 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.
◆ partialMessagesAllowed() [1/2]
| 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:
If mlog0 and mlog1 are both emitting to standard error then the output might look like this (sans prefixes):
Disabling partial message output would have prevented the first partial message.
◆ partialMessagesAllowed() [2/2]
| 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:
If mlog0 and mlog1 are both emitting to standard error then the output might look like this (sans prefixes):
Disabling partial message output would have prevented the first partial message.
◆ prefix() [1/2]
| 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.
◆ prefix() [2/2]
| 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.
◆ maybeTerminatePrior()
|
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.
◆ maybePrefix()
|
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.
◆ maybeBody()
|
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.
◆ maybeFinal()
|
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.
◆ render()
|
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.
◆ gangInternal()
|
protected |
Cause this sink to be coordinated with others.
Thread safety: This method is thread-safe.
Member Data Documentation
◆ partialMessagesAllowed_
|
protected |
The documentation for this class was generated from the following file:
