ball_multiplexobserver

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Thread Safety
  • Usage
    • Example: Basic Usage

Purpose

Provide a multiplexing observer that forwards to other observers.

Deprecated:

Use ball_broadcastobserver instead.

Classes

• ball::MultiplexObserver: multiplexing observer that forwards log records

See also

ball_record, ball_context, ball_streamobserver, ball_loggermanager

Description

This component provides a concrete implementation of the ball::Observer protocol for receiving and processing log records:

             ( ball::MultiplexObserver )
                          |             ctor
                          |             registerObserver
                          |             deregisterObserver
                          |             numRegisteredObservers
                          V
                  ( ball::Observer )
                                        dtor
                                        publish
                                        releaseRecords

ball::MultiplexObserver is a concrete class derived from ball::Observer that processes the log records it receives through its publish method by forwarding them to other concrete observers. ball::MultiplexObserver maintains a registry of observers to which it forwards log records. Clients of ball::MultiplexObserver register observers using the registerObserver method and unregister observers with the deregisterObserver method. Once registered, an observer receives all log records that its associated multiplexing observer receives.

Thread Safety

ball::MultiplexObserver is thread-safe and thread-enabled, meaning that multiple threads may share the same instance, or may have their own instances.

Usage

This section illustrates intended use of this component.

Example: Basic Usage

Note: This usage example retained here for reference purposes for legacy code that still uses multiplex observers. The use of this component is strongly discouraged.

Multiplexing observers are used to interface a ball logging system, which generates log records, with the multiplicity of observers that are to receive the generated records that are published. Establishing this interface proceeds in three logical steps:

  (1) Create a distinguished `ball::MultiplexObserver` that will be the
      unique observer to receive log records directly from the logging
      system.
  (2) Create the other observers required by the application and register
      each of these observers with some `ball::MultiplexObserver`.  (Note
      that a `ball::MultiplexObserver` may be registered with another
      `ball::MultiplexObserver`.)
  (3) Install the distinguished multiplexor from step (1) within the
      `ball` logging system.

This example demonstrates the use of a multiplexing observer to forward log records from a ball logging system to three registered observers. Each of the three registered observers performs distinct actions upon receipt of log records:

  (1) `defaultObserver`, an instance of `ball::StreamObserver`, formats
      the records it receives and outputs them to `stdout`.
  (2) `logfileObserver`, an instance of `my_LogfileObserver` (assumed to
      be a concrete class derived from `ball::Observer`) writes selected
      records to a log file.
  (3) `encryptingObserver`, an instance of `my_EncryptingObserver` (also
      assumed to be a concrete class derived from `ball::Observer`) creates
      a compact, encrypted representation of each record, suitable for
      sending over an unsecure network.

First, we create the three downstream observers that will be registered with multiplexor observer:

   ball::StreamObserver   defaultObserver(&bsl::cout);
   my_LogfileObserver     logfileObserver(&bsl::cout);
   my_EncryptingObserver  encryptingObserver(&bsl::cout);

Next, we create an initially empty multiplexing observer multiplexor and register the three downstream observers multiplexor:

   ball::MultiplexObserver multiplexor;
   assert(0 == multiplexor.numRegisteredObservers());
 
   multiplexor.registerObserver(&defaultObserver);
   multiplexor.registerObserver(&logfileObserver);
   multiplexor.registerObserver(&encryptingObserver);
   assert(3 == multiplexor.numRegisteredObservers());

Then, multiplexor is installed within a ball logging system to be the direct recipient of published log records. The code uses deprecated ball::LoggerManager API and is elided.

Henceforth, all log records that are published by the logging system will be transmitted to the publish method of multiplexor which, in turn, forwards them to defaultObserver, logfileObserver, and encryptingObserver by calling their respective publish methods.

Finally, deregister the three observers when the logs have been all forwarded:

   multiplexor.deregisterObserver(&defaultObserver);
   multiplexor.deregisterObserver(&logfileObserver);
   multiplexor.deregisterObserver(&encryptingObserver);

Note that any observer must exist before registering with multiplexor. Any observer already registered must deregister before its destruction. Additional observers may be registered with multiplexor at any time. Similarly, observers may be unregistered at any time. This capability allows for extremely flexible observation scenarios.