[#BloombergLP-balm-Category]
= xref:BloombergLP.adoc[BloombergLP]::xref:BloombergLP/balm.adoc[balm]::Category
:relfileprefix: ../../
:mrdocs:

This class provides a mechanism for representing a category&period; A category is an identifier used to group related metrics&period; A `Category` object contains the address of a null&hyphen;terminated string, `name`, holding the name of the category and a boolean value, `enabled`, indicating whether the category is currently enabled&period;

== Synopsis

Declared in `&lt;balm&lowbar;category&period;h&gt;`

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

== Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/balm/Category/2constructor.adoc[`Category`]         [.small]#[constructor]#
| Create a category having the specified `name` address&period; Optionally specify `enabledFlag`, the enabled status of the category&semi; if `enabledFlag` is not specified, the `enabled` status is `true`&period; The behavior is undefined unless `name` remains valid and unmodified for the lifetime of this object&period;
| xref:BloombergLP/balm/Category/2destructor.adoc[`&#126;Category`] [.small]#[destructor]#
| Destroy this category object&period;
| xref:BloombergLP/balm/Category/enabled.adoc[`enabled`] 
| Report whether this category is enabled&period; This function is fully thread&hyphen;safe&period;
| xref:BloombergLP/balm/Category/isEnabledRaw.adoc[`isEnabledRaw`] 
| Return a _reference_ to a const value indicating the enabled status of this category, allowing downstream uses to minimize latency by avoiding indirection through abstracted interfaces, albeit at some risk of object&hyphen;lifetime violations&period; The returned reference must not be allowed to outlive this category object&period;
| xref:BloombergLP/balm/Category/name.adoc[`name`] 
| Return the address of the non&hyphen;modifiable null&hyphen;terminated string containing the name of this category&period;
| xref:BloombergLP/balm/Category/print.adoc[`print`] 
| Print this category to the specified output `stream` in some human readable form, and return the modifiable `stream`&period;
| xref:BloombergLP/balm/Category/registerCategoryHolder.adoc[`registerCategoryHolder`] 
| Load into the specified `holder` the address of this category, its `enabled()` status, and the address of the next holder in the linked list of category holders maintained by this object (prepending `holder` to this category&apos;s linked list of category holders)&period; This category will update `holder&hyphen;&gt;enabled()` when its enabled state changes, and will reset `holder` (i&period;e&period;, `holder&hyphen;&gt;reset()`) when this category is destroyed&period; The behavior is undefined unless `holder` remains valid and _unmodified_ (by the client) for the lifetime of this object and is _not_ registered again with any category (including this one)&period;
| xref:BloombergLP/balm/Category/setEnabled.adoc[`setEnabled`] 
| Set the `enabled` state of this category to the value of the specified `enabledFlag` and update any `CategoryHolder` objects registered with this category&period; Note that this operation is _not_ atomic, and other threads may simultaneously access the current enabled value while this operation is performed&period; Also note that this operation has _linear_ performance with respect to the number of registered category holders for `category`&period;
| xref:BloombergLP/balm/Category/setName.adoc[`setName`] 
| Set the name of this metric to the specified `name` address&period; The behavior is undefined unless `name` remains valid and unmodified for the lifetime of this object&period;
|===



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