Completed sections "Test Executables", "Server-Side Options", and

"Client-Side Options".  Reformatted headings so that they're
surrounded by asterisks rather than followed by lines of dashes.

1 files changed, 185 insertions, 14 deletions

diff --git a/performance-tests/SCTP/README.SCTP_PERF_TEST b/performance-tests/SCTP/README.SCTP_PERF_TEST
index 3e378c77b49..22b7e646d1e 100644
--- a/performance-tests/SCTP/README.SCTP_PERF_TEST
+++ b/performance-tests/SCTP/README.SCTP_PERF_TEST
@@ -1,7 +1,10 @@
+$Id$
+
 Release 1.0 - January 2003
 
-Performance Test Overview
--------------------------
+***********************************
+*    Performance Test Overview    *
+***********************************
 
 This directory contains performance tests for measuring round-trip
 latency statistics of ACE synchronous messaging using unmarshalled
@@ -17,16 +20,18 @@ available:
 All three of these tests share the same architecture, which is
 described in the following section.
 
-Test Architecture
------------------
+***************************
+*    Test Architecture    *
+***************************
 
 As mentioned above, the performance tests measure round-trip latency
-statistics.  We are talking about the round-trip between two service
+statistics.  We are talking about the round trip between two service
 endpoints, a client and a server.  The client sends the server an
 arbitrary message with a specific length---up to 2^16 bytes---and the
 server responds with a 2-byte reply.  The client measures and records
-the time it takes to complete this exchanges.  This test is repeated
-through many iterations, and client outputs the resulting statistics.
+the time it takes to complete this exchange.  The whole test is then
+repeated through many iterations, and finally the client outputs the
+resulting statistics.
 
 In detail,
 
@@ -43,11 +48,11 @@ In detail,
       * the desired number of iterations (by default 1 million)
 
 3.  The client connects to the server's passive-mode socket.  If all
-    goes well, the client and server will each end up with a data-mode
+    goes well, the client and server will each obtain a data-mode
     socket that serves as a communication endpoint.
 
 4.  The client sends an initial header message containing the intended
-    number of iterations, along with the message length (which will be
+    number of iterations and the message length (which will be
     the same for each iteration).  Armed with this information, the
     server spawns a separate thread to handle these iterations.
 
@@ -58,7 +63,7 @@ In detail,
     fall into one of these "bins", or it will fall outside the entire
     range and will be logged as an outlier.
 
-6.  The client and server repeats the following interaction for each
+6.  The client and server repeat the following interaction for each
     test iteration.
 
     a.  The client starts a stopwatch.
@@ -84,13 +89,179 @@ In detail,
     loop waiting for more clients to connect to the passive-mode
     socket.
 
-Test Executables
-----------------
+**************************
+*    Test Executables    *
+**************************
+
+You must rely on a different pair of client and server executables
+depending on whether you desire to use the SOCK_STREAM service or the
+SOCK_SEQPACK service.
+
+The SOCK_STREAM client and server are called SOCK_STREAM_clt and
+SOCK_STREAM_srv, respectively.  The SOCK_SEQPACK client and server are
+called SOCK_SEQPACK_clt and SOCK_SEQPACK_srv, respectively.
+
+Each of these executables uses SCTP as its default protocol.  As an
+extra feature, SOCK_STREAM_clt and SOCK_STREAM_srv offer TCP as an
+alternate protocol.  The choice between TCP and SCTP is exposed via
+the '-t' option.
+
+Any of the four executables will show usage information if you run it
+with the '-h' option.  For instance, here is the usage message
+produced by SOCK_STREAM_clt:
+
+./SOCK_STREAM_clt - Measures round trip latency statistics of ACE synchronous
+                    messaging (SOCK_Stream) using unmarshalled ACE_CDR::Octet.
+USAGE: ./SOCK_STREAM_clt [ -<flag> [<val>] | --<name> [<val>] ]...
+
+  Flag  Args           Option-Name                 Default
+   -c   int            test-iterations             1000000
+   -n   none           test-enable-nagle           NO NAGLING
+   -t   str (sctp|tcp) test-transport-protocol     sctp
+
+   -m   dbl            histogram-min-bin           0
+   -M   dbl            histogram-max-bin           10000
+   -x   int            histogram-num-outliers      100
+   -b   int            histogram-bin-count         1000
+
+   -p   int            server-port                 45453
+   -H   str            server-host                 localhost
+
+   -s   int (0-16)     payload-size-power-of-2     <MUST SET VALUE>
+
+   -h   none           help
+
+For each option, the long "Option-Name" may be prefixed by two dashes
+and used on the command line in place of the shorter "Flag".  Hence
+
+   ./SOCK_STREAM_clt -s 5
+
+is equivalent to 
+
+   ./SOCK_STREAM_clt --payload-size-power-of-2 5
+
+The options shown above for SOCK_STREAM_clt (and the similar options
+available for SOCK_SEQPACK_clt) are discussed in the next section.
+
+*****************************
+*    Client-Side Options    *
+*****************************
+
+The following options are available for both SOCK_STREAM_clt and
+SOCK_SEQPACK_clt.
+
+    test-iterations  [ -c int ]
+
+        the number of times to repeat the round-trip-latency test
+        loop.  The default is 1000000.
+
+    test-enable-nagle  [ -n ]
+
+        Enable Nagle's algorithm (which is disabled by default).
+
+    histogram-min-bin  [ -m double ]
+
+        the lower boundary on the range of the histogram.
+        The default is 0.  The unit of measurement is the millisecond.
+
+    histogram-max-bin  [ -M double ]
+
+        the upper boundary on the range of the histogram.
+        The default is 10000.  The unit of measurement is the
+        millisecond.
+
+    histogram-num-outliers  [ -x int ]
+
+        the maximum number of outliers to maintain in the histogram.
+        The default is 100.
+
+    histogram-bin-count  [ -b int ]
+
+        the number of histogram bins.  The default is 1000.  The width
+        of each bin will be
+
+          (histogram-max-bin - histogram-min-bin) / histogram-bin-count
+
+    server-port  [ -p int ]
+    server-host  [ -H string ]
+
+        the port and hostname where the server's passive-mode socket
+        is bound.  The default port is 45453 and the default host is
+        localhost.
+
+    payload-size-power-of-2  [ -s int ]
+
+        an integer X.  The size of the payload will be 2^X bytes.
+
+    help  [ -h ]
+
+        Show usage message.
+
+The following option is available only for SOCK_STREAM_clt:
+
+    test-transport-protocol  [ -t (sctp|tcp) ]
+
+        the protocol for the test.  The default is sctp.
+
+In contrast, SOCK_SEQPACK_clt always uses SCTP as its protocol.
+
+*****************************
+*    Server-Side Options    *
+*****************************
+
+The following options are available for both SOCK_STREAM_srv and
+SOCK_SEQPACK_srv:
+
+    test-enable-nagle  [ -n ]
+
+        Enable Nagle's algorithm (which is disabled by default).
+
+    server-port  [ -p int ]
+ 
+        the port where the server's passive-mode socket will be
+        bound.  The default is 45453.
+
+    help  [ -h ]
+
+        Show usage message.
+
+The following option is available for both SOCK_STREAM_srv and
+SOCK_SEQPACK_srv, but the latter offers additional functionality:
+
+    server-accept-addr  [ -a w.x.y.z ]              (for SOCK_STREAM_srv)
+                        [ -a w.x.y.z,a.b.c.d,... ]  (for SOCK_SEQPACK_srv)
+
+        the network address (or addresses) to which the server's
+        passive-mode socket will be bound.
+
+        The default value of INADDR_ANY should be sufficient for
+        machines that have only one network interface.
+
+        If your machine has two interfaces, and you wish to bind the
+        socket only to one of these, then you may explicitly specify
+        the desired interface with an expression such as
+        "-a 192.168.221.104" or "-a 192.168.1.43".
+
+        If your machine has three or more interfaces, and you wish to
+        bind the socket only to a subset of two or more, AND you are
+        using SOCK_SEQPACK_srv, THEN you may explicitly specify the
+        desired interface with an expression such as 
+        "-a 192.168.221.104,192.168.1.43".  The argument here is a
+        comma-delimited list of dotted-decimal IPv4 addresses with no
+        whitespace interspersed.  This level of control is not
+        possible with SOCK_STREAM_srv.
+
+The following option is available only for SOCK_STREAM_srv:
+
+    test-transport-protocol  [ -t (sctp|tcp) ]
 
+        the protocol for the test.  The default is sctp.
 
+In contrast, SOCK_SEQPACK_srv always uses SCTP as its protocol.
 
-Test Walk-Through
------------------
+***************************
+*    Test Walk-Through    *
+***************************
 
 The SOCK_STREAM performance test