This directory contains correctness tests and performance microbenchmarks for
GASNet. For convenience, the mpi directory also contains some comparable MPI
performance microbenchmarks, some contributed from outside sources.

See the top-level GASNet README for information on running all the tests using
the GASNet Makefile-based test harness.  
See comments at the top of each file for test description, and run any test with
--help to see usage information for individual tests.


Coding standards for GASNet tests:
---------------------------------
All GASNet test code must adhere to the following coding standards:

* All of the general linguistic coding standards listed in the top-level GASNet README-devel

* Tests should only use public GASNet interfaces (ie prefixed with gasnet_ or gasnett_).
Tests must never invoke gasneti_, gasnetc_ or gasnete_ interfaces - this ensures test
portability across GASNet conduits and GASNet implementations. Any tests of GASNet 
internal functionality belong in ../gasnet_diagnostic.c, where they will be invoked 
by testinternal.

* test.h contains numerous tools which capture common idioms for GASNet test
code. Test authors should be familiar with the services provided by this
header and use them rather than re-implementing ad-hoc solutions. 

Specifically:

 - All tests must invoke test_init immediately after attach to register usage info
   and init the framework. Failures in argument parsing should call test_usage().
   
 - Tests needing segment space should use TEST_SEGSZ_REQUEST and TEST_SEG instead 
   of gasnet_getSegmentInfo, as the former handles SEGMENT_EVERYTHING correctly

 - Barriers should be written as BARRIER(), unless there's a reason to directly
   invoke the GASNet barrier functions (like testing barrier correctness)

 - Threaded barriers should use PTHREAD_BARRIER(numthreads) or PTHREAD_LOCALBARRIER(numthreads)

 - Non-fatal errors should issue a message using ERR("msg",...) (works just like printf)

 - Fatal errors should be written as FATALERR("msg",...) (works just like gasnett_fatalerror)

 - Informational messages should use MSG("msg",...) instead of printf,
   or MSG0("msg",...) if the message is collective and should only be issued by node 0

 - Allocation should use test_malloc, test_calloc, test_free

 - Calls to the core API should be surrounded with GASNET_Safe()

 - Pthread creation should be done using test_createandjoin_pthreads

 - Timing should be done with TIME() or gasnett_ticks_now() (latter provides ns granularity) 

 - Tests needing random numbers should use TEST_RAND and friends, and should
   include an optional seed argument that is passed to TEST_SRAND

 - Tests with many optional parts should use the TEST_SECTION* interface

 - Tests needing a computational delay should use test_delay

In all cases, see existing tests for examples of correct usage.

* All else being equal, when writing new test code it's usually preferable to
expand an existing test with related functionality rather than creating a
whole new test, unless one is testing a truly novel aspect of functionality or
performance. This helps to reduce build time and nightly test cost for the tests.

* New tests should be added to tests/Makefile.in (with appropriate arguments, if necessary)
and also to tests/harness/gasnet-tests/harness.conf

