# Spectra ORB

# C++ Edition

# Lightweight Event Service Guide

![in-commerce\nOSG](.spectra-orb-c-edition-lightweight-event-service-user-guide-2/0212b1c320cf95358a7ccb75d3e7d3abf1020543bf2d455d3474ae5a804fd92f.jpg)

# Spectra ORB

# C++ Edition

# LIGHTWEIGHT

# EVENT SERVICE GUIDE

# Copyright Notice

© 2013 PrismTech Limited. All rights reserved.

This document may be reproduced in whole but not in part.

The information contained in this document is subject to change without notice and is made available in good faith without liability on the part of PrismTech Limited or PrismTech Corporation.

All trademarks acknowledged.

# CONTENTS

# Table of Contents

# Preface

About the Lightweight Event Service Guide. . . . . . . . . vii

Contacts . . . . . . . viii

# Introduction

Description xi

Overview . . . . . . xi

Benefits . . . . . . . xi

Features . . . . . . . xii

Limitations . . . . . . . xii

# The Lightweight Event Service

Chapter 1 Concepts 3

1.1 Basic Concept . . . .

1.2 Architecture. . . . .

1.2.1 The Details . . .

1.2.1.1 Events . . .

1.2.1.2 Event Communication Model. .

1.2.1.3 Event Channel. .

1.2.1.4 Admin Objects . . .

1.2.1.5 Proxies . .

1.2.1.6 Queues . . . . 8

1.2.1.7 Federation . . .

Chapter 2 Running the Service 11

2.1 Embedding the Service. . . . . 1

2.1.1 Configuration Structure . . .

2.1.1.1 Blocking versus Rejecting Events . . . . . . 12

2.1.2 The init() Method. . . . . 13

2.1.3 Simple Example . . . . . . 14

2.2 Running from the Command Line . . . . . . . . . . 14

2.2.1 Running on a Fixed Endpoint . . . . 15

2.2.2 lweventcpp Source Code . . . . . 15

Index 21

Table of Contents

# P re f a c e

# About the Lightweight Event Service Guide

The Lightweight Event Service Guide describes the Spectra ORB Lightweight Event Service C++ Edition product and how it can be used as a minimal, lightweight messaging service for resource-constrained, CORBA-based applications using the Spectra ORB.

The Lightweight Event Service Guide is included with the Spectra ORB C++ Edition Documentation Set and is intended to be used with the IDL, Reference, and User Guides, as well as the other documents included with the Spectra ORB C++ Edition product. Please refer to the Product Guide for a complete list of documents.

# Intended Audience

The Lightweight Event Service Guide is intended to be used by developers who wish to integrate the Spectra ORB Lightweight Event Service into products which comply with OMG standards for object services. Readers who use this guide should have a good understanding of the relevant programming languages (e.g. C++, IDL) and of the relevant underlying technologies (e.g. CORBA).

# Organisation

The Lightweight Event Service Guide is organised into the following sections:

• the Introduction provides a general description of the service along with a list of its main features, potential uses, and benefits
• the Concepts section describes the service’s concepts and architecture
• the Running the Service section describes how to run the service programmatically or from the command line.

# Conventions

The conventions listed below are used to guide and assist the reader in understanding the Lightweight Event Service Guide.

<table><tr><td>!</td><td>Item of special significance or where caution needs to be taken.</td></tr><tr><td>i</td><td>Item contains helpful hint or special information.</td></tr><tr><td>WIN</td><td>Information applies to Windows (e.g. XP, Vista, Windows 7) only.</td></tr><tr><td>UNIX</td><td>Information applies to Unix-based systems (e.g. Solaris) only.</td></tr><tr><td>C</td><td>C language specific</td></tr><tr><td>C++</td><td>C++ language specific</td></tr></table>

# Java Java language specific.

Hypertext links are shown as blue italic underlined.

On-Line (PDF) versions of this document: Items shown as cross references to other parts of the document, e.g. Contacts on page viii, are hypertext links: jump to that section of the document by clicking on the cross reference.

```txt
% Commands or input which the user enters on the command line of their computer terminal
```

Courier fonts indicate programming code and file names.

Extended code fragments are shown as small Courier font in shaded boxes:

```javascript
NameComponent newName[] = new NameComponent[1];
// set id field to "example" and kind field to an empty string scarf
newName[0] = new NameComponent("example", "");
```

Italics and Italic Bold indicate new terms or emphasise an item.

Arial Bold is indicates user-related actions, e.g. File > Save from a menu.

Step 1: One of several steps required to complete a task.

# Contacts

PrismTech can be reached at the following contact points for information and technical support.

<table><tr><td>USA Corporate Headquarters</td><td>European Head Office</td></tr><tr><td>PrismTech Corporation</td><td>PrismTech Limited</td></tr><tr><td>400 TradeCenter</td><td>PrismTech House</td></tr><tr><td>Suite 5900</td><td>5th Avenue Business Park</td></tr><tr><td>Woburn, MA</td><td>Gateshead</td></tr><tr><td>01801</td><td>NE11 0NG</td></tr><tr><td>USA</td><td>UK</td></tr></table>

Tel: +1 781 569 5819 Tel: +44 (0)191 497 9900

Fax: +44 (0)191 497 9901

Web: http://www.prismtech.com

Technical questions: crc@prismtech.com (Customer Response Center)

Sales enquiries: sales@prismtech.com

# INTRODUCTION

# Description

# Overview

The Spectra ORB Lightweight Event Service implementation is a subset of the Object Management Group’s (OMG) Event Service Specification and addresses the needs of resource-constrained environments, such as embedded systems. The Lightweight Event Service is backwards compatible with the full Event Service.

The Spectra ORB Lightweight Event Service C++ Edition is compliant with the OMG’s Lightweight Event Service Specification and satisfies the requirements of the Software Communications Architecture (SCA).

The OMG’s Event Service enables data, referred to as events, to be sent and received as messages between distributed software objects in a decoupled fashion. Objects which send message through an intermediary, such as the Event Service, are referred to as being decoupled. Objects which send messages directly between each other are referred to as being tightly coupled.

Decoupling objects which send messages to each other provides a variety of advantages and benefits over tightly coupling the objects. Advantages can include greatly improved scalability, improvements to maintainability, greater flexibility, and others (see Benefits below). In general terms, decoupling enables events to be transmitted more efficiently and flexibly than when events are sent directly between objects (tightly coupled).

The Lightweight Event Service would be typically used in sectors and industries that employ highly constrained environments which prevent the use of standard CORBA services, such as in embedded systems.

# Benefits

Some of the benefits of the Spectra ORB Lightweight Event Service include:

• small code footprint size
• high performance
• ease of maintenance when adding or removing objects which supply and consume events
• more efficient use of network bandwidth between objects which supply events (suppliers) and objects which use or consume events (consumers)
• performance increasingly improves over tight coupling as the number of suppliers and consumers increases

# Features

The Spectra ORB Lightweight Event Service provides the features listed below. These features are compliant with the OMG’s Event Service Specification, Version 1.1 and the OMG’s Lightweight Services submission.

• a lightweight, minimal service for use in applications and environments which require small code size and high performance
• decouples the transmission of events between suppliers and consumers by using an event channel and proxies1
• avoidance of poor performance due to polling by using the push style event transmission model for event notification

# Limitations

The Spectra ORB Lightweight Event Service does not support:

• the pull model of event transmission (i.e. only the push model is supported)
• typed events

However, the lightweight version of the service does provide all of the other features of the full Event Service and is backwards compatible with it.

# THE LIGHTWEIGHT EVENT SERVICE

# CHAPTER

# 1 Concepts

# 1.1 Basic Concept

There are many situations when an object needs to receive notification that an event has been generated or produced by another object, such as when an alarm control panel of a security system needs to know if a remote alarm has been activated. The object may also need to know details about the event itself so that it can take appropriate action. Using the security system example, the alarm panel may need to know which alarm was activated, its location, the reason for the alarm (break-in, fire, etc.) in order to provide appropriate information to security officers.

Obviously, the objects producing and using the event need to be connected to each other in some fashion so that communication of the event can occur. A simple solution would be to connect the objects together directly: notification of an event occurrence and information about it being communicated directly between the two objects. Importantly, these objects would then be tightly coupled to each other: changes effecting the communication of the event by one object will directly affect the other object.

Tight coupling performs well when one object is connected to only one other object. If, however, many objects are connected to many others, especially when the number of objects changes, then maintainability, performance, and scalability become serious issues. For example, each time an event producer object (e.g. a new alarm) is added, then all event users, or consumer, objects (e.g. the alarm panels in the building, at the security firm, in the police or fire stations) will need to be changed, too. In software terms, code for all consumer objects, i.e. the consumers, will need to be altered, re-compiled, tested, etc., whenever supplier objects, i.e. the suppliers, are added.

Also, communication between tightly coupled objects is synchronous, that is before the supplier can send an event, the consumer must be ready to receive it. If a supplier is connected to several consumers, then it must wait for the slowest consumer to receive (or consume) the event before it can proceed.

Decoupling suppliers and consumers through an intermediary can overcome these issues. If new suppliers or consumers are added to the system, then only the intermediary needs to be altered, not each consumer or supplier, respectively.

Further, the intermediary can provide event buffers, or queues, and multi-threading capabilities in order to enable asynchronous communication: events can be sent and received without waiting for the slowest “member of the pack”.

An intermediary can therefore take over the task of communicating events between suppliers and consumers: it can provide a service for them, who become its clients.

The Event Service was the first service that the OMG specified for the decoupled, asynchronous communication of events between event producer and consumer client objects. By decoupling the objects, through the use of an event channel and proxies, the Event Service provided improved maintainability, performance and scalability over systems which rely on tightly coupled objects.

Like the OMG’s Event Service, PrismTech’s Lightweight Event Service (for convenience, referred to as the Event Service throughout this document) provides decoupled, asynchronous communication between supplier and consumer client objects. However, the Lightweight Event Service provides only those features which are needed for a constrained size and performance environment.

# 1.2 Architecture

The Event Service can be considered from two viewpoints:

1. From the journey that an event takes from supplier to consumer, i.e. its transmission path.
2. How the Event Service components are conceptually connected and created.

# 1.2.0.0.1 Event Transmission

A supplier generates events.

1. The supplier sends the events to a proxy representing the consumer, the consumer proxy.
2. The consumer proxy forwards the events to a supplier admin object.
3. Numerous consumer proxies can be connected to a single supplier admin object. The supplier admin object sends all events it receives to the event channel.
4. The event channel transmits the events to a consumer admin object. The consumer admin object then forwards those events to its individual supplier proxies.
5. Each supplier proxy sends its events to their respective event consumers (one proxy per consumer).

Figure 1, Basic Event Service Architecture, shows the service’s basic conceptual components and event transmission paths.

![The diagram illustrates a system architecture with a left-to-right flow of events.\n\n**Labeled Blocks:**\n*   **Green Circles (Far Left):** Two blocks labeled 'Push Supplier'.\n*   **Yellow Circles (Left of Center):** Two blocks labeled 'Proxy Push Consumer'.\n*   **Blue Circle (Center-Left):** One block labeled 'Supplier Admin Object'.\n*   **Pink Circle (Center):** One block labeled 'Event Channel'.\n*   **Blue Circle (Center-Right):** One block labeled 'Consumer Admin Object'.\n*   **Yellow Circles (Right of Center):** Two blocks labeled 'Proxy Push Supplier'.\n*   **Green Circles (Far Right):** Two blocks labeled 'Push Consumer'.\n*   **Yellow Arrow (Bottom):** Labeled 'Direction of Event Flow'.\n\n**Connections:**\n1.  Each 'Push Supplier' connects to its corresponding 'Proxy Push Consumer'.\n2.  Both 'Proxy Push Consumer' blocks connect to the 'Supplier Admin Object'.\n3.  The 'Supplier Admin Object' connects to the 'Event Channel'.\n4.  The 'Event Channel' connects to the 'Consumer Admin Object'.\n5.  The 'Consumer Admin Object' connects to both 'Proxy Push Supplier' blocks.\n6.  Each 'Proxy Push Supplier' connects to its corresponding 'Push Consumer'.](.spectra-orb-c-edition-lightweight-event-service-user-guide-2/e0a163047d362a1d61cd7689f7f35a24689f73ca674c87c50bd7538a4189ed0d.jpg)

Figure 1 Basic Event Service Architecture

# 1.2.0.0.2 Component Connection and Creation

The components of the service are organised hierarchically. The main component is the event channel.

Admin objects are created by the event channel; proxies are created from the admin objects. Finally, each proxy is connected to a client supplier object or client consumer object.

# 1.2.0.0.3 Main Components and Features

The Event Service consists of the following main types of component. Together, they transmit events using a transmission model.

The main types of component are event channels, admin objects, proxies, and queues

The type of events which can be transmitted by the Event Service are CORBA Anys, which are generally referred to in the context of the Event Service as untyped or Event Style events.

The transmission model used by the Event Service is the push model (described below).

Figure 2, Main Components, shows the service’s main components, including queues.

![This flowchart illustrates an event flow system, generally moving from left to right as indicated by the 'Direction of Event Flow' arrow at the bottom. The diagram is divided into a central green area and external components.\n\n**Labeled Blocks:**\n*   **Left Side (External):** Two green circles labeled 'Push Supplier'.\n*   **Left Side (Internal):** Two yellow circles labeled 'Proxy Push Consumer'.\n*   **Center-Left (Internal):** One blue circle labeled 'Supplier Admin Object'.\n*   **Center (Internal):** One pink circle labeled 'Event Channel'.\n*   **Center-Bottom (Internal):** One cyan cylinder labeled 'Master Event Queue'.\n*   **Center-Right (Internal):** One blue circle labeled 'Consumer Admin Object'.\n*   **Right Side (Internal):** Two yellow circles labeled 'Proxy Push Supplier'.\n*   **Right Side (Internal):** Two cyan cylinders labeled 'Proxy Queue'.\n*   **Far Right (External):** Two green circles labeled 'Push Consumer'.\n\n**Connections:**\n*   **Input Flow:**\n    *   Each 'Push Supplier' connects to a corresponding 'Proxy Push Consumer'.\n    *   Both 'Proxy Push Consumer' blocks connect to the 'Supplier Admin Object'.\n*   **Central Processing:**\n    *   The 'Supplier Admin Object' connects to the 'Event Channel'.\n    *   The 'Event Channel' connects to the 'Consumer Admin Object'.\n    *   The 'Event Channel' also connects downwards to the 'Master Event Queue'.\n*   **Output Flow:**\n    *   The 'Consumer Admin Object' splits into two paths, connecting to both 'Proxy Push Supplier' blocks.\n    *   Each 'Proxy Push Supplier' connects to a corresponding 'Proxy Queue'.\n    *   Each 'Proxy Push Supplier' also connects to a corresponding 'Push Consumer' on the far right.](.spectra-orb-c-edition-lightweight-event-service-user-guide-2/d1489f6a1124142d36ffa8b908f219174795e6904bd28064786f033a5cb89e53.jpg)

Figure 2 Main Components

These components, event types, transmission models, methods and features will be described in detail below.

# 1.2.1 The Details

# 1.2.1.1 Events

The Event Service transmits one type of event: untyped.

Untyped events encapsulate basic data types transmitted and received by client objects. Untyped events include the OMG defined Any type, which is also referred to as an Event Style event.

# 1.2.1.2 Event Communication Model

The Event Service uses one communication model, the push model. In the push model, suppliers actively send or push events to the event channel and consumers passively receive them.

Figure 1, Basic Event Service Architecture, on page 5 shows the proxies which are used with the push model, namely the proxy push consumer and proxy push supplier.

# 1.2.1.3 Event Channel

The event channel is the component which provides the loosely coupled communication between client objects: it is the event channel which handles supplier registration and broadcasting of events to consumers.

Each Event Service server provides a single event channel.

The event channel creates admin objects, which in turn create proxies. This creation process forms a channel - admin - proxy hierarchy.

# 1.2.1.4 Admin Objects

Admin objects perform administrative and management functions, such as creating proxies.

Admin objects are associated with either suppliers or consumers (referred to as supplier admin objects or consumer admin objects).

i Note that supplier admin objects create consumer proxies, and vice versa (remembering that suppliers connect to consumer proxies, consumers connect to supplier proxies).

An event channel in the Event Service has one admin object for suppliers and one admin object for consumers. Each admin object can have any number of proxies.

Admin objects manage or administer the proxies that they have created.

# 1.2.1.5 Proxies

Proxies connect supplier and consumer client objects to the event channel of the Event Service. Importantly, proxies represent or stand-in for a client. For example, a supplier behaves as if it is connected to an actual consumer, however it is actually connected to a proxy for the consumer, i.e. a consumer proxy : suppliers connect to consumer proxies; consumers connect to supplier proxies.

The Event Service uses only the ProxyPushConsumer and ProxyPushSupplier proxy types.

# 1.2.1.5.1 Connection and Disconnection States

Figure 3, Proxy States, illustrates the states a proxy can have during creation and disconnection.

![Based on the provided image, here is the description of the flowchart:\n\n**Labeled Blocks (Nodes):**\n*   **not connected** (Green circle)\n*   **connected** (Yellow circle)\n*   **destroyed** (Pink circle)\n\n**Connections (Edges):**\n*   An arrow labeled **create** points to the **not connected** block.\n*   An arrow labeled **connect** goes from **not connected** to **connected**.\n*   An arrow labeled **disconnect** goes from **not connected** to **destroyed**.\n*   An arrow labeled **disconnected** goes from **connected** to **destroyed**.\n*   An arrow labeled **disconnect** goes from **destroyed** back to **connected**.](.spectra-orb-c-edition-lightweight-event-service-user-guide-2/d602732712ca3ff4fc6202b2e727d551e1c109e961a711f967003a88c3526eea.jpg)

Figure 3 Proxy States

A proxy is a communication end point and disconnecting it implies that the proxy object is destroyed. After being disconnected, the proxy can no longer be used to send or receive events.

A push consumer can also disconnect a proxy by raising the Disconnected exception in the push operation.

![The image shows a standard triangular warning sign with a thick red border and a white background. Centered inside is a black exclamation mark.](.spectra-orb-c-edition-lightweight-event-service-user-guide-2/525ab45b697392b82544024d1f0388506fe8031bd4a182eb3f2269baf0cd548b.jpg)

It is the client’s responsibility to disconnect (and therefore destroy) the proxy when the client terminates since the service has no means of knowing that the client no longer exists. Accordingly, the client should call its associated proxy’s disconnect method. For example, if the client is a push supplier connected to a ProxyPushConsumer (suppliers connect to proxy consumers, consumers connect to proxy suppliers), then the disconnect\_push\_consumer() method for its ProxyPushConsumer object should be called prior to termination.

# 1.2.1.6 Queues

Queues are buffers for storing events until consumers are ready to receive the events. Queues free suppliers from the need to wait for consumers to consume their events before continuing.

The event channel has a master event queue and each proxy supplier has a proxy queue, one proxy queue per consumer object (see Figure 2, Main Components, on page 6).

Incoming events enter the master event queue. Events are then dispatched into proxy queues. The event is removed from the master queue after it has been dispatched to the proxy queue.

# 1.2.1.7 Federation

Federation is a method of connecting separate Event Service instances and their event channels together (see Figure 4, Event Service Federation).

Federation effectively creates a composite system partitioned into any number of subsystems. Partitioning an event system into multiple event subsystems can have a number of advantages:

• Performance:

- enabling multiple hosts to be used for utilising increased CPU resources
- providing fan-out to consumers on the local machine

Sending events to a channel that in turn forwards them to a number of consumers can result in great performance improvements. As an example, if the consumers are all on the same machine the events can be sent using one network invocation and a series of local invocations.

• Reliability:

\- avoiding single points of failure

By having multiple event channels it is possible to avoid single points of failure. Although parts of the system may no longer receive events if an event channel fails, this does not necessarily have to affect other consumers.

• Flexibility:

\- makes it easy to move event subsystems

Figure 4 shows that a supplier proxy can act as a supplier and a proxy consumer can act as consumer. This allows channels to be federated without using special clients that forward events from one channel to another. A proxy supplier can be connected directly to a proxy consumer.

![Based on the provided image, here is the accurate description of the flowchart:\n\n**Legend:**\n*   A yellow arrow at the bottom labeled 'Direction of Event Flow'.\n\n**Event Service 1:**\n*   **Blocks:** Two green circles labeled 'Push Supplier', two yellow circles labeled 'Proxy Consumer', one pink circle labeled 'Event Channel', and two yellow circles labeled 'Proxy Supplier'.\n*   **Connections:**\n    *   The two 'Push Supplier' circles point to the 'Proxy Consumer' circles.\n    *   The 'Proxy Consumer' circles point to the central 'Event Channel'.\n    *   The 'Event Channel' points to the 'Proxy Supplier' circles.\n    *   The top 'Proxy Supplier' points upward to a 'Proxy Consumer' in Event Service 2.\n    *   The bottom 'Proxy Supplier' points downward to a 'Proxy Consumer' in Event Service 3.\n\n**Event Service 2:**\n*   **Blocks:** Two yellow circles labeled 'Proxy Consumer', one pink circle labeled 'Event Channel', two yellow circles labeled 'Proxy Supplier', and two green circles labeled 'Push Consumer'.\n*   **Connections:**\n    *   The two 'Proxy Consumer' circles point to the central 'Event Channel'.\n    *   The 'Event Channel' points to the 'Proxy Supplier' circles.\n    *   Each 'Proxy Supplier' points to a 'Push Consumer' circle.\n\n**Event Service 3:**\n*   **Blocks:** Two yellow circles labeled 'Proxy Consumer', one pink circle labeled 'Event Channel', two yellow circles labeled 'Proxy Supplier', and two green circles labeled 'Push Consumer'.\n*   **Connections:**\n    *   The two 'Proxy Consumer' circles point to the central 'Event Channel'.\n    *   The 'Event Channel' points to the 'Proxy Supplier' circles.\n    *   Each 'Proxy Supplier' points to a 'Push Consumer' circle.](.spectra-orb-c-edition-lightweight-event-service-user-guide-2/3bf5c8c7a671f4c40a28da8a7ae1e466a2745ca200cedd2156a320a6cbaef846.jpg)

Figure 4 Event Service Federation

# CHAPTER

# 2 Running the Service

The Spectra ORB Lightweight Event Service is usually run by embedding it into an executable or module, however it can also be run from the command line. This section describes how to run the Spectra ORB Lightweight Event Service programmatically by embedding it, plus provides an example of how it can be run from the command line - complete with source code.

# 2.1 Embedding the Service

The following basic tasks must be performed in order to embed an Event Service instance into an executable or code module:

Step 1: Include the following include statement in your code:

#include "eOrb/EORB/EventService.h"

Step 2: Ensure your build system has \$(EORBHOME)/include/eOrb/services/lw on its include path.

Step 3: Configure your event service instance by setting the property fields in the event service’s configuration structure: these properties are used to determine specific aspects of your EventChannel instance’s behaviour.

Step 4: Instantiate an EventChannel instance: this is achieved by calling the Event Service’s init() method.

# 2.1.1 Configuration Structure

The structure mentioned in Step 2: above defines the property fields described below under Table 1, Configuration Property Descriptions. An example of setting the configuration structure fields is shown in Example 1, Setting the Configuration Structure Fields, on page 12.

Table 1 Configuration Property Descriptions

<table><tr><td>Property</td><td>Description</td></tr><tr><td>qosChannelMaxSize</td><td>Sets the maximum number of events which will be queued (buffered) by each EventChannel. The default value for all platforms, except for VxWorks, is 10240 events.The default value for VxWorks is 100 (due to constraints related to this specific platform).</td></tr></table>

![The image displays a red triangular outline with a black exclamation mark centered inside it, set against a transparent background.](.spectra-orb-c-edition-lightweight-event-service-user-guide-2/dcb4edd9d516a14fe112df3bba3f6f5e088f2aa86dea0cf1b00fcacedd281799.jpg)

Table 1 Configuration Property Descriptions (Continued)

<table><tr><td>Property</td><td>Description</td></tr><tr><td>qosProxyMaxSize</td><td>Sets the maximum number of events which will be queued by each ProxyPushSupplier. The default value, except for VxWorks, is 1024 events.The default value for VxWorks is 100 (due to constraints related to this specific platform).</td></tr><tr><td>qosProxyStackSize</td><td>Sets the proxy queue thread&#x27;s stack size in bytes. The default value of zero (0) sets the stack size to the platform&#x27;s default stack size.</td></tr><tr><td>qosChannelPushMode</td><td>Sets the EventChannel push mode to BLOCK or REJECT.The push mode determines whether push callers will be blocked (BLOCK) or their events rejected (REJECT) when the channel&#x27;s queue is full. BLOCK is the default.(See Blocking versus Rejecting Events below.)</td></tr><tr><td>qosProxyPushMode</td><td>Sets the ProxyPushSupplier&#x27;s push mode to BLOCK or REJECT.The push mode determines whether the event channel will be blocked from pushing events (BLOCK) or the events rejected (REJECT) when the proxy&#x27;s queue is full. BLOCK is the default.(See Blocking versus Rejecting Events below.)</td></tr></table>

Example 1 Setting the Configuration Structure Fields
```txt
EORB::EventService::Config config;
config.qosChannelMaxSize = 1000;
config.qosProxyStackSize = 4096;
config.qosChannelPushMode = EventService.REJECT;
config.qosProxyMaxSize = 100;
config.qosProxyPushMode = EventService.BLOCK;
```

# 2.1.1.1 Blocking versus Rejecting Events

The block and reject push modes enable users to alter the behaviour of the Event Service to best suit their particular needs regarding how the transmission of events are treated when the event channel and proxy queues are full. Generally, BLOCK ensures that all events are received (subject to the limitations of Best Effort Quality of Service1) at the expense of the transmission rate being limited to the slowest consumer, whereas REJECT ensures the fastest possible speed at the expense of losing events sent to slow consumers.

# 2.1.1.1.1 Event Channel

If the event channel’s queue is full and its push mode is set to block, then the clients which are pushing events onto the channel will be blocked (i.e. they must wait until the queue has space to accept events). The block mode ensures that no events are lost.

If the event channel’s queue is full and its push mode is set to reject, then clients can continue to push events onto the channel. However, events will be rejected (i.e. lost) and a IMP\_LIMIT exception will be returned to the client for each rejected event. The result is that events will be lost, plus there is the added overhead of returning the exception.

# 2.1.1.1.2 Proxy Push Supplier

If the ProxyPushSupplier’s queue is full and its push mode is set to block, then the event channel will be blocked from sending events to any proxy. The block mode ensures that no events are lost (subject to Best Effort), however the rate that events can be sent to consumers is limited to the rate of the slowest consumer.

If a ProxyPushSupplier’s queue is full and its push mode is set to reject, then the event channel will continue to push events to all consumer clients connected to the channel, however events will be rejected (i.e. lost) by the ProxyPushSupplier whose queue is full. Consumers which can accept events more quickly are allowed to continue to receive events, but the (slower) consumer will loose events.

# 2.1.2 The init() Method

The Event Service’s init() method initialises an Event Service instance. The method takes two parameters:

• a reference to the orb object the service is to be run on
• a reference to a PortableServer::POA that the service will run in
• the configuration structure (described under Configuration Structure on page 11)

The method returns the instance’s reference. This reference can be used directly, or be stored or pushed for use by other methods, modules, etc.

# Example 2 Using the init() Method

The following code extract creates an Event Service (channel) instance using the EORB::EventService::init() method. The init() method takes an ORB object (created using ORB\_init()), a POA instance and a configuration structure instance (see Setting the Configuration Structure Fields on page 12).

```cpp
CosEventChannelAdmin::EventChannel_var channel;
CORBA::ORB_var orb = CORBA::ORB_init (argc, argv);
channel = EORB::EventService::init (orb, poa, config);
```

# 2.1.3 Simple Example

The source code for a simple example showing how the Event Service can be run from the command line is provided under lweventcpp Source Code on page 15 and a benchmark example is provided in examples/cpp/services/event below the installation directory.

# 2.2 Running from the Command Line

The Event Service can run from the command line using the lweventcpp example executable with zero or more of the options listed in Table 2. These options are the command line equivalent of the embedded service’s configurable properties.

```txt
% lweentcpp [options]
```

i Blocking versus Rejecting Events, below, should be read before using the -EventServiceChannelPushMode or -EventServiceProxyPushMode options.

Table 2 Command Line Options

<table><tr><td>Option</td><td>Description</td></tr><tr><td>-EventServiceChannelMaxSize</td><td>Sets the maximum number of events, , which will be queued (buffered) by the EventChannel.The default value for all platforms, except for VxWorks, is 10000 events.⚠ The default value for VxWorks is 100 (due to constraints related to this specific platform).</td></tr><tr><td>-EventServiceChannelPushMode</td><td>Sets the EventChannel push mode. The push mode determines whether push callers will be blocked (BLOCK) or their events rejected (REJECT) when the channel’s queue is full.The default is BLOCK.(See Blocking versus Rejecting Events on page 12.)</td></tr><tr><td>-EventServiceProxyMaxSize</td><td>Sets the maximum number of events, , which will be queued by the ProxyPushSupplier. The default value for all platforms, except for VxWorks, is 1024 events.⚠ The default value for VxWorks is 100 (due to constraints related to this specific platform).</td></tr><tr><td>-EventServiceProxyPushMode</td><td>Sets the ProxyPushSupplier's push mode. The push mode determines whether the event channel will be blocked from pushing events (BLOCK) or the events rejected (REJECT) when the proxy's queue is full.The default is BLOCK.(See Blocking versus Rejecting Events on page 12.)</td></tr><tr><td>-EventServiceProxyStackSize</td><td>Sets the ProxyPushSupplier thread's stack size in bytes. The default value of zero (0) sets the stack size to the platform's default stack size.The default is 0</td></tr><tr><td>-EventServiceUIOP</td><td>Runs the service on a UIOP endpoint. Only available on systems where UIOP is a supported transport.The default is no.</td></tr></table>

# 2.2.1 Running on a Fixed Endpoint

The server can be run on a fixed endpoint by running with the -ORBPOAEndpoints argument. The Event Service servant is created within a child POA EventService so for example can be run on a fixed IIOP endpoint with:

-ORBPOAEndpoints EventService:iiop:&lt;host&gt;:&lt;port&gt;

and resolved as an initial reference by a client using:

-ORBInitRef EventService=corbaloc:iiop:&lt;host&gt;:&lt;port&gt;/EventService

# 2.2.2 lweventcpp Source Code

The source code for lweventcpp is shown below.

The IOR for the service is published by registering it with the ORB as an initial reference. The Spectra ORB-specific Stdio and File plugins then ensure that this reference is both published to stdout and written to a file corresponding to the name of the registered reference. Note that the normal try-catch block has been replaced with the EORB\_TRY and EORB\_CATCH macros.

![The image shows a triangular warning sign with a thick red border and a white interior. Centered inside the triangle is a large black exclamation mark. Below the exclamation mark, positioned near the bottom edge of the red border, is a small black arrow pointing downwards.](.spectra-orb-c-edition-lightweight-event-service-user-guide-2/24b66e11c400c6cb297382cad344c99177b1683f63a6d2f0c4afbb07c6a65d64.jpg)

The config.qosChannelMaxSize and config.qosProxyMaxSize properties must be set to values less than or equal to 100 on VxWorks.

```cpp
#include "eOrb/EORB/Plugin/Any.h"
#include "eOrb/EORB/Plugin/POA.h"
#include "eOrb/EORB/EventService.h"
#include "eOrb/PortableServer/POAManager.h"

static void usage ()
{
#if EORB_USE_STDIO
    CORBA::ULong c = EORB::EventService::DEFAULT_CHANNEL_MAX_SIZE;
    CORBA::ULong p = EORB::EventService::DEFAULT_PROXY_MAX_SIZE;

    printf ("Valid optional arguments :\n");

    printf (" -EventServiceChannelMaxSize &lt;num&gt; ");
    printf ("default is %d\n", c);

    printf (" -EventServiceProxyMaxSize &lt;num&gt; ");
    printf ("default is %d\n", p);

    printf (" -EventServiceChannelPushMode &lt;BLOCK | REJECT&gt; ");
    printf ("default is BLOCK\n");

    printf (" -EventServiceChannelPushMode &lt;BLOCK | REJECT&gt; ");
    printf ("default is BLOCK\n");

    printf (" -EventServiceProxyStackSize &lt;num&gt; ");
    printf ("default is 0\n");

#if EORB_USE_UIOP
    printf (" -EventServiceUIOP ");
    printf ("default is no\n");
#endif

#endif
}

static EORB::EventService::PushMode pmtoi (const char *pmstr)
{
    if (CORBA::string_cmp (pmstr, "REJECT") == 0)
    {
    return EORB::EventService::REJECT;
    }
    else if (CORBA::string_cmp (pmstr, "BLOCK") == 0)
    {
    return EORB::EventService::BLOCK;
    }

    return EORB::EventService::BLOCK;
}

EORB_MAIN (lweventcpp)
{
    EORB_DECLARE_ENV;

    EORB::Plugin::Any::add ();
    EORB::Plugin::IIOP::add ();
    EORB::Plugin::POA::add );

    EORB_Stdio_plugin ();
    EORB_File_plugin ();
```

```txt
EORB_TRY
{
    CORBA::ORB_var orb;
    CosEventChannelAdmin::EventChannel_var channel;
    EORB::EventService::Config cfg;

    /* Set default cfg values */

    cfg.qosChannelMaxSize = EORB::EventService::DEFAULT_CHANNEL_MAX_SIZE;
    cfg.qosProxyMaxSize = EORB::EventService::DEFAULT_PROXY_MAX_SIZE;
    cfg.qosChannelPushMode = EORB::EventService::BLOCK;
    cfg.qosProxyPushMode = EORB::EventService::BLOCK;
    cfg.qosProxyStackSize = 0;

    /* Check for command line cfg overrides */

    for (uint8_t argi = 1; argi &lt; argc; argi++)
    {
    char* s = argv[argi];

    if (CORBA::string_cmp (s, "-EventServiceChannelMaxSize") == 0)
    {
    cfg.qosChannelMaxSize = atoi (argv[++argi]);
    }
    else if (CORBA::string_cmp (s, "-EventServiceProxyMaxSize") == 0)
    {
    cfg.qosProxyMaxSize = atoi (argv[++argi]);
    }
    else if (CORBA::string_cmp (s, "-EventServiceChannelPushMode") == 0)
    {
    cfg.qosChannelPushMode = pmtoi (argv[++argi]);
    }
    else if (CORBA::string_cmp (s, "-EventServiceProxyPushMode") == 0)
    {
    cfg.qosProxyPushMode = pmtoi (argv[++argi]);
    }
    else if (CORBA::string_cmp (s, "-EventServiceProxyStackSize") == 0)
    {
    cfg.qosProxyStackSize = atoi (argv[++argi]);
    }

    #if EORB_USE_UIOP
    else if (strcmp (argv[argi], "-EventServiceUIOP") == 0)
    {
    EORB::Plugin::UIOP::add();
    }

    #endif
    else if (CORBA::string_cmp (s, "-help") == 0)
    {
    usage ();
    exit (1);
    }
    }

    orb = CORBA::ORB_init (argc, argv EORB_ENV_VARN);
    EORB_CHECK_ENV;

    CORBA::Object_var obj;
    PortableServer::POA_var poa;
    PortableServer::POA_var child;
    CORBA::PolicyList poaPolicies (0);
```

```c
obj = orb-&gt;resolve_initial_references ("RootPOA" EORB_ENV_VARN);
poa = PortableServer::POA::_narrow (obj EORB_ENV_VARN);

child = poa->create_POA
(
    "EventService",
    PortableServer::POAManager::_nil (
    poaPolicies
    EORB_ENV_VARN
);
EORB_CHECK_ENV;

channel = EORB::EventService::init (orb, child, cfg EORB_ENV_VARN);
EORB_CHECK_ENV;

orb->register_initial_reference
(
    "EventService",
    channel
    EORB_ENV_VARN
);
EORB_CHECK_ENV;

#if EORB_USE_STDIO
const char * cpm;
const char * ppm;

cpm = (cfg.qosChannelPushMode == EORB::EventService::BLOCK)
? "BLOCK":"REJECT";
ppm = (cfg.qosProxyPushMode == EORB::EventService::BLOCK)
? "BLOCK":"REJECT";

printf("\nEventService has started\n");
printf(" ChannelMaxSize : %d\n", cfg.qosChannelMaxSize);
printf(" ProxyMaxSize : %d\n", cfg.qosProxyMaxSize);
printf(" ChannelPushMode : %s\n", cpm);
printf(" ProxyPushMode : %s\n", ppm);
printf(" ProxyStackSize : %d\n", cfg.qosProxyStackSize);
fflush (stdout);

#endif

orb->run (EORB_ENV_VAR1);
EORB_CHECK_ENV;
}
EORB_CATCH (CORBA::Exception, exc)
{
    fprintf (stderr, "EventService exception: %s\n", exc._rep_id());
    return 1;
}
EORB_END_TRY

return 0;
}
```

# INDEX

# I n d e x

# A

Admin Objects . . . . . . 7

Architecture . . . . . 4

# B

Basic Concept . . . . . . . 3

Benefits. . . . . . . xi

Basic Event Service Architecture . . . . . . . . . . . . . 5

# C

Component Connection and Creation . . . . . . . . . 5

Connection and Disconnection States . . . . . . . . . 7

Concepts . . . . 3

# E

Event

Event Service Federation . . . . . 10

Transmission . . . 4

Event Transmission . . . 4

Event Channel

Events . . . . . 6

Event Communication Model. . . . . 6

# F

Federation . . . . . 9

# M

Main Components . . . . 6

Main Components and Features. . .

# P

Proxies . .

Proxy States . . . . 8

# Q

Queues . . . . 8

# R

Running from the Command Line . . . . . . . . . . . 14

Running the Service . . . . 11

Index
[🔗 Link to the original document](.spectra-orb-c-edition-lightweight-event-service-user-guide-2/spectra-orb-c-edition-lightweight-event-service-user-guide.pdf)