src/third_party/sqlite/src/ext/async/sqlite3async.h

   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