Component ball_transmission [Package ball]

Enumerate the set of states for log record transmission. More...

Namespaces
namespace	ball

---

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Usage
    • Example 1: Syntax
    • Example 2: Logging

Purpose:

Enumerate the set of states for log record transmission.

Classes:

ball::Transmission

namespace for log record transmission states

See also:

Component ball_context, Component ball_observer

Description:

This component provides a namespace, ball::Transmission, for the enum type ball::Transmission::Cause. Cause enumerates the list of conditions (or states) that can cause a log record to be transmitted. In addition, this component supports functions that convert the Cause enumerators to a well-defined ASCII representation.

Usage:

This section illustrates intended use of this component.

Example 1: Syntax:

The following snippets of code provide a simple illustration of ball::Transmission usage.

First create a variable cause of type ball::Transmission::Cause and initialize it to the value ball::Transmission::e_TRIGGER_ALL:

  ball::Transmission::Cause cause = ball::Transmission::e_TRIGGER_ALL;

Next, store a pointer to its ASCII representation in a variable asciiCause of type const char *:

  const char *asciiCause = ball::Transmission::toAscii(cause);
  assert(0 == strcmp(asciiCause, "TRIGGER_ALL"));

Finally, print the value of cause to bsl::cout.

  bsl::cout << cause << bsl::endl;

This statement produces the following output on stdout:

  TRIGGER_ALL

Example 2: Logging:

The Cause enumeration defined in this component allows a logging system to describe the condition causing the publication of a log message. One possible interpretation of three of these conditions is as follows:

e_PASSTHROUGH:
indicate that a message is being output as a stand-alone message.

e_TRIGGER:
indicate that a message is being output as part of a dump of all messages archived for the current thread.

e_TRIGGER_ALL:
indicate that a message is being output as part of a dump of all messages archived for all threads.

This example illustrates the use of ball::Transmission::Cause by a hypothetical logging system.

We define a simple logger class named my_Logger. Assume that my_Logger accepts messages from clients (e.g., the threads in a multi-threaded application) and archives them in-core. Further assume that the message archive is bounded in size in which case my_Logger removes older messages to make room for newer ones as the need arises. When a thread encounters an unusual, unexpected, or undesirable condition that it wishes to bring to the attention of an operator (say, sitting at a console terminal), it "publishes" the message. That is the role of the publish method in the interface of my_Logger:

  // my_logger.h

  class my_Logger {
    // ...
    public:
      my_Logger();
      ~my_Logger();
      void publish(const char *message, ball::Transmission::Cause cause);
      // ...
  };

The publish method, defined in the following, shows the different actions that are taken for the three distinct causes of log message publication:

  // my_logger.cpp

  my_Logger::my_Logger() { }

  my_Logger::~my_Logger() { }

  void my_Logger::publish(const char                *message,
                          ball::Transmission::Cause  cause)
  {
      using namespace std;
      switch (cause) {
        case ball::Transmission::e_PASSTHROUGH: {
          cout << ball::Transmission::toAscii(cause) << ":\t" << message
               << endl;
        } break;
        case ball::Transmission::e_TRIGGER: {
          cout << ball::Transmission::toAscii(cause) << ":\t" << message
               << endl;
          cout << "\t[ dump all messages archived for current thread ]"
               << endl;
        } break;
        case ball::Transmission::e_TRIGGER_ALL: {
          cout << ball::Transmission::toAscii(cause) << ":\t" << message
               << endl;
          cout << "\t[ dump all messages archived for *all* threads ]"
               << endl;
        } break;
        default: {
          cout << "***ERROR*** Unsupported Message Cause: "  << message
               << endl;
          return;
        } break;
      }
  }

  // ...

Finally, we create a my_Logger object and publish three (simplistic) messages, each with a different cause:

  my_Logger logger;

  const char *MSG_PASSTHROUGH = "report relatively minor problem";
  const char *MSG_TRIGGER     = "report serious thread-specific problem";
  const char *MSG_TRIGGER_ALL = "report process-impacting problem";

  logger.publish(MSG_PASSTHROUGH, ball::Transmission::e_PASSTHROUGH);
  logger.publish(MSG_TRIGGER,     ball::Transmission::e_TRIGGER);
  logger.publish(MSG_TRIGGER_ALL, ball::Transmission::e_TRIGGER_ALL);

The following output is produced on stdout:

  PASSTHROUGH:    report relatively minor problem
  TRIGGER:        report serious thread-specific problem
                  [ dump all messages archived for current thread ]
  TRIGGER_ALL:    report process-impacting problem
                  [ dump all messages archived for *all* threads ]