Usage Guide (test)
Introduction
The test programme is a thin command line veneer to libtest. It runs a series of tests, first for the porting abstraction layer (and so can be used to validate any new ports) and then upon each data structure, and stops running on any test failure or error of any kind.
Testing lock-free code is problematic since a large class of bugs are race conditions, which are impossible or nearly impossible to methodically reproduce. As such testing consists in part of simple API tests to enure every function does what it is supposed to do at least when in the absence of race conditions, but in the main of best-effort attempts to provoke race conditions and detect them.
Make sure you run the release build - the debug build does so much extra work that it misses race conditions the release build will pick up on.
Running
The test programme is run from the command line. Change directory into test_and_benchmark/test/bin/ and type;
test -r
The full command line (which is printed by -h or by running with no arguments) is as follows;
test -e -h -i [n] -m [n] -r -v
-e : empirically determine Exclusive Reservation Granule
(currently supports only ARM32)
-h : help
-i [n] : number of iterations (default : 1)
-m [n] : memory for tests, in mb (default : 512)
-r : run (causes test to run; present so no args gives help)
-v : version
Arguments
-e : Attempts to determine the Exclusive Reservation Granule. See Exclusive Reservation Granule (ARM, POWERPC) for details; this is only needed on ARM and POWERPC, and only currently supported for ARM32.
-h : Show help.
-i [n] : The test programme will loop n times. Any error (e.e. allocation failure) or test failure will cause the test programme to print and error and exit completely, rather than merely abort the current iteration.
-m [n] : There are a large number of tests. Mainly these tests run one thread per logical core, but there are a few API tests and a few single-threaded tests. Each test being run typically allocates a large number of data structure elements with which to perform the test. The value supplied to the -m argument is the amount of memory to be used for element allocation, in megabytes. The code does not properly or consistently check for memory exhaustion; a safe absolute minimum is 4mb, 64mb is a reasonable minimum for testing, and anything more than 1gb gives no advantage.
-r : If run with no arguments, the help text is displayed. As such, an argument is needed to inform the test programme that it is in fact to run tests, which is why the "-r" argument exists.
-v : Shows the build version, like so;
test 7.1.0 (release, user-mode) libshared 7.1.0 (release, Linux, user-mode) libtest 7.1.0 (release, Linux, user-mode) liblfds 7.1.0 (release, Linux, user-mode, x64, GCC >= 4.7.3)