Home | History | Annotate | Download | only in locks
      1 COMPILE : make
      2 RUN LOCAL: ./locktests -n <number of concurent process> -f <test file> [-T]
      3 
      4 
      5 GOAL : This test is aimed at stressing the fcntl locking functions.
      6 A master process sets a lock on a file region (byte range locking).
      7 Several slave processes try to perform operations on this region, such
      8 as: read, write, set a new lock ...
      9 The expected results of these operations are known.
     10 If the operation's result is the same as the expected one, the test
     11 succeeds, otherwise it fails.
     12 
     13 
     14 HISTORY : This program was been written to stress NFSv4 locks.
     15 
     16 Slaves are concurrent processes or threads.
     17 -n <num>  : Number of threads to use (mandatory).
     18 -f <file> : Run the test on a test file defined by the -f option (mandatory).
     19 -T        : Use threads instead of processes (optional).
     20 
     21 
     22 
     23 * RUN NETWORK *
     24 
     25 Test server:
     26 ./locktests -n <number of concurent processes> -f <test file> -c <number of clients>
     27 
     28 Test clients:
     29 ./locktests --server <server host name>
     30 
     31 
     32 Multiple clients options
     33 _______________________
     34 
     35 These options have been developed to test NFSv4 locking when multiple
     36 clients try to use the same file.  It uses a test server and several test
     37 clients.
     38 
     39 				--------------
     40 				|            |
     41 				| NFS SERVER |
     42 				|            |
     43 				--------------
     44 				      |
     45 				      |
     46 		-----------------------------------------------
     47 		|		      |			      |
     48 		|		      |			      |
     49 	------------------    -------------------     ------------------
     50 	|  NFS Client 1  |    |  NFS Client 1   |     |  NFS Client 1  |
     51 	|    running     |    |    running      |     |    running     |
     52 	| a CLIENT TEST  |    | the SERVER TEST |     | a CLIENT TEST  |
     53 	------------------    -------------------     ------------------
     54 
     55 See the DEPLOY file to know how to configure client test on each client.
     56 
     57 Server options are:
     58 
     59 -n <num>  : Number of threads to use (mandatory).
     60 -f <file> : Run the test on given test file defined by the -f option (mandatory).
     61 -c <num>  : Number of clients to connect before starting the tests.
     62 
     63 
     64 Client options
     65 ______________
     66 --server <server hostname>
     67 
     68 
     69 * EXAMPLES *
     70 ============
     71 
     72 Local testing:
     73 ./locktests -n 50 -f /file/system/to/test
     74 
     75 Multiple clients:
     76 -on the test server (called host1):
     77 	./locktest -n 50 -f /network/file/system/to/test -c 3
     78 	(Server waiting for 3 clients to be connected)
     79 
     80 -test clients:
     81 	./locktest --server host1
     82 
     83 
     84 HOW TO UNDERSTAND TEST RESULTS
     85 ==============================
     86 Ten tests are performed:
     87  1. WRITE ON A READ  LOCK
     88  2. WRITE ON A WRITE LOCK
     89  3. READ  ON A READ  LOCK
     90  4. READ  ON A WRITE LOCK
     91  5. SET A READ  LOCK ON A READ  LOCK
     92  6. SET A WRITE LOCK ON A WRITE LOCK
     93  7. SET A WRITE LOCK ON A READ  LOCK
     94  8. SET A READ  LOCK ON A WRITE LOCK
     95  9. READ LOCK THE WHOLE FILE BYTE BY BYTE
     96  10. WRITE LOCK THE WHOLE FILE BYTE BY BYTE
     97 
     98 
     99 For each test, the MASTER process takes a lock (READ/WRITE LOCK) and
    100 the SLAVE processes try to perform the following operations on the
    101 locked section:
    102 
    103  - WRITE
    104  - READ
    105  - SET A WRITE LOCK
    106  - SET A WRITE LOCK
    107 
    108 If a slave process performs its test operation without error it prints
    109 "=", otherwise it prints "x".
    110 
    111 An operation performed "without error" means:
    112 
    113  - The operation (write, read, fcntl ...) returns no error code, and
    114  - errno is not changed.
    115 
    116 However, "the slave performs its test operation without error" does NOT
    117 mean the "result is correct".  For example, a slave process is NOT
    118 allowed to set a READ LOCK on an already-set WRITE LOCK.  When such
    119 operations are performed, the correct and expected result is that the
    120 tested function returns the EAGAIN error code.
    121 
    122 When all tests have been processed, the result of each process for each
    123 test is compared with the table of expected results, and a new table is
    124 displayed:
    125 
    126 For example:
    127     200 processes of 200 successfully ran test : READ  ON A READ  LOCK
    128     200 processes of 200 successfully ran test : SET A READ  LOCK ON A WRITE LOCK
    129 
    130 This result lists the process/thread both on local and remote machines.
    131 
    132 Note that the testing locks with thread on multiple clients is disabled
    133 because it does not make sense: 2 different clients obviously run at
    134 least 2 different processes (thread information cannot be shared
    135 between this thread over the network).
    136 
    137 EXPECTED RESULTS
    138 ================
    139 Here is the table of expected results, depending on :
    140  - Slave test operations (READ, WRITE, SET A WRITE LOCK ... )
    141  - Master Operation (SET A READ/A WRITE LOCK )
    142  - Slave types (Processes, threads)
    143  - Locking profile (POSIX locking, Mandatory locking)
    144 
    145 
    146 ================================================================================================
    147                                    |                     Master  process/thread                |
    148 ===================================|===========================================================|
    149 Slave type  |   Test operation     |  advisory         locking    |   mandatory      locking   |
    150 ___________________________________|______________________________|____________________________|
    151             |                      |  read lock       write lock  |   read lock     write lock |
    152 ___________________________________|______________________________|____________________________|
    153 thread      |   set a read lock    |   Allowed         Allowed    |    Allowed       Allowed   |
    154             |   set a write lock   |   Allowed         Allowed    |    Allowed       Allowed   |
    155             |   read               |   Allowed         Allowed    |    Allowed       Allowed   |
    156             |   write              |   Allowed         Allowed    |    Allowed       Allowed   |
    157 ===================================+==============================+============================|
    158 process     |   set a read lock    |   Allowed         Denied     |    Allowed       Denied    |
    159             |   set a write lock   |   Denied          Denied     |    Denied        Denied    |
    160             |   read               |   Allowed         Allowed    |    Denied        Allowed   |
    161             |   write              |   Allowed         Allowed    |    Denied        Denied    |
    162 ================================================================================================
    163 
    164 
    165 **************
    166 Bull SA - 2006 - http://nfsv4.bullopensource.org
    167 Tony Reix: tony.reix (a] bull.net
    168 Aurlien Charbon: aurelien.charbon@ext bull.net
    169 **************
    170