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

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

== Synopsis

Declared in `&lt;ball&lowbar;categorymanager&period;h&gt;`

[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&hyphen;supplied functor that translates external category names to internal names&period;
| 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 &ast;)` method&period;
|===


== Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/ball/CategoryManager/2constructor-00.adoc[`CategoryManager`]         [.small]#[constructor]#
| Constructors
| xref:BloombergLP/ball/CategoryManager/2destructor.adoc[`&#126;CategoryManager`] [.small]#[destructor]#
| Destroy this category manager&period;
| 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&period; Return a pointer to the newly added category in case it did not already exist&period; 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&period; If no such category or category hierarchical setting exists use the defaults&period; Otherwise, if a category already exists with (the possibly filtered) `categoryName` do nothing and return 0&period;
| xref:BloombergLP/ball/CategoryManager/addDefaultCategory.adoc[`addDefaultCategory`] 
| If this method is called the first time (`d&lowbar;defaultCategory&lowbar;p` is null) add a new category with the (unspecified) default category name (possibly changed by the registered category name filter callback)&period; Use the default threshold levels for the new category&period; The behavior is undefined if the default category already exists but has not been added by this method&period;
| xref:BloombergLP/ball/CategoryManager/addRule.adoc[`addRule`] 
| Add the specified `ruleToAdd` to the set of (unique) rules maintained by this object&period; Return the number of rules added (i&period;e&period;, 1 on success and 0 if a rule with the same value is already present)&period; The behavior is undefined unless a lock is not held by this thread on the mutex returned by `rulesetMutex`&period;
| xref:BloombergLP/ball/CategoryManager/addRules.adoc[`addRules`] 
| Add each rule in the specified `ruleSet` to the set of (unique) rules maintained by this object&period; Return the number of rules added&period; The behavior is undefined unless a lock is not held by this thread on the mutex returned by `rulesetMutex`&period; Note that each rule having the same value as an existing rule will be ignored&period;
| 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&period;
| xref:BloombergLP/ball/CategoryManager/defaultRecordThresholdLevel.adoc[`defaultRecordThresholdLevel`] 
| Return the default record threshold level of this object&period;
| xref:BloombergLP/ball/CategoryManager/defaultThresholdLevels.adoc[`defaultThresholdLevels`] 
| Return the default threshold levels associated with this object&period;
| xref:BloombergLP/ball/CategoryManager/defaultTriggerAllThresholdLevel.adoc[`defaultTriggerAllThresholdLevel`] 
| Return the default trigger&hyphen;all threshold level of this object&period;
| xref:BloombergLP/ball/CategoryManager/defaultTriggerThresholdLevel.adoc[`defaultTriggerThresholdLevel`] 
| Return the default trigger threshold level of this object&period;
| xref:BloombergLP/ball/CategoryManager/length.adoc[`length`] 
| Return the number of categories in the registry of this category manager&period;
| 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&period; A capacity of 0 implies that no limit will be imposed&semi; otherwise, new categories may be added only if `numCategories() &lt; maxNumCategories()`&period; Note that `0 &lt; maxNumCategories() &lt; numCategories()` _is_ a valid state, implying no new categories may be added&period;
| xref:BloombergLP/ball/CategoryManager/operator_subs-0d.adoc[`operator&lsqb;&rsqb;`] 
| Subscript operators
| xref:BloombergLP/ball/CategoryManager/removeAllRules.adoc[`removeAllRules`] 
| Remove every rule from the set of rules maintained by this object&period; The behavior is undefined unless a lock is not held by this thread on the mutex returned by `rulesetMutex`&period;
| xref:BloombergLP/ball/CategoryManager/removeRule.adoc[`removeRule`] 
| Remove the specified `ruleToRemove` from the set of (unique) rules maintained by this object&period; Return the number of rules removed (i&period;e&period;, 1 on success and 0 if no rule having the same value is found)&period; The behavior is undefined unless a lock is not held by this thread on the mutex returned by `rulesetMutex`&period;
| xref:BloombergLP/ball/CategoryManager/removeRules.adoc[`removeRules`] 
| Remove each rule in the specified `ruleSet` from the set of rules maintained by this object&period; Return the number of rules removed&period; The behavior is undefined unless a lock is not held by this thread on the mutex returned by `rulesetMutex`&period;
| 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&period; See the function&hyphen;level documentation of `CategoryHolder&colon;&colon;reset()` for further information on the default value of category holders&period;
| xref:BloombergLP/ball/CategoryManager/resetDefaultThresholdLevels.adoc[`resetDefaultThresholdLevels`] 
| Reset the default threshold levels to the original &quot;factory&hyphen;supplied&quot; default values or the factory overrides supplied at construction&period;
| xref:BloombergLP/ball/CategoryManager/ruleSet.adoc[`ruleSet`] 
| Return a `const` reference to the rule set maintained by this category manager&period; The mutex returned by `rulesetMutex` should be locked prior to accessing the rule set&period;
| xref:BloombergLP/ball/CategoryManager/ruleSetSequenceNumber.adoc[`ruleSetSequenceNumber`] 
| Return the sequence number that tracks changes to the rule set maintained by this category manager&period; 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&period;
| xref:BloombergLP/ball/CategoryManager/rulesetMutex.adoc[`rulesetMutex`] 
| Return a non&hyphen;`const` reference to the mutex that is used to guard against concurrent access to the rule set&period; A lock on the returned mutex should be acquired before accessing the properties of the rule set returned by `ruleSet`&period; The behavior is undefined unless a lock is acquired solely for the purpose of calling `ruleSet`&period;
| 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&period; The behavior is undefined unless `category` is non&hyphen;null&period;
| 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 &quot;factory&hyphen;supplied&quot; default values or the factory overrides supplied at construction&period; The behavior is undefined unless `category` is non&hyphen;null&period;
| 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 `&lsqb;0 &period;&period; 255&rsqb;`&period; Return 0 on success, and a non&hyphen;zero value otherwise (with no effect on any of the default threshold levels)&period;
| xref:BloombergLP/ball/CategoryManager/setDefaultThresholdLevelsCallback.adoc[`setDefaultThresholdLevelsCallback`] 
| Set the default&hyphen;thresholds callback to the specified `defaultThresholdLevelsCallback` if it is not null, and remove any existing callback if `defaultThresholdLevelsCallback` is null&period;
| xref:BloombergLP/ball/CategoryManager/setMaxNumCategories.adoc[`setMaxNumCategories`] 
| Set the capacity of this category registry to the specified `length`&period; If `length` is 0, no limit will be imposed&period; No categories are removed from the registry if the current number of categories exceeds `length`&period; However, subsequent attempts to add categories to the registry will fail&period; The behavior is undefined unless `0 &lt;&equals; length`&period;
| 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 `&lsqb;0 &period;&period; 255&rsqb;`&period; 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 `&lsqb;0 &period;&period; 255&rsqb;`&period; Return the address of the (possibly newly&hyphen;created) modifiable category on success, and 0 otherwise (with no effect on any category)&period; The behavior is undefined unless a lock is not held by this thread on the mutex returned by `rulesetMutex`&period;
| 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)&period; In case `categoryNamePrefix` is empty update all categories with the threshold levels and delete all stored orphan hierarchical settings&period; In other words an empty category setting will never overwrite the defaults for future hierarchical categories&period; The behavior is undefined unless a lock is not held by this thread on the mutex returned by `rulesetMutex`&period; If any of the specified threshold levels is invalid, return a negative value&period;
| xref:BloombergLP/ball/CategoryManager/thresholdLevelsForNewCategory.adoc[`thresholdLevelsForNewCategory`] 
| Load into the specified `&ast;levels` the threshold levels that would be set for a newly and non&hyphen;hierarchically created category&period; Return 0 on success and a non&hyphen;zero value otherwise&period; 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 `&ast;levels`&period; Otherwise, if no default threshold levels callback has been provided, the default threshold levels are used&period; Note that this function will report an error if the callback returns invalid levels&period;
| xref:BloombergLP/ball/CategoryManager/visitCategories-0a9.adoc[`visitCategories`] 
| `visitCategories` overloads
|===



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