Improve comments and documentation of the asynchronous IO VFS module. (CVS 6543)
FossilOrigin-Name: 92bc6be2a86f8a68ceded2bc08fe7d6ff23b56fb
diff --git a/ext/async/sqlite3async.h b/ext/async/sqlite3async.h
index c057432..100dfff 100644
--- a/ext/async/sqlite3async.h
+++ b/ext/async/sqlite3async.h
@@ -5,32 +5,201 @@
#define SQLITEASYNC_VFSNAME "sqlite3async"
/*
-** Install the asynchronous IO VFS.
+** THREAD SAFETY NOTES:
+**
+** Of the four API functions in this file, the following are not threadsafe:
+**
+** sqlite3async_initialize()
+** sqlite3async_shutdown()
+**
+** Care must be taken that neither of these functions is called while
+** another thread may be calling either any sqlite3async_XXX() function
+** or an sqlite3_XXX() API function related to a database handle that
+** is using the asynchronous IO VFS.
+**
+** These functions:
+**
+** sqlite3async_run()
+** sqlite3async_control()
+**
+** are threadsafe. It is quite safe to call either of these functions even
+** if another thread may also be calling one of them or an sqlite3_XXX()
+** function related to a database handle that uses the asynchronous IO VFS.
+*/
+
+/*
+** Initialize the asynchronous IO VFS and register it with SQLite using
+** sqlite3_vfs_register(). If the asynchronous VFS is already initialized
+** and registered, this function is a no-op. The asynchronous IO VFS
+** is registered as "sqlite3async".
+**
+** The asynchronous IO VFS does not make operating system IO requests
+** directly. Instead, it uses an existing VFS implementation for all
+** required file-system operations. If the first parameter to this function
+** is NULL, then the current default VFS is used for IO. If it is not
+** NULL, then it must be the name of an existing VFS. In other words, the
+** first argument to this function is passed to sqlite3_vfs_find() to
+** locate the VFS to use for all real IO operations. This VFS is known
+** as the "parent VFS".
+**
+** If the second parameter to this function is non-zero, then the
+** asynchronous IO VFS is registered as the default VFS for all SQLite
+** database connections within the process. Otherwise, the asynchronous IO
+** VFS is only used by connections opened using sqlite3_open_v2() that
+** specifically request VFS "sqlite3async".
+**
+** If a parent VFS cannot be located, then SQLITE_ERROR is returned.
+** In the unlikely event that operating system specific initialization
+** fails (win32 systems create the required critical section and event
+** objects within this function), then SQLITE_ERROR is also returned.
+** Finally, if the call to sqlite3_vfs_register() returns an error, then
+** the error code is returned to the user by this function. In all three
+** of these cases, intialization has failed and the asynchronous IO VFS
+** is not registered with SQLite.
+**
+** Otherwise, if no error occurs, SQLITE_OK is returned.
*/
int sqlite3async_initialize(const char *zParent, int isDefault);
/*
-** Uninstall the asynchronous IO VFS.
+** This function unregisters the asynchronous IO VFS using
+** sqlite3_vfs_unregister().
+**
+** On win32 platforms, this function also releases the small number of
+** critical section and event objects created by sqlite3async_initialize().
*/
void sqlite3async_shutdown();
/*
-** Process events on the write-queue.
+** This function may only be called when the asynchronous IO VFS is
+** installed (after a call to sqlite3async_initialize()). It processes
+** zero or more queued write operations before returning. It is expected
+** (but not required) that this function will be called by a different
+** thread than those threads that use SQLite. The "background thread"
+** that performs IO.
+**
+** How many queued write operations are performed before returning
+** depends on the global setting configured by passing the SQLITEASYNC_HALT
+** verb to sqlite3async_control() (see below for details). By default
+** this function never returns - it processes all pending operations and
+** then blocks waiting for new ones.
+**
+** If multiple simultaneous calls are made to sqlite3async_run() from two
+** or more threads, then the calls are serialized internally.
*/
void sqlite3async_run();
/*
-** Control/configure the asynchronous IO system.
+** This function may only be called when the asynchronous IO VFS is
+** installed (after a call to sqlite3async_initialize()). It is used
+** to query or configure various parameters that affect the operation
+** of the asynchronous IO VFS. At present there are three parameters
+** supported:
+**
+** * The "halt" parameter, which configures the circumstances under
+** which the sqlite3async_run() parameter is configured.
+**
+** * The "delay" parameter. Setting the delay parameter to a non-zero
+** value causes the sqlite3async_run() function to sleep for the
+** configured number of milliseconds between each queued write
+** operation.
+**
+** * The "lockfiles" parameter. This parameter determines whether or
+** not the asynchronous IO VFS locks the database files it operates
+** on. Disabling file locking can improve throughput.
+**
+** This function is always passed two arguments. When setting the value
+** of a parameter, the first argument must be one of SQLITEASYNC_HALT,
+** SQLITEASYNC_DELAY or SQLITEASYNC_LOCKFILES. The second argument must
+** be passed the new value for the parameter as type "int".
+**
+** When querying the current value of a paramter, the first argument must
+** be one of SQLITEASYNC_GET_HALT, GET_DELAY or GET_LOCKFILES. The second
+** argument to this function must be of type (int *). The current value
+** of the queried parameter is copied to the memory pointed to by the
+** second argument. For example:
+**
+** int eCurrentHalt;
+** int eNewHalt = SQLITEASYNC_HALT_IDLE;
+**
+** sqlite3async_control(SQLITEASYNC_HALT, eNewHalt);
+** sqlite3async_control(SQLITEASYNC_GET_HALT, &eCurrentHalt);
+** assert( eNewHalt==eCurrentHalt );
+**
+** See below for more detail on each configuration parameter.
+**
+** SQLITEASYNC_HALT:
+**
+** This is used to set the value of the "halt" parameter. The second
+** argument must be one of the SQLITEASYNC_HALT_XXX symbols defined
+** below (either NEVER, IDLE and NOW).
+**
+** If the parameter is set to NEVER, then calls to sqlite3async_run()
+** never return. This is the default setting. If the parameter is set
+** to IDLE, then calls to sqlite3async_run() return as soon as the
+** queue of pending write operations is empty. If the parameter is set
+** to NOW, then calls to sqlite3async_run() return as quickly as
+** possible, without processing any pending write requests.
+**
+** If an attempt is made to set this parameter to an integer value other
+** than SQLITEASYNC_HALT_NEVER, IDLE or NOW, then sqlite3async_control()
+** returns SQLITE_MISUSE and the current value of the parameter is not
+** modified.
+**
+** Modifying the "halt" parameter affects calls to sqlite3async_run()
+** made by other threads that are currently in progress.
+**
+** SQLITEASYNC_DELAY:
+**
+** This is used to set the value of the "delay" parameter. If set to
+** a non-zero value, then after completing a pending write request, the
+** sqlite3async_run() function sleeps for the configured number of
+** milliseconds.
+**
+** If an attempt is made to set this parameter to a negative value,
+** sqlite3async_control() returns SQLITE_MISUSE and the current value
+** of the parameter is not modified.
+**
+** Modifying the "delay" parameter affects calls to sqlite3async_run()
+** made by other threads that are currently in progress.
+**
+** SQLITEASYNC_LOCKFILES:
+**
+** This is used to set the value of the "lockfiles" parameter. This
+** parameter must be set to either 0 or 1. If set to 1, then the
+** asynchronous IO VFS uses the xLock() and xUnlock() methods of the
+** parent VFS to lock database files being read and/or written. If
+** the parameter is set to 0, then these locks are omitted.
+**
+** This parameter may only be set when there are no open database
+** connections using the VFS and the queue of pending write requests
+** is empty. Attempting to set it when this is not true, or to set it
+** to a value other than 0 or 1 causes sqlite3async_control() to return
+** SQLITE_MISUSE and the value of the parameter to remain unchanged.
+**
+** If this parameter is set to zero, then it is only safe to access the
+** database via the asynchronous IO VFS from within a single process. If
+** while writing to the database via the asynchronous IO VFS the database
+** is also read or written from within another process, or via another
+** connection that does not use the asynchronous IO VFS within the same
+** process, the results are undefined (and may include crashes or database
+** corruption).
+**
+** Alternatively, if this parameter is set to 1, then it is safe to access
+** the database from multiple connections within multiple processes using
+** either the asynchronous IO VFS or the parent VFS directly.
*/
int sqlite3async_control(int op, ...);
/*
** Values that can be used as the first argument to sqlite3async_control().
*/
-#define SQLITEASYNC_HALT 1
-#define SQLITEASYNC_DELAY 2
-#define SQLITEASYNC_GET_HALT 3
-#define SQLITEASYNC_GET_DELAY 4
+#define SQLITEASYNC_HALT 1
+#define SQLITEASYNC_GET_HALT 2
+#define SQLITEASYNC_DELAY 3
+#define SQLITEASYNC_GET_DELAY 4
+#define SQLITEASYNC_LOCKFILES 5
+#define SQLITEASYNC_GET_LOCKFILES 6
/*
** If the first argument to sqlite3async_control() is SQLITEASYNC_HALT,