Title: Experiences of Implementing the Observer Design Pattern (Part 3)

This is a novel approach, based on 'signals' (messages) and 'slots' (message destinations). Qt is a very neat GUI library that works on Unix and Win32. The KDE desktop environment is based upon it. I have a lot of respect for their approach. It is very flexible, type safe and certainly inventive. However, it has a number of drawbacks which make it impractical for my use. First, it would necessitate a dependency on a GUI library (which is far too large a dependency for small code libraries). Second, it requires the generation of some implementation code for each class using signals or slots. This 'meta class' code will enlarge the code base^[1]. Thirdly, as a consequence of this a meta compilation stage is required to automatically generate this code.

The Qt approach adds extensions to the C++ language (i.e. the signal and slot keywords) to provide a very flexible implementation. However, I am looking to stay strictly within the bounds of standard C++^[2].

Hickey has some strong views on what a callback is/should be, some of which I am not sure I agree with. He reviews some of the approaches and describes their shortfalls (interestingly, he slates a simplistic version of what I present below). However, he presents a novel method of using templates to create a type-safe and generic callback system. However, as presented in the article the system is not as flexible as we would like. For example, multiple numbers of callbacks can be stored in a vector and iterated over. However, for each notifying object you have to write attach/detach/iteration code from scratch.

Now this is a really nice solution. I will not say too much about it because my implementation is based heavily on Bartosik's work. I include him in this list because I do not deserve credit for what he has already done. Although based on Bartosik's design, this implementation augments his work in several key areas.

I have to say that I was surprised that hardly anyone replied to my calls for other Observer implementations in previous articles. Either people do not have any better implementations (I find that hard to believe), did not read the article (my heart sinks) or could not be bothered (in which case, I now encourage you again to respond - you do not have to write an article, just mail me your code). If you know of any other good implementations provided by off-the-shelf libraries, then please write in to let us know.

The use of this notifier framework is simple. Using the good old examples of the Exhibitionist and Voyeur classes (which are types of Notifier and Listener, respectively) we would write something like the following. First we forward declare the class that will be sending the events.

class Exhibitionist;

Next we define an interface for this class to call back to. This interface defines the events that the Exhibitionist can send. Note that we must include a typedef describing the type of the Notifier class. This is needed by the implementation of the framework later on. In this example we have only one event. Note that I prefix its name with Exhibitionist_. I have found this to be a useful convention, use it at your discretion.

class ExhibitionistListener {
  public:
    typedef Exhibitionist notifier_type;
    virtual void Exhibitionist_Event (Exhibitionist *src, int data) {}
};

Note that the callback methods are required to be virtual (the system will not work otherwise), and that the method provides a default implementation that does nothing. You could define the method as pure virtual (i.e. write "= 0;" rather than "{}"). Like this, however, you can chose to only handle some events and do nothing for others by being selective in your overriding.

Now that the interface is defined we can implement a Voyeur class in terms of it. This is shown below. Note that the Voyeur inherits from Listener<ExhibitionistListener>. This class inherits from the ExhibitionistListener directly. Therefore the Voyeur can redefine the interface's virtual methods to act on any notifications.

class Voyeur : public Listener<ExhibitionistListener> {
  public:
    void foo(Exhibitionist *e) {
// we want to listen to the Exhibitionist
      attachTo(e);
    }
    virtual void Exhibitionist_Event (Exhibitionist *src, int data) {
      cout << "Moo " << data << '\n';
    }
};

If you call Voyeur::foo the Voyeur will attach itself to the specified Exhibitionist. Whenever this Exhibitionist raises an Exhibitionist_Event then the Voyeur object will receive the event and moo accordingly. The Voyeur can explicitly disconnect itself from an Exhibitionist by calling a detachFrom(Exhibitionist *) method.

So finally it remains for us to see how to implement an Exhibitionist. Again, it is simple.

class Exhibitionist : public Notifier<ExhibitionistListener> {
  public:
    doSomething(){
      notify( &ExhibitionistListener::Exhibitionist_Event, 10);
    }
};

That is it! Now if you call Exhibitionist::doSomething it will send an event to all attached listeners.

You will note that in the notification we only specify one integer parameter (as well as the actual callback method), although the interface method had two parameters. The framework automatically provides the first parameter as a pointer to the source object. This means that when you define an interface you have to bear this in mind.

Why have I done this? I have found that it is generally useful to know which the source object is when handling a notification. This is especially useful when you are listening to more than one object of the same type. Perhaps this is specific to my application of the pattern (somehow I doubt this).

Although I have not shown it here, the system provides a mechanism for Listeners to be automatically informed of when Notifiers are deleted which is often very useful. However, the real bonus of the whole system is this: if either of the Voyeur or Exhibitionist objects are deleted, the link between them is automatically broken (we will see how later). This is what makes the system simple and safe to use.

Just in case you find it hard to visualise, the hierarchy of classes involved looks something like this (although the Listener<> is in fact inheriting from ExhibitionistListener).

Figure 1.

As you can see, a system of this type is generic (not limited to a few interface types) type safe (parameter types are preserved and C++ conversions can be employed), flexible (allows any number of event types each with any number of parameters, modulo the implicit src pointer), and above all really easy to use (partly due to the safety features provided).

The only major wish-list features we have not provided are the ability to call non-member functions (we can create adaptors to do this) and the freedom from inheritance. However, this latter ideal is not really attainable since you need to inherit from a base class to gain the notification implementation.

Since using the Notifier and Listener classes is deceptively simple there has to be some hairy code making it work in the background. This is where it gets interesting.

In order to show the full implementation we will add functionality a step at a time. The full versions of the Notifier and Listener classes are heavily interdependent in order to implement the safety features. I have ordered some of the following code to aid the reader. You should (hopefully) be able to read from the top down.

The Notifier implementation looks roughly like this:

template <class interface_type> Listener;
template <class interface_type>
class Notifier {
  public:
    typedef Listener<interface_type> listener_type;
    friend listener_type;
  private:
    std::vector<listener_type*> listeners;
  protected:
    template <typename func_type>
    void notify(func_type func);
    template <typename func_type, typename p1_type>
    void notify(func_type func, const p1_type &p1);
    template <typename func_type, typename p1_type, typename p2_type>
    void notify(func_type func, const p1_type &p1, const p2_type &p2);
    virtual ~Notifier();
  private:
// only called by listener_type, returns whether call is valid
    bool attach(listener_type *listener){
      if(find(listeners.begin(), listeners.end(), listener) != listeners.end())
          return false;
      listeners.push_back(listener);
      return true; 
    }
    bool detach(listener_type *listener) {
      if (find(listeners.begin(), listeners.end(), listener)== listeners.end())
         return false;
      listeners.erase(listener);
      return true;
    }
    typedef Notifier<interface_type> self_type;
    typedef typename interface_type::notifier_type c_notifier_type;
    Notifier(const self_type &);
    self_type &operator=(const self_type &);
    void doEvent(const AbstractEvent<interface_type>&);
};

What we have seen above is basically the management of a list of Listener objects. The other interesting point that can be seen is that we have declared a version of the notify method for each number of parameters which we want to support. This is a running theme through the implementation. In the code above we can handle notifications with 0-2 parameters. You can extend the implementation as required^[3]. Note that the notify functions are template members. This allows us to provide callback methods with any type of parameters in a type safe way.

Note that the c_notifier_type typedef describes the concrete Notifier type that will inherit from this class. We need this in the implementation later on.

Now to implement the notify methods, we define a template functor (in a similar vein to [Hickey]) to call the appropriate method on the interface_type. We define a simple abstract interface for this functor:

template <class interface_type>
class AbstractEvent {
  public:
    virtual void operator()(interface_type *listener) const = 0;
};

Now we add a doEvent method to the Notifier class interface that iterates over every attached Listener and invokes the functor on it. This is called by each of the notify methods.

void doEvent(const AbstractEvent<interface_type> &event){
  for (size_t i = 0; i < listeners.size(); i++) {
    event(listeners[i]);
  }
}

It is the Event class (that inherits from the AbstractEvent) that does the clever stuff - calling the appropriate interface method. Before showing the class let us see how the notify methods create Event objects. This shows the case of one extra parameter, extend or contract accordingly for the others:

template <typename func_type, typename p1_type>
void Notifier::notify(func_type func, const p1_type &p1){
  typedef Event<interface_type, func_type, c_notifier_type, p1_type> event_type;
  doEvent(event_type(func, static_cast<c_notifier_type*>(this), p1));
}

Although this does not mean much on its own, it will be helpful to bear in mind as you read the definition of the Event class. Again it is declared for 0-2 parameters and may be extended accordingly. The definition of arg_count and num_type follow, with a discussion of the code.

template <class interface_type, typename listener_func,typename p1_type = def_type,
          typename p2_type = def_type>
class Event : public AbstractEvent<interface_type> {
  public:
    explicit Event(listener_func func, const p1_type &p1 = p1_type(),
                   const p2_type &p2 = p2_type())
       : func(func), p1(p1), p2(p2), {}
    virtual void operator()(interface_type *listener) const {
      const unsigned int argCount = arg_count<p1_type>::count
                                  + arg_count<p2_type>::count;
      if (listener) invokeImpl(listener, num_type<argCount>());
    }
  protected:
    template <class T>
    void invokeImpl(T *listener, num_type<0>) const {(void)(listener->*func)(); }
    template <class T>
    void invokeImpl(T *listener, num_type<1>) const {(void)(listener->*func)(p1); }
    template <class T>
    void invokeImpl(T *listener, num_type<2>) const {(void)(listener->*func)(p1, p2);
    }
  private:
    const listener_func func;
    const p1_type       p1;
    const p2_type       p2;
};

The constructor stores the callback method to call and the parameters with which to call it. If you do not instantiate the template class with all the parameter types then a def_type is supplied. This is a dummy type that represents 'not used'. It looks like this:

  class def_type {};

It is the operator() method that works out how many parameter types have been supplied, by using the arg_count class - this works out how many of the template parameters were explicitly specified (the others will be def_type). arg_count looks like this:

  template <typename T> struct arg_count { enum { count=1 }; };
  template <> struct arg_count<def_type> { enum { count=0 }; };

You may like to look at that a little more just to work out how the argCount variable gets to hold the number of func_type parameters that have been specified.

Using this value, operator() selects one of the overloaded invokeImpl methods to call. There is one of these for each of the number of parameters supported (0-2). We use another clever template 'macro' num_type to select only the relevant invokeImpl. The invokeImpls are template member functions when they need not be (after all the T type is already known to be interface_type). This is vital though, since only one of these methods will be valid for each event. The other invokeImpls are ignored by the compiler.

num_type is provided by the following innocuous bit of code:

  template<unsigned> class num_type {};

Now, each invokeImpl method calls the appropriate interface_type member function with the appropriate number of parameters.

Now we have seen the entire trace of execution of a Notifier callback. It quite cunning, and perhaps you will need to read it over a couple of times to really appreciate what is going on (I certainly did to check I wrote it correctly!)

The best bit about all these template shenanigans is that it is all worked out at compile time - it has very little runtime overhead at all (the expense is a little auto-generated code, which has a very small practical cost).

Now let us see what the Listener looks like. (Do not worry, the frightening bit is over now.) The Listener obviously provides a mechanism to attach to and detach from Notifiers. It also remembers which Notifiers it is attached to, so that it can detach from them if it is deleted.

template <class interface_type>
class Listener : public interface_type {
  public:
    typedef Notifier<interface_type> notifier_type;
    typedef typename interface_type::notifier_type c_notifier_type;
    friend notifier_type;
  private:
    std::vector<notifier_type*> notifiers;
  public:
// Now whether attachTo and detachFrom are public or protected is your choice, it 
// depends on how you want to use the API
    void attachTo(notifier_type *notifier) {
      if (notifier->attach(this))notifiers.push_back(notifier);
    }
    void detachFrom(notifier_type *notifier) {
      if (notifiers.erase(notifier)) notifier->detach(this);
    }
  protected:
    virtual ~Listener() {
// This provides some of the 'object safety'
      for (size_t i = 0; i < notifiers.size(); i++) { notifiers[i]->detach(this); }
    }
  private:
    typedef Listener<interface_type> self_type;
    Listener(const self_type &);
    self_type &operator=(const self_type &);
};

That is not really too hair raising. There is one member function that I have left out, which I now present. This is the mechanism by which a Listener can be automatically informed when a Notifier is deleted.

The Listener declares a protected method using the c_notifier_type typedef:

  virtual void Notifier_Deleted(c_notifier_type *notifier) {}

This can be reimplemented by concrete Listener classes (for example, the Voyeur class) if they want to know when their Notifier is deleted. The Voyeur would override Notifier_Deleted(Exhibitionist *src), for example.

This is called by a private Listener method, which is in turn called by the Notifier destructor. This is why the notifier_type is a friend of the Listener class. Here is the final private Listener method:

  void NotifierImpl_Deleted(c_notifier_type *src) {
    notifiers.erase(static_cast<notifier_type*>(src));
    this->Notifier_Deleted(src);
  }

Finally, we see how the Notifier destructor calls this:

template <interface_type>
virtual Notifier::~Notifier(){
  for (size_t i = 0; i < listeners.size(); i++){
    listeners[i]->NotifierImpl_Deleted(static_cast<c_notifier_type*>(this));
  }
}

This completes the description of the implementation of the Observer pattern. It involves some fairly complex C++ code, so you may want to go over it again. Whilst it is a lot to take in, it is in fact a really elegant and neat solution. The Getting the Code section at the end of this article describes where you can download the complete implementation. You may find this useful.

Note that in my 'real' version the implementation classes (Event, def_type et al) which clutter the global namespace unnecessarily have been hidden (slightly) within an Impl namespace. This prevents the user from becoming unnecessarily caught up in the implementation details. It also contains another slight modification, described in the next section.