Component ball_ruleset [Package ball]

Provide a set of unique rules. More...

Namespaces
namespace	ball

---

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:

Component 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);