4. Running the examples

4.1. Start the Naming Service (omniNames)
4.2. Start the omniEvents daemon (omniEvents)
4.3. Create an Event Channel (eventc)
4.4. Run one or more example suppliers/consumers

The examples programs (eventc, pushsupp, pushcons, pullsupp, pullcons) are also available as Python and Java. Look in examples/python/* and examples/java/*.

In these examples, we run omniEvents from the command line. A real installation would probably use a system service, as mentioned in the installation section.

4.1. Start the Naming Service (omniNames)

You must start the naming service (omniNames) as the examples make use of the naming service to locate the event channel factory. Please refer to the omniORB documentation for information on how to set up the naming service.

4.2. Start the omniEvents daemon (omniEvents)

omniEvents implements an Event Channel Factory server which clients can use to create Event Channels. The factory registers itself with the Naming Service to enable clients to locate it.

Before you start, you may need to set the environment variable OMNIORB_CONFIG to contain the full path name of the file omniORB.cfg. The default is /etc/omniORB.cfg. For example:

% OMNIORB_CONFIG=/wib/wob/omniORB.cfg; export OMNIORB_CONFIG

Start omniEvents by running the executable. The binary is in PREFIX/sbin (if you used the configure --prefix parameter), or in /usr/local/sbin (by default). Once the service is correctly started up, it automatically backgrounds itself (Unix only).

Example 2. Startup from the command-line.

% omniEvents -l $HOME
%

omniEvents supports the following options:

  cold start syntax: src/omniEvents [-pPORT] [-aENDPOINT] [OPTIONS]
  warm start syntax: src/omniEvents [OPTIONS]

  COLD START OPTIONS:
   -p PORT      configure server port [11169]
   -a ENDPOINT  set alternate endPoint for failover

  OPTIONS:
   -l PATH      full path to data directory* [/var/lib/omniEvents]
   -P PIDFILE   keep track of running instance in PIDFILE.
   -N ID        factory naming service id   ["EventChannelFactory"]
   -f           Stay in the foreground.
   -t FILE      Send trace messages to FILE instead of syslog.
   -v           print the IOR of the new EventChannelFactory.
   -V           display version
   -h           display this help text

  *You can also set the environment variable OMNIEVENTS_LOGDIR
  to specify the directory where the data files are kept.

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

omniEvents supports persistent channels by writing all state changes to a file. This persistency datafile is stored in /var/lib/omniEvents/ by default. Use the -l option or the OMNIEVENTS_LOGDIR environment variable to override the default.

4.3. Create an Event Channel (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 the omniEvents process.

Note

You can by-pass the factory completely and instantiate the event channel directly within your own process by linking your application directly with the omniEvents shared libraries. The src/main.cc file is a good starting point to find out how.

eventc then registers the created Event Channel with the Naming Service, and exits.

eventc has the following options:

  syntax: tools/eventc OPTIONS [FACTORY_URI]

  FACTORY_URI: The factory may be specified as a URI.
   This may be an IOR, or a corbaloc::: or corbaname::: URI.
   For example: corbaloc::localhost:11169/omniEvents

  OPTIONS:                                         DEFAULT:
   -n channel name                                  ["EventChannel"]
   -N factory name (if URI is not specified)        ["EventChannelFactory"]
   -c override default CyclePeriod_ns of new channel (nanoseconds)
   -i set the InsName of new channel, to enable access via corbaloc
   -p override default MaxNumProxies of new channel
   -q override default MaxQueueLength of new channel
   -r override default PullRetryPeriod for new channel (seconds)
   -t set an event type filter, FilterId=<RepositoryId>
   -v print the IOR of the new EventChannel to standard output.
   -h display this help text
  OLD OPTIONS: (only used by omniEvents v2.4 and earlier)
   -m override default MaxEventsPerConsumer for new channel

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 omniORB specific option -ORBtraceLevel 20. eventc terminates once the event channel has been created:

% eventc
%

4.4. Run one or more example suppliers/consumers

There are four example clients: pushsupp, pushcons, pullsupp and 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 exercise the disconnect functionality provided by the channel.

  syntax: examples/pushsupp OPTIONS [CHANNEL_URI]
  CHANNEL_URI: The event channel may be specified as a URI.
   This may be an IOR, or a corbaloc::: or corbaname::: URI.
  OPTIONS:                                         DEFAULT:
   -d NUM   disconnect after sending NUM events     [0 - never disconnect]
   -r       connect using a nil reference
   -s SECS  sleep SECS seconds after disconnecting  [0]
   -n NAME  channel name (if URI is not specified)  ["EventChannel"]
   -h       display this help text

  syntax: examples/pushcons OPTIONS [CHANNEL_URI]
  CHANNEL_URI: The event channel may be specified as a URI.
   This may be an IOR, or a corbaloc::: or corbaname::: URI.
  OPTIONS:                                         DEFAULT:
   -d NUM   disconnect after receiving NUM events   [0 - never disconnect]
   -s SECS  sleep SECS seconds after disconnecting  [0]
   -n NAME  channel name (if URI is not specified)  ["EventChannel"]
   -h       display this help text

  syntax: examples/pullsupp OPTIONS [CHANNEL_URI]
  CHANNEL_URI: The event channel may be specified as a URI.
   This may be an IOR, or a corbaloc::: or corbaname::: URI.
  OPTIONS:                                         DEFAULT:
   -d NUM   disconnect after sending NUM events     [0 - never disconnect]
   -s SECS  sleep SECS seconds after disconnecting  [0]
   -n NAME  channel name (if URI is not specified)  ["EventChannel"]
   -h       display this help text

  syntax: examples/pullcons OPTIONS [CHANNEL_URI]
  CHANNEL_URI: The event channel may be specified as a URI.
   This may be an IOR, or a corbaloc::: or corbaname::: URI.
  OPTIONS:                                         DEFAULT:
   -t       enable try_pull mode
   -r       connect using a nil reference
   -d NUM   disconnect after receiving NUM events   [0 - never disconnect]
   -s SECS  sleep SECS seconds after disconnecting  [0]
   -n NAME  channel name (if URI is not specified)  ["EventChannel"]
   -h       display this help text

The -t option in pullcons causes the pull consumer to issue non-blocking try_pull() invocations rather than blocking pull()s.

Example 3. Here is what to expect during a typical session

  % examples/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
  ...

  % examples/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
  ...

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 the -r option of eventc can be used to specify a pull retry period QOS parameter. This parameter represents a timeout in seconds to wait for before each poll cycle. This parameter defaults to 1 second.