
This file contains information on omniEvents, an implementation of the Event
Service Specification v1.0 for omniORB2.

Readers are assumed familar with the concepts presented in the Event Service
specification such as Event Channels, suppliers, consumers and the basic models of communication possible between Suppliers and Consumers, namely the Push and
Pull models, and mixed operation modes.

For more information on the Event Service specification readers should refer
to the CORBAservices : Common Object Services Specification pages at:

http://www.omg.org/corba/sectrans.html

omniEvents implements untyped event channels as Corba objects. Channels can be
created directly within a user process like normal server objects or instead
in a global process containing an Event Channel Factory handling create requests
from clients.

omniEvents supports the following models :

   Push Supplier - Push Consumer
   Pull Supplier - Pull Consumer
   Push Supplier - Pull Consumer

The hybrid Pull-Push model (i.e Pull Supplier - Push Consumer) where the
channel plays an Agent role is not currently supported). See "OMG Event Object
Service", SIGS Vol9, Num 2, February 1997 for an introduction to the various
communication models at "http://www.cs.wustl.edu/~schmidt/C++-report-col9.ps.gz"

omniEvents has been tested with omniORB 2.0.6 on the following platform(s):

   HPUX 10.20/ aC++ (B3910 A.01.04)

Configuration
=============

There are no additional configuration requirements other than those used by
omniORB2 for your particular platform. omniEvents uses the same make mechanism
as omniORB2.

Building the examples
=====================

You are strongly encouraged to try out the examples provided. To build the
examples type 'make' in the src/appl/omniEvents directory. Make sure that 'make'
is GNUmake because the makefiles are all GNUmake specific.

Running the examples
====================

When built the examples provide the following executables :

 - eventd
 - eventc
 - pushsupp
 - pushcons
 - pullsupp
 - pullcons

1. Start the Naming Service (omniNames)
----------------------------------------

You must start the naming service (omniNames) because the examples make use of
it to locate the event channel factory and event channel. Please refer to the
REDAME file supplied with the omniORB2 distribution if you don't know how to
start omniNames.

2. Start the Event Channel Factory (eventd)
-------------------------------------------

The examples provide an Event Channel Factory server process (eventd) which
clients use to create Event Channels within. The factory registers itself
with the Naming Service in order to allow clients to locate it. eventd
has the following options :

usage: eventd [-N name] [-K kind] [-h]

         -N name specify factory name ["EventChannelFactory"]
         -K kind specify factory kind ["EventChannelFactory"]
         -h     display usage

The options provided allow you to override the default name used to register
the Event Channel Factory with the Naming Service.

eventd starts silently unless it encounters any problems or if you turn tracing
on by supplying the omniORB2 specific option -ORBtraceLevel 20. Use the default
parameters when you start eventd by not supplying any:

After starting, eventd should block awaiting requests from clients.

% eventd

3. Run the Event Channel Factory Client (eventc)
------------------------------------------------

eventc resolves the factory name with the Naming service and then contacts
the factory to request an Event Channel. Note that the Event Channel is
always created within the factory address space.

Note : you can by-pass the factory completely and instanciate the event channel
       directly within a process by linking in the appropiate object file
       (CosEvent_i.o)

eventc then registers the created Event Channel with the Naming Service.

eventc has the folowing options :

usage: eventc [-n name] [-k kind] [-N name] [-K kind] [-r sec] [-h]

         -n name specify channel name ["EventChannel"]
         -k kind specify channel kind ["EventChannel"]
         -N name specify factory name ["EventChannelFactory"]
         -K kind specify factory kind ["EventChannelFactory"]
         -r pull retry period (in seconds) [1 sec]]
         -h     display usage

The options provided allow you to override the default name used to register
the Event Channel Factory and the created Event Channel  with the Naming
Service.

eventc starts silently unless it encounters any problems or if you turn tracing
on by supplying the omniORB2 specific option -ORBtraceLevel 20. Use the default
parameters when you start eventc by not supplying any:

eventc terminates once the event channel has been created :

% eventc
%

3. Run one or more suppliers/consumers (pushsupp, pushcons, pullsupp, pullcons)
-------------------------------------------------------------------------------

When run, each supplier and consumer contacts the Naming Service to obtain a
reference to the Event Channel created in step 2 above. They then connect
themselves to the channel and do their bits. The data sent through the channel
is always of type long in the examples.

As per eventc, you can override the default name used to register
the channel in the naming service. The -d option is used to exersize the
disconnect functionaly provided by the channel.

usage: pushsupp [-d n] [-h]

         -d n   disconnect after n pushes
         -n name specify channel name ["EventChannel"]
         -k kind specify channel kind ["EventChannel"]
         -h     display usage

usage: pushcons [-d n] [-h]

         -d n   disconnect after n pushes
         -n name specify channel name ["EventChannel"]
         -k kind specify channel kind ["EventChannel"]
         -h     display usage

usage: pullsupp [-d n] [-h]

         -d n   disconnect after n pulls
         -n name specify channel name ["EventChannel"]
         -k kind specify channel kind ["EventChannel"]
         -h     display usage

usage: pullcons [-t] [-d n] [-n name] [-k kind] [-h]

         -t      enable try_pull mode
         -d n    disconnect after n pulls
         -n name specify channel name ["EventChannel"]
         -k kind specify channel kind ["EventChannel"]
         -h     display usage

The -t option in pullcons causes the pull consumer to issue non-blocking
try_pull invokations rather then straight pulls.

Here is what to expect during a typical session :

% ./pushsupp
Looking for EventChannel
Obtained SupplierAdmin.
Obtained ProxyPushConsumer.
Connected Push Supplier.
Push Supplier: push() called. Data : 0
Push Supplier: push() called. Data : 1
Push Supplier: push() called. Data : 2
Push Supplier: push() called. Data : 3
Push Supplier: push() called. Data : 4
Push Supplier: push() called. Data : 5
...

% ./pushcons
Obtained ConsumerAdmin.
Obtained ProxyPushSupplier.
Connected Push Consumer.
Push Consumer: push () called. Data : 0
Push Consumer: push () called. Data : 1
Push Consumer: push () called. Data : 2
Push Consumer: push () called. Data : 3
Push Consumer: push () called. Data : 4
Push Consumer: push () called. Data : 5
Push Consumer: push () called. Data : 6
...


Note, pull consumers cause the event channel to poll every pull supplier
connected when they request an event (using pull, not try_pull) until an
event enters the event channel (which could come from a push supplier).

In order to prevent the Event Channel from consuming excessive CPU when
polling for events avalueparameter is supplier to the Channel Factory using
the criteria parameter (ultimately to the Event Channel at construction time)
representing a timeout in Seconds to wait for before each poll cycle. This
parameter defaults to 1 Second and cannot be reduced, only increased.

I hope you have fun with omniEvents,

Paul Nader (Paul.Nader@alcatel.com.au)
