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

This class provides a mechanism for associating attributes with the current thread, and evaluating the logging rules associated with a category using those stored attributes&period; `AttributeContext` contains class data members that must be initialized (using the `initialize` class method) with a `CategoryManager` object containing a `RuleSet` that represents the currently installed logging rules for the process&period; Clients can obtain the context for the current thread by calling the `getContext` class method&period; The `addAttributes` and `removeAttributes` methods are used to add and remove collections of attributes from the (thread&hyphen;local) context object&period; Finally, `AttributeContext` provides methods (used primarily by other components in the `ball` package&apos;) to determine the effect of the current logging rules on the logging thresholds of a category&period; The `hasRelevantActiveRules` method returns `true` if there are any relevant and active rules that might modify the logging thresholds of the supplied category&period; A rule is &quot;relevant&quot; if the rule&apos;s pattern matches the category&apos;s name, and a rule is &quot;active&quot; if all the attributes defined for the rule are satisfied by the current thread&apos;s attributes (i&period;e&period;, `Rule&colon;&colon;evaluate` returns `true` for the collection of attributes maintained for the current thread by the thread&apos;s `AttributeContext` object)&period; The `determineThresholdLevels` method returns the logging threshold levels for a category, factoring in any active rules that apply to the category that might override the category&apos;s thresholds&period; The behavior for the `hasRelevantActiveRules` and `determineThresholdLevels` methods is undefined unless `initialize` has been called&period; Note that, in practice, `initialize` is called _internally_ when the logger manager singleton is initialized&semi; clients ordinarily should not call `initialize` directly&period;

== Synopsis

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

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

== Type Aliases

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/ball/AttributeContext/iterator.adoc[`iterator`] 
| Iterator over the attribute containers in an `AttributeContext`&period;
|===


== Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/ball/AttributeContext/addAttributes.adoc[`addAttributes`] 
| Add the specified `attributes` container to the list of attribute containers maintained by this object&period; The behavior is undefined unless `attributes` remains valid _and_ _unmodified_ until either `attributes` is removed from this context, `clearCache` is called, or this object is destroyed&period; Note that this method can be invoked safely even if the `initialize` class method has not yet been called&period;
| xref:BloombergLP/ball/AttributeContext/clearCache.adoc[`clearCache`] 
| Clear this object&apos;s cache of evaluated rules&period; Note that this method must be called if an `AttributeContainer` object supplied to `addAttributes` is modified outside of this context&period;
| xref:BloombergLP/ball/AttributeContext/containers.adoc[`containers`] 
| Return a `const` reference to the list of attribute containers maintained by this object&period; Note that this method can be invoked safely even if the `initialize` class method has not yet been called&period;
| xref:BloombergLP/ball/AttributeContext/determineThresholdLevels.adoc[`determineThresholdLevels`] 
| Populate the specified `levels` with the threshold levels for the specified `category`&period; This method compares the threshold levels defined by `category` with those of any active rules that apply to that category, and determines the minimum severity (i&period;e&period;, the maximum numerical value) for each respective threshold amongst those values&period; A rule applies to `category` if the rule&apos;s pattern matches `category&hyphen;&gt;categoryName()`, and a rule is active if all the attributes defined for that rule are satisfied by the current thread&apos;s attributes (i&period;e&period;, `Rule&colon;&colon;evaluate` returns `true` for the collection of attributes maintained by this object)&period; This method operates on the set of rules maintained by the category manager supplied to the `initialize` class method (which, in practice, should be the global set of rules for the process)&period; The behavior is undefined unless `initialize` has previously been invoked without a subsequent call to `reset`, and `category` is contained in the registry maintained by the category manager supplied to `initialize`&period;
| xref:BloombergLP/ball/AttributeContext/hasAttribute.adoc[`hasAttribute`] 
| Return `true` if an attribute having the specified `value` exists in any of the attribute containers maintained by this object, and `false` otherwise&period; Note that this method can be invoked safely even if the `initialize` class method has not yet been called&period;
| xref:BloombergLP/ball/AttributeContext/hasRelevantActiveRules.adoc[`hasRelevantActiveRules`] 
| Return `true` if there is at least one rule defined for this process that is both &quot;relevant&quot; to the specified `category` and &quot;active&quot;, and `false` otherwise&period; A rule is &quot;relevant&quot; to `category` if the rule&apos;s pattern matches `category&hyphen;&gt;categoryName()`, and a rule is &quot;active&quot; if all the attributes defined for that rule are satisfied by the current thread&apos;s attributes (i&period;e&period;, `Rule&colon;&colon;evaluate` returns `true` for the collection of attributes maintained by this object)&period; This method operates on the set of rules maintained by the category manager supplied to the `initialize` class method (which, in practice, should be the global set of rules for the process)&period; The behavior is undefined unless `initialize` has previously been invoked without a subsequent call to `reset`, and `category` is contained in the registry maintained by the category manager supplied to `initialize`&period;
| xref:BloombergLP/ball/AttributeContext/print.adoc[`print`] 
| Format this object to the specified output `stream` at the (absolute value of) the optionally specified indentation `level` and return a reference to `stream`&period; If `level` is specified, optionally specify `spacesPerLevel`, the number of spaces per indentation level for this and all of its nested objects&period; If `level` is negative, suppress indentation of the first line&period; If `spacesPerLevel` is negative, format the entire output on one line, suppressing all but the initial indentation (as governed by `level`)&period; If `stream` is not valid on entry, this operation has no effect&period;
| xref:BloombergLP/ball/AttributeContext/removeAttributes.adoc[`removeAttributes`] 
| Remove the specified `element` from the list of attribute containers maintained by this object&period; Note that this method can be invoked safely even if the `initialize` class method has not yet been called&period;
|===


== Static Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/ball/AttributeContext/getContext.adoc[`getContext`] 
| Return the address of the current thread&apos;s attribute context, if such context exists&semi; otherwise, create an attribute context, install it in thread&hyphen;local storage, and return the address of the newly created context&period; Note that this method can be invoked safely even if the `initialize` class method has not yet been called&period;
| xref:BloombergLP/ball/AttributeContext/initialize.adoc[`initialize`] 
| Initialize the static data members of `AttributeContext` using the specified `categoryManager`&period; Optionally specify a `globalAllocator` used to supply memory&period; If `globalAllocator` is 0, the currently installed global allocator is used&period; Unless `reset` is subsequently called, invoking this method more than once will log an error message using `bsls&colon;&colon;Log&colon;&colon;platformDefaultMessageHandler`, but will have no other effect&period; Note that in practice this method will be called _automatically_ when the `LoggerManager` singleton is initialized &hyphen;&hyphen; i&period;e&period;, it is not intended to be called directly by clients of the `ball` package&period;
| xref:BloombergLP/ball/AttributeContext/lookupContext.adoc[`lookupContext`] 
| Return the address of the modifiable `AttributeContext` object installed in local storage for the current thread, or 0 if no attribute context has been created for this thread&period; Note that this method can be invoked safely even if the `initialize` class method has not yet been called&period;
| xref:BloombergLP/ball/AttributeContext/reset.adoc[`reset`] 
| Reset the static data members of `AttributeContext` to their initial state (0)&period; Unless `initialize` is subsequently called, invoking this method more than once has no effect&period; Note that in practice this method will be called _automatically_ when the `LoggerManager` singleton is destroyed &hyphen;&hyphen; i&period;e&period;, it is not intended to be called directly by clients of the `ball` package&period;
| xref:BloombergLP/ball/AttributeContext/visitAttributes.adoc[`visitAttributes`] 
| Invoke the specified `visitor` for all attributes in all attribute containers maintained by this object&period;
|===


== Friends

[cols="1,4"]
|===
| Name| Description
| `xref:BloombergLP/ball/AttributeContextProctor.adoc[BloombergLP::ball::AttributeContextProctor]`
| This class implements a proctor that, on its own destruction, will destroy the attribute context of the current thread&period; Attribute contexts are stored in thread&hyphen;local memory&period; On destruction, objects of this type will deallocate the current thread&apos;s attribute context (if one has been created), and set the thread&hyphen;local storage pointer to 0&period;
|===


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