ECS

- The ECS C++ Annotation and Event I/O Interface

SYNOPSIS

#include <ECS/ECS.hh>

class ECS
{
	public:
	_ECSAIO_PRIVAPI static voic mainloop
	   (
	     const struct timeval* timeout = 0, bool idle = true
	   );
	_ECSAIO_PRIVAPI static int32 poll
	   (bool doAll = true);
	_ECSAIO_PRIVAPI static void shutdown();
};

CLASS TYPE

Static

AUDIENCE

ECS Application Developers

DESCRIPTION

This is an object oriented interface for communication with ecsd.

This API is suitable for development of programs for performing input and/or output of events from the correlation engine, and for the development of annotation servers.

This API aims to provide the same functionality as the C ANNO and EIO APIs while hiding much of the complexity. However the restrictions applicable to the C API also apply here.

The API uses a callback mechanism to receive output from the engine. The expected usage is that a program will create instances of the classes ECS_EventReceiver and ECS_Annotater, set their filters and register them with the appropriate ECS Engine instance(s).

The program must then call ECS::mainloop() or call ECS::poll() repeatedly. These methods will make callbacks to the registered handlers when information of interest arrives.

Use of mainloop() and poll() is not necessary in programs which only send events to the engine.

The ECS class exists to provide a namespace for ECS methods which are not associated with a particular class instance.

This class also maintains global status information which is used to manage communications with the engine. This information is not publicly accessible.

PUBLIC MEMBERS

`mainloop()`

_ECSAIO_PRIVAPI static void mainloop

(

	const struct timeval* timeout = 0,

	bool idle = true

);

This method will monitor event channels for incoming events or annotation requests. When an event or annotation request is received, a call will be made to the appropriate handler class to process the event.

This method will block until the shutdown() method is called by a handler class or a timeout occurs.

Timeout has two modes of operation.

The default mode (idle = true) provides an idle timer. If no events or annotation request arrive, and no monitored file descriptors become readable for the specified time then mainloop() will exit.
The second mode (idle = false) is used to specify a duration from the time at which it is invoked after which mainloop() will exit.

The accuracy of this second mode is limited as mainloop() may pass control to user code (in ECS_EventRecievers, etc). What is guaranteed is that mainloop() will not block after the specified duration has passed, and will exit as soon as control is returned to it.

`poll()`

_ECSAIO_PRIVAPI static int32 poll(bool doAll = true);

This method will check to see if any events or annotation requests have arrived which have yet to be processed. If there are any then the appropriate handler class will be called to process the event or request.

If doAll is true this method will only return when there are no more pending events or requests. This is the recommended usage.

If doAll is false then only the next pending request will be processed and the call will return.

`shutdown()`

_ECSAIO_PRIVAPI static void shutdown();

An event handler or annotation class may call this when it decides to terminate processing. When the handler returns mainloop() will exit and return control to the calling routine.

NOTE

A single process can communicate with at most 8 engine instances. The communication resources are allocated the first time that communications are established with an engine and are not released until the process exits.

LIBRARY

ECS

VERSION

1.4

DATE RELEASED

1998/02/25

AUTHOR(S)

Hewlett-Packard Company

ECS