Usage Guide (test)
Introduction
The test programme 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 liblfds700/test/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 -h -i [n] -m [n] -r -v -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
-h : show help
-i [n] : the test programme will loop n times. The test programme runs clean under valgrind on 64-bit Linux. Any error (e.e. allocation failure) or test failure will cause the test programme to print and error and exit.
-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. Some other minor allocations also occur, so the argument is not exactly honoured. By and large, the more memory, the better, but there are one or two tests which are slowish and become slower the more data structure elements are present in the data structure.
-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.0.0 (Release) (Dec 5 2015 01:33:39) liblfds 7.0.0 (Release, Linux (user-mode), ARM (32-bit), GCC >= 4.7.3) (Dec 5 2015 01:32:48)
Output
On a full successful test run, the following output is generated (this is for a system with DWCAS, so all the tests run);
Test Iteration 01 ================= Abstraction Atomic Tests ======================== Atomic CAS...passed Atomic DCAS...passed Atomic exchange...passed Binary Tree (add-only, unbalanced) Tests ======================================== Alignment...passed Fail and overwrite on existing key...passed Random adds and walking (fail on existing key)...passed Random adds and walking (overwrite on existing key)...passed Freelist Tests ============== Alignment...passed Popping...passed Pushing...passed Pushing array...passed Popping and pushing (5 seconds)...passed Rapid popping and pushing (10 seconds)...passed Hash (add-only) Tests ===================== Fail and overwrite on existing key...passed Random adds and get (fail on existing key)...passed Random adds, get and iterate (overwrite on existing key)...passed Iterate...passed List (add-only, ordered, singly-linked) Tests ============================================= Alignment...passed New ordered...passed New ordered with cursor (5 seconds)...passed List (add-only, singly-linked, unordered) Tests =============================================== Alignment...passed New start...passed New end...passed New after...passed Queue Tests =========== Alignment...passed Enqueuing...passed Dequeuing...passed Enqueuing and dequeuing (5 seconds)...passed Rapid enqueuing and dequeuing (5 seconds)...passed Freeing...passed Queue (bounded, single consumer, single producer) Tests ======================================================= Enqueuing...passed Dequeuing...passed Enqueuing and dequeuing (8 seconds)...passed Ringbuffer Tests ================ Reading...passed Reading and writing (5 seconds)...passed Writing (5 seconds)...passed Stack Tests =========== Alignment...passed Popping...passed Pushing...passed Pushing array...passed Popping and pushing (5 seconds)...passed Rapid popping and pushing (5 seconds)...passed