Description

Collection of facilities.

A facility group is a collection of message facilities that allows its members to be configured collectively, such as from command-line parsing. Each stream can be enabled or disabled individually, a member facility can be enabled or disabled as a whole, or specific importance levels can be enabled or disabled across the entire collection.

Whenever a member facility is enabled as a whole, the current set of enabled importance levels is used. This set is maintained automatically: when the first facility is inserted, its enabled importance levels initialize the default set. Whenever a message importance level is enabled or diabled via the version of enable or disable that takes an importance argument, the set is adjusted.

Thread safety: This object is thread safe.

Definition at line 1736 of file Message.h.

#include <Message.h>

Public Types
typedef std::set< Importance >	ImportanceSet
	A set of importance levels.

Public Member Functions
	Facilities ()
	Constructs an empty container of Facility objects.

	Facilities (const Facilities &)
	Copy constructor.

Facilities &	operator= (const Facilities &)
	Assignment operator.

ImportanceSet	impset () const
	Return the set of default-enabled message importances. More...

Facilities &	impset (Importance, bool enabled)
	Add or remove a default importance level. More...

Facilities &	erase (const std::string &name)
	Remove a facility by name. More...

Facilities &	erase (Facility &facility)
	Remove all occurrences of the facility. More...

Facility &	facility (const std::string &name) const
	Return an existing facility by name. More...

std::vector< std::string >	facilityNames () const
	Return names for all known facilities. More...

std::string	control (const std::string &s)
	Parse a single command-line switch and enable/disable the indicated streams. More...

std::string	configuration () const
	Returns a configuration string. More...

void	shutdown ()
	Reset facilities to initial state. More...

void	print (std::ostream &) const
	Print the list of facilities and their states. More...


Facilities &	insert (Facility &facility, const std::string &name="")
	Register a facility so it can be controlled as part of a collection of facilities. More...

Facilities &	insertAndAdjust (Facility &facility, std::string name="")
	Register a facility so it can be controlled as part of a collection of facilities. More...


Facilities &	reenable ()
	Readjust all member facilities. More...

Facilities &	reenableFrom (const Facilities &other)
	Readjust all member facilities. More...


Facilities &	enable (Importance, bool b=true)
	Enable/disable specific importance level across all facilities. More...

Facilities &	disable (Importance imp)
	Enable/disable specific importance level across all facilities. More...


Facilities &	disable (const std::string &switch_name)
	Enable/disable a facility by name. More...

Facilities &	enable (const std::string &switch_name, bool b=true)
	Enable/disable a facility by name. More...


Facilities &	enable (bool b=true)
	Enable/disable all facilities. More...

Facilities &	disable ()
	Enable/disable all facilities. More...

Member Function Documentation

◆ impset() [1/2]

ImportanceSet Sawyer::Message::Facilities::impset ( ) const

Return the set of default-enabled message importances.

See Facilities class documentation for details.

Thread safety: This method is thread-safe.

◆ impset() [2/2]

Facilities& Sawyer::Message::Facilities::impset	(	Importance	,
		bool	enabled
	)

Add or remove a default importance level.

The specified level is inserted or removed from the set of default enabled importance levels without affecting any member facility objects. If this Facilities doesn't have a default importance set then it is initialized to {WARN, ERROR, FATAL} prior to adding or removing the specified level. Calling this function also prevents the first insert from initializing the set of default importance levels. See Facilities class documentation for details.

Thread safety: This method is thread-safe.

See also: insert, insertAndAdjust, reenable.

◆ insert()

Facilities& Sawyer::Message::Facilities::insert	(	Facility &	facility,
		const std::string &	name = `""`
	)

Register a facility so it can be controlled as part of a collection of facilities.

The optional name is the FACILITY_NAME string of the control language for the inserted facility, and defaults to the facility's name (see control). The name consists of one or more symbols separated by "::", or "." and often corresponds to the source code component that it serves. Names are case-sensitive in the control language. No two facilities in the same facility group may have the same name, but a single facility may appear multiple times in the group with different names.

This method comes in two flavors: insert, and insertAndAdjust. The latter immediately enables and disables the facility's streams according to the current default importance levels of this facility group. If facility is the first facility to be inserted, and it is inserted by insert rather than insertAndAdjust, then the facility's currently enabled streams are used to initialize the set of default enabled importance levels.

The facility is incorporated by reference and should not be destroyed until after this facility group is destroyed.

Thread safety: This method is thread-safe.

◆ insertAndAdjust()

Facilities& Sawyer::Message::Facilities::insertAndAdjust	(	Facility &	facility,
		std::string	name = `""`
	)

Register a facility so it can be controlled as part of a collection of facilities.

The optional name is the FACILITY_NAME string of the control language for the inserted facility, and defaults to the facility's name (see control). The name consists of one or more symbols separated by "::", or "." and often corresponds to the source code component that it serves. Names are case-sensitive in the control language. No two facilities in the same facility group may have the same name, but a single facility may appear multiple times in the group with different names.

This method comes in two flavors: insert, and insertAndAdjust. The latter immediately enables and disables the facility's streams according to the current default importance levels of this facility group. If facility is the first facility to be inserted, and it is inserted by insert rather than insertAndAdjust, then the facility's currently enabled streams are used to initialize the set of default enabled importance levels.

The facility is incorporated by reference and should not be destroyed until after this facility group is destroyed.

Thread safety: This method is thread-safe.

◆ erase() [1/2]

Facilities& Sawyer::Message::Facilities::erase ( const std::string & name )

Remove a facility by name.

Thread safety: This method is thread-safe.

◆ erase() [2/2]

Facilities& Sawyer::Message::Facilities::erase ( Facility & facility )

Remove all occurrences of the facility.

Thread safety: This method is thread-safe.

◆ facility()

Facility& Sawyer::Message::Facilities::facility ( const std::string & name ) const

Return an existing facility by name.

Returns a reference to the specified facility. Throws an std::domain_error if no facility exists with the specified name.

Thread safety: This method is thread safe, but it returns a reference to a facility that could be deleted before it can be used. The caller must ensure that no other thread is invoking the erase method concurrently on this same Facilities object.

◆ facilityNames()

std::vector<std::string> Sawyer::Message::Facilities::facilityNames ( ) const

Return names for all known facilities.

Thread safety: This method is thread-safe.

◆ control()

std::string Sawyer::Message::Facilities::control ( const std::string & s )

Parse a single command-line switch and enable/disable the indicated streams.

Returns an empty string on success, or an error message on failure. No configuration changes are made if a failure occurs.

The control string, s, is a sentence in the following language:

Sentence             := (FacilitiesControl ( ',' FacilitiesControl )* )?
 
FacilitiesControl    := AllFacilitiesControl | NamedFacilityControl
AllFacilitiesControl := StreamControlList
NamedFacilityControl := FACILITY_NAME '(' StreamControlList ')'
 
StreamControlList    := StreamControl ( ',' StreamControl )*
StreamControl        := StreamState? Relation? STREAM_NAME | 'all' | 'none'
StreamState          := '+' | '!'
Relation             := '>=' | '>' | '<=' | '<'

The language is processed left-to-right and stream states are affected immediately. This allows, for instance, turning off all streams and then selectively enabling streams.

Some examples:

all                             // enable all event messages
none,debug                      // turn on only debugging messages
all,!debug                      // turn on all except debugging
fatal                           // make sure fatal errors are enabled (without changing others)
none,<=trace                    // disable all except those less than or equal to 'trace'
 
frontend(debug)                 // enable debugging streams in the 'frontend' facility
warn,frontend(!warn)            // turn on warning messages everywhere except the frontend

The global list, AllFacilitiesControl, also affects the list of default-enabled importance levels.

Thread safety: This method is thread-safe.

◆ configuration()

std::string Sawyer::Message::Facilities::configuration ( ) const

Returns a configuration string.

Returns a string suitable for passing to control.

◆ reenable()

Facilities& Sawyer::Message::Facilities::reenable ( )

Readjust all member facilities.

All members are readjusted to enable only those importance levels that are part of this facility group's default importance levels. It is as if we called disable then enable for each message facility by name. See Facilities class documentation for details.

Thread safety: This method is thread-safe.

See also: impset

◆ reenableFrom()

Facilities& Sawyer::Message::Facilities::reenableFrom ( const Facilities & other )

Readjust all member facilities.

All members are readjusted to enable only those importance levels that are part of this facility group's default importance levels. It is as if we called disable then enable for each message facility by name. See Facilities class documentation for details.

Thread safety: This method is thread-safe.

See also: impset

◆ enable() [1/3]

Facilities& Sawyer::Message::Facilities::enable	(	Importance	,
		bool	b = `true`
	)

Enable/disable specific importance level across all facilities.

This method also affects the set of "current importance levels" used when enabling an entire facility.

Thread safety: This method is thread-safe.

See also: impset

◆ disable() [1/3]

Facilities& Sawyer::Message::Facilities::disable ( Importance imp )

inline

Enable/disable specific importance level across all facilities.

This method also affects the set of "current importance levels" used when enabling an entire facility.

Thread safety: This method is thread-safe.

See also: impset

Definition at line 1900 of file Message.h.

◆ disable() [2/3]

Facilities& Sawyer::Message::Facilities::disable ( const std::string & switch_name )

inline

Enable/disable a facility by name.

When disabling, all importance levels of the specified facility are disabled. When enabling, only the current importance levels are enabled for the facility. If the facility is not found then nothing happens.

Thread safety: This method is thread-safe.

Definition at line 1911 of file Message.h.

◆ enable() [2/3]

Facilities& Sawyer::Message::Facilities::enable	(	const std::string &	switch_name,
		bool	b = `true`
	)

Enable/disable a facility by name.

When disabling, all importance levels of the specified facility are disabled. When enabling, only the current importance levels are enabled for the facility. If the facility is not found then nothing happens.

Thread safety: This method is thread-safe.

◆ enable() [3/3]

Facilities& Sawyer::Message::Facilities::enable ( bool b = true )

Enable/disable all facilities.

When disabling, all importance levels of all facilities are disabled. When enabling, only the current importance levels are enabled for each facility.

Thread safety: This method is thread-safe.

◆ disable() [3/3]

Facilities& Sawyer::Message::Facilities::disable ( )

inline

Enable/disable all facilities.

When disabling, all importance levels of all facilities are disabled. When enabling, only the current importance levels are enabled for each facility.

Thread safety: This method is thread-safe.

Definition at line 1924 of file Message.h.

◆ shutdown()

void Sawyer::Message::Facilities::shutdown ( )

Reset facilities to initial state.

This function resets each referenced Facility object to its default-constructed state in preparation for program exit.

◆ print()

void Sawyer::Message::Facilities::print ( std::ostream & ) const

Print the list of facilities and their states.

This is mostly for debugging purposes. The output may have internal line feeds and will end with a line feed.

Thread safety: This method is thread-safe.

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

Message.h

Description

Public Types

Public Member Functions

Member Function Documentation

◆ impset() [1/2]

◆ impset() [2/2]

◆ insert()

◆ insertAndAdjust()

◆ erase() [1/2]

◆ erase() [2/2]

◆ facility()

◆ facilityNames()

◆ control()

◆ configuration()

◆ reenable()

◆ reenableFrom()

◆ enable() [1/3]

◆ disable() [1/3]

◆ disable() [2/3]

◆ enable() [2/3]

◆ enable() [3/3]

◆ disable() [3/3]

◆ shutdown()

◆ print()