2. libcw event interface

---

2.1 Overriding methods

Class methods listed in the next paragraphs are prepended with a little ball.  The color of this ball indicates whether or not you are expected to override that method in a derived class:

2.2 Classes defined by libcw

2.2.1 Introduction

The library defines five classes, in libcw/events.h:

class busy_interface_ct;

template<class EVENTTYPE>
  class event_request_base_tct;

template<class EVENTREQUESTBASE>
  class event_request_queue_tct;

template<class EVENTREQUESTBASE, class EVENTREQUESTQUEUE = event_request_queue_tct<EVENTREQUESTBASE> >
  class event_server_tct;

template<class EVENTREQUESTBASE, class EVENTREQUESTQUEUE = event_request_queue_tct<EVENTREQUESTBASE> >
  class event_data_server_tct;

There are in total seven nested (template) classes, three defined by busy_interface_ct, two by event_server_tct and two by event_data_server_tct.  However, these nested classes are of no concern to the user and will not be mentioned any further.

Either event_server_tct or event_data_server_tct is the actual event server.  They are identical except that the latter supports event request data.  All other characteristics that distinguish different event servers are defined in the two template parameter classes that are passed to it: EVENTREQUESTBASE and EVENTREQUESTQUEUE.

EVENTREQUESTQUEUE determines the characteristics of the request queue: the type of queue and how the requests are stored and retrieved.  class event_request_queue_tct is a default class which uses a deque to store the event requests and which handles all requests (in the order in which they were requested) every time its trigger() method is called.  Most custom event servers will need to write a different EVENTREQUESTQUEUE class.

EVENTREQUESTBASE must be derived from event_request_base_tct.  It determines the characteristics of the requests themselves.  In particular, it defines data that needs to be stored in the request object itself (which is passed with the requests).  This data can for instance be used use by the trigger call to determine which requests need handling.

2.2.2 class busy_interface_ct

This class represents a busy interface.  It is only a default class however and the user may define their own busy interface, or use this one as a base class.

An event client can have zero or more busy interface objects, one of which it can pass to the event server when requesting events from it.

A busy interface class must define the following public methods:

When an event occurs for a client that provided a busy interface, then the is_busy() method is called; when this method returns false then first the set_busy() method is called, then the call back function of the client is called and finally the unset_busy() method is called.  If is_busy() returned true however, then the queue() method is called.

2.2.3 template<class EVENTTYPE> class event_request_base_tct

This class is only needed when you design a new EventServer class.  It is an abstract class, used as base class for event request objects, and needs to be passed to the event server as the EVENTREQUESTBASE template parameter.

You will need to derive your own EventRequestBase class from this class when you want to use specific event request data, see below.

Class event_request_base_tct defines the following public methods:

Usually, add_reference() and release() will be called as a pair as part of the queuing mechanism of a busy interface class.  The method release() is always called after a request is handle()-ed.

Further more, the following type is defined:

Finally, class event_request_base_tct is an interface, defining the virtual functions:

You should not override or call these two functions.

2.2.4 template<class EVENTREQUESTBASE> class event_request_queue_tct;

This is the default EVENTREQUESTQUEUE template parameter of event_server_tct and event_data_server_tct.  It stores requests in a STL deque.  All requests are handled, in the same order as that they were added, when the trigger() method is called.

Click here for information on what a custom EVENTREQUESTQUEUE must provide.

Class event_request_queue_tct has one public method:

2.2.5 template<class EVENTREQUESTBASE, class EVENTREQUESTQUEUE> class event_server_tct

This class defines an interface for requesting events without request data, by means of four overloaded operator() template methods:

EVENTCLIENT, REQUESTCOOKIE and BUSYINTERFACE can be any arbitrary class type, although BUSYINTERFACE must provide the necessary methods of course.  In general, the provided busy_interface_ct will be sufficient.

The REQUESTCOOKIE object is copied into the request object and returned with em(), the call back function, when the request is being handled.

2.2.6 template<class EVENTREQUESTBASE, class EVENTREQUESTQUEUE> class event_data_server_tct

This class defines an interface for requesting events with request data, by means of four overloaded operator() template methods.  It is completely identical with class event_server_tct above, except that the first parameter of the operator() methods is of type EVENTREQUESTBASE::event_request_data_ct and will be passed as initialization data to the constructor of EVENTREQUESTBASE.

Note the difference between event_request_data_ct and REQUESTCOOKIE:  The first is a fixed type determined by the developer of the event server.  REQUESTCOOKIE is arbitrary and can differ from request to request.  The Cookie object is returned to the caller, while the request data is not; and vica versa, the Cookie object is not available to the event server code while the request data can be used in (for example) the trigger method.

2.3 EventServer classes

Defining a new Event Server involves the definition of, at most, five classes:

class EventData
class EventType
class EventRequestBase
class RequestQueue
class EventServer

2.3.1 EventData

Libcw makes no distinction between EventData and EventType: Only EventType is used.  EventData merely contains data and operators that work on that data, while EventType must be an unique type, devoted to this specific EventServer.  EventType can be derived from EventData allowing to use EventData also for other purposes (like other event servers).

2.3.2 EventType

This class is specific for this EventServer, hence the use of the word type.  However, you will mostly consider it to be data, and that is correct because it should be derived from EventData.  EventType is the type that is passed from the event server to the event client, as parameter of the call back function.  While the type can be any arbitrary object, it should be noted that it is passed as a const reference.  This means that you can't change it until you copied it.  It might be obvious why a reference is passed, and not a copy, while that is faster.  The reason it has to be const is that the same object is passed to every client that requested the event.

2.3.3 EventRequestBase

For every request made by a client, a request object needs to be stored in a queue.  The created objects are of different types however: Different clients, different call back functions, different busy interfaces if any and different cookies if any.  Therefore we can only store a pointer in the queue: A pointer to the base class of the request object.  EventRequestBase is this base class, allowing you to control the objects available in the request queue.

The EventRequestBase must be derived from event_request_base_tct.

Request data

It is possible to add extra attributes to the EventRequestBase: You can add one object which will be initialized with data provided by the client, when the client issues its request.  In order to do so, you need to define the type event_request_data_ct inside your EventRequestBase class and provide a constructor that takes that type as single parameter.

Example:

class MyEventType { /* ... */ };

class MyEventRequestBase: public event_request_base_tct<MyEventType> {
  typedef struct timeval event_request_data_ct;
private:
  struct timeval t;
public:
  MyEventRequestBase(struct timeval a) : t(a) { }
};

In order to let the event server create request objects with this constructor, one must use event_data_server_tct.  Class event_server_tct will call the default constructor of EventRequestBase.

2.3.4 EventRequestQueue

This object is a base class for the event server.  It must store requests and call the handle() method of the requests when they are triggered (optionally deleting requests after that by calling their release() method).

When the object is destructed, it must call the release() method of all requests that are still stored.

An EventRequestQueue class must define one protected method:

Example:

class MyEventRequestQueue {
  typedef priority_queue<MyEventRequestBase*, list<MyEventRequestBase*>, ptr_greater> event_requests_ct;
private:
  event_requests_ct event_requests;
  ~MyEventRequestQueue();
public:
  struct again* it_happened(int hard);  /* (arbitrary) trigger method */
protected:
  void add_request(MyEventRequestBase* er) { event_requests.push(er); }
};

MyEventRequestQueue::~MyEventRequestQueue()
{
  while (!event_requests.empty())
  {
    event_requests.top()->release();
    event_requests.pop();
  }
}

Here ptr_greater is a function object that sorts the priority queue.

For a working example of an event server that uses a priority queue, see libcw/timing.h.

2.3.5 EventServer

EventServer is basically just a typedef.  Depending on whether or not you use request data, one defines this type as:

typedef event_server_tct<EventRequestBase, EventRequestQueue> EventServer;

or as

typedef event_data_server_tct<EventRequestBase, EventRequestQueue> EventServer;

---

Copyright © 1999 Carlo Wood.  All rights reserved.