ACE/examples/Service_Configurator/IPC-tests/README

   1
   2
   3 This file describes how to invoke the tests in the
   4 $ACE_ROOT/examples/Service_Configurator/IPC-test/{client,server}
   5 directories.  These tests exercise all of the ACE IPC SAP
   6 communication mechanisms, the Reactor event demultiplexor, and the
   7 Service Configurator dynamic service configuration framework.  To gain
   8 a deeper understanding of what is going on, you should read the the
   9 Wrapper Facade, Reactor, and Component Configurator patterns in POSA2
  10 <http://www.dre.vanderbilt.edu/~schmidt/POSA/> and check out the following
  11 papers on the ACE framework components:
  12
  13 http://www.dre.vanderbilt.edu/~schmidt/PDF/IPC_SAP-92.pdf
  14 http://www.dre.vanderbilt.edu/~schmidt/PDF/Reactor1-93.pdf
  15 http://www.dre.vanderbilt.edu/~schmidt/PDF/Reactor2-93.pdf
  16 http://www.dre.vanderbilt.edu/~schmidt/PDF/reactor-rules.pdf
  17 http://www.dre.vanderbilt.edu/~schmidt/PDF/Svc-Conf.pdf
  18
  19 The key to running these client/server tests is to understand the
  20 purpose of the svc.conf file located in the
  21 $ACE_ROOT/examples/Service_Configurator/IPC-test/server/ directory.
  22 This file contains a list of services that may be dynamically
  23 configured into a the address space of a network daemon process.  If
  24 you look at the example svc.conf file included in the tests you'll see
  25 that some entries are commented out (the comment symbol is the '#',
  26 which is an "ignore until end-of-line comment" with the same semantics
  27 as the UNIX C and Bourne shells).  Before reading any further, take a
  28 look at this svc.conf file with your favorite editor or file browser.
  29
  30 There are several types of entries in this file.  The two most
  31 important are the lines beginning with the keywords "static" and
  32 "dynamic".  For example, the first non-commented line says:
  33
  34 static ACE_Service_Manager "-d -p 3911"
  35
  36 When this line is parsed at startup time by the Service Configurator
  37 object in the ./server_test executable, it causes the pre-configured
  38 Svc_Manager object to be initialized with an "argv" argument of "-d -p
  39 3911."  This results in TCP port 3911 being created to listen
  40 connection requests from clients.  To see how this works do the
  41 following:
  42
  43 1. Comment out all the other lines except
  44
  45    static Svc_Manager "-d -p 3911"
  46
  47    in the svc.conf file
  48
  49 2. Start up the ./server_test executable in one window, as follows:
  50
  51    % ./server_test -d
  52
  53 3. Make another window on the *same* host and cd to the ./client/
  54    directory
  55
  56 4. Run the ./remote_service_directory_test program as follows:
  57
  58         % ./remote_service_directory_test -p 3911 -h localhost
  59
  60 If everything has been compiled and initialized correctly, you should
  61 get the following message:
  62
  63         Svc_Manager 3911/tcp # lists all services in the daemon
  64
  65 This message is telling you that the Svc_Manager is currently the only
  66 service that is active within the ./server_test program.  To configure
  67 and activate another service dynamically, perform the following steps:
  68
  69 1. *Without* shutting down the ./server_test program, edit the svc.conf
  70    file.  Comment out the Svc_Manager line by adding a '#' at the
  71    front, i.e.:
  72
  73    # static Svc_Manager "-d -p 3911"
  74
  75    and then uncomment the second line:
  76
  77    dynamic Remote_Brdcast Service_Object * ./IPC_Tests_Server:remote_broadcast "-p 10001"
  78
  79 2. If you're running on an OS platform that supports SIGHUP, send the
  80    SIGHUP signal to the process running the ./server_test program.
  81    This will cause the ./server_test program to reconfigure itself
  82    based on the new contents of the svc.conf file.  Not every platform
  83    supports SIGHUP. However, the remote_service_directory_test in
  84    ./client/ can be used to reconfigure services, e.g., by passing it
  85    parameters as follows:
  86
  87    % ./remote_service_directory_test -p 3911 -h localhost -r
  88
  89    The '-r' flag instructs the server to reconfigure itself.
  90
  91    After reconfiguration, you'll now have a second active service in
  92    the address space of the ./server_test daemon.  To see this, rerun
  93    the remote_service_directory_test command, e.g.:
  94
  95    % ./remote_service_directory_test -p 3911 -h localhost
  96
  97    You should now see the following output:
  98
  99    Svc_Manager 3911/tcp # lists all services in the daemon
 100    Remote_Brdcast 10001/udp # tests broadcasting
 101
 102    which indicates that the remote broadcast service is now active.
 103
 104 3. To test the remote broadcast service, run the following program
 105    in the ./client/ directory:
 106
 107    % ./broadcast_client_test -p 10001
 108
 109    This should cause the window running the ./server_test to
 110    display the following output:
 111
 112    received broadcast datagram from host spare.ics.uci.edu
 113    ----------------------------------------
 114    testing socket broadcast service
 115    ----------------------------------------
 116
 117 If you want to run other tests, using other configurations, simply
 118 uncomment the appropriate lines in the svc.conf file and experiment
 119 with the corresponding test drivers in the ./client/ directory.  All
 120 the source code is available so once you get the hang of what is
 121 happening, you might want to take a look at how it is all implemented.
 122 You may be surprised at how much of the ACE framework code is
 123 reused for each different service.  Moreover, writing a new service is
 124 often simply a matter of copying an existing file and filling in the
 125 behavior of some of the methods (e.g., the handle_input() method and
 126 the init() method).
 127