ChangeLogTag:Wed Feb 23 18:58:06 2000 Douglas C. Schmidt <schmidt@tango.cs.wustl.edu>

13 files changed, 225 insertions, 122 deletions

diff --git a/TAO/ChangeLogs/ChangeLog-02a b/TAO/ChangeLogs/ChangeLog-02a
index 05fcbed3946..01f5cdd6e8c 100644
--- a/TAO/ChangeLogs/ChangeLog-02a
+++ b/TAO/ChangeLogs/ChangeLog-02a
@@ -1,3 +1,9 @@
+Wed Feb 23 20:36:30 2000  Douglas C. Schmidt  <schmidt@tango.cs.wustl.edu>
+
+	* tests/README: Updated this file to include brief descriptions of 
+	  all tests in the subdirectories.  Thanks to Rick Hess
+ 	  <rick.hess@lmco.com> for reporting this.
+
 Wed Feb 23 14:42:16 2000  Carlos O'Ryan  <coryan@uci.edu>
 
         * tests/IDL_Test/Makefile:
diff --git a/TAO/tests/Collocation/README b/TAO/tests/Collocation/README
index bcdad70d063..653c748f365 100644
--- a/TAO/tests/Collocation/README
+++ b/TAO/tests/Collocation/README
@@ -2,8 +2,8 @@ This program performs a series of sanity check on the collocation support in TAO
 
 After building the example, you'll get:
 
-  Coll_Test_Stubs.{dll,so}: This library contains stub implementations.
+        Coll_Test_Stubs.{dll,so}: This library contains stub implementations.
 
-  Diamond.{dll,so}: This library contains the implementation Diamond object.
+        Diamond.{dll,so}: This library contains the implementation Diamond object.
 
-  Collocation[.exe]: This program performs the collocation test.
\ No newline at end of file
+        Collocation[.exe]: This program performs the collocation test.
diff --git a/TAO/tests/Connection_Purging/README b/TAO/tests/Connection_Purging/README
index 7a460182c4a..94f1516d540 100644
--- a/TAO/tests/Connection_Purging/README
+++ b/TAO/tests/Connection_Purging/README
@@ -1,115 +1,104 @@
-
-
 Connection Purging Test       By: Kirthika Parameswaran <kirthika@cs.wustl.edu>            
 =======================           Irfan Pyarali <irfan@cs.wustl.edu>
 
-
 This is a test which stress tests the connection management and checks
 whether cached handlers are purged effectively when the process runs
 out of descriptors.
 
+Connection Caching Feature
+--------------------------
 
-In detail:
----------
+Motivation:
 
-    Connection Caching Feature
-    --------------------------
+In TAO, open connections are stored in a connection cache and reused
+for the subsequent requests between the same client and server.  This
+is done to avoid the cost of establishing new connections. Every
+connection needs a OS handle which has to obtained from the OS. The OS
+can allot only a fixed number of handles to a process.  This can
+become a issue in case of clients and servers with multiple handles
+open who may not be allowed to establish a new connection as the
+process has run out of handles.
 
-          Motivation:
+Aim:
 
-          In TAO, open connections are stored in a connection cache and
-          reused for the subsequent requests between the same client and
-          server.  This is done to avoid the cost of establishing new
-          connections. Every connection needs a OS handle which has to
-          obtained from the OS. The OS can allot only a fixed number of
-          handles to a process.  This can become a issue in case of
-          clients and servers with multiple handles open who may not be
-          allowed to establish a new connection as the process has run out
-          of handles.
+Clients and servers should be able to to continue making new
+connections by tearing down "old" connections.
 
-          Aim:
+Solution: Auto-purging
 
-          Clients and servers should be able to to continue making new
-          connections by tearing down "old" connections.
+The connections are stored in a cache. When ever the connect call
+fails due to the process running out of handles, auto-purging will
+kick in and some "old" connections will be removed from the connection
+cache.  The decision about which connections are "old" is made by the
+caching strategies. The percentage of existing connections to be
+purged is controlled by a purge percent.
 
-          Solution: Auto-purging
+ACE classes: Caching_Utility, Cleanup_Stratgies, and
+Caching_Strategies have been used.  Simple examples are available in
+$ACE_ROOT/tests/Cached_Accept_Conn_Test.cpp and
+$ACE_ROOT/tests/Cached_Conn_Test.cpp.
 
-          The connections are stored in a cache. When ever the connect
-          call fails due to the process running out of handles,
-          auto-purging will kick in and some "old" connections will be
-          removed from the connection cache.  The decision about which
-          connections are "old" is made by the caching strategies. The
-          percentage of existing connections to be purged is controlled by
-          a purge percent.
+Note that the users can also purge handles used by the ORB explicitly
+through TAO_Connector_Registry::purge_connections().  This can enable
+them to open new handles for their application.
 
-          ACE classes: Caching_Utility, Cleanup_Stratgies, and
-          Caching_Strategies have been used.  Simple examples are
-          available in $ACE_ROOT/tests/Cached_Accept_Conn_Test.cpp and
-          $ACE_ROOT/tests/Cached_Conn_Test.cpp.
+Test:
+----
 
-          Note that the users can also purge handles used by the ORB
-          explicitly through TAO_Connector_Registry::purge_connections().
-          This can enable them to open new handles for their application.
+This test creates the number of "server" ORBs specified by the -i
+option and has a client ORB which invokes remote methods on these
+ORBs.
 
-    Test:
-    ----
-      
-       This test creates the number of "server" ORBs specified by the
-       -i option and has a client ORB which invokes remote methods on
-       these ORBs. 
-        
-       Two possible cases:
+Two possible cases:
 
-    1. When the process runs out of handles during "connect", the
-       Connector removes handlers from its connection cache depending
-       upon the kind of connection caching strategy followed. (by
-       default: Least Recently Used) set by the
-       ORBConnectionCachingStrategy option.
+1. When the process runs out of handles during "connect", the
+Connector removes handlers from its connection cache depending upon
+the kind of connection caching strategy followed. (by default: Least
+Recently Used) set by the ORBConnectionCachingStrategy option.
 
-    2. When the "accept" or "open" calls made by the Acceptors in the
-       same process fail, request is made on all the Connectors of all
-       the ORBs in the system to perform purging depending on the
-       ORBPurgePercentage value provided.
+2. When the "accept" or "open" calls made by the Acceptors in the same
+process fail, request is made on all the Connectors of all the ORBs in
+the system to perform purging depending on the ORBPurgePercentage
+value provided.
 
-    Note: This test does not use the Collocation optimisations since 
-    we want to use up handles and test the connection caching as well
-    as purging.
+Note: This test does not use the Collocation optimisations since we
+want to use up handles and test the connection caching as well as
+purging.
 
-   Options:
-   -------
+Options:
+-------
 
-       i:  Number of iteration which equals the number of server orbs.
+i:  Number of iteration which equals the number of server orbs.
 
-       d:  Debugging ON 
+d:  Debugging ON 
 
-       a:  Number of handles to be kept free. The Handle Gobbler will
-           eat up the max_handles specified for the OS but leave
-           behind the handles requested. This helps in testing more
-           effectively. Please remember to set this value judiciously.
-        
-       r:  Number of remote call invocations to be made by the client
-           on the servant.
+a:  Number of handles to be kept free. The Handle Gobbler will
+   eat up the max_handles specified for the OS but leave
+   behind the handles requested. This helps in testing more
+   effectively. Please remember to set this value judiciously.
 
-       ?:  help!
-       
- 
-  Options Using  svc.conf:
-  -----------------------
+r:  Number of remote call invocations to be made by the client
+   on the servant.
 
-  Through options to the Resource_Factory :-
-    -ORBConnectionCachingStrategy <lru/lfu/fifo/null>
-    -ORBPurgePercent <percentage>
+?:  help!
 
 
-  Execution:
-  ---------
+Options Using  svc.conf:
+-----------------------
+
+Through options to the Resource_Factory :-
+-ORBConnectionCachingStrategy <lru/lfu/fifo/null>
+-ORBPurgePercent <percentage>
+
+Execution:
+---------
 
-        Simply run the ./run_test.pl !
+Simply run the ./run_test.pl !
 
-   else
+else
 
-        ./Connection_Purging -ORBCollocation no 
+./Connection_Purging -ORBCollocation no 
 
-        with options specified per need.    
+with options specified per need.    
 
 
diff --git a/TAO/tests/Endpoint_Per_Priority/README b/TAO/tests/Endpoint_Per_Priority/README
index ac7c74cb72b..ec3afb8bfd3 100644
--- a/TAO/tests/Endpoint_Per_Priority/README
+++ b/TAO/tests/Endpoint_Per_Priority/README
@@ -1,10 +1,10 @@
 # $Id$
 
-	A simple test to verify that endpoint-per-priority works. This 
-is a concurrency strategy where each endpoint is assigned a thread
-running at a different priority. The priority of each endpoint is
-transmitted to the client as a Tagged Component of the IOR.  The
-client makes the request on the right endpoint to preserve priority
-end-to-end.
+A simple test that verifies of TAO's endpoint-per-priority model
+works.  This is a concurrency strategy where each endpoint is assigned
+a thread running at a different priority. The priority of each
+endpoint is transmitted to the client as a Tagged Component of the
+IOR.  The client makes the request on the right endpoint to preserve
+priority end-to-end.
 
 	Check the run_test.pl script to check how this is used.
diff --git a/TAO/tests/Explicit_Event_Loop/README b/TAO/tests/Explicit_Event_Loop/README
index 66996c57b85..939e4134b7e 100644
--- a/TAO/tests/Explicit_Event_Loop/README
+++ b/TAO/tests/Explicit_Event_Loop/README
@@ -1,11 +1,10 @@
 $Id$
 
-Explicit Event Loop test.
+This tests the methods work_pending() and perform_work() methods of
+the orb.  The simple time server, instead of calling orb->run(), has
+an loop in which work_pending() and perform_work() are called
+explicitly.  Its usage is specified below.
 
-This is a test of the methods work_pending() and perform_work() methods of the orb.
-The simple time server, instead of calling orb->run(), has an loop in which 
-work_pending() and perform_work() are called explicitly.   Its usage is specified 
-below.
 ______________________________________________________________________________
 This test has been adapted from code in chapter 3 of "Advanced CORBA 
 Programming with C++" by Michi Henning and Steve Vinoski. Copyright 1999. 
@@ -15,7 +14,6 @@ Moran <mm4@cs.wustl.edu>.   All of these changes are documented in the file
 CHANGES in this directory.
 ______________________________________________________________________________
 
-
 Summary:
     This is the simple time server given in chapter 3 of the book.
     There is a server process which holds a servant object which can return 
diff --git a/TAO/tests/FL_Cube/README b/TAO/tests/FL_Cube/README
index a882db73603..b50b764e52c 100644
--- a/TAO/tests/FL_Cube/README
+++ b/TAO/tests/FL_Cube/README
@@ -1,9 +1,10 @@
 # $Id$
 
+Test the integration of the FL toolkit and TAO.
+
 Simply run the server and the client, as follows:
 
 $ server -o foo.ior
 $ client -k file://foo.ior
 
-	The test only does something useful if the FL toolkit was
-enabled.
+The test only does something useful if the FL toolkit was enabled.
diff --git a/TAO/tests/IORManipulation/README b/TAO/tests/IORManipulation/README
index e1f7e997912..10fb424eccc 100644
--- a/TAO/tests/IORManipulation/README
+++ b/TAO/tests/IORManipulation/README
@@ -1,5 +1,5 @@
-This program test the basic operation of the 
-IORManipulation interface
+This program test the basic operation of TAO's IORManipulation
+interface.
 
 Run the application as follows.
 
diff --git a/TAO/tests/Interceptors/README b/TAO/tests/Interceptors/README
index 06b8ef50cf9..b991425377e 100644
--- a/TAO/tests/Interceptors/README
+++ b/TAO/tests/Interceptors/README
@@ -1,7 +1,5 @@
 # $Id$
 
-= server, client
-
 This test allows you to visually check the correct invocation of
 TAO's pseudo-portable interceptors.  To run the test, try:
 
diff --git a/TAO/tests/MProfile/README b/TAO/tests/MProfile/README
index 56bf4005a1e..9726b6dff0c 100644
--- a/TAO/tests/MProfile/README
+++ b/TAO/tests/MProfile/README
@@ -1,4 +1,5 @@
-This program tests fundamentals of FT.
+This program tests fundamentals of TAO's ORB fault tolerance by
+merging multiple profiles in a single object reference.
 
 Run the application as follows.
 
@@ -8,7 +9,6 @@ $ client -k file://file_name1 -m file://file_name2
 (When a message "Kill primray " appears on screen, kill the server
 exhibiting the IOR in file with name "file_name1". )
 
-
 Comments:
 ========
 
diff --git a/TAO/tests/MProfile_Forwarding/README b/TAO/tests/MProfile_Forwarding/README
index cc52f6d72d5..a11a56e0216 100644
--- a/TAO/tests/MProfile_Forwarding/README
+++ b/TAO/tests/MProfile_Forwarding/README
@@ -1,6 +1,6 @@
-This test is a test case for one of the problems that was reported by
-the DOORS team at Lucent. The test is aimed at testing the following
-scenario. 
+This test evalutes ORB fault tolerance support, based on one of the
+problems that was reported by the DOORS team at Lucent. The test is
+aimed at testing the following scenario.
 
 1. We will have three copies of the same server running. Let me call
 them as ref1, ref2 & ref3.
diff --git a/TAO/tests/QtTests/README b/TAO/tests/QtTests/README
index 563abffd4d6..b5f1679ad3b 100644
--- a/TAO/tests/QtTests/README
+++ b/TAO/tests/QtTests/README
@@ -1,7 +1,7 @@
 # $Id$
 
 Introduction:
-------------
+
 This example illustrates the usage of the QtReactor from TAO.  The
 server creates a display dialog which has a lcd display. The client
 creates a dialog with a quit button & a slider. On dragging the slider
diff --git a/TAO/tests/README b/TAO/tests/README
index 5e763a57b47..d31c2b10b9a 100644
--- a/TAO/tests/README
+++ b/TAO/tests/README
@@ -7,49 +7,160 @@ how to run the following tests:
         . CDR
 
           This directory contains several tests for the CDR stream
-          class. 
+          class.
+
+        . Collocation
+
+          This program performs a series of sanity check on the
+          collocation support in TAO.
+
+        . Connection_Purging
+
+          This is a test which stress tests the connection management
+          and checks whether cached handlers are purged effectively
+          when the process runs out of descriptors.
 
         . DynAny_Test
         
           Tests TAO's DynAny feature, which allows composition and
           decomposition of arbitrarily complex CORBA::Any values at
           runtime, without requiring any compile-time knowledge of the
-          IDL. 
+          IDL.
+
+        . Endpoint_Per_Priority
+
+          A simple test that verifies of TAO's endpoint-per-priority
+          model works.
+
+        . Explicit_Event_Loop
+
+          This tests the methods work_pending() and perform_work()
+          methods of the orb.
+
+        . FL_Cube
+
+          Test the integration of the FL toolkit and TAO.
+
+        . Faults
+
+          A little test to check the the ORB can handle server and
+          client crashes.
+
+        . IDL_Test
+
+          A collection of the IDL examples that have caused problems
+          in the past for the IDL compiler. Most files need only to
+          build cleanly, except pragma.idl, which generates pragma
+          prefixes. These prefixes are checked for correctness in
+          main.cpp.
+
+        . IORManipulation
+
+          This program test the basic operation of TAO's
+          IORManipulation interface.
+
+        . InterOp-Naming
+
+          This service allows the ORB to be administratively
+          configured to return object references from
+          CORBA::ORB::resolve_initial_references () for non-locality
+          constrained objects.
+
+        . Interceptors
+
+          This test allows you to visually check the correct
+          invocation of TAO's pseudo-portable interceptors.
+
+        . Leader_Followers
 
-	  IDL_Test
+          This is a test for server applications that have client
+          threads (threads making remote calls) starting before event
+          loop threads (threads running the event loop).
 
-	  A collection of the IDL examples that have caused problems
-	  in the past for the IDL compiler. Most files need only to
-	  build cleanly, except pragma.idl, which generates pragma
-	  prefixes. These prefixes are checked for correctness in
-	  main.cpp.
+        . MProfile
+
+          This program tests fundamentals of TAO's ORB fault tolerance
+          by merging multiple profiles in a single object reference.
+
+        . MProfile_Forwarding
+
+          This test evalutes ORB fault tolerance support.
+
+        . MT_Client
+
+          This is a simple test for multi-threaded clients; it just
+          creates a simple server process and runs a client with
+          multiple thread sharing the same object reference.
+
+        . MT_Server
+
+          This is a simple test for a thread-pool server.  It creates
+          a server process with a variable number of threads, multiple
+          clients can send requests to it, the requests are handled in
+          different threads.
 
         . Multiple_Inheritance
 
           This test exercises IDL interfaces that inherit from
           multiple interfaces.
 
+        . Native_Exceptions
+
+          Simple test to show (and verify) that TAO can generate code
+          for platforms with native exception support, including
+          passing the exception around.
+
         . NestedUpcall
 
           Tests TAO's nested upcall feature, which allows
           single-threaded clients and servers to perform callbacks on
           each other without deadlocking.
 
+        . Nested_Event_Loop
+
+          This is a test of invoking nested event loop calls from user
+          code, i.e., a call to perform_work() or run() from the
+          implementation of the servant.
+
+        . ORB_init
+
+          The ORB_init test simply verifies that the CORBA::ORB_init()
+          call behaves as defined in the OMG CORBA specification.
+
         . OctetSeq
 
-	  Measures the cost of marshaling and demarshaling of
+          Measures the cost of marshaling and demarshaling of
           sequences of octets of different sizes. NOTE: TAO optimizes
-	  this so the cost should be constant!
+          this so the cost should be constant!
+
+        . POA
+
+          Tests and illustates various Portable Object Adapter (POA)
+          interfaces and their usage scenarios.
 
         . Param_Test
  
           Tests all the features of TAO's protocol engine.
 
-        . Connection_Purging
+        . QtTests
 
-          Tests how multiple conenctions are evicted when needed.
+          This example illustrates the usage of the QtReactor from TAO.
 
         . Smart Proxies
         
-          Tests the smart proxy feature which allows the user to specify 
-          a proxy in plaec of the default proxy (stub).
+          Tests the smart proxy feature which allows the user to
+          specify a proxy in plaec of the default proxy (stub).
+
+        . Timed_Buffered_Oneways
+
+          This is a test for oneways with buffering and timing
+          constraints.
+
+        . Timeout
+
+          A simple test for timeouts.
+
+        . Xt_Stopwatch
+
+          This example illustrates the usage of the XtReactor from
+          TAO.
diff --git a/TAO/tests/Xt_Stopwatch/README b/TAO/tests/Xt_Stopwatch/README
index cbd37f5000f..0e132991ce5 100644
--- a/TAO/tests/Xt_Stopwatch/README
+++ b/TAO/tests/Xt_Stopwatch/README
@@ -1,7 +1,7 @@
 # $Id$
 
 Introduction:
-------------
+
 This example illustrates the usage of the XtReactor from TAO.  The
 server creates a small display dialog and the client displays a dialog
 with a start and stop button.  On pressing the start button the server