Functional Description

Description of the Event Management. More...

Description of the Event Management.

The OpenClovis Event Service is a communication mechanism based on the concept of event channels. It is a publish and/or subscribe mechanism where a publisher can communicate with one or more subscribers asynchronously by publishing events over an event channel. The publishers and subscribers can be any component residing anywhere in the cluster.

An Event has a standard header and zero or more bytes of publisher event data. Publishers and Subscribers can communicate over multiple event channels. Multiple publishers and multiple subscribers can communicate over a single event channel. Subscribers are anonymous, which means that they can join and leave an event channel at any time without involving the publisher(s). An Event publisher can also be an Event subscriber.

The Event Service function does not impose a specific layout or format for the published event data. Publishers and subscribers on an event channel must agree on the structure of the data for events published on that event channel. They can use data marshalling, if support for heterogeneity is required. Conventions on the structure of the event data can vary from one event channel to another.

Usage Model

A component can subscribe to receive events on an event channel using the clEventSubscribe() function. The Event Service delivers events to a subscribing component using the clEvtEventDeliverCallback() function of that component. To stop receiving events for which it has registered, a subscriber can invoke the clEventUnsubscribe() function. If a component terminates abnormally, the Event Service closes all of its open event channels.

Service Description

Events

An event consists of a standard set of event attributes (event header) and zero or more bytes of event data. An event header is allocated using the clEventAllocate() function and is released using the clEventFree() function. The clEventAllocate() function returns a handle that can be used in subsequent invocations of the Event Service functions. The event attributes are written and read using {{SET}} and {{GET}} functions of the Event Service function. These attributes cannot be read and written directly. An event is published using the clEventPublish() function. The parameters to be specified for this function are event handle, additional information (optional), and event data contained in a data buffer. Thus, a published event consists of the event header that contains the set of attributes and additional information (optional) contained in the data buffer.

Event Channels

An event channel enables multiple publishers to communicate with multiple subscribers. It is global to a cluster and is identified by a unique name. To use the Event Service, a component must open an event channel using the clEventChannelOpen() or clEventChannelOpenAsync() function. The event channel is created, if it does not exist. A component can open an event channel to publish events and subscribe to receive events. Publishers can also act as subscribers on the same event channel. Event channels can be deleted using the clEventChannelUnlink() function. When an event is allocated for an event channel using the clEventAllocate() call, it can be published several times on the same event channel, by changing its attributes prior to each publication.

The OpenClovis Event Channel has the following features:

• Best effort delivery: The Event Service provides best effort delivery of events to an anonymous set of subscribers. A published event can be lost or it can be delivered to a subset of the subscribers. Some subscribers receive the event while others do not. For example, there is no guarantee that an event is delivered to all existing subscribers, if the publisher fails while publishing the event. A subscriber may lose events, if the subscriber node is overwhelmed with events.

• At most once delivery: The Event Service does not deliver the same event for a subscription of a subscriber multiple times.

• Event priority: Events are published with a certain priority. High priority events are delivered ahead of low priority events.

• Event ordering: For a given priority, events are received by subscribers in the order in which the publisher published the events.

• Retention time: Events published with a non-zero retention period are retained for a specified duration. This duration can be provided while allocating an Event. This provides the opportunity for new subscribers to obtain events that were published before their subscription to the event channel. Processes can use the Event Service functions to remove events before the retention time expires.

• Payload structure: The Event Service function does not impose a specific layout or format for the published event data or payload. Publishers and subscribers on an event channel must agree on the structure of the data for events published on that event channel and can use data marshalling support for heterogeneity is required. Conventions on the structure of the event data can vary from one event channel to another.

• Event Filtering: The standard set of event attributes include an array of event patterns. The values of these patterns are set by the event publisher and are used to organize events into various categories. All users (publishers and subscribers) of an event channel must share the same conventions regarding the number of patterns being used, their ordering, contents, and meaning. For example, an event channel, used to notify changes made to a relational database, can define events where only three patterns are used as follows:
  1. The first pattern contains the name of the database being modified.
  2. The second pattern contains the name of the table being modified.
  3. The third pattern contains the primary key of the record being modified.
  The event data can be used to provide a description of the modified fields and the old/new values. Event patterns play an important role in the Event Service, as they are the basis for filtering the events that must be delivered to a particular subscriber. When subscribing on an event channel, a component must specify the filters that need to be applied on published events. Only events which satisfy the filters are delivered to the component. Using the previous example of the database notifications published on an event channel, a subscriber can provide a filter array indicating:
  1. The name of a database required by the subscriber.
  2. The name of a table required by the subscriber.
  3. No filter for the primary key. If a filter is not specified, the component will receive all notification events related to the specified table, in the specified database for any primary key.