Add some extra comments to the header in test_async.c. (CVS 4407)

FossilOrigin-Name: 79cf4e886cd5f1cd22574ce13135d4e32c1047b6

manifest

@@ -1,5 +1,5 @@
-C Fix\stemp\sfile\shandling\sfor\sOS/2\sso\sthat\strailing\sslashes\sor\sbackslashes\nare\sstripped\soff\sthe\spath\sgotten\sfrom\sthe\senvironment.\sOtherwise\sfull\npaths\smight\scontain\smultiple\sslashes\swhich\scauses\sopening\sof\sfiles\sto\nfail.\s(CVS\s4406)
+C Add\ssome\sextra\scomments\sto\sthe\sheader\sin\stest_async.c.\s(CVS\s4407)
-D 2007-09-05T22:28:23
+D 2007-09-06T07:47:18
 F Makefile.in cbfb898945536a8f9ea8b897e1586dd1fdbcc5db
 F Makefile.linux-gcc 65241babba6faf1152bf86574477baab19190499
 F README 9c4e2d6706bdcc3efdd773ce752a8cdab4f90028
@@ -145,7 +145,7 @@ F src/test6.c 0513982dfef4da2a4154b538d2bf538b84ca21d3
 F src/test7.c a9d509d0e9ad214b4772696f49f6e61be26213d1
 F src/test8.c f113aa3723a52113d0fa7c28155ecd37e7e04077
 F src/test9.c b46c8fe02ac7cca1a7316436d8d38d50c66f4b2f
-F src/test_async.c 9bf363454cc1d5e0695c2ae51dd626f1f115fbe3
+F src/test_async.c c913005fbe672679c465b8027524e44d0805b52d
 F src/test_autoext.c 855157d97aa28cf84233847548bfacda21807436
 F src/test_btree.c c1308ba0b88ab577fa56c9e493a09829dfcded9c
 F src/test_config.c 6fb459214b27952b143f45e35200d94096d54cc6
@@ -570,7 +570,7 @@ F www/tclsqlite.tcl 8be95ee6dba05eabcd27a9d91331c803f2ce2130
 F www/vdbe.tcl 87a31ace769f20d3627a64fa1fade7fed47b90d0
 F www/version3.tcl 890248cf7b70e60c383b0e84d77d5132b3ead42b
 F www/whentouse.tcl fc46eae081251c3c181bd79c5faef8195d7991a5
-P ea1d76e3fae599f7197f32852f1722b61ae3f8a7
+P 96aa96ac11ab63b51e4322e88ded4f931e1e78c8
-R 5b31a1ca01a73935ad745691ba7d9c55
+R 822408f19109fa4e09fe9b9979527829
-U pweilbacher
+U danielk1977
-Z 42de2c8d32b51dcecffe0766dc9b21eb
+Z 68602741cdf9332e0c40304397107c48

manifest.uuid

@@ -1 +1 @@
-96aa96ac11ab63b51e4322e88ded4f931e1e78c8
+79cf4e886cd5f1cd22574ce13135d4e32c1047b6

src/test_async.c

@@ -42,6 +42,11 @@
 ** written directly to disk, but is placed in the "write-queue" to be
 ** handled by the background thread.
 **
+** When files opened with the asynchronous vfs are read from 
+** (using sqlite3OsRead()), the data is read from the file on 
+** disk and the write-queue, so that from the point of view of
+** the vfs reader the OsWrite() appears to have already completed.
+**
 ** The special vfs is registered (and unregistered) by calls to 
 ** function asyncEnable() (see below).
 **
@@ -56,15 +61,48 @@
 ** run out of memory.  Users of this technique may want to keep track of
 ** the quantity of pending writes and stop accepting new write requests
 ** when the buffer gets to be too big.
-*/
+**
-
+** LOCKING + CONCURRENCY
-/* 
+**
-** If this symbol is defined, then file-system locks are obtained as
+** Multiple connections from within a single process that use this
-** required. This slows things down, but allows multiple processes
+** implementation of asynchronous IO may access a single database
-** to access the database concurrently. If this symbol is not defined,
+** file concurrently. From the point of view of the user, if all
-** then connections from within a single process will respect each
+** connections are from within a single process, there is no difference
-** others database locks, but external connections will not - leading
+** between the concurrency offered by "normal" SQLite and SQLite
-** to database corruption.
+** using the asynchronous backend.
+**
+** If connections from within multiple database files may access the
+** database file, the ENABLE_FILE_LOCKING symbol (see below) must be
+** defined. If it is not defined, then no locks are established on 
+** the database file. In this case, if multiple processes access 
+** the database file, corruption will quickly result.
+**
+** If ENABLE_FILE_LOCKING is defined (the default), then connections 
+** from within multiple processes may access a single database file 
+** without risking corruption. However concurrency is reduced as
+** follows:
+**
+**   * When a connection using asynchronous IO begins a database
+**     transaction, the database is locked immediately. However the
+**     lock is not released until after all relevant operations
+**     in the write-queue have been flushed to disk. This means
+**     (for example) that the database may remain locked for some 
+**     time after a "COMMIT" or "ROLLBACK" is issued.
+**
+**   * If an application using asynchronous IO executes transactions
+**     in quick succession, other database users may be effectively
+**     locked out of the database. This is because when a BEGIN
+**     is executed, a database lock is established immediately. But
+**     when the corresponding COMMIT or ROLLBACK occurs, the lock
+**     is not released until the relevant part of the write-queue 
+**     has been flushed through. As a result, if a COMMIT is followed
+**     by a BEGIN before the write-queue is flushed through, the database 
+**     is never unlocked,preventing other processes from accessing 
+**     the database.
+**
+** Defining ENABLE_FILE_LOCKING when using an NFS or other remote 
+** file-system may slow things down, as synchronous round-trips to the 
+** server may be required to establish database file locks.
 */
 #define ENABLE_FILE_LOCKING
 
@@ -77,7 +115,6 @@
 */
 #if OS_UNIX && SQLITE_THREADSAFE
 
-
 /*
 ** This demo uses pthreads.  If you do not have a pthreads implementation
 ** for your operating system, you will need to recode the threading 
@@ -128,12 +165,24 @@ static void asyncTrace(const char *zFormat, ...){
 **     * See the last two paragraphs under "The Writer Thread" for
 **       an assumption to do with file-handle synchronization by the Os.
 **
+** Deadlock prevention:
+**
+**     There are three mutex used by the system: the "writer" mutex, 
+**     the "queue" mutex and the "lock" mutex. Rules are:
+**
+**     * It is illegal to block on the writer mutex when any other mutex
+**       are held, and 
+**
+**     * It is illegal to block on the queue mutex when the lock mutex
+**       is held.
+**
+**     i.e. mutex's must be grabbed in the order "writer", "queue", "lock".
+**
 ** File system operations (invoked by SQLite thread):
 **
-**     xOpenXXX (three versions)
+**     xOpen
 **     xDelete
 **     xFileExists
-**     xSyncDirectory
 **
 ** File handle operations (invoked by SQLite thread):
 **