[#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. `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. Clients can obtain the context for the current thread by calling the `getContext` class method. The `addAttributes` and `removeAttributes` methods are used to add and remove collections of attributes from the (thread‐local) context object. Finally, `AttributeContext` provides methods (used primarily by other components in the `ball` package') to determine the effect of the current logging rules on the logging thresholds of a category. The `hasRelevantActiveRules` method returns `true` if there are any relevant and active rules that might modify the logging thresholds of the supplied category. A rule is "relevant" if the rule's pattern matches the category's name, and a rule is "active" if all the attributes defined for the rule are satisfied by the current thread's attributes (i.e., `Rule::evaluate` returns `true` for the collection of attributes maintained for the current thread by the thread's `AttributeContext` object). 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's thresholds. The behavior for the `hasRelevantActiveRules` and `determineThresholdLevels` methods is undefined unless `initialize` has been called. Note that, in practice, `initialize` is called _internally_ when the logger manager singleton is initialized; clients ordinarily should not call `initialize` directly.

== Synopsis

Declared in `<ball_attributecontext.h>`

[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`.
|===


== 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. 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. Note that this method can be invoked safely even if the `initialize` class method has not yet been called.
| xref:BloombergLP/ball/AttributeContext/clearCache.adoc[`clearCache`] 
| Clear this object's cache of evaluated rules. Note that this method must be called if an `AttributeContainer` object supplied to `addAttributes` is modified outside of this context.
| xref:BloombergLP/ball/AttributeContext/containers.adoc[`containers`] 
| Return a `const` reference to the list of attribute containers maintained by this object. Note that this method can be invoked safely even if the `initialize` class method has not yet been called.
| xref:BloombergLP/ball/AttributeContext/determineThresholdLevels.adoc[`determineThresholdLevels`] 
| Populate the specified `levels` with the threshold levels for the specified `category`. 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.e., the maximum numerical value) for each respective threshold amongst those values. A rule applies to `category` if the rule's pattern matches `category‐>categoryName()`, and a rule is active if all the attributes defined for that rule are satisfied by the current thread's attributes (i.e., `Rule::evaluate` returns `true` for the collection of attributes maintained by this object). 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). 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`.
| 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. Note that this method can be invoked safely even if the `initialize` class method has not yet been called.
| xref:BloombergLP/ball/AttributeContext/hasRelevantActiveRules.adoc[`hasRelevantActiveRules`] 
| Return `true` if there is at least one rule defined for this process that is both "relevant" to the specified `category` and "active", and `false` otherwise. A rule is "relevant" to `category` if the rule's pattern matches `category‐>categoryName()`, and a rule is "active" if all the attributes defined for that rule are satisfied by the current thread's attributes (i.e., `Rule::evaluate` returns `true` for the collection of attributes maintained by this object). 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). 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`.
| 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`. If `level` is specified, optionally specify `spacesPerLevel`, the number of spaces per indentation level for this and all of its nested objects. If `level` is negative, suppress indentation of the first line. If `spacesPerLevel` is negative, format the entire output on one line, suppressing all but the initial indentation (as governed by `level`). If `stream` is not valid on entry, this operation has no effect.
| xref:BloombergLP/ball/AttributeContext/removeAttributes.adoc[`removeAttributes`] 
| Remove the specified `element` from the list of attribute containers maintained by this object. Note that this method can be invoked safely even if the `initialize` class method has not yet been called.
|===


== Static Member Functions

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


== 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. Attribute contexts are stored in thread‐local memory. On destruction, objects of this type will deallocate the current thread's attribute context (if one has been created), and set the thread‐local storage pointer to 0.
|===


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