#include <balm_metricregistry.h>

Detailed Description

The class defines a thread-aware mechanism for registering metrics and metric categories. A metric is uniquely identified by its name and category, and the metric registry provides a mapping from those identifying properties to a balm::MetricId. A balm::MetricRegistry object also provides a mapping from a category name to the address of a non-modifiable balm::Category object.

See balm_metricregistry

Public Member Functions
	BSLMF_NESTED_TRAIT_DECLARATION (MetricRegistry, bslma::UsesBslmaAllocator)

	MetricRegistry (bslma::Allocator *basicAllocator=0)

	~MetricRegistry ()

MetricId	addId (const char category, const char name)

MetricId	getId (const char category, const char name)

const Category *	addCategory (const char *category)

const Category *	getCategory (const char *category)

void	setCategoryEnabled (const Category *category, bool value)

void	setAllCategoriesEnabled (bool value)

void	registerCategoryHolder (const Category category, CategoryHolder holder)

void	setPreferredPublicationType (const MetricId &metric, PublicationType::Value type)

void	setFormat (const MetricId &metricId, const MetricFormat &format)

MetricDescription::UserDataKey	createUserDataKey ()

void	setUserData (const MetricId &metricId, MetricDescription::UserDataKey key, const void *value)

void	setUserData (const char categoryName, MetricDescription::UserDataKey key, const void value, bool prefixFlag=false)

bsl::size_t	numMetrics () const

bsl::size_t	numCategories () const

const Category *	findCategory (const char *category) const

MetricId	findId (const char category, const char name) const

void	getAllCategories (bsl::vector< const Category * > *categories) const

bsl::ostream &	print (bsl::ostream &stream, int level=0, int spacesPerLevel=4) const

Constructor & Destructor Documentation

◆ MetricRegistry()

balm::MetricRegistry::MetricRegistry ( bslma::Allocator * basicAllocator = 0 )

Create an empty metric registry. Optionally specify a basicAllocator used to supply memory. If basicAllocator is 0, the currently installed default allocator is used.

◆ ~MetricRegistry()

balm::MetricRegistry::~MetricRegistry ( )

Destroy this metric registry.

Member Function Documentation

◆ addCategory()

const Category * balm::MetricRegistry::addCategory ( const char * category )

Add the specified category to this registry, unless it has already been registered. Return the address of the newly-created non-modifiable balm::Category object on success, and 0 otherwise.

Precondition: The behavior is undefined unless category is null-terminated.

◆ addId()

MetricId balm::MetricRegistry::addId	(	const char *	category,
		const char *	name
	)

Add the specified category and name to this registry, unless it has already been registered, and return a balm::MetricId object identifying the newly-registered metric. If the indicated metric has already been registered, the returned balm::MetricId object will not be valid (i.e., isValid will return false).

Precondition: The behavior is undefined unless category and name are null-terminated.

◆ BSLMF_NESTED_TRAIT_DECLARATION()

balm::MetricRegistry::BSLMF_NESTED_TRAIT_DECLARATION	(	MetricRegistry	,
		bslma::UsesBslmaAllocator
	)

◆ createUserDataKey()

MetricDescription::UserDataKey balm::MetricRegistry::createUserDataKey ( )

Return a new unique key that can be used to associate (via setUserData) and retrieve (via userData) a value with a metric (or group of metrics).

Note: Note that the returned key can be used by clients of balm to associate additional information with a metric.

◆ findCategory()

const Category * balm::MetricRegistry::findCategory ( const char * category ) const

Find the specified category, a null-terminated string, in this registry. Return the address of the non-modifiable balm::Category object corresponding to the category, or 0 if no such category has been registered.

◆ findId()

MetricId balm::MetricRegistry::findId	(	const char *	category,
		const char *	name
	)		const

Find the specified null-terminated strings category and name in this registry. Return the balm::MetricId object corresponding to the metric having the category and name, if found, or an invalid metric id if no such metric has been registered (i.e., isValid will return false).

◆ getAllCategories()

void balm::MetricRegistry::getAllCategories ( bsl::vector< const Category * > * categories ) const

Append to the specified categories the addresses of all the categories registered by this balm::MetricRegistry object.

◆ getCategory()

const Category * balm::MetricRegistry::getCategory ( const char * category )

Return the address of the non-modifiable balm::Category object for the specified category. If no corresponding category exists, register a new category and return the address of the newly-created balm::Category object.

Precondition: The behavior is undefined unless category is null-terminated.

Note: Note that this operation is guaranteed to return a valid address.

◆ getId()

MetricId balm::MetricRegistry::getId	(	const char *	category,
		const char *	name
	)

Return a balm::MetricId object for the metric identified by the specified category and name. If no corresponding metric has already been registered, register a new metric and return a balm::MetricId object identifying that newly-registered metric.

Precondition: The behavior is undefined unless category and name are null-terminated.

Note: Note that this operation is guaranteed to return a valid balm::MetricId object.

◆ numCategories()

bsl::size_t balm::MetricRegistry::numCategories ( ) const

Return the number of categories in this registry.

◆ numMetrics()

bsl::size_t balm::MetricRegistry::numMetrics ( ) const

Return the number of metrics in this registry.

◆ print()

bsl::ostream & balm::MetricRegistry::print	(	bsl::ostream &	stream,
		int	level = `0`,
		int	spacesPerLevel = `4`
	)		const

Format this object to the specified output stream at the (absolute value of) the optionally specified indentation level and return a reference to stream. If level is specified, optionally specify spacesPerLevel, the number of spaces per indentation level for this and all of its nested objects. If level is negative, suppress indentation of the first line. If spacesPerLevel is negative, format the entire output on one line, suppressing all but the initial indentation (as governed by level). If stream is not valid on entry, this operation has no effect.

◆ registerCategoryHolder()

void balm::MetricRegistry::registerCategoryHolder	(	const Category *	category,
		CategoryHolder *	holder
	)

Load into the specified holder the address of the specified category, its enabled status, and the address of the next holder in the linked list of category holders maintained by category (prepending holder to the linked list of category holders for category). The supplied category will update the value returned by holder->enabled() when its enabled state changes, and will reset holder (i.e., holder->reset()) when category is destroyed.

Precondition: The behavior is undefined unless holder remains valid and unmodified (by the client) for the lifetime of this object.

This method should not be used directly by client code. It is an implementation detail of the balm metric collection system.

◆ setAllCategoriesEnabled()

void balm::MetricRegistry::setAllCategoriesEnabled ( bool value )

Set whether each currently registered category is enabled to the specified value, and ensure that categories registered after this call are initialized as either enabled or disabled, accordingly. This operation is logically equivalent to iterating over the list of currently registered categories and calling setCategoryEnabled on each category individually, and also setting a default enabled value (for newly-created categories). Hence, subsequent calls setCategoryEnabled will override this value for a particular category.

Note: Note that this operation is thread-safe, but not atomic: Other threads may simultaneously access the current enabled status for registered categories while this operation completes. Also note that this operation has linear runtime performance with respect to the total number of category holders registered with this repository.

◆ setCategoryEnabled()

void balm::MetricRegistry::setCategoryEnabled	(	const Category *	category,
		bool	value
	)

Set whether the specified category is enabled to the specified value.

Precondition: The behavior is undefined unless category is a valid address of a category previously returned by this metric registry.

Note: Note that this operation is thread-safe, but not atomic: Other threads may simultaneously access the current enabled value for category while this operation completes. Also note that this operation has linear runtime performance with respect to the number of registered category holders for category.

◆ setFormat()

void balm::MetricRegistry::setFormat	(	const MetricId &	metricId,
		const MetricFormat &	format
	)

Set the format for the specified metricId to the specified format.

Note: Note that there is no uniform specification for how publisher implementations will interpret the supplied format. Also note that the format for a metric is accessed through the balm::MetricDescription. For example:
metric.description()->format();

◆ setPreferredPublicationType()

void balm::MetricRegistry::setPreferredPublicationType	(	const MetricId &	metric,
		PublicationType::Value	type
	)

Set the preferred publication type of the specified metric to the specified type. The preferred publication type of a metric indicates the preferred aggregate to publish for that metric, or balm::PublicationType::UNSPECIFIED if there is no preference.

Precondition: The behavior is undefined unless metric was previously returned by this metric registry.

Note: Note that there is no uniform definition for how publishers will interpret this value; an UNSPECIFIED value generally indicates that the all the collected aggregates (total, count, minimum, and maximum value) should be published. Also note that the preferred publication type is accessed through the balm::MetricDescription (i.e., metric.description()->preferredPublicationType()).

◆ setUserData() [1/2]

void balm::MetricRegistry::setUserData	(	const char *	categoryName,
		MetricDescription::UserDataKey	key,
		const void *	value,
		bool	prefixFlag = `false`
	)

Associate the specified value with the specified key in any metric belonging to a category having the specified categoryName, or a category whose name begins with categoryName, as determined by the optionally specified prefixFlag. If prefixFlag is false or is not specified, only those metrics belonging to a category having categoryName will be mapped; otherwise, value will be associated with key for all metrics belonging to any category whose name begins with categoryName. This association applies to existing metrics as well as any subsequently created ones. When a metric is created that matches more than one registered category prefix, it is not specified which supplied value will be associated with key, unless only one of those values is non-null, in which case the unique non-null value is used.

Precondition: The behavior is undefined unless key was previously returned from createUserDataKey.

◆ setUserData() [2/2]

void balm::MetricRegistry::setUserData	(	const MetricId &	metricId,
		MetricDescription::UserDataKey	key,
		const void *	value
	)

Associate the specified value with the specified key in the description of the specified metricId.

Precondition: The behavior is undefined unless key was previously returned from createUserDataKey.

Note: Note that this method allows clients of balm to associate (opaque) application-specific information with a metric.

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

balm_metricregistry.h