Annotation of embedaddon/sqlite3/ext/async/sqlite3async.h, revision 1.1
1.1 ! misho 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:
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to sqlite3async.h 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