Add comments describing upcoming changes to crash-test module (test6.c). No code

changes. (CVS 4223)

FossilOrigin-Name: 63631c17376bcb5a7aa305408aaeaf03738d7b95

manifest

@@ -1,5 +1,5 @@
-C Add\sa\sfirst\scut\sat\sthe\snew\sversion\s3.5\sinterface\sdefinitions\sto\ssqlite.h.in.\s(CVS\s4219)
+C Add\scomments\sdescribing\supcoming\schanges\sto\scrash-test\smodule\s(test6.c).\sNo\scode\nchanges.\s(CVS\s4223)
-D 2007-08-14T01:58:53
+D 2007-08-14T17:42:06
 F Makefile.in 0c0e53720f658c7a551046442dd7afba0b72bfbe
 F Makefile.linux-gcc 65241babba6faf1152bf86574477baab19190499
 F README 9c4e2d6706bdcc3efdd773ce752a8cdab4f90028
@@ -120,7 +120,7 @@ F src/test2.c 24458b17ab2f3c90cbc1c8446bd7ffe69be62f88
 F src/test3.c a280931fb40222b7c90da45eea926459beee8904
 F src/test4.c 8b784cd82de158a2317cb4ac4bc86f91ad315e25
 F src/test5.c c40a4cf43266c1c6da7bcb737d294304a177e6cc
-F src/test6.c 5957d249d437e4db74045ce2f1f661648d94bf94
+F src/test6.c 2c4ed21787944bd8896cba80d4a544d8bed5473e
 F src/test7.c 03fa8d787f6aebc6d1f72504d52f33013ad2c8e3
 F src/test8.c 27a61c60f736066646a9e9ca21acdfdf0f3ea11e
 F src/test9.c c0f38f7795cc51d37db6c63874d90f40f10d0f0e
@@ -525,7 +525,7 @@ F www/tclsqlite.tcl 8be95ee6dba05eabcd27a9d91331c803f2ce2130
 F www/vdbe.tcl 87a31ace769f20d3627a64fa1fade7fed47b90d0
 F www/version3.tcl 890248cf7b70e60c383b0e84d77d5132b3ead42b
 F www/whentouse.tcl fc46eae081251c3c181bd79c5faef8195d7991a5
-P 64989904d44556eee0ea0270f8d4f0e903ffcfdf
+P 0a57f3dd4de12278732e3ca9d8a95f85c351da03
-R 310d3532a0d40fc315057804e8516252
+R 16d3a3345c4f7cdf1b006e163dd58115
-U drh
+U danielk1977
-Z 1ad81155802eaf199fd615d9a659a7aa
+Z e9b871793bc7c661bca1a2a8cf8f790f

manifest.uuid

@@ -1 +1 @@
-0a57f3dd4de12278732e3ca9d8a95f85c351da03
+63631c17376bcb5a7aa305408aaeaf03738d7b95

src/test6.c

@@ -21,11 +21,99 @@
 
 #ifndef SQLITE_OMIT_DISKIO  /* This file is a no-op if disk I/O is disabled */
 
-/*
-** crashFile is a subclass of OsFile that is taylored for the
-** crash test module.
-*/
 typedef struct crashFile crashFile;
+typedef struct WriteBuffer WriteBuffer;
+
+/*
+** Method:
+**
+**   This layer is implemented as a wrapper around the "real" 
+**   sqlite3_file object for the host system. Each time data is 
+**   written to the file object, instead of being written to the
+**   underlying file, the write operation is stored in an in-memory 
+**   structure (type WriteBuffer). This structure is placed at the
+**   end of a global ordered list (the write-list).
+**
+**   When data is read from a file object, the requested region is
+**   first retrieved from the real file. The write-list is then 
+**   traversed and data copied from any overlapping WriteBuffer 
+**   structures to the output buffer. i.e. a read() operation following
+**   one or more write() operations works as expected, even if no
+**   data has actually been written out to the real file.
+**
+**   When a fsync() operation is performed, an operating system crash 
+**   may be simulated, in which case exit(-1) is called (the call to 
+**   xSync() never returns). Whether or not a crash is simulated,
+**   the data associated with a subset of the WriteBuffer structures 
+**   stored in the write-list is written to the real underlying files 
+**   and the entries removed from the write-list. If a crash is simulated,
+**   a subset of the buffers may be corrupted before the data is written.
+**
+**   The exact subset of the write-list written and/or corrupted is
+**   determined by the simulated device characteristics and sector-size.
+**
+** "Normal" mode:
+**
+**   Normal mode is used when the simulated device has none of the
+**   SQLITE_IOCAP_XXX flags set.
+**
+**   In normal mode, if the fsync() is not a simulated crash, the 
+**   write-list is traversed from beginning to end. Each WriteBuffer
+**   structure associated with the file handle used to call xSync()
+**   is written to the real file and removed from the write-list.
+**
+**   If a crash is simulated, one of the following takes place for 
+**   each WriteBuffer in the write-list, regardless of which 
+**   file-handle it is associated with:
+**
+**     1. The buffer is correctly written to the file, just as if
+**        a crash were not being simulated.
+**
+**     2. Nothing is done.
+**
+**     3. Garbage data is written to all sectors of the file that 
+**        overlap the region specified by the WriteBuffer. Or garbage
+**        data is written to some contiguous section within the 
+**        overlapped sectors.
+**
+** Device Characteristic flag handling:
+**
+**   If the IOCAP_ATOMIC flag is set, then option (3) above is 
+**   never selected.
+**
+**   If the IOCAP_ATOMIC512 flag is set, and the WriteBuffer represents
+**   an aligned write() of an integer number of 512 byte regions, then
+**   option (3) above is never selected. Instead, each 512 byte region
+**   is either correctly written or left completely untouched. Similar
+**   logic governs the behaviour if any of the other ATOMICXXX flags
+**   is set.
+**
+**   If either the IOCAP_SAFEAPPEND or IOCAP_SEQUENTIAL flags are set
+**   and a crash is being simulated, then an entry of the write-list is
+**   selected at random. Everything in the list after the selected entry 
+**   is discarded before processing begins.
+**
+**   If IOCAP_SEQUENTIAL is set and a crash is being simulated, option 
+**   (1) is selected for all write-list entries except the last. If a 
+**   crash is not being simulated, then all entries in the write-list
+**   that occur before at least one write() on the file-handle specified
+**   as part of the xSync() are written to their associated real files.
+**
+**   If IOCAP_SAFEAPPEND is set and the first byte written by the write()
+**   operation is one byte past the current end of the file, then option
+**   (1) is always selected.
+*/
+struct WriteBuffer {
+  i64 iOffset;             /* Byte offset of the start of this write() */
+  int nBuf;                /* Number of bytes written */
+  u8 *zBuf;                /* Pointer to copy of written data */
+  crashFile *pFile;        /* File this write() applies to */
+};
+
+/*
+** crashFile is a subclass of OsFile that is taylored for 
+** the crash test module.
+*/
 struct crashFile {
   IoMethod const *pMethod; /* Must be first */
   u8 **apBlk;              /* Array of blocks that have been written to. */