Annotation of embedaddon/sqlite3/ext/async/README.txt, revision 1.1
1.1 ! misho 1:
! 2: Normally, when SQLite writes to a database file, it waits until the write
! 3: operation is finished before returning control to the calling application.
! 4: Since writing to the file-system is usually very slow compared with CPU
! 5: bound operations, this can be a performance bottleneck. This directory
! 6: contains an extension that causes SQLite to perform all write requests
! 7: using a separate thread running in the background. Although this does not
! 8: reduce the overall system resources (CPU, disk bandwidth etc.) at all, it
! 9: allows SQLite to return control to the caller quickly even when writing to
! 10: the database, eliminating the bottleneck.
! 11:
! 12: 1. Functionality
! 13:
! 14: 1.1 How it Works
! 15: 1.2 Limitations
! 16: 1.3 Locking and Concurrency
! 17:
! 18: 2. Compilation and Usage
! 19:
! 20: 3. Porting
! 21:
! 22:
! 23:
! 24: 1. FUNCTIONALITY
! 25:
! 26: With asynchronous I/O, write requests are handled by a separate thread
! 27: running in the background. This means that the thread that initiates
! 28: a database write does not have to wait for (sometimes slow) disk I/O
! 29: to occur. The write seems to happen very quickly, though in reality
! 30: it is happening at its usual slow pace in the background.
! 31:
! 32: Asynchronous I/O appears to give better responsiveness, but at a price.
! 33: You lose the Durable property. With the default I/O backend of SQLite,
! 34: once a write completes, you know that the information you wrote is
! 35: safely on disk. With the asynchronous I/O, this is not the case. If
! 36: your program crashes or if a power loss occurs after the database
! 37: write but before the asynchronous write thread has completed, then the
! 38: database change might never make it to disk and the next user of the
! 39: database might not see your change.
! 40:
! 41: You lose Durability with asynchronous I/O, but you still retain the
! 42: other parts of ACID: Atomic, Consistent, and Isolated. Many
! 43: appliations get along fine without the Durablity.
! 44:
! 45: 1.1 How it Works
! 46:
! 47: Asynchronous I/O works by creating a special SQLite "vfs" structure
! 48: and registering it with sqlite3_vfs_register(). When files opened via
! 49: this vfs are written to (using the vfs xWrite() method), the data is not
! 50: written directly to disk, but is placed in the "write-queue" to be
! 51: handled by the background thread.
! 52:
! 53: When files opened with the asynchronous vfs are read from
! 54: (using the vfs xRead() method), the data is read from the file on
! 55: disk and the write-queue, so that from the point of view of
! 56: the vfs reader the xWrite() appears to have already completed.
! 57:
! 58: The special vfs is registered (and unregistered) by calls to the
! 59: API functions sqlite3async_initialize() and sqlite3async_shutdown().
! 60: See section "Compilation and Usage" below for details.
! 61:
! 62: 1.2 Limitations
! 63:
! 64: In order to gain experience with the main ideas surrounding asynchronous
! 65: IO, this implementation is deliberately kept simple. Additional
! 66: capabilities may be added in the future.
! 67:
! 68: For example, as currently implemented, if writes are happening at a
! 69: steady stream that exceeds the I/O capability of the background writer
! 70: thread, the queue of pending write operations will grow without bound.
! 71: If this goes on for long enough, the host system could run out of memory.
! 72: A more sophisticated module could to keep track of the quantity of
! 73: pending writes and stop accepting new write requests when the queue of
! 74: pending writes grows too large.
! 75:
! 76: 1.3 Locking and Concurrency
! 77:
! 78: Multiple connections from within a single process that use this
! 79: implementation of asynchronous IO may access a single database
! 80: file concurrently. From the point of view of the user, if all
! 81: connections are from within a single process, there is no difference
! 82: between the concurrency offered by "normal" SQLite and SQLite
! 83: using the asynchronous backend.
! 84:
! 85: If file-locking is enabled (it is enabled by default), then connections
! 86: from multiple processes may also read and write the database file.
! 87: However concurrency is reduced as follows:
! 88:
! 89: * When a connection using asynchronous IO begins a database
! 90: transaction, the database is locked immediately. However the
! 91: lock is not released until after all relevant operations
! 92: in the write-queue have been flushed to disk. This means
! 93: (for example) that the database may remain locked for some
! 94: time after a "COMMIT" or "ROLLBACK" is issued.
! 95:
! 96: * If an application using asynchronous IO executes transactions
! 97: in quick succession, other database users may be effectively
! 98: locked out of the database. This is because when a BEGIN
! 99: is executed, a database lock is established immediately. But
! 100: when the corresponding COMMIT or ROLLBACK occurs, the lock
! 101: is not released until the relevant part of the write-queue
! 102: has been flushed through. As a result, if a COMMIT is followed
! 103: by a BEGIN before the write-queue is flushed through, the database
! 104: is never unlocked,preventing other processes from accessing
! 105: the database.
! 106:
! 107: File-locking may be disabled at runtime using the sqlite3async_control()
! 108: API (see below). This may improve performance when an NFS or other
! 109: network file-system, as the synchronous round-trips to the server be
! 110: required to establish file locks are avoided. However, if multiple
! 111: connections attempt to access the same database file when file-locking
! 112: is disabled, application crashes and database corruption is a likely
! 113: outcome.
! 114:
! 115:
! 116: 2. COMPILATION AND USAGE
! 117:
! 118: The asynchronous IO extension consists of a single file of C code
! 119: (sqlite3async.c), and a header file (sqlite3async.h) that defines the
! 120: C API used by applications to activate and control the modules
! 121: functionality.
! 122:
! 123: To use the asynchronous IO extension, compile sqlite3async.c as
! 124: part of the application that uses SQLite. Then use the API defined
! 125: in sqlite3async.h to initialize and configure the module.
! 126:
! 127: The asynchronous IO VFS API is described in detail in comments in
! 128: sqlite3async.h. Using the API usually consists of the following steps:
! 129:
! 130: 1. Register the asynchronous IO VFS with SQLite by calling the
! 131: sqlite3async_initialize() function.
! 132:
! 133: 2. Create a background thread to perform write operations and call
! 134: sqlite3async_run().
! 135:
! 136: 3. Use the normal SQLite API to read and write to databases via
! 137: the asynchronous IO VFS.
! 138:
! 139: Refer to sqlite3async.h for details.
! 140:
! 141:
! 142: 3. PORTING
! 143:
! 144: Currently the asynchronous IO extension is compatible with win32 systems
! 145: and systems that support the pthreads interface, including Mac OSX, Linux,
! 146: and other varieties of Unix.
! 147:
! 148: To port the asynchronous IO extension to another platform, the user must
! 149: implement mutex and condition variable primitives for the new platform.
! 150: Currently there is no externally available interface to allow this, but
! 151: modifying the code within sqlite3async.c to include the new platforms
! 152: concurrency primitives is relatively easy. Search within sqlite3async.c
! 153: for the comment string "PORTING FUNCTIONS" for details. Then implement
! 154: new versions of each of the following:
! 155:
! 156: static void async_mutex_enter(int eMutex);
! 157: static void async_mutex_leave(int eMutex);
! 158: static void async_cond_wait(int eCond, int eMutex);
! 159: static void async_cond_signal(int eCond);
! 160: static void async_sched_yield(void);
! 161:
! 162: The functionality required of each of the above functions is described
! 163: in comments in sqlite3async.c.
! 164:
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to README.txt CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / sqlite3 / ext / async