OVERVIEW

This directory contains source code for an application-level
Communication Gateway implemented with ACE.  This prototype was
developed in my cs422 OS class at Washington University in 1994.  The
Gateway has recently been updated to illustrate the use of Event
Channels, which forward events from Suppliers to Consumers in a
distributed system.

You can get a paper that explains the patterns used in this
implementation at the following WWW URL:

http://www.cs.wustl.edu/~schmidt/TAPOS-95.ps.gz

----------------------------------------

DIRECTORY STRUCTURE

There are 2 directories:

1. Gateway

        This directory contains the source code for the
        application-level Gateway process, gatewayd.  The gatewayd
        routes event messages between Peers.  By default, the gatewayd
        plays the Connector role and initializes itself by reading the
        proxy_config and consumer_config files:
           
        1. The proxy_config file establishes the "physical
           configuration" of the Consumer and Supplier proxies.  This
           file tells the Gateway what connections to establish with
           particular hosts using particular ports.
           
        2. The consumer_config file establishes the "logical
           configuration."  This file tells the Gateway how to forward
           data coming from Suppliers to the appropriate Consumers.
           
        The application Gateway generally should be started after all
        the Peers described below, though the process should work
        correctly even if it starts first.
                      
2. Peer

        This directory contains the source code for the Peer process,
        peerd.  There are typically many Peers, which act as suppliers
        and consumers of event messages that are routed through the
        gatewayd.
           
        To do anything interesting you'll need at least two Peers: one
        to supply events and one to consume events.  In the
        configuration files, these two types of Peers are designated
        as follows:

        1. Supplier Peers (designated by an 'S' in the Gateway's
           proxy_config configuration file).  These Peers are
           "suppliers" of events to the Gateway.

        2. Consumer Peers (designated by an 'C' in the Gateway's
           proxy_config file).  These Peers are "consumers" of events
           forwarded by the Gateway.  Forwarding is based on the
           settings in the consumer_config configuration file.

----------------------------------------           

HOW TO RUN THE TESTS

To run the tests do the following:

1. Compile everything (i.e., first compile the ACE libraries, then
   compile the Gateway and Peer directories).

2. Edit the consumer_config and proxy_config files as discussed
   above to indicate the desired physical and logical mappings
   for Consumers and Suppliers.
   
3. Start up the Peers (peerd).  You can start up as many as you
   like, as per the proxy_config file, but you'll need at least two
   (i.e., one Supplier and Consumer).  I typically start up each Peer
   in a different window on a different machine, but you can run them
   on the same machine as long as you pick different port numbers.
   The Peers will print out some diagnostic info and then block
   awaiting connections from the Gateway.

   If you want to set the port numbers of the Peers from
   the command-line do the following:
   
   a. Change the svc.conf file in the ./Peer/ directory to
      another name (e.g., foo.conf).  This will keep the
      program from starting up with the svc.conf file
      (which dynamically links in the Peers and uses the -a option to
      set the port).
      
   b. Then run the peers in different windows as
   
      # Window 1 (Supplier)
      % peerd -a S:10003

      # Window 2 (Consumer)
      % peerd -a C:10004

      etc.  Naturally, you can also edit the svc.conf file, but that
      may be more of a pain if you've got a network filesystem and
      all your hosts share the same svc.conf file.

4. Start up the Gateway (gatewayd).  This will print out a bunch of
   messages as it reads the config files and connects to all the Peers.
   By default, the Gateway is purely reactive, i.e., it handles
   Consumers and Suppliers in the same thread of control.  However,
   if you give the '-t OUTPUT_MT' option the Gateway will handle all
   Consumers in separate threads.  If you give the '-t INPUT_MT' option
   the Gateway will handle all Suppliers in separate threads.  If you
   give the '-t INPUT_MT|OUTPUT_MT' option both Consumers and Suppliers
   will be handled in the separate threads.

   Assuming everything works, then all the Peers will be connected.
   If some of the Peers aren't set up correctly, or if they aren't
   started first, then the Gateway will use an exponential backoff
   algorithm to attempt to reestablish those connections.

5. Once the Gateway has connected with all the Peers you can send
   events from Supplier Peers by typing commands in the Peer window.
   This Supplier will be sent to the Gateway, which will forward the
   event to all Consumer Peers that have "subscribed" to receive these
   events.

   Note that if you type ^C in a Peer window the Peer will shutdown
   its handlers and exit.  The Gateway will detect this and will start
   trying to reestablish the connection using the same exponential
   backoff algorithm it used for the initial connection establishment.

7. When you want to terminate a Gateway, just type ^C or type any 
   characters in the ./gatewayd window and the process will shut down 
   gracefully.

Please let me know if there are any problems, questions, or
suggestions for improvement.

        Doug

        schmidt@cs.wustl.edu