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

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

== Synopsis

Declared in `<balm_category.h>`

[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. Optionally specify `enabledFlag`, the enabled status of the category; if `enabledFlag` is not specified, the `enabled` status is `true`. The behavior is undefined unless `name` remains valid and unmodified for the lifetime of this object.
| xref:BloombergLP/balm/Category/2destructor.adoc[`~Category`] [.small]#[destructor]#
| Destroy this category object.
| xref:BloombergLP/balm/Category/enabled.adoc[`enabled`] 
| Report whether this category is enabled. This function is fully thread‐safe.
| 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‐lifetime violations. The returned reference must not be allowed to outlive this category object.
| xref:BloombergLP/balm/Category/name.adoc[`name`] 
| Return the address of the non‐modifiable null‐terminated string containing the name of this category.
| 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`.
| 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's linked list of category holders). This category will update `holder‐>enabled()` when its enabled state changes, and will reset `holder` (i.e., `holder‐>reset()`) when this category is destroyed. 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).
| 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. Note that this operation is _not_ atomic, and other threads may simultaneously access the current enabled value while this operation is performed. Also note that this operation has _linear_ performance with respect to the number of registered category holders for `category`.
| xref:BloombergLP/balm/Category/setName.adoc[`setName`] 
| Set the name of this metric to the specified `name` address. The behavior is undefined unless `name` remains valid and unmodified for the lifetime of this object.
|===



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