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

Description

Collection of streams.

This forms a collection of message streams for a software component and contains one stream per message importance level. A facility is intended to be used by a software component at whatever granularity is desired by the author (program, name space, class, method, etc.) and is usually given a string name that is related to the software component which it serves. The string name becomes part of messages and is also the default name used by Facilities::control. The name follows a particular syntax described below. All message streams created for the facility are given the same name, message prefix generator, and message sink, but they can be adjusted later on a per-stream basis.

The C++ name for the facility is often just "mlog" or "logger" (appropriately scoped) so that code to emit messages is self documenting. The name "log" is sometimes used, but can be ambiguous with the ::log function in math.h.

The string name for the facility follows a particular syntax: the name is composed of one or more components separated from one another by separators. Each component contains one or more letters, digits, and underscores. A separator is a dot ("."), one or two colons (":" or "::"), or a hyphen ("-").

mlog[ERROR] <<"I got an error\n";

Thread safety: This object is thread-safe except where noted.

Definition at line 1606 of file Message.h.

#include <Message.h>

Public Member Functions

 Facility ()
 Construct an empty facility. More...
 
 Facility (const Facility &other)
 Construct a new facility from an existing facility. More...
 
Facilityoperator= (const Facility &src)
 Assignment operator. More...
 
 Facility (const std::string &name, const DestinationPtr &destination)
 
Facilityinitialize (const std::string &name)
 Initializes this facility with default destinations. More...
 
Facilityinitialize (const std::string &name, const DestinationPtr &destination)
 Initialize all streams with specified destination.
 
bool isConstructed () const
 Returns true if called on an object that has been constructed. More...
 
std::string name () const
 Return the name of the facility. More...
 
FacilityrenameStreams (const std::string &name="")
 Renames all the facility streams. More...
 
FacilityinitStreams (const DestinationPtr &)
 Cause all streams to use the specified destination. More...
 
Streamget (Importance imp)
 Returns a stream for the specified importance level. More...
 
Streamoperator[] (Importance imp)
 Returns a stream for the specified importance level. More...
 
std::string comment () const
 Property: Comment associated with facility. More...
 
Facilitycomment (const std::string &)
 Property: Comment associated with facility. More...
 

Static Public Member Functions

static bool isValidName (const std::string &)
 Tests whether a name is valie. More...
 

Static Protected Member Functions

static std::vector< std::string > parseName (const std::string &)
 

Constructor & Destructor Documentation

◆ Facility() [1/2]

Sawyer::Message::Facility::Facility ( )
inline

Construct an empty facility.

The facility will have no name and all streams will be uninitialized. Any attempt to emit anything to a facility in the default state will cause an std::runtime_error to be thrown with a message similar to "stream INFO is not initialized yet". This facility can be initialized by assigning it a value from another initialized facility.

Definition at line 1621 of file Message.h.

◆ Facility() [2/2]

Sawyer::Message::Facility::Facility ( const Facility other)

Construct a new facility from an existing facility.

The new facility will point to the same streams as the existing facility.

Member Function Documentation

◆ operator=()

Facility& Sawyer::Message::Facility::operator= ( const Facility src)

Assignment operator.

The destination facility will point to the same streams as the source facility.

◆ initialize()

Facility& Sawyer::Message::Facility::initialize ( const std::string &  name)

Initializes this facility with default destinations.

All streams are enabled and all output goes to file descriptor 2 (standard error) via unbuffered system calls.

◆ isConstructed()

bool Sawyer::Message::Facility::isConstructed ( ) const
inline

Returns true if called on an object that has been constructed.

Returns true if this is constructed, false if it's allocated but not constructed. For instance, this method may return false if the object is declared at namespace scope and this method is called before the C++ runtime has had a chance to initialize it.

Thread safety: This method is not thread-safe.

Definition at line 1656 of file Message.h.

◆ get()

Stream& Sawyer::Message::Facility::get ( Importance  imp)

Returns a stream for the specified importance level.

It is permissible to do the following:

Stream m1 = (mlog[INFO] <<"message 1 part 1");
Stream m2 = (mlog[INFO] <<"message 2 part 1");
m1 <<" part 2\n";
m2 <<" part 2\n";

Thread safety: This method is thread-safe.

◆ operator[]()

Stream& Sawyer::Message::Facility::operator[] ( Importance  imp)
inline

Returns a stream for the specified importance level.

It is permissible to do the following:

Stream m1 = (mlog[INFO] <<"message 1 part 1");
Stream m2 = (mlog[INFO] <<"message 2 part 1");
m1 <<" part 2\n";
m2 <<" part 2\n";

Thread safety: This method is thread-safe.

Definition at line 1673 of file Message.h.

◆ isValidName()

static bool Sawyer::Message::Facility::isValidName ( const std::string &  )
static

Tests whether a name is valie.

Returns true if the specified string satisfies the requirements for being a valid facility name.

◆ name()

std::string Sawyer::Message::Facility::name ( ) const

Return the name of the facility.

This is a read-only field initialized at construction time.

Thread safety: This method is thread-safe.

◆ comment() [1/2]

std::string Sawyer::Message::Facility::comment ( ) const

Property: Comment associated with facility.

The comment should be a single-line string without terminating punctuation (for consistency, although not enforced). The comment is printed as part of the output when listing the facility names.

Thread safety: This method is thread-safe.

◆ comment() [2/2]

Facility& Sawyer::Message::Facility::comment ( const std::string &  )

Property: Comment associated with facility.

The comment should be a single-line string without terminating punctuation (for consistency, although not enforced). The comment is printed as part of the output when listing the facility names.

Thread safety: This method is thread-safe.

◆ renameStreams()

Facility& Sawyer::Message::Facility::renameStreams ( const std::string &  name = "")

Renames all the facility streams.

Invokes Stream::facilityName for each stream. If a name is given then that name is used, otherwise this facility's name is used.

Thread safety: This method is thread-safe.

◆ initStreams()

Facility& Sawyer::Message::Facility::initStreams ( const DestinationPtr )

Cause all streams to use the specified destination.

This can be called for facilities that already have streams and destinations, but it can also be called to initialize the streams for a default-constructed facility.

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::INFO
@ INFO
Informative messages.
Definition: Message.h:326
Sawyer::Message::ERROR
@ ERROR
Error messages that indicate an abnormal situation from which the program was able to at least partia...
Definition: Message.h:330