NOTE: Only test_nx.c has been updated for nexus-4.0.  The others are
still written to the nexus-3.0 API.

This is the Nexus test suite README.

Currently, the Nexus test suite consists of five executables used to exercise
various pieces of Nexus.  The five executables are:

        test_acquire - used to test acquiring nodes into a Nexus computation
                       by means of a call to nexus_acquire_nodes()

        test_args - used to test command-line user and package arguments
                    to a Nexus application

        test_comm - used to test communications of various size buffers of
                    each Nexus data type between nodes withing the same
                    Nexus context and nodes withing different Nexus contexts;
                    also contains code to run communications tests between
                    a "server" using nexus_allow_attach() and a "client"
                    using nexus_attach()

        test_cond - used to test the Nexus routines for locking and unlocking
                    mutexes and for waiting and signaling condition variables

        test_polltime - used to determine an average time to call nexus_poll()

Each executable accepts command-line parameters that control the specific
behavior of the executable.  These command-line parameters and examples of
what they should look like are shown below.

The main() function of each executable contains additional information about
the specific executable.

In general, when an executable in the test suite run successfully it produces
a success message and returns a return code of 0 to the operating system.
When an executable in the test suite encounters an error, it produces an error
message for each error encountered, terminates with a message indicating that
some of the tests in the module produced an error, and returns a return code
of 1 to the operating system.  By this mechanism, the test suite could be
automated with a simple shell script for automated testing.

Each test program has a #define VERBOSE near the beginning of the source code.
As delivered, this line is commented out.  By removing the comment and defining
VERBOSE, messages detailing the current state of the executing program will be
printed while the test program runs.  This can be used to easily enable
debugging.



test_acquire
------------
This program is used to test nexus_acquire_nodes() by acquiring nodes from a
specified machine into the running test executable.  The program accepts three
command-line parameters for the name of the machine to acquire the nodes on,
the starting node number to acquire, and the number of total nodes to acquire.
For example:

        % test_acquire jaeger.mcs.anl.gov 1 3

tells the program to attempt acquire nodes jaeger.mcs.anl.gov#1,
jaeger.mcs.anl.gov#2, and jaeger.mcs.anl.gov#3 into the test execution.

If no command-line parameters are specified, the executable attempts to acquire
one node designated as node 1 from the localhost machine.



test_args
---------
This program is used to test command-line user and package arguments to a
Nexus application.  It expects to be invoked as in the following example:

        % test_args test1 test2 test3 -nx -test

If this program is complied with #define VERBOSE it instead echoes the
specified command-line arguments to the screen and indicates whether the
Nexus package argument ("-nx -test") was successfully located on the
command-line.



test_comm
---------
This program is used to test communications of various size buffers of each
Nexus data type between nodes within the same Nexus context and nodes within
different Nexus contexts.  Additionally, it contains code to run communications
tests between a "server" using nexus_allow_attach() and a "client" using
nexus_attach().  Presently nexus_allow_attach() and nexus_attach() are
experimental routines for allowing attachments to a Nexus computation to
take place while the computation is running.

There are three major ways that the program can be invoked.

First, the program can be invoked with the first parameter "testcomm" to signal
the program to execute basic communications tests.  If this test is selected,
the program expects to receive a beginning buffer size, an ending buffer size,
and a step size for the sizes of buffers desired by the user.  For example:

                % test_comm testcomm 1 1001 100

tells the program to execute basic communications tests with a beginning buffer
size of 1, an ending buffer size of 1001, and an increment for the buffer size
of 100 between iterations.

Second, the program can be invoked with the first parameter "server" to signal
the program that it is to act as an attach test server.  If this test is
selected, the program expects to receive a TCP port number that the server is
to listen for attachments on.  For example:

                % test_comm server 7000

tells the program to operate as an attach test server listening on TCP port
7000.  The user would then run test_comm in a second session as a client and
attach to the same TCP port to conduct the test.

Third, the program can be invoked with the first parameter "client" to signal
the program that it is to act as an attach test client.  If this test is
selected, the program expects to receive a hostname and TCP port number
for the machine where the server is running, and a beginning buffer size,
and ending buffer size, and a step size for the sizes of buffers desired
the the user.  For example:

                % test_comm client dalek.mcs.anl.gov 7000 1 1001 100

tells the program to operate as an attach test client, contacting the host
dalek.mcs.anl.gov on TCP port 7000.  Once connected, it will execute
communications tests with a beginning buffer size of 1, an ending buffer size
of 1001, and an increment for the buffer size of 100 between iterations.

If this program is invoked without any command-line parameters it will execute
a basic communications test with default values for the beginning buffer size,
the ending buffer size, and the step size.



test_cond
---------
This program is used to test the Nexus routines for locking and unlocking
mutexes and for waiting and signaling condition variables.  It does not
examine any command-line parameters.




test_polltime
-------------
This program is used to determine an average time to call nexus_poll().  It
accepts one command line parameter which is the number of times to call
nexus_poll().  It then divides the total wallclock time for all calls by the
number of calls made to determine the average time for the call.

If no command-line parameters are specified, the program assumes a default
value of 10000 calls.

