ball::AttributeContext Class Reference

#include <ball_attributecontext.h>

Detailed Description

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

Note that, in practice, initialize is called internally when the logger manager singleton is initialized; clients ordinarily should not call initialize directly.

See ball_attributecontext

Public Types
typedef AttributeContainerList::iterator	iterator

Public Member Functions
iterator	addAttributes (const AttributeContainer *attributes)
void	clearCache ()
void	removeAttributes (iterator element)
bool	hasRelevantActiveRules (const Category *category) const
void	determineThresholdLevels (ThresholdAggregate *levels, const Category *category) const
bool	hasAttribute (const Attribute &value) const
const AttributeContainerList &	containers () const
bsl::ostream &	print (bsl::ostream &stream, int level=0, int spacesPerLevel=4) const

Static Public Member Functions
static AttributeContext *	getContext ()
static void	initialize (CategoryManager *categoryManager, bslma::Allocator *globalAllocator=0)
static AttributeContext *	lookupContext ()
static void	reset ()
static void	visitAttributes (const bsl::function< void(const ball::Attribute &)> &visitor)

Friends
class	AttributeContextProctor

Member Typedef Documentation

iterator

typedef AttributeContainerList::iterator ball::AttributeContext::iterator

Member Function Documentation

addAttributes()

AttributeContext::iterator ball::AttributeContext::addAttributes ( const AttributeContainer *  attributes )

inline

Add the specified attributes container to the list of attribute containers maintained by this object.

Precondition

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

Note that this method can be invoked safely even if the initialize class method has not yet been called.

clearCache()

void ball::AttributeContext::clearCache ( )

inline

Clear this object's cache of evaluated rules.

Note

Note that this method must be called if an AttributeContainer object supplied to addAttributes is modified outside of this context.

containers()

const AttributeContainerList & ball::AttributeContext::containers ( ) const

inline

Return a const reference to the list of attribute containers maintained by this object.

Note

Note that this method can be invoked safely even if the initialize class method has not yet been called.

determineThresholdLevels()

void ball::AttributeContext::determineThresholdLevels	(	ThresholdAggregate *	levels,
		const Category *	category
	)		const

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).

Precondition

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.

getContext()

static AttributeContext * ball::AttributeContext::getContext ( )

static

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

Note that this method can be invoked safely even if the initialize class method has not yet been called.

hasAttribute()

bool ball::AttributeContext::hasAttribute ( const Attribute &  value ) const

inline

Return true if an attribute having the specified value exists in any of the attribute containers maintained by this object, and false otherwise.

Note

Note that this method can be invoked safely even if the initialize class method has not yet been called.

hasRelevantActiveRules()

bool ball::AttributeContext::hasRelevantActiveRules

(

const Category *

category

)

const

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).

Precondition

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.

initialize()

static void ball::AttributeContext::initialize ( CategoryManager *  categoryManager, bslma::Allocator *  globalAllocator = 0  )

static

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

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.

lookupContext()

static AttributeContext * ball::AttributeContext::lookupContext ( )

static

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

Note that this method can be invoked safely even if the initialize class method has not yet been called.

print()

bsl::ostream & ball::AttributeContext::print	(	bsl::ostream &	stream,
		int	level = 0,
		int	spacesPerLevel = 4
	)		const

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.

removeAttributes()

void ball::AttributeContext::removeAttributes ( iterator  element )

inline

Remove the specified element from the list of attribute containers maintained by this object.

Note

Note that this method can be invoked safely even if the initialize class method has not yet been called.

reset()

static void ball::AttributeContext::reset ( )

static

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

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.

visitAttributes()

static void ball::AttributeContext::visitAttributes ( const bsl::function< void(const ball::Attribute &)> &  visitor )

static

Invoke the specified visitor for all attributes in all attribute containers maintained by this object.

Friends And Related Symbol Documentation

AttributeContextProctor

friend class AttributeContextProctor

friend

---

The documentation for this class was generated from the following file:

• ball_attributecontext.h