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

Information on the Event Service specification can be obtained from the
"CORBAservices : Common Object Services Specification" pages at:

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

omniEvents implements untyped event channels as Corba objects. OmniEvents can be used
in one of two ways:

- Channels can be instanciated within a user process by linking in the static
  library (libomniEvents.a or omniEvents.lib).

- Channels can be instanciated remotely by the Event Channel Factory (eventd).

omniEvents now supports all combinations of push/pull communication models :

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

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.7 on the following platform(s):

   o HPUX 10.20/ aC++ (B3910 A.01.04)
   o SGI IRIX 6.5 C++ 7.2.1 
   o AIX 4.2.1/xlC 3.1.4.7/STLport
   o Linux 2.0 (x86)/egcs-980302/GNU Libc version 2
   o Digital Unix 4.0D/ DEC C++ compiler version 6.0
   o Linux 2.0 (x86)/ GNU C++ compiler version 2.7.2 / Linuxthreads 0.5
   o Linux 2.0 (x86)/egcs-980302/GNU Libc version 2
   o Windows NT / Windows 95 / Visual C++ version 5.0
   o Solaris 2.{5,6}/ Sun SparcCompiler C++ version 4.2


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

There are no configuration requirements other than those used by omniORB2 for your
particular platform. omniEvents uses the same make mechanism as omniORB2.
Make sure that 'make' is GNUmake as the makefiles are GNUmake specific.

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

To build the examples type 'make' in the src/appl/omniEvents directory. If all goes
well you should end up with the following:

  +----------------------------------+-----------------------------------------+
  |              Platform            |                                         |
  +-----------------+----------------+                Description              |
  |     Unix        |   Windows      |                                         |
  +-----------------+----------------+-----------------------------------------+
  | eventd          | eventd.exe     | Event Channel factory server            |
  +-----------------+----------------+-----------------------------------------+
  | eventc          | eventc.exe     | Event Channel factory client            |
  +-----------------+----------------+-----------------------------------------+
  | pushsupp        | pushsupp.exe   | Push Supplier client                    |
  +-----------------+----------------+-----------------------------------------+
  | pushcons        | pushcons.exe   | Push Consumer client                    |
  +-----------------+----------------+-----------------------------------------+
  | pullsupp        | pullsupp.exe   | Pull Supplier client                    |
  +-----------------+----------------+-----------------------------------------+
  | pullcons        | pullcons.exe   | Pull Consumer client                    |
  +-----------------+----------------+-----------------------------------------+
  | libomniEvents.a | omniEvents.lib | omniEvents implementation library       |
  +-----------------+----------------+-----------------------------------------+


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

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
README file supplied with the omniORB2 distribution for information on how to
start omniNames.

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

The examples provide an Event Channel Factory server process (eventd) which
clients can use to create Event Channels. The factory registers itself
with the Naming Service to enable clients to locate it. eventd supports 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.

After starting, eventd blocks 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. The Event Channel is 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 your application directly with the
       omniEvents library.

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 [-s n]] [-n name] [-k kind] [-h]

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

usage: pushcons [-d n -s n]] [-n name] [-k kind] [-h]

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

usage: pullsupp [-d n -s n]] [-n name] [-k kind] [-h]

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

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

         -t      enable try_pull mode
         -d n    disconnect after n pulls
         -s n   sleep n seconds after disconnecting
         -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 a value parameter 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 find omniEvents useful,

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