Component ball_multiplexobserver [Package ball]

Provide a multiplexing observer that forwards to other observers. More...

Namespaces
namespace	ball

---

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:

Component ball_record, Component ball_context, Component ball_streamobserver, Component 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.