From 204251a869f952c4e0c6ca80f499d5e4fdbe0807 Mon Sep 17 00:00:00 2001 From: Albert Cheng Date: Wed, 16 Oct 2013 16:18:20 -0500 Subject: [svn-r24305] Preceding committed version was a mistake. Comitting this in to restore it back to previus version. --- test/AtomicWriterReader.txt | 128 ++++++++++++++------------------------------ 1 file changed, 41 insertions(+), 87 deletions(-) diff --git a/test/AtomicWriterReader.txt b/test/AtomicWriterReader.txt index 2771af1..dc0a3bd 100644 --- a/test/AtomicWriterReader.txt +++ b/test/AtomicWriterReader.txt @@ -1,94 +1,48 @@ -POSIX Write Order Test Instructions -=================================== +Atomic Tests Instructions +========================= -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. +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. Building the Tests ------------------ -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. +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 Running the Tests ----------------- -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). - +$ atomic_writer -n -i +$ atomic_reader -n -i + +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. -- cgit v0.12