ACE/apps/Gateway/README

   1
   2
   3 OVERVIEW
   4
   5 This directory contains source code for an application-level
   6 Communication Gateway implemented with ACE.  This prototype was
   7 developed in my cs422 OS class at Washington University in 1994.  The
   8 Gateway has recently been updated to illustrate the use of Event
   9 Channels, which forward events from Suppliers to Consumers in a
  10 distributed system.
  11
  12 You can get a paper that explains the patterns used in this
  13 implementation at the following WWW URL:
  14
  15 http://www.dre.vanderbilt.edu/~schmidt/PDF/TAPOS-00.pdf
  16
  17 ----------------------------------------
  18
  19 DIRECTORY STRUCTURE
  20
  21 There are 2 directories:
  22
  23 1. Gateway
  24
  25         This directory contains the source code for the
  26         application-level Gateway process, gatewayd.  The gatewayd
  27         routes event messages between Peers.  By default, the gatewayd
  28         plays the Connector role and initializes itself by reading the
  29         connection_config and consumer_config files:
  30
  31         1. The connection_config file establishes the "physical
  32            configuration" of the Consumer and Supplier proxies.  This
  33            file tells the Gateway what connections to establish with
  34            particular hosts using particular ports.
  35
  36         2. The consumer_config file establishes the "logical
  37            configuration."  This file tells the Gateway how to forward
  38            data coming from Suppliers to the appropriate Consumers.
  39
  40         The application Gateway generally should be started after all
  41         the Peers described below, though the process should work
  42         correctly even if it starts first.
  43
  44 2. Peer
  45
  46         This directory contains the source code for the Peer process,
  47         peerd.  There are typically many Peers, which act as suppliers
  48         and consumers of event messages that are routed through the
  49         gatewayd.
  50
  51         To do anything interesting you'll need at least two Peers: one
  52         to supply events and one to consume events.  In the
  53         configuration files, these two types of Peers are designated
  54         as follows:
  55
  56         1. Supplier Peers (designated by an 'S' in the Gateway's
  57            connection_config configuration file).  These Peers are
  58            "suppliers" of events to the Gateway.
  59
  60         2. Consumer Peers (designated by an 'C' in the Gateway's
  61            connection_config file).  These Peers are "consumers" of
  62            events forwarded by the Gateway.  Forwarding is based on
  63            the settings in the consumer_config configuration file.
  64
  65 ----------------------------------------
  66
  67 HOW TO RUN THE TESTS
  68
  69 To run the tests do the following:
  70
  71 1. Compile everything (i.e., first compile the ACE libraries, then
  72    compile the Gateway and Peer directories).
  73
  74 2. Edit the consumer_config and connection_config files as discussed
  75    above to indicate the desired physical and logical mappings
  76    for Consumers and Suppliers.
  77
  78 3. Start up the Peers (peerd).  You can start up as many as you
  79    like, as per the connection_config file, but you'll need at least two
  80    (i.e., one Supplier and Consumer).  I typically start up each Peer
  81    in a different window on a different machine, but you can run them
  82    on the same machine as long as you pick different port numbers.
  83    The Peers will print out some diagnostic info and then block
  84    awaiting connections from the Gateway.
  85
  86    If you want to set the port numbers of the Peers from
  87    the command-line do the following:
  88
  89    a. Change the svc.conf file in the ./Peer/ directory to
  90       another name (e.g., foo.conf).  This will keep the
  91       program from starting up with the svc.conf file
  92       (which dynamically links in the Peers and uses the -a option to
  93       set the port).
  94
  95    b. Then run the peers in different windows as
  96
  97       # Window 1 (Supplier)
  98       % peerd -a S:10011
  99
 100       # Window 2 (Consumer)
 101       % peerd -a C:10012
 102
 103       etc.  Naturally, you can also edit the svc.conf file, but that
 104       may be more of a pain if you've got a network filesystem and
 105       all your hosts share the same svc.conf file.
 106
 107 4. Start up the Gateway (gatewayd).  This will print out a bunch of
 108    messages as it reads the config files and connects to all the Peers.
 109    By default, the Gateway is purely reactive, i.e., it handles
 110    Consumers and Suppliers in the same thread of control.  However,
 111    if you give the '-t OUTPUT_MT' option the Gateway will handle all
 112    Consumers in separate threads.  If you give the '-t INPUT_MT' option
 113    the Gateway will handle all Suppliers in separate threads.  If you
 114    give the '-t INPUT_MT|OUTPUT_MT' option both Consumers and Suppliers
 115    will be handled in the separate threads.
 116
 117    Assuming everything works, then all the Peers will be connected.
 118    If some of the Peers aren't set up correctly, or if they aren't
 119    started first, then the Gateway will use an exponential backoff
 120    algorithm to attempt to reestablish those connections.
 121
 122 5. Once the Gateway has connected with all the Peers you can send
 123    events from Supplier Peers by typing commands in the Peer window.
 124    This Supplier will be sent to the Gateway, which will forward the
 125    event to all Consumer Peers that have "subscribed" to receive these
 126    events.
 127
 128    Note that if you type ^C in a Peer window the Peer will shutdown
 129    its handlers and exit.  The Gateway will detect this and will start
 130    trying to reestablish the connection using the same exponential
 131    backoff algorithm it used for the initial connection establishment.
 132
 133 7. When you want to terminate a Gateway, just type ^C or type any
 134    characters in the ./gatewayd window and the process will shut down
 135    gracefully.
 136
 137
 138