| OLD | NEW |
|---|
| (Empty) |
| 1 | |
| 2 #ifndef __SQLITEASYNC_H_ | |
| 3 #define __SQLITEASYNC_H_ 1 | |
| 4 | |
| 5 /* | |
| 6 ** Make sure we can call this stuff from C++. | |
| 7 */ | |
| 8 #ifdef __cplusplus | |
| 9 extern "C" { | |
| 10 #endif | |
| 11 | |
| 12 #define SQLITEASYNC_VFSNAME "sqlite3async" | |
| 13 | |
| 14 /* | |
| 15 ** THREAD SAFETY NOTES: | |
| 16 ** | |
| 17 ** Of the four API functions in this file, the following are not threadsafe: | |
| 18 ** | |
| 19 ** sqlite3async_initialize() | |
| 20 ** sqlite3async_shutdown() | |
| 21 ** | |
| 22 ** Care must be taken that neither of these functions is called while | |
| 23 ** another thread may be calling either any sqlite3async_XXX() function | |
| 24 ** or an sqlite3_XXX() API function related to a database handle that | |
| 25 ** is using the asynchronous IO VFS. | |
| 26 ** | |
| 27 ** These functions: | |
| 28 ** | |
| 29 ** sqlite3async_run() | |
| 30 ** sqlite3async_control() | |
| 31 ** | |
| 32 ** are threadsafe. It is quite safe to call either of these functions even | |
| 33 ** if another thread may also be calling one of them or an sqlite3_XXX() | |
| 34 ** function related to a database handle that uses the asynchronous IO VFS. | |
| 35 */ | |
| 36 | |
| 37 /* | |
| 38 ** Initialize the asynchronous IO VFS and register it with SQLite using | |
| 39 ** sqlite3_vfs_register(). If the asynchronous VFS is already initialized | |
| 40 ** and registered, this function is a no-op. The asynchronous IO VFS | |
| 41 ** is registered as "sqlite3async". | |
| 42 ** | |
| 43 ** The asynchronous IO VFS does not make operating system IO requests | |
| 44 ** directly. Instead, it uses an existing VFS implementation for all | |
| 45 ** required file-system operations. If the first parameter to this function | |
| 46 ** is NULL, then the current default VFS is used for IO. If it is not | |
| 47 ** NULL, then it must be the name of an existing VFS. In other words, the | |
| 48 ** first argument to this function is passed to sqlite3_vfs_find() to | |
| 49 ** locate the VFS to use for all real IO operations. This VFS is known | |
| 50 ** as the "parent VFS". | |
| 51 ** | |
| 52 ** If the second parameter to this function is non-zero, then the | |
| 53 ** asynchronous IO VFS is registered as the default VFS for all SQLite | |
| 54 ** database connections within the process. Otherwise, the asynchronous IO | |
| 55 ** VFS is only used by connections opened using sqlite3_open_v2() that | |
| 56 ** specifically request VFS "sqlite3async". | |
| 57 ** | |
| 58 ** If a parent VFS cannot be located, then SQLITE_ERROR is returned. | |
| 59 ** In the unlikely event that operating system specific initialization | |
| 60 ** fails (win32 systems create the required critical section and event | |
| 61 ** objects within this function), then SQLITE_ERROR is also returned. | |
| 62 ** Finally, if the call to sqlite3_vfs_register() returns an error, then | |
| 63 ** the error code is returned to the user by this function. In all three | |
| 64 ** of these cases, intialization has failed and the asynchronous IO VFS | |
| 65 ** is not registered with SQLite. | |
| 66 ** | |
| 67 ** Otherwise, if no error occurs, SQLITE_OK is returned. | |
| 68 */ | |
| 69 int sqlite3async_initialize(const char *zParent, int isDefault); | |
| 70 | |
| 71 /* | |
| 72 ** This function unregisters the asynchronous IO VFS using | |
| 73 ** sqlite3_vfs_unregister(). | |
| 74 ** | |
| 75 ** On win32 platforms, this function also releases the small number of | |
| 76 ** critical section and event objects created by sqlite3async_initialize(). | |
| 77 */ | |
| 78 void sqlite3async_shutdown(); | |
| 79 | |
| 80 /* | |
| 81 ** This function may only be called when the asynchronous IO VFS is | |
| 82 ** installed (after a call to sqlite3async_initialize()). It processes | |
| 83 ** zero or more queued write operations before returning. It is expected | |
| 84 ** (but not required) that this function will be called by a different | |
| 85 ** thread than those threads that use SQLite. The "background thread" | |
| 86 ** that performs IO. | |
| 87 ** | |
| 88 ** How many queued write operations are performed before returning | |
| 89 ** depends on the global setting configured by passing the SQLITEASYNC_HALT | |
| 90 ** verb to sqlite3async_control() (see below for details). By default | |
| 91 ** this function never returns - it processes all pending operations and | |
| 92 ** then blocks waiting for new ones. | |
| 93 ** | |
| 94 ** If multiple simultaneous calls are made to sqlite3async_run() from two | |
| 95 ** or more threads, then the calls are serialized internally. | |
| 96 */ | |
| 97 void sqlite3async_run(); | |
| 98 | |
| 99 /* | |
| 100 ** This function may only be called when the asynchronous IO VFS is | |
| 101 ** installed (after a call to sqlite3async_initialize()). It is used | |
| 102 ** to query or configure various parameters that affect the operation | |
| 103 ** of the asynchronous IO VFS. At present there are three parameters | |
| 104 ** supported: | |
| 105 ** | |
| 106 ** * The "halt" parameter, which configures the circumstances under | |
| 107 ** which the sqlite3async_run() parameter is configured. | |
| 108 ** | |
| 109 ** * The "delay" parameter. Setting the delay parameter to a non-zero | |
| 110 ** value causes the sqlite3async_run() function to sleep for the | |
| 111 ** configured number of milliseconds between each queued write | |
| 112 ** operation. | |
| 113 ** | |
| 114 ** * The "lockfiles" parameter. This parameter determines whether or | |
| 115 ** not the asynchronous IO VFS locks the database files it operates | |
| 116 ** on. Disabling file locking can improve throughput. | |
| 117 ** | |
| 118 ** This function is always passed two arguments. When setting the value | |
| 119 ** of a parameter, the first argument must be one of SQLITEASYNC_HALT, | |
| 120 ** SQLITEASYNC_DELAY or SQLITEASYNC_LOCKFILES. The second argument must | |
| 121 ** be passed the new value for the parameter as type "int". | |
| 122 ** | |
| 123 ** When querying the current value of a paramter, the first argument must | |
| 124 ** be one of SQLITEASYNC_GET_HALT, GET_DELAY or GET_LOCKFILES. The second | |
| 125 ** argument to this function must be of type (int *). The current value | |
| 126 ** of the queried parameter is copied to the memory pointed to by the | |
| 127 ** second argument. For example: | |
| 128 ** | |
| 129 ** int eCurrentHalt; | |
| 130 ** int eNewHalt = SQLITEASYNC_HALT_IDLE; | |
| 131 ** | |
| 132 ** sqlite3async_control(SQLITEASYNC_HALT, eNewHalt); | |
| 133 ** sqlite3async_control(SQLITEASYNC_GET_HALT, &eCurrentHalt); | |
| 134 ** assert( eNewHalt==eCurrentHalt ); | |
| 135 ** | |
| 136 ** See below for more detail on each configuration parameter. | |
| 137 ** | |
| 138 ** SQLITEASYNC_HALT: | |
| 139 ** | |
| 140 ** This is used to set the value of the "halt" parameter. The second | |
| 141 ** argument must be one of the SQLITEASYNC_HALT_XXX symbols defined | |
| 142 ** below (either NEVER, IDLE and NOW). | |
| 143 ** | |
| 144 ** If the parameter is set to NEVER, then calls to sqlite3async_run() | |
| 145 ** never return. This is the default setting. If the parameter is set | |
| 146 ** to IDLE, then calls to sqlite3async_run() return as soon as the | |
| 147 ** queue of pending write operations is empty. If the parameter is set | |
| 148 ** to NOW, then calls to sqlite3async_run() return as quickly as | |
| 149 ** possible, without processing any pending write requests. | |
| 150 ** | |
| 151 ** If an attempt is made to set this parameter to an integer value other | |
| 152 ** than SQLITEASYNC_HALT_NEVER, IDLE or NOW, then sqlite3async_control() | |
| 153 ** returns SQLITE_MISUSE and the current value of the parameter is not | |
| 154 ** modified. | |
| 155 ** | |
| 156 ** Modifying the "halt" parameter affects calls to sqlite3async_run() | |
| 157 ** made by other threads that are currently in progress. | |
| 158 ** | |
| 159 ** SQLITEASYNC_DELAY: | |
| 160 ** | |
| 161 ** This is used to set the value of the "delay" parameter. If set to | |
| 162 ** a non-zero value, then after completing a pending write request, the | |
| 163 ** sqlite3async_run() function sleeps for the configured number of | |
| 164 ** milliseconds. | |
| 165 ** | |
| 166 ** If an attempt is made to set this parameter to a negative value, | |
| 167 ** sqlite3async_control() returns SQLITE_MISUSE and the current value | |
| 168 ** of the parameter is not modified. | |
| 169 ** | |
| 170 ** Modifying the "delay" parameter affects calls to sqlite3async_run() | |
| 171 ** made by other threads that are currently in progress. | |
| 172 ** | |
| 173 ** SQLITEASYNC_LOCKFILES: | |
| 174 ** | |
| 175 ** This is used to set the value of the "lockfiles" parameter. This | |
| 176 ** parameter must be set to either 0 or 1. If set to 1, then the | |
| 177 ** asynchronous IO VFS uses the xLock() and xUnlock() methods of the | |
| 178 ** parent VFS to lock database files being read and/or written. If | |
| 179 ** the parameter is set to 0, then these locks are omitted. | |
| 180 ** | |
| 181 ** This parameter may only be set when there are no open database | |
| 182 ** connections using the VFS and the queue of pending write requests | |
| 183 ** is empty. Attempting to set it when this is not true, or to set it | |
| 184 ** to a value other than 0 or 1 causes sqlite3async_control() to return | |
| 185 ** SQLITE_MISUSE and the value of the parameter to remain unchanged. | |
| 186 ** | |
| 187 ** If this parameter is set to zero, then it is only safe to access the | |
| 188 ** database via the asynchronous IO VFS from within a single process. If | |
| 189 ** while writing to the database via the asynchronous IO VFS the database | |
| 190 ** is also read or written from within another process, or via another | |
| 191 ** connection that does not use the asynchronous IO VFS within the same | |
| 192 ** process, the results are undefined (and may include crashes or database | |
| 193 ** corruption). | |
| 194 ** | |
| 195 ** Alternatively, if this parameter is set to 1, then it is safe to access | |
| 196 ** the database from multiple connections within multiple processes using | |
| 197 ** either the asynchronous IO VFS or the parent VFS directly. | |
| 198 */ | |
| 199 int sqlite3async_control(int op, ...); | |
| 200 | |
| 201 /* | |
| 202 ** Values that can be used as the first argument to sqlite3async_control(). | |
| 203 */ | |
| 204 #define SQLITEASYNC_HALT 1 | |
| 205 #define SQLITEASYNC_GET_HALT 2 | |
| 206 #define SQLITEASYNC_DELAY 3 | |
| 207 #define SQLITEASYNC_GET_DELAY 4 | |
| 208 #define SQLITEASYNC_LOCKFILES 5 | |
| 209 #define SQLITEASYNC_GET_LOCKFILES 6 | |
| 210 | |
| 211 /* | |
| 212 ** If the first argument to sqlite3async_control() is SQLITEASYNC_HALT, | |
| 213 ** the second argument should be one of the following. | |
| 214 */ | |
| 215 #define SQLITEASYNC_HALT_NEVER 0 /* Never halt (default value) */ | |
| 216 #define SQLITEASYNC_HALT_NOW 1 /* Halt as soon as possible */ | |
| 217 #define SQLITEASYNC_HALT_IDLE 2 /* Halt when write-queue is empty */ | |
| 218 | |
| 219 #ifdef __cplusplus | |
| 220 } /* End of the 'extern "C"' block */ | |
| 221 #endif | |
| 222 #endif /* ifndef __SQLITEASYNC_H_ */ | |
| 223 | |
| OLD | NEW |
|---|
Chromium Code Reviews
Issue 3108030:
Move bundled copy of sqlite one level deeper to better separate it... (Closed)
Base URL: svn://svn.chromium.org/chrome/trunk/src/