#include <ball_categorymanager.h>

Detailed Description

This class manages a set (or "registry") of categories. Categories may be added to the registry, but they cannot be removed. However, the threshold levels of existing categories may be accessed and modified directly.

See ball_categorymanager

Public Types
typedef CategoryCallbacks::NameFilter	CategoryNameFilterCallback

typedef CategoryCallbacks::DefaultThresholdLevels	DefaultThresholdLevelsCallback

Public Member Functions
	CategoryManager (bslma::Allocator *basicAllocator=0)

	CategoryManager (int defaultRecordLevel, int defaultPassLevel, int defaultTriggerLevel, int defaultTriggerAllLevel, const DefaultThresholdLevelsCallback &defaultThresholdLevelsCallback, const CategoryNameFilterCallback &categoryNameFilterCallback, bslma::Allocator *basicAllocator=0)

	~CategoryManager ()

Category &	operator[] (int index)

Category *	addCategory (const char *categoryName, int recordLevel, int passLevel, int triggerLevel, int triggerAllLevel)

Category *	addCategory (CategoryHolder categoryHolder, const char categoryName, int recordLevel, int passLevel, int triggerLevel, int triggerAllLevel)

Category *	addCategoryHierarchically (const char *categoryName)

void	addDefaultCategory ()

Category &	defaultCategory ()

Category *	lookupCategory (const char *categoryName)

Category *	lookupCategory (CategoryHolder categoryHolder, const char categoryName)

void	resetCategoryHolders ()

void	resetDefaultThresholdLevels ()

const Category *	setCategory (const char *categoryName)

const Category *	setCategory (CategoryHolder categoryHolder, const char categoryName)

Category *	setCategory (const char *categoryName, int recordLevel, int passLevel, int triggerLevel, int triggerAllLevel)

int	setDefaultThresholdLevels (int recordLevel, int passLevel, int triggerLevel, int triggerAllLevel)

void	setDefaultThresholdLevelsCallback (const DefaultThresholdLevelsCallback *defaultThresholdLevelsCallback)

Category *	setThresholdLevels (const char *categoryName, int recordLevel, int passLevel, int triggerLevel, int triggerAllLevel)

int	setThresholdLevelsHierarchically (const char *categoryNamePrefix, int recordLevel, int passLevel, int triggerLevel, int triggerAllLevel)

int	addRule (const Rule &ruleToAdd)

int	addRules (const RuleSet &ruleSet)

int	removeRule (const Rule &ruleToRemove)

int	removeRules (const RuleSet &ruleSet)

void	removeAllRules ()

bslmt::Mutex &	rulesetMutex ()

void	setMaxNumCategories (int length)

template<class t_CATEGORY_VISITOR >
void	visitCategories (const t_CATEGORY_VISITOR &visitor)

const Category &	operator[] (int index) const

const Category &	defaultCategory () const

int	length () const

const Category *	lookupCategory (const char *categoryName) const

int	maxNumCategories () const

const RuleSet &	ruleSet () const

bsls::Types::Int64	ruleSetSequenceNumber () const

void	setCategoryThresholdsToCurrentDefaults (Category *category) const

void	setCategoryThresholdsToFactoryDefaults (Category *category) const

template<class t_CATEGORY_VISITOR >
void	visitCategories (const t_CATEGORY_VISITOR &visitor) const

int	defaultPassThresholdLevel () const

int	defaultRecordThresholdLevel () const

int	defaultTriggerAllThresholdLevel () const

int	defaultTriggerThresholdLevel () const

ThresholdAggregate	defaultThresholdLevels () const

int	thresholdLevelsForNewCategory (ThresholdAggregate levels, const char categoryName) const

Member Typedef Documentation

◆ CategoryNameFilterCallback

typedef CategoryCallbacks::NameFilter ball::CategoryManager::CategoryNameFilterCallback

CategoryNameFilterCallback is the type of the user-supplied functor that translates external category names to internal names.

◆ DefaultThresholdLevelsCallback

typedef CategoryCallbacks::DefaultThresholdLevels ball::CategoryManager::DefaultThresholdLevelsCallback

DefaultThresholdLevelsCallback is the type of the functor that determines default threshold levels for categories added to the registry by the setCategory(const char *) method.

Constructor & Destructor Documentation

◆ CategoryManager() [1/2]

ball::CategoryManager::CategoryManager ( bslma::Allocator * basicAllocator = 0 )

explicit

Create a category manager with the hardwired default levels for new categories and no defaults or namefilter callback set. Optionally specify a basicAllocator used to supply memory. If basicAllocator is 0, the currently installed default allocator is used.

◆ CategoryManager() [2/2]

ball::CategoryManager::CategoryManager	(	int	defaultRecordLevel,
		int	defaultPassLevel,
		int	defaultTriggerLevel,
		int	defaultTriggerAllLevel,
		const DefaultThresholdLevelsCallback &	defaultThresholdLevelsCallback,
		const CategoryNameFilterCallback &	categoryNameFilterCallback,
		bslma::Allocator *	basicAllocator = `0`
	)

Create a category manager with the specified default threshold level values defaultRecordLevel, defaultPassLevel, defaultTriggerLevel, defaultTriggerAllLevel, the defaultThresholdLevelsCallback, and the categoryNameFilterCallback. Optionally specify a basicAllocator used to supply memory. If basicAllocator is 0, the currently installed default allocator is used.

◆ ~CategoryManager()

ball::CategoryManager::~CategoryManager ( )

Destroy this category manager.

Member Function Documentation

◆ addCategory() [1/2]

Category * ball::CategoryManager::addCategory	(	CategoryHolder *	categoryHolder,
		const char *	categoryName,
		int	recordLevel,
		int	passLevel,
		int	triggerLevel,
		int	triggerAllLevel
	)

Add to the registry of this category manager a category having the specified categoryName, possibly changed by the registered category name filter callback, and having the specified recordLevel, passLevel, triggerLevel, and triggerAllLevel threshold values, respectively, if there is no category having (the possibly filtered) categoryName and each of the specified threshold values is in the range [0 .. 255]. Return the address of the newly-created, modifiable category on success, and 0 otherwise. If a newly-created category is returned and the specified categoryHolder is non-null, then also load into categoryHolder the returned category and its maximum level and link categoryHolder to the category.

Precondition: The behavior is undefined unless a lock is not held by this thread on the mutex returned by rulesetMutex.

Note: Note that if a category having (the possibly filtered) categoryName already exists in the registry, 0 is returned.; Note that an existing category will not be modified if a category with the (possibly filtered) categoryName already exists.

◆ addCategory() [2/2]

Category * ball::CategoryManager::addCategory	(	const char *	categoryName,
		int	recordLevel,
		int	passLevel,
		int	triggerLevel,
		int	triggerAllLevel
	)

inline

Add to the registry of this category manager a category having the specified categoryName, possibly changed by the registered category name filter callback, and having the specified recordLevel, passLevel, triggerLevel, and triggerAllLevel threshold values, respectively, if there is no category having (the possibly filtered) categoryName and each of the specified threshold values is in the range [0 .. 255]. Return the address of the newly-created, modifiable category on success, and 0 otherwise.

Precondition: The behavior is undefined unless a lock is not held by this thread on the mutex returned by rulesetMutex.

Note: Note that if a category having (the possibly filtered) categoryName already exists in the registry, 0 is returned.; Note that an existing category will not be modified if a category with the (possibly filtered) categoryName already exists.

◆ addCategoryHierarchically()

Category * ball::CategoryManager::addCategoryHierarchically ( const char * categoryName )

Add a new category with the specified categoryName, possibly changed by the registered category name filter callback, unless it already exists. Return a pointer to the newly added category in case it did not already exist. Determine the threshold levels for the category by finding the longest category name or category name prefix that is a prefix of this (possibly filtered) categoryName and use its settings. If no such category or category hierarchical setting exists use the defaults. Otherwise, if a category already exists with (the possibly filtered) categoryName do nothing and return 0.

◆ addDefaultCategory()

void ball::CategoryManager::addDefaultCategory ( )

If this method is called the first time (d_defaultCategory_p is null) add a new category with the (unspecified) default category name (possibly changed by the registered category name filter callback). Use the default threshold levels for the new category.

Precondition: The behavior is undefined if the default category already exists but has not been added by this method.

◆ addRule()

int ball::CategoryManager::addRule ( const Rule & ruleToAdd )

Add the specified ruleToAdd to the set of (unique) rules maintained by this object. Return the number of rules added (i.e., 1 on success and 0 if a rule with the same value is already present).

Precondition: The behavior is undefined unless a lock is not held by this thread on the mutex returned by rulesetMutex.

◆ addRules()

int ball::CategoryManager::addRules ( const RuleSet & ruleSet )

Add each rule in the specified ruleSet to the set of (unique) rules maintained by this object. Return the number of rules added.

Precondition: The behavior is undefined unless a lock is not held by this thread on the mutex returned by rulesetMutex.

Note: Note that each rule having the same value as an existing rule will be ignored.

◆ defaultCategory() [1/2]

Category & ball::CategoryManager::defaultCategory ( )

inline

Return a non-const reference to the Default Category in this category registry.

Precondition: The behavior is undefined unless addDefaultCategory has been called.

◆ defaultCategory() [2/2]

const Category & ball::CategoryManager::defaultCategory ( ) const

inline

Return a const reference to the Default Category in this category registry.

Precondition: The behavior is undefined unless addDefaultCategory has been called.

◆ defaultPassThresholdLevel()

int ball::CategoryManager::defaultPassThresholdLevel ( ) const

Return the default pass threshold level of this object.

◆ defaultRecordThresholdLevel()

int ball::CategoryManager::defaultRecordThresholdLevel ( ) const

Return the default record threshold level of this object.

◆ defaultThresholdLevels()

ThresholdAggregate ball::CategoryManager::defaultThresholdLevels ( ) const

Return the default threshold levels associated with this object.

◆ defaultTriggerAllThresholdLevel()

int ball::CategoryManager::defaultTriggerAllThresholdLevel ( ) const

Return the default trigger-all threshold level of this object.

◆ defaultTriggerThresholdLevel()

int ball::CategoryManager::defaultTriggerThresholdLevel ( ) const

Return the default trigger threshold level of this object.

◆ length()

int ball::CategoryManager::length ( ) const

inline

Return the number of categories in the registry of this category manager.

◆ lookupCategory() [1/3]

Category * ball::CategoryManager::lookupCategory	(	CategoryHolder *	categoryHolder,
		const char *	categoryName
	)

Return the address of the modifiable category having the specified categoryName in the registry of this category manager, or 0 if no such category exists. If a category is returned and the specified categoryHolder is non-null, then also load into categoryHolder the returned category and its maximum level and link categoryHolder to the category if it has not yet been linked.

Note: Note that the category name is possibly changed by the registered category name filter callback before the lookup.

◆ lookupCategory() [2/3]

Category * ball::CategoryManager::lookupCategory ( const char * categoryName )

Return the address of the modifiable category having the specified categoryNamein the registry of this category manager, or 0 if no such category exists.

Note: Note that the category name is possibly changed by the registered category name filter callback before the lookup.

◆ lookupCategory() [3/3]

const Category * ball::CategoryManager::lookupCategory ( const char * categoryName ) const

Return the address of the non-modifiable category having the specified categoryName, possibly changed by the registered category name filter callback, in the registry of this category manager, or 0 if no such category exists.

◆ maxNumCategories()

int ball::CategoryManager::maxNumCategories ( ) const

inline

Return the current capacity of this category registry. A capacity of 0 implies that no limit will be imposed; otherwise, new categories may be added only if numCategories() < maxNumCategories().

Note: Note that 0 < maxNumCategories() < numCategories() is a valid state, implying no new categories may be added.

◆ operator[]() [1/2]

Category & ball::CategoryManager::operator[] ( int index )

inline

Return a non-const reference to the category at the specified index in the registry of this category manager.

Precondition: The behavior is undefined unless 0 <= index < length().

◆ operator[]() [2/2]

const Category & ball::CategoryManager::operator[] ( int index ) const

inline

Return a const reference to the category at the specified index in the registry of this category manager.

Precondition: The behavior is undefined unless 0 <= index < length().

◆ removeAllRules()

void ball::CategoryManager::removeAllRules ( )

Remove every rule from the set of rules maintained by this object.

Precondition: The behavior is undefined unless a lock is not held by this thread on the mutex returned by rulesetMutex.

◆ removeRule()

int ball::CategoryManager::removeRule ( const Rule & ruleToRemove )

Remove the specified ruleToRemove from the set of (unique) rules maintained by this object. Return the number of rules removed (i.e., 1 on success and 0 if no rule having the same value is found).

Precondition: The behavior is undefined unless a lock is not held by this thread on the mutex returned by rulesetMutex.

◆ removeRules()

int ball::CategoryManager::removeRules ( const RuleSet & ruleSet )

Remove each rule in the specified ruleSet from the set of rules maintained by this object. Return the number of rules removed.

Precondition: The behavior is undefined unless a lock is not held by this thread on the mutex returned by rulesetMutex.

◆ resetCategoryHolders()

void ball::CategoryManager::resetCategoryHolders ( )

Reset the category holders to which all categories in the registry of this category manager are linked to their default value. See the function-level documentation of CategoryHolder::reset() for further information on the default value of category holders.

◆ resetDefaultThresholdLevels()

void ball::CategoryManager::resetDefaultThresholdLevels ( )

Reset the default threshold levels to the original "factory-supplied" default values or the factory overrides supplied at construction.

◆ ruleSet()

const RuleSet & ball::CategoryManager::ruleSet ( ) const

inline

Return a const reference to the rule set maintained by this category manager. The mutex returned by rulesetMutex should be locked prior to accessing the rule set.

◆ rulesetMutex()

bslmt::Mutex & ball::CategoryManager::rulesetMutex ( )

inline

Return a non-const reference to the mutex that is used to guard against concurrent access to the rule set. A lock on the returned mutex should be acquired before accessing the properties of the rule set returned by ruleSet.

Precondition: The behavior is undefined unless a lock is acquired solely for the purpose of calling ruleSet.

◆ ruleSetSequenceNumber()

bsls::Types::Int64 ball::CategoryManager::ruleSetSequenceNumber ( ) const

inline

Return the sequence number that tracks changes to the rule set maintained by this category manager. The value returned by this method is guaranteed to monotonically increase between calls before and after the rule set is changed, and is otherwise implementation defined.

◆ setCategory() [1/3]

const Category * ball::CategoryManager::setCategory	(	CategoryHolder *	categoryHolder,
		const char *	categoryName
	)

Add to this category registry a new category having the specified categoryName, possibly changed by the registered category name filter callback, and default threshold levels if (the possibly filtered) categoryName is not present in the registry and the number of categories in the registry is less than the registry capacity. Return the address of the (possibly newly-created) non-modifiable category having (the possibly filtered) categoryName, if such a category exists, and the address of the non-modifiable Default Category otherwise. If the specified categoryHolder is non-null, then also load into categoryHolder the returned category and its maximum level and link categoryHolder to the category if it has not yet been linked.

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

Note: Note that a valid category address is always returned.

◆ setCategory() [2/3]

const Category * ball::CategoryManager::setCategory ( const char * categoryName )

inline

Add to this category registry a new category having the specified categoryName, possibly changed by the registered category name filter callback, and default threshold levels if (the possibly filtered) categoryName is not present in the registry and the number of categories in the registry is less than the registry capacity. Return the address of the (possibly newly-created) non-modifiable category having (the possibly filtered) categoryName, if such a category exists, and the address of the non-modifiable Default Category otherwise.

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

Note: Note that a valid category address is always returned.

◆ setCategory() [3/3]

Category * ball::CategoryManager::setCategory	(	const char *	categoryName,
		int	recordLevel,
		int	passLevel,
		int	triggerLevel,
		int	triggerAllLevel
	)

Add to this category registry a new category having the specified categoryName, possibly changed by the registered category name filter callback, and having recordLevel, passLevel, triggerLevel, and triggerAllLevel threshold levels, respectively, if (1) (the possibly filtered) categoryName is not present in the registry, (2) the number of categories in the registry is less than the registry capacity, and (3) recordLevel, passLevel, triggerLevel, and triggerAllLevel are all within the range [0 .. 255]. If (the possibly filtered) categoryName is already present and each threshold level is within the valid range then reset the threshold levels of (the possibly filtered) categoryName to the specified values. Return the address of the (possibly newly-created) modifiable category having (the possibly filtered) categoryName if that categoryName was either created or its thresholds reset, and 0 otherwise.

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

Note: Note that 0, and not the Default Category, is returned on failure.

◆ setCategoryThresholdsToCurrentDefaults()

void ball::CategoryManager::setCategoryThresholdsToCurrentDefaults ( Category * category ) const

Set the threshold levels of the specified category in this category registry of this category manager to the current default threshold values.

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

◆ setCategoryThresholdsToFactoryDefaults()

void ball::CategoryManager::setCategoryThresholdsToFactoryDefaults ( Category * category ) const

Set the threshold levels of the specified category in the category registry of this category manager to the original "factory-supplied" default values or the factory overrides supplied at construction.

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

◆ setDefaultThresholdLevels()

int ball::CategoryManager::setDefaultThresholdLevels	(	int	recordLevel,
		int	passLevel,
		int	triggerLevel,
		int	triggerAllLevel
	)

Set the default threshold levels to the specified recordLevel, passLevel, triggerLevel, and triggerAllLevel values, respectively, if each threshold level is in the range [0 .. 255]. Return 0 on success, and a non-zero value otherwise (with no effect on any of the default threshold levels).

◆ setDefaultThresholdLevelsCallback()

void ball::CategoryManager::setDefaultThresholdLevelsCallback ( const DefaultThresholdLevelsCallback * defaultThresholdLevelsCallback )

Set the default-thresholds callback to the specified defaultThresholdLevelsCallback if it is not null, and remove any existing callback if defaultThresholdLevelsCallback is null.

◆ setMaxNumCategories()

void ball::CategoryManager::setMaxNumCategories ( int length )

inline

Set the capacity of this category registry to the specified length. If length is 0, no limit will be imposed. No categories are removed from the registry if the current number of categories exceeds length. However, subsequent attempts to add categories to the registry will fail.

Precondition: The behavior is undefined unless 0 <= length.

◆ setThresholdLevels()

Category * ball::CategoryManager::setThresholdLevels	(	const char *	categoryName,
		int	recordLevel,
		int	passLevel,
		int	triggerLevel,
		int	triggerAllLevel
	)

Set the threshold levels of the category having the specified categoryName, possibly changed by the registered category name filter callback, in the registry of this category manager to the specified recordLevel, passLevel, triggerLevel, and triggerAllLevel values, respectively, if a category having (the possibly filtered) categoryName exists and each of the specified threshold values is in the range [0 .. 255]. Otherwise, add to the registry a category having (the possibly filtered) categoryName and recordLevel, passLevel, triggerLevel, and triggerAllLevel threshold values, respectively, if there is no category having (the possibly filtered) categoryName and each of the specified threshold values is in the range [0 .. 255]. Return the address of the (possibly newly-created) modifiable category on success, and 0 otherwise (with no effect on any category).

Precondition: The behavior is undefined unless a lock is not held by this thread on the mutex returned by rulesetMutex.

◆ setThresholdLevelsHierarchically()

int ball::CategoryManager::setThresholdLevelsHierarchically	(	const char *	categoryNamePrefix,
		int	recordLevel,
		int	passLevel,
		int	triggerLevel,
		int	triggerAllLevel
	)

Set the threshold levels of all existing and future categories whose name starts with the specified categoryNamePrefix unless it is empty, possibly changed by the registered category name filter callback, to the specified recordLevel, passLevel, triggerLevel, and triggerAllLevel if those levels form valid settings and return the number of categories updated (zero or a positive number). In case categoryNamePrefix is empty update all categories with the threshold levels and delete all stored orphan hierarchical settings. In other words an empty category setting will never overwrite the defaults for future hierarchical categories.

Precondition: The behavior is undefined unless a lock is not held by this thread on the mutex returned by rulesetMutex. If any of the specified threshold levels is invalid, return a negative value.

◆ thresholdLevelsForNewCategory()

int ball::CategoryManager::thresholdLevelsForNewCategory	(	ThresholdAggregate *	levels,
		const char *	categoryName
	)		const

Load into the specified *levels the threshold levels that would be set for a newly and non-hierarchically created category. Return 0 on success and a non-zero value otherwise. If the client has configured a default threshold levels callback, the categoryName, possibly changed by the registered category name filter callback, will be supplied to that callback which will set *levels. Otherwise, if no default threshold levels callback has been provided, the default threshold levels are used.

Note: Note that this function will report an error if the callback returns invalid levels.

◆ visitCategories() [1/2]

template<class t_CATEGORY_VISITOR >

void ball::CategoryManager::visitCategories ( const t_CATEGORY_VISITOR & visitor )

Invoke the specified visitor functor on each category managed by this object, supplying that functor modifiable access to each category. visitor must be a functor that can be called as if it had the following signature:

void operator()(Category *);

ball::Category

Definition ball_category.h:184

Precondition: The behavior is undefined if visitor calls any method on this CategoryManager object.

◆ visitCategories() [2/2]

template<class t_CATEGORY_VISITOR >

void ball::CategoryManager::visitCategories ( const t_CATEGORY_VISITOR & visitor ) const

Invoke the specified visitor functor on each category managed by this object, supplying that functor non-modifiable access to each category. visitor must be a functor that can be called as if it had the following signature:

void operator()(const Category *);

Precondition: The behavior is undefined if visitor calls any method on this CategoryManager object.

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

ball_categorymanager.h

Detailed Description

Public Types

Public Member Functions

Member Typedef Documentation

◆ CategoryNameFilterCallback

◆ DefaultThresholdLevelsCallback

Constructor & Destructor Documentation

◆ CategoryManager() [1/2]

◆ CategoryManager() [2/2]

◆ ~CategoryManager()

Member Function Documentation

◆ addCategory() [1/2]

◆ addCategory() [2/2]

◆ addCategoryHierarchically()

◆ addDefaultCategory()

◆ addRule()

◆ addRules()

◆ defaultCategory() [1/2]

◆ defaultCategory() [2/2]

◆ defaultPassThresholdLevel()

◆ defaultRecordThresholdLevel()

◆ defaultThresholdLevels()

◆ defaultTriggerAllThresholdLevel()

◆ defaultTriggerThresholdLevel()

◆ length()

◆ lookupCategory() [1/3]

◆ lookupCategory() [2/3]

◆ lookupCategory() [3/3]

◆ maxNumCategories()

◆ operator[]() [1/2]

◆ operator[]() [2/2]

◆ removeAllRules()

◆ removeRule()

◆ removeRules()

◆ resetCategoryHolders()

◆ resetDefaultThresholdLevels()

◆ ruleSet()

◆ rulesetMutex()

◆ ruleSetSequenceNumber()

◆ setCategory() [1/3]

◆ setCategory() [2/3]

◆ setCategory() [3/3]

◆ setCategoryThresholdsToCurrentDefaults()

◆ setCategoryThresholdsToFactoryDefaults()

◆ setDefaultThresholdLevels()

◆ setDefaultThresholdLevelsCallback()

◆ setMaxNumCategories()

◆ setThresholdLevels()

◆ setThresholdLevelsHierarchically()

◆ thresholdLevelsForNewCategory()

◆ visitCategories() [1/2]

◆ visitCategories() [2/2]