Return to sqlite3async.h CVS log

Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / sqlite3 / ext / async

sqlite3

    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: