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 224
