Proxy methods

A proxy method is a regular function that acts as a method (non-static member function) of a collectable object. Proxy methods are useful if you need to connect an event to a method with incompatible arguments.

Suppose, for instance, that you have two classes, named SignalSampler and RealTimeGraph, that are defined as follows:

class SignalSampler : public Collectable
{
 public:
 
  // First event argument  : time of sample.
  // Second event argument : signal level.
 
  Event<Time,double>  newSampleEvent;
  
  
  // More members ...
  
};

class RealTimeGraph : public Collectable
{
 public:
 
  void addPoint ( double value, const Time& t );
  
  
  // More members ...
  
};

Now you want to connect the newSampleEvent of the SignalSampler class to the method addPoint of the RealTimeGraph. Unfortunately, this is not possible because the order of the arguments is incorrect. This problem can be solved elegantly by defining a proxy method that calls the addPoint method with the arguments in the correct order. The following code shows how to do this.

void addPointProxy ( RealTimeGraph&  graph,
                     const Time&     t,
                     double          value )
{
  graph.addPoint ( value, t );
}


int main ()
{
  Ref<SignalSampler> sampler = newInstance<SignalSampler> ();
  Ref<RealTimeGraph> graph   = newInstance<RealTimeGraph> ();
  
  connect ( sampler->newSampleEvent,
            graph,
            & addPointProxy );
  
  // ...
  
  return 0;
}

The proxy method addPointProxy has three arguments. The first argument is a reference to the collectable object to which the newSampleEvent has been connected. The other two arguments are the arguments of the event. Connecting the newSampleEvent to the proxy method is similar to connecting the event to a normal method.

In general, a proxy method has the following signature:

R proxyMethod ( T& obj, A a, B b, C c )

with R the return type (usually void); with T the type of the object on which the proxy method operates; and with A, B and C the argument types of the proxy method. These must be compatible with the argument types of the event that is connected to the proxy method. The number of arguments may be less than three; the only requirement is that the number of arguments does not exceed the number of arguments of the event that is connected to the proxy method.

An event is connected to a proxy method by calling the connect() function with three arguments: the event to be connected, the object on which the proxy is to operate, and the address of the proxy method. For instance, the call

connect ( e, obj, & proxy )

connects the event e to the proxy method proxy. When the event is emitted, the proxy method is called with the object obj as its first argument, and with the event arguments as the remaining arguments. If the event has more arguments than the proxy method, then the last few event arguments are discarded.