Component ball_broadcastobserver [Package ball]

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

Namespaces
namespace	ball

---

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Thread Safety
  • Usage
    • Example 1: Delayed Observer Configuration

Purpose:

Provide a broadcast observer that forwards to other observers.

Classes:

ball::BroadcastObserver

observer that forwards to other observers

See also:

Component ball_record, Component ball_context, Component ball_observer, Component ball_loggermanager

Description:

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

                 ,-----------------------.
                ( ball::BroadcastObserver )
                 `-----------------------'
                            |             ctor
                            |             registerObserver
                            |             deregisterObserver
                            |             deregisterAllObservers
                            |             findObserver
                            |             numRegisteredObservers
                            |             visitObservers
                            V
                     ,--------------.
                    ( ball::Observer )
                     `--------------'
                                          dtor
                                          publish
                                          releaseRecords

ball::BroadcastObserver 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::BroadcastObserver maintains a registry of named observers to which it forwards log records. Clients of ball::BroadcastObserver register observers using the registerObserver method and unregister observers with the deregisterObserver method. Once registered, an observer receives all log records that its associated broadcast observer receives.

Thread Safety:

ball::BroadcastObserver is thread-safe, meaning that multiple threads may share the same instance, or may have their own instances (see bsldoc_glossary).

Usage:

In this section we show intended use of this component.

Example 1: Delayed Observer Configuration:

In this example, we will show how ball::BroadcastObserver can be used to implement delayed observer configuration.

First, we define an elided custom observer that conforms to the ball::Observer protocol and supports a configure method:

  class ConfigurableObserver : public ball::Observer {
      // DATA
      bool d_configureFlag;   // configuration completion flag

    public:
      // CREATORS
      ConfigurableObserver() : d_configureFlag(false)
      {
      }

      // MANIPULATORS
      void configure() {
          // Configure this observer.
          d_configureFlag = true;
      }

      void publish(const bsl::shared_ptr<ball::Record>& record,
                   const ball::Context&                 context)
          // Publish the specified 'record' with the specified 'context'.
      {
          // Do not publish any records until configuration has been done.
          if (!d_configureFlag) {
              return;                                               // RETURN
          }
          // Publish the record.
          // ...
      }
      // ACCESSORS
      bool isConfigured() const
      {
          return d_configureFlag;
      }
  };

Then, we create a shared pointer to a ConfigurableObserver object and register it with a broadcast observer:

  bsl::shared_ptr<ConfigurableObserver>
                                   myObserverPtr(new ConfigurableObserver());

  ball::BroadcastObserver broadcastObserver;

  int rc = broadcastObserver.registerObserver(myObserver, "observer");

  assert(0 == rc);

Finally, we can retrieve the registered observer and configure it:

  bsl::shared_ptr<ConfigurableObserver> tmpObserverPtr;

  rc = broadcastObserver.findObserver(&tmpObserverPtr, "observer");

  assert(0 == rc);
  assert(myObserverPtr == tmpObserverPtr);
  assert(false == tmpObserverPtr->isConfigured());

  tmpObserverPtr->configure();

  assert(true == tmpObserverPtr->isConfigured());

Note that there is an alternative way to obtain a shared pointer to the registered observer:

  bsl::shared_ptr<Observer> oPtr =
                                  broadcastObserver.findObserver("observer");

  assert(oPtr.ptr());

  bsl::shared_ptr<ConfigurableObserver> anotherObserverPtr;

  bslstl::SharedPtrUtil::dynamicCast(&anotherObserverPtr, oPtr);

  assert(myObserverPtr == anotherObserverPtr);