Event Manager Interface


1. General

Event manager interface was introduced to generalize I/O multiplexing and close functionality. It is portable across platforms, but interface might be slightly different. Read/Write indications and timers are supported on all platforms, while signals are specific to UNIX and WSA indications, events, window messages are specific to windows.

2. Design goals

Main design goal of this component is to provide generic, platform-independent way of managing thread's main loop. This interface was introduced to minimize software component's knowledge about particular event manager implementation.

3. Interface

Object model is comprised of main event manager component and several event objects, that can be registered/de-registered with event manager. Every event object has bound type, describing the nature of the event. Currently supported event types are read/write indications on I/O descriptors, timers, signals, events, window messages.

Event object also has callback interface. This interface is used to notify the user, that requested event occurred. This interface is normally implemented by client code, interested in receiving notifications.

The type of the event and callback interface implementation are bound to event object at construction time. But the fact whether this callback is invoked is controlled by presence of the event object in particular event manager. And generally speaking, single instance of event object should be bound to single event manager, i.e. it is not recommended to have single event object, registered with different event managers (i.e. in different threads). This would require extra synchronization, that may have an impact on performance with a small functional improvement.

Important property of the event object of any type is persistence, i.e. if event object is registered with event manager, it will fire events according to its type as long as it remains registered and specified condition is met. For example timer will invoke callback interface every period T. There is no need to re-activate event object on every callback execution.

Event manager abstract class is IEventManagerInterface. In addition to pure virtual functions, it also has several typedefs:

Back to the top ↑

3.1. Event Objects

Lifetime. Event objects are normally instantiated in client code and kept alive as long as there is an interest in corresponding event. When event object is being registered in event manager, the copy of supplied object is stored internally. There is a reason to keep the instance of event object outside event manager even after event object is registered, because event object itself is key for removal. Event object may be altered; for example, internally stored socket registered as read interest can be changed. However if change operation applies to user copy of event object, it will not automatically alter the copy, stored in event manager. This change can be activated by either removing/inserting event object or by altering the copy stored inside event manager. This copy can be accessed via the reference, returned from AddEvent call.

Generally event object can be thought as a placeholder for the following concepts:

Event object exports following types:

Event object has the following methods (IEventManagerInterface is omitted for clarity):

Every event object is uniquely identified by bound integer value. Unique value is assigned to every instance when it is registered with event manager. Copy or assignment does not generate new identifier. Method returns current value of the unique identifier:

TIdentifier GetEventObjectID()const throw();

Following methods allow comparison of different instances:

Method returns the type, bound to event object: EInternalRequestedEvent GetEventType() const throw();

These methods are specific to particular types of event object:

Note that all event object calls, described above, are specific to particular subset of event object types. If event object was constructed with the the type, incompatible with called function, the result is undefined. In particular, debug assertion is thrown and such behavior may result in malfunction in release version, or at least in improper behavior.

Back to the top ↑

3.2. Event object's callback interface

Callback interface has embedded enumeration ECallbackStatus, representing possible return values from callback method.

Callback method has the following prototype:
virtual ECallbackStatus OnEvent(const CEventObjectType& _crefEventObject) = 0;
User class normally derives from callback interface and overrides this method, providing a reference to implementation during event object construction. When requested event occurs, overridden callback method is called, supplying a reference to event object, stored inside event manager. This reference can be used to make a difference between objects, which may cause particular callback execution. This gives an ability to use single sink method to catch events bound to different event objects.

Callback interface method has return value. This value is used to say event manager whether subsequent event notifications are required or not. If callback returns eSucc constant, event manager should continue notifications for target event object. Otherwise eRemoveCorrEventObject is returned and event manager should de-register event object and stop notifications. Note that the same behavior can be achieved by calling event manager's RemoveEvent method. Note that it is safe to perform several RemoveEvent invocations from inside callback method, de-registering different event objects. But beware of removing target event object with RemoveEvent and returning eRemoveCorrEventObject at the same time. This is not guaranteed to work.

eRemoveCorrEventObject also has a special mission: it was introduced to optimize removal process. When RemoveEvent method is called, implementation is likely to search through internal structures to locate event object to be removed. On the other side event manager can optimize removal process when eRemoveCorrEventObject is returned from callback method, because it already has positioned iterator.

Back to the top ↑

3.3. Event manager's interface methods

Event manager interface defines following pure virtual methods:

4. Dependencies

Event manager interface is dependent on system-specific functionality for handling I/O multiplexing, events, windows messages, time support.... cassert functionality is used to diagnose improper usage on early stage of development.

Back to the top ↑

5. Revisions


6. Special notes about implementation

This section is primary intended for event manager interface implementors and can be safely skipped if new implementation is not planned.

Event object class has additional interface for exclusive use by event manager implementation. This interface is comprised of the following methods:

Interface header is created to facilitate integration of event manager functionality into independent components. Event manager implementations currently exist for Windows and UNIX platforms and based on rich experience of our team in developing robust middle-ware applications.

Back to the top ↑

Last modified: Wed Jun 12 10:55:44 JST 2002 © Orchid Technology K.K. 2002 All rights reserved