ball_broadcastobserver

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

ball_record, ball_context, ball_observer, 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
 
    // Configure this observer.
    void configure() {
        d_configureFlag = true;
    }
 
    using Observer::publish;  // avoid hiding base class method
 
    /// Publish the specified `record` with the specified `context`.
    void publish(const bsl::shared_ptr<ball::Record>& record,
                 const ball::Context&                 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);