[#BloombergLP-ball-CategoryManager]
= xref:BloombergLP.adoc[BloombergLP]::xref:BloombergLP/ball.adoc[ball]::CategoryManager
:relfileprefix: ../../
:mrdocs:

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.

== Synopsis

Declared in `<ball_categorymanager.h>`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
class CategoryManager;
----

== Type Aliases

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/ball/CategoryManager/CategoryNameFilterCallback.adoc[`CategoryNameFilterCallback`] 
| `CategoryNameFilterCallback` is the type of the user‐supplied functor that translates external category names to internal names.
| xref:BloombergLP/ball/CategoryManager/DefaultThresholdLevelsCallback.adoc[`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.
|===


== Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/ball/CategoryManager/2constructor-00.adoc[`CategoryManager`]         [.small]#[constructor]#
| Constructors
| xref:BloombergLP/ball/CategoryManager/2destructor.adoc[`~CategoryManager`] [.small]#[destructor]#
| Destroy this category manager.
| xref:BloombergLP/ball/CategoryManager/addCategory-01.adoc[`addCategory`] 
| `addCategory` overloads
| xref:BloombergLP/ball/CategoryManager/addCategoryHierarchically.adoc[`addCategoryHierarchically`] 
| 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.
| xref:BloombergLP/ball/CategoryManager/addDefaultCategory.adoc[`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. The behavior is undefined if the default category already exists but has not been added by this method.
| xref:BloombergLP/ball/CategoryManager/addRule.adoc[`addRule`] 
| 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). The behavior is undefined unless a lock is not held by this thread on the mutex returned by `rulesetMutex`.
| xref:BloombergLP/ball/CategoryManager/addRules.adoc[`addRules`] 
| Add each rule in the specified `ruleSet` to the set of (unique) rules maintained by this object. Return the number of rules added. The behavior is undefined unless a lock is not held by this thread on the mutex returned by `rulesetMutex`. Note that each rule having the same value as an existing rule will be ignored.
| xref:BloombergLP/ball/CategoryManager/defaultCategory-0c.adoc[`defaultCategory`] 
| `defaultCategory` overloads
| xref:BloombergLP/ball/CategoryManager/defaultPassThresholdLevel.adoc[`defaultPassThresholdLevel`] 
| Return the default pass threshold level of this object.
| xref:BloombergLP/ball/CategoryManager/defaultRecordThresholdLevel.adoc[`defaultRecordThresholdLevel`] 
| Return the default record threshold level of this object.
| xref:BloombergLP/ball/CategoryManager/defaultThresholdLevels.adoc[`defaultThresholdLevels`] 
| Return the default threshold levels associated with this object.
| xref:BloombergLP/ball/CategoryManager/defaultTriggerAllThresholdLevel.adoc[`defaultTriggerAllThresholdLevel`] 
| Return the default trigger‐all threshold level of this object.
| xref:BloombergLP/ball/CategoryManager/defaultTriggerThresholdLevel.adoc[`defaultTriggerThresholdLevel`] 
| Return the default trigger threshold level of this object.
| xref:BloombergLP/ball/CategoryManager/length.adoc[`length`] 
| Return the number of categories in the registry of this category manager.
| xref:BloombergLP/ball/CategoryManager/lookupCategory-06.adoc[`lookupCategory`] 
| `lookupCategory` overloads
| xref:BloombergLP/ball/CategoryManager/maxNumCategories.adoc[`maxNumCategories`] 
| 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 that `0 < maxNumCategories() < numCategories()` _is_ a valid state, implying no new categories may be added.
| xref:BloombergLP/ball/CategoryManager/operator_subs-0d.adoc[`operator[]`] 
| Subscript operators
| xref:BloombergLP/ball/CategoryManager/removeAllRules.adoc[`removeAllRules`] 
| Remove every rule from the set of rules maintained by this object. The behavior is undefined unless a lock is not held by this thread on the mutex returned by `rulesetMutex`.
| xref:BloombergLP/ball/CategoryManager/removeRule.adoc[`removeRule`] 
| 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). The behavior is undefined unless a lock is not held by this thread on the mutex returned by `rulesetMutex`.
| xref:BloombergLP/ball/CategoryManager/removeRules.adoc[`removeRules`] 
| Remove each rule in the specified `ruleSet` from the set of rules maintained by this object. Return the number of rules removed. The behavior is undefined unless a lock is not held by this thread on the mutex returned by `rulesetMutex`.
| xref:BloombergLP/ball/CategoryManager/resetCategoryHolders.adoc[`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.
| xref:BloombergLP/ball/CategoryManager/resetDefaultThresholdLevels.adoc[`resetDefaultThresholdLevels`] 
| Reset the default threshold levels to the original "factory‐supplied" default values or the factory overrides supplied at construction.
| xref:BloombergLP/ball/CategoryManager/ruleSet.adoc[`ruleSet`] 
| 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.
| xref:BloombergLP/ball/CategoryManager/ruleSetSequenceNumber.adoc[`ruleSetSequenceNumber`] 
| 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.
| xref:BloombergLP/ball/CategoryManager/rulesetMutex.adoc[`rulesetMutex`] 
| 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`. The behavior is undefined unless a lock is acquired solely for the purpose of calling `ruleSet`.
| xref:BloombergLP/ball/CategoryManager/setCategory-00.adoc[`setCategory`] 
| `setCategory` overloads
| xref:BloombergLP/ball/CategoryManager/setCategoryThresholdsToCurrentDefaults.adoc[`setCategoryThresholdsToCurrentDefaults`] 
| Set the threshold levels of the specified `category` in this category registry of this category manager to the current default threshold values. The behavior is undefined unless `category` is non‐null.
| xref:BloombergLP/ball/CategoryManager/setCategoryThresholdsToFactoryDefaults.adoc[`setCategoryThresholdsToFactoryDefaults`] 
| 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. The behavior is undefined unless `category` is non‐null.
| xref:BloombergLP/ball/CategoryManager/setDefaultThresholdLevels.adoc[`setDefaultThresholdLevels`] 
| 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).
| xref:BloombergLP/ball/CategoryManager/setDefaultThresholdLevelsCallback.adoc[`setDefaultThresholdLevelsCallback`] 
| Set the default‐thresholds callback to the specified `defaultThresholdLevelsCallback` if it is not null, and remove any existing callback if `defaultThresholdLevelsCallback` is null.
| xref:BloombergLP/ball/CategoryManager/setMaxNumCategories.adoc[`setMaxNumCategories`] 
| 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. The behavior is undefined unless `0 <= length`.
| xref:BloombergLP/ball/CategoryManager/setThresholdLevels.adoc[`setThresholdLevels`] 
| 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). The behavior is undefined unless a lock is not held by this thread on the mutex returned by `rulesetMutex`.
| xref:BloombergLP/ball/CategoryManager/setThresholdLevelsHierarchically.adoc[`setThresholdLevelsHierarchically`] 
| 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. 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.
| xref:BloombergLP/ball/CategoryManager/thresholdLevelsForNewCategory.adoc[`thresholdLevelsForNewCategory`] 
| 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 that this function will report an error if the callback returns invalid levels.
| xref:BloombergLP/ball/CategoryManager/visitCategories-0a9.adoc[`visitCategories`] 
| `visitCategories` overloads
|===



[.small]#Created with https://www.mrdocs.com[MrDocs]#