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