modernc.org/cc@v1.0.1/v2/testdata/_sqlite/ext/async/sqlite3async.h (about)

     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(void);
    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(void);
    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