Toggling Log Output
[Run-time Environment]

During some runs, particularly explicit codes, writing to the log file generates excessive output that is not needed. Once method of trimming this output is to only send it to the log file at a specified interval. The LogControl subsystem provides a mechanism for the developer to provide simple output rule and the user to specify the rule to control the desired output.

The LogControl subsystem does this by directing the output to the log file stream buffer or redirecting it to an in memory stream based on the evaluation of the rule. This in memory stream can be discarded or can later be written to the log file if an error condition arises.

By usong this technique, the statements which currently write to the log file are not effected and if the system is not activated, the normal output is produced.

Log Control Sentry

A sentry class, LogControl takes an output stream and a rule as an argument. When the LogControl's next() function is called, the output stream is directed to write to the log file or to the cache based on the result of the evaluation of the rule.

In the following example, the construction of the LogControl sentry stores the sierra::out() stream, its stream buffer, and the rule associated with the m_name. A cache ostringstream is also created to cache the potentially discarded output. Each time the log_control's next() function is called, the rule is evaluated and the results determine which stream buffer to attach to the sierra::out() stream; either sierra::out()'s original if the rule returns true or the cache's. The previously cached text is discarded at each next() execution.

If the execution fails, the cached stream buffer is written to the original output stream and the cache is cleared.

    stk::LogControl log_control(sierra::out(), m_name);
    while (!done) {
      try {
      catch (std::exception &x) {;

The LogControl's maintain a link to the parent LogControl for each stream. Therefore, each shares the same log stream and original log stream buffer. On construction, the root LogControl has the original stream buffer of the log stream, so the root's log stream buffer pointer is copied to new LogControl sentry. On destruction, since the log streams are all shared, the log stream must have it's stream buffer replaced with the original log stream or it's cache stream depending upon it current state.

Log Control Rules

The logging or caching of a log stream is determined by a log rule. A log rule class consists of a clone() function and a next() function and inherit from LogControlRule.

    struct LogControlRule
      virtual LogControlRule *clone() const = 0;
      virtual bool next() = 0;

The clone() pure virtual function allows the rule to be copied. And is implemented as

    virtual LogControlRule *clone() const {
      return new MyRuleClass(*this);

The next() function is used to determine the destination of the output stream. If the next function returns true, the log stream write to its original stream buffer, which is generally the log file. When it returns false, the output is written to the current log control sentry's cache stream.

Predefined Log Control Rules

The LogControlRuleAlways and LogControlRuleInteval rules are predefined. The LogControlRuleAlways' next() function always returns true resulting the output always going to the log file. The LogControlRuleInteval is constructed with an interval and maintains a count. The LogControlRuleInteval's next() function increments the count and returns true of the count mod interval is zero.

Log Control Rule Registration

To simplify the usage of rules, the LogControl subsystem maintains a mapping of named rules. These rules are copied during the construction of the LogControl sentries when they are constructed by passing a rule name.

The addLogControlRule() function adds the rule to the map with specifed name.

Generated on Tue Jul 13 09:27:33 2010 for Sierra Toolkit by  doxygen 1.4.7