[svn-r24304] Removed the iteration (-i) option since it does not make sense to for

the writer process to rewrite the data file while the reader process
may still be reading linked blocks of the previous iteration.

Tested: jam

2 files changed, 91 insertions, 56 deletions

diff --git a/test/AtomicWriterReader.txt b/test/AtomicWriterReader.txt
index dc0a3bd..2771af1 100644
--- a/test/AtomicWriterReader.txt
+++ b/test/AtomicWriterReader.txt
@@ -1,48 +1,94 @@
-Atomic Tests Instructions
-=========================
+POSIX Write Order Test Instructions
+===================================
 
-Purpose:
---------
-This documents how to build and run the Atomic Writer and Reader tests.
-The atomic test is to verify if atomic read-write operation on a system works.
-The two programs are atomic_writer.c and atomic_reader.c.
-atomic_writer.c: is the "write" part of the test; and
-atomic_reader.c: is the "read" part of the test.
+Purpose
+-------
+This documents shows the requirments, implementaion design and instructions
+of building and running the POSIX Write Order test.  The name of the
+test is twriteorder and it resides in the test/ directory.
+
+Requirements
+------------
+The test is to verify that the write order is strictly consistent.
+The SWMR feature requires that the order of write is strictly consistent.
+"Strict consistency in computer science is the most stringent consistency
+model.  It says that a read operation has to return the result of the
+latest write operation which occurred on that data item."--
+(http://en.wikipedia.org/wiki/Linearizability#Definition_of_linearizability).
+This is also an alternative form of what POSIX write require that after a
+write operation has returned success, all reads issued afterward should
+get the same data the write has written.
+
+Implementation Design
+---------------------
+The test simulates what SWMR does by writing chained blocks and see if
+they can be read back correctly.
+There is a writer process and a read process.
+The file is divided into 2KB partitions. Then writer writes 1 chained
+block, each of 1KB big, in each partition after the first partition.
+Each chained block has this structure:
+Byte 0-3: offset address of its child block. The last child uses 0 as NULL.
+Byte 4-1023: some artificial data.
+The child block address of Block 1 is NULL (0).
+The child block address of Block 2 is the offset address of Block 1.
+The child block address of Block n is the offset address of Block n-1.
+After all n blocks are written, the offset address of Block n is written
+to the offset 0 of the first partition.
+Therefore, by the time the offset address of Block n is written to this
+position, all n chain-linked blocks have been written.
+
+The other reader processes will try to read the address value at the
+offset 0. The value is initially NULL(0). When it changes to non-zero,
+it signifies the writer process has written all the chain-link blocks
+and they are ready for the reader processes to access.
+
+If the system, in which the writer and reader processes run, the readers
+will always get all chain-linked blocks correctly. If the order of write
+is not maintained, some reader processes may found unexpect block data.
 
 Building the Tests
 ------------------
-The two test parts are automically built during configure and make process.
-But to build them individually, you can do in test/ directory:
-$ gcc atomic_writer
-$ gcc atomic_reader
+The name of the test is twriteorder in the test directory. It is added
+to the test suite and is built during the "make" process and is run by
+the test_usecases.sh test. Users may inspect test/test_usecases.sh.in
+to see the examples of testing.
 
 Running the Tests
 -----------------
-$ atomic_writer -n <number of integers to write> -i <number of iterations for writer>
-$ atomic_reader -n <number of integers to read> -i <number of iterations for reader>
-
-Note**
-(1) "atomic_data" is the data file used by both the writer/reader in the
-    current directory.
-(2) The value for -n should be the same for both the writer and the reader.
-(3) The values for options n and i should be positive integers.
-(4) For this version, the user has to provide both options -n and -i to run
-    the writer and the reader.
-(5) If the user wants to run the writer for a long time, just provides a
-    large number for -i.
-
-Examples
---------
-$ ./atomic_writer -n 10000 -i 5
-  Try to atomic write 10000 integers patterns 10000 time, and iterate the whole
-  write process 5 times.
-
-$ ./atomic_reader -n 10000 -i 2
-  Try to atomic read 10000 integers patterns 10000 times, and iterate only once.
-  A summary is posted at the end. If all atomic reads are correct, it will not
-  show any read beyond "0 re-tries", that is all reads have succeeded in the
-  first read attempt.
-
-Remark:
-You usually want the writer to iterate more times than the reader so that
-the writing will not finish before reading is done.
+twriteorder test accepts the following options:
+$ ./twriteorder -h
+usage: twriteorder [OPTIONS]
+  OPTIONS
+     -h            Print a usage message and exit
+     -l w|r        launch writer or reader only. [default: launch both]
+     -b N          Block size [default: 1024]
+     -p N          Partition size [default: 2048]
+     -n N          Number of linked blocks [default: 512]
+
+More Examples
+-------------
+
+# run test with default parameters and launch both writer and reader
+#processes.
+$ twriteorder
+
+# run test with blocksize of 1000 bytes (default is 1024 bytes).
+$ twriteorder -b 1000
+
+# run test with partition size of 3000 bytes (default is 2048 bytes).
+$ twriteorder -p 3000
+
+# run test with 2000 linked blocks (default is 512 blocks).
+$ twriteorder -n 2000
+
+# Launch only the writer process.
+$ twriteorder -l w
+
+# Launch only the reader process.
+$ twriteorder -l r
+
+Note that if you want to launch the writer and the reader processes
+manually (for example in different machines sharing a common file system),
+you need to start the writer process (-l w) first, and then the reader
+process (-l r).
+
diff --git a/test/twriteorder.c b/test/twriteorder.c
index 50c762c..e43d58f 100644
--- a/test/twriteorder.c
+++ b/test/twriteorder.c
@@ -68,7 +68,6 @@
 #define BLOCKSIZE_DFT   1024	/* 1KB */
 #define PARTITION_DFT	2048	/* 2KB */
 #define NLINKEDBLOCKS_DFT 512	/* default 512 */
-#define ITERATIONS_DFT	1	/* default 1 */
 #define SIZE_BLKADDR	4	/* expected sizeof blkaddr */
 #define Hgoto_error(val)	{ret_value=val; goto done;}
 
@@ -90,7 +89,7 @@ int parse_option(int argc, char * const argv[]);
 /* Global Variable definitions */
 const char *progname_g="twriteorder";	/* program name */
 int	write_fd_g;
-int	blocksize_g, part_size_g, nlinkedblock_g, iterations_g;
+int	blocksize_g, part_size_g, nlinkedblock_g;
 part_t  launch_g;
 
 /* Function definitions */
@@ -106,7 +105,7 @@ usage(const char *prog)
     fprintf(stderr, "     -b N          Block size [default: %d]\n", BLOCKSIZE_DFT);
     fprintf(stderr, "     -p N          Partition size [default: %d]\n", PARTITION_DFT);
     fprintf(stderr, "     -n N          Number of linked blocks [default: %d]\n", NLINKEDBLOCKS_DFT);
-    fprintf(stderr, "     -i N          Number of iterations to repeat the whole thing. [default: %d] (not yet implemented.\n", ITERATIONS_DFT);
+    fprintf(stderr, "     where N is an integer value\n");
     fprintf(stderr, "\n");
 }
 
@@ -118,14 +117,13 @@ parse_option(int argc, char * const argv[])
     int ret_value=0;
     int c;
     /* command line options: See function usage for a description */
-    /* const char *nagg_options = "f:hi:l:n:s:y:z:"; */
-    const char *nagg_options = "hb:i:l:n:p:";
+    const char *cmd_options = "hb:l:n:p:";
 
     /* suppress getopt from printing error */
     opterr = 0;
 
     while (1){
-	c = getopt (argc, argv, nagg_options);
+	c = getopt (argc, argv, cmd_options);
 	if (-1 == c)
 	    break;
 	switch (c) {
@@ -154,13 +152,6 @@ parse_option(int argc, char * const argv[])
 		Hgoto_error(-1);
 	    };
 	    break;
-	  case 'i':	/* iterations */
-	    if ((iterations_g = atoi(optarg)) <= 0){
-		fprintf(stderr, "bad iterations number %s, must be a positive integer\n", optarg);
-		usage(progname_g);
-		Hgoto_error(-1);
-	    };
-	    break;
 	  case 'l':	/* launch reader or writer only */
 	    switch (*optarg) {
 	      case 'r':	/* reader only */
@@ -209,7 +200,6 @@ int setup_parameters(int argc, char * const argv[])
     blocksize_g = BLOCKSIZE_DFT;
     part_size_g = PARTITION_DFT;
     nlinkedblock_g = NLINKEDBLOCKS_DFT;
-    iterations_g = ITERATIONS_DFT;
     launch_g = UC_READWRITE;
 
     /* parse options */
@@ -221,7 +211,6 @@ int setup_parameters(int argc, char * const argv[])
     printf("blocksize = %ld\n", (long)blocksize_g);
     printf("part_size = %ld\n", (long)part_size_g);
     printf("nlinkedblock = %ld\n", (long)nlinkedblock_g);
-    printf("iterations = %ld\n", (long)iterations_g);
     printf("launch = %d\n", launch_g);
     return(0);
 }