1 files changed, 136 insertions, 0 deletions
diff --git a/ACE/apps/Gateway/README b/ACE/apps/Gateway/README
new file mode 100644
index 00000000000..7861e1051e9
--- /dev/null
+++ b/ACE/apps/Gateway/README
@@ -0,0 +1,136 @@
+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/PDF/TAPOS-00.pdf
+
+----------------------------------------
+
+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
+        connection_config and consumer_config files:
+
+        1. The connection_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
+           connection_config configuration file).  These Peers are
+           "suppliers" of events to the Gateway.
+
+        2. Consumer Peers (designated by an 'C' in the Gateway's
+           connection_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 connection_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 connection_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:10011
+
+      # Window 2 (Consumer)
+      % peerd -a C:10012
+
+      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.
+
+
+