ball_ruleset

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Thread Safety
  • Usage

Purpose

Provide a set of unique rules.

Classes

• ball::RuleSet: container for unique rules

See also

ball_rule

Description

This component provides a value-semantic container, ball::RuleSet, for storage and efficient retrieval of ball::Rule objects.

This component participates in the implementation of "Rule-Based Logging". For more information on how to use that feature, please see the package level documentation and usage examples for "Rule-Based Logging".

Thread Safety

ball::RuleSet is not thread-safe in that multiple threads attempting to concurrently modify the same ball::RuleSet object will leave the object in an undefined state. To ensure thread-safety, concurrent accesses to a ball::RuleSet must be serialized by a mutex.

Usage

The following code fragments illustrate how to use a rule set.

We first create a rule whose pattern is WEEKEND* and whose threshold levels are all ball::Severity::e_OFF except the pass-through level. A pass-through level of ball::Severity::e_INFO indicates that whenever the rule is active and the severity equals or exceeds ball::Severity::e_INFO, log records will be passed to the observer:

ball::Rule rule1("WEEKEND*",               // pattern
                 ball::Severity::e_OFF,    // record level
                 ball::Severity::e_INFO,   // pass-through level
                 ball::Severity::e_OFF,    // trigger level
                 ball::Severity::e_OFF);   // triggerAll level

Next, we create another rule having a different pattern, but the same threshold levels:

ball::Rule rule2("WEEKDAY*",               // pattern
                 ball::Severity::e_OFF,    // record level
                 ball::Severity::e_INFO,   // pass-through level
                 ball::Severity::e_OFF,    // trigger level
                 ball::Severity::e_OFF);   // triggerAll level

We then create a ball::RuleSet object, add the two rules, and verify that rules were added correctly:

ball::RuleSet ruleSet;
assert(0 <= ruleSet.addRule(rule1));
assert(0 <= ruleSet.addRule(rule2));
assert(2 == ruleSet.numRules());

Duplicate rules cannot be added:

assert(-1 == ruleSet.addRule(rule1));
assert(-1 == ruleSet.addRule(rule2));
assert( 2 == ruleSet.numRules());

Rules in a rule set can be looked up by the ruleId method:

int i1 = ruleSet.ruleId(rule1);
int i2 = ruleSet.ruleId(rule2);
assert(0 <= i1); assert(i1 < ruleSet.maxNumRules());
assert(0 <= i2); assert(i2 < ruleSet.maxNumRules());
assert(i1 != i2);

The removeRule method can be used to remove rules from a rule set.

assert(ruleSet.removeRule(rule1));
assert(1 == ruleSet.numRules());
assert(ruleSet.ruleId(rule1) < 0);
assert(ruleSet.ruleId(rule2) == i2);