navit/maptool/sqlite3async.h


#ifndef __SQLITEASYNC_H_
#define __SQLITEASYNC_H_ 1

/*
** Make sure we can call this stuff from C++.
*/
#ifdef __cplusplus
extern "C" {
#endif

#define SQLITEASYNC_VFSNAME "sqlite3async"

/*
** THREAD SAFETY NOTES:
**
** Of the four API functions in this file, the following are not threadsafe:
**
**   sqlite3async_initialize()
**   sqlite3async_shutdown()
**
** Care must be taken that neither of these functions is called while 
** another thread may be calling either any sqlite3async_XXX() function
** or an sqlite3_XXX() API function related to a database handle that
** is using the asynchronous IO VFS.
**
** These functions:
**
**   sqlite3async_run()
**   sqlite3async_control()
**
** are threadsafe. It is quite safe to call either of these functions even
** if another thread may also be calling one of them or an sqlite3_XXX()
** function related to a database handle that uses the asynchronous IO VFS.
*/

/*
** Initialize the asynchronous IO VFS and register it with SQLite using
** sqlite3_vfs_register(). If the asynchronous VFS is already initialized
** and registered, this function is a no-op. The asynchronous IO VFS
** is registered as "sqlite3async".
**
** The asynchronous IO VFS does not make operating system IO requests 
** directly. Instead, it uses an existing VFS implementation for all
** required file-system operations. If the first parameter to this function
** is NULL, then the current default VFS is used for IO. If it is not
** NULL, then it must be the name of an existing VFS. In other words, the
** first argument to this function is passed to sqlite3_vfs_find() to
** locate the VFS to use for all real IO operations. This VFS is known
** as the "parent VFS".
**
** If the second parameter to this function is non-zero, then the 
** asynchronous IO VFS is registered as the default VFS for all SQLite 
** database connections within the process. Otherwise, the asynchronous IO
** VFS is only used by connections opened using sqlite3_open_v2() that
** specifically request VFS "sqlite3async".
**
** If a parent VFS cannot be located, then SQLITE_ERROR is returned.
** In the unlikely event that operating system specific initialization
** fails (win32 systems create the required critical section and event 
** objects within this function), then SQLITE_ERROR is also returned.
** Finally, if the call to sqlite3_vfs_register() returns an error, then 
** the error code is returned to the user by this function. In all three
** of these cases, intialization has failed and the asynchronous IO VFS
** is not registered with SQLite.
**
** Otherwise, if no error occurs, SQLITE_OK is returned.
*/ 
int sqlite3async_initialize(const char *zParent, int isDefault);

/*
** This function unregisters the asynchronous IO VFS using 
** sqlite3_vfs_unregister().
**
** On win32 platforms, this function also releases the small number of 
** critical section and event objects created by sqlite3async_initialize().
*/ 
void sqlite3async_shutdown();

/*
** This function may only be called when the asynchronous IO VFS is 
** installed (after a call to sqlite3async_initialize()). It processes
** zero or more queued write operations before returning. It is expected
** (but not required) that this function will be called by a different 
** thread than those threads that use SQLite. The "background thread"
** that performs IO.
**
** How many queued write operations are performed before returning 
** depends on the global setting configured by passing the SQLITEASYNC_HALT
** verb to sqlite3async_control() (see below for details). By default
** this function never returns - it processes all pending operations and 
** then blocks waiting for new ones.
**
** If multiple simultaneous calls are made to sqlite3async_run() from two
** or more threads, then the calls are serialized internally.
*/
void sqlite3async_run();

/*
** This function may only be called when the asynchronous IO VFS is 
** installed (after a call to sqlite3async_initialize()). It is used 
** to query or configure various parameters that affect the operation 
** of the asynchronous IO VFS. At present there are three parameters 
** supported:
**
**   * The "halt" parameter, which configures the circumstances under
**     which the sqlite3async_run() parameter is configured.
**
**   * The "delay" parameter. Setting the delay parameter to a non-zero
**     value causes the sqlite3async_run() function to sleep for the
**     configured number of milliseconds between each queued write 
**     operation.
**
**   * The "lockfiles" parameter. This parameter determines whether or 
**     not the asynchronous IO VFS locks the database files it operates
**     on. Disabling file locking can improve throughput.
**
** This function is always passed two arguments. When setting the value
** of a parameter, the first argument must be one of SQLITEASYNC_HALT,
** SQLITEASYNC_DELAY or SQLITEASYNC_LOCKFILES. The second argument must
** be passed the new value for the parameter as type "int".
**
** When querying the current value of a paramter, the first argument must
** be one of SQLITEASYNC_GET_HALT, GET_DELAY or GET_LOCKFILES. The second 
** argument to this function must be of type (int *). The current value
** of the queried parameter is copied to the memory pointed to by the
** second argument. For example:
**
**   int eCurrentHalt;
**   int eNewHalt = SQLITEASYNC_HALT_IDLE;
**
**   sqlite3async_control(SQLITEASYNC_HALT, eNewHalt);
**   sqlite3async_control(SQLITEASYNC_GET_HALT, &eCurrentHalt);
**   assert( eNewHalt==eCurrentHalt );
**
** See below for more detail on each configuration parameter.
**
** SQLITEASYNC_HALT:
**
**   This is used to set the value of the "halt" parameter. The second
**   argument must be one of the SQLITEASYNC_HALT_XXX symbols defined
**   below (either NEVER, IDLE and NOW).
**
**   If the parameter is set to NEVER, then calls to sqlite3async_run()
**   never return. This is the default setting. If the parameter is set
**   to IDLE, then calls to sqlite3async_run() return as soon as the
**   queue of pending write operations is empty. If the parameter is set
**   to NOW, then calls to sqlite3async_run() return as quickly as 
**   possible, without processing any pending write requests.
**
**   If an attempt is made to set this parameter to an integer value other
**   than SQLITEASYNC_HALT_NEVER, IDLE or NOW, then sqlite3async_control() 
**   returns SQLITE_MISUSE and the current value of the parameter is not 
**   modified.
**
**   Modifying the "halt" parameter affects calls to sqlite3async_run() 
**   made by other threads that are currently in progress.
**
** SQLITEASYNC_DELAY:
**
**   This is used to set the value of the "delay" parameter. If set to
**   a non-zero value, then after completing a pending write request, the
**   sqlite3async_run() function sleeps for the configured number of 
**   milliseconds.
**
**   If an attempt is made to set this parameter to a negative value,
**   sqlite3async_control() returns SQLITE_MISUSE and the current value
**   of the parameter is not modified.
**
**   Modifying the "delay" parameter affects calls to sqlite3async_run() 
**   made by other threads that are currently in progress.
**
** SQLITEASYNC_LOCKFILES:
**
**   This is used to set the value of the "lockfiles" parameter. This
**   parameter must be set to either 0 or 1. If set to 1, then the
**   asynchronous IO VFS uses the xLock() and xUnlock() methods of the
**   parent VFS to lock database files being read and/or written. If
**   the parameter is set to 0, then these locks are omitted.
**
**   This parameter may only be set when there are no open database
**   connections using the VFS and the queue of pending write requests
**   is empty. Attempting to set it when this is not true, or to set it 
**   to a value other than 0 or 1 causes sqlite3async_control() to return
**   SQLITE_MISUSE and the value of the parameter to remain unchanged.
**
**   If this parameter is set to zero, then it is only safe to access the
**   database via the asynchronous IO VFS from within a single process. If
**   while writing to the database via the asynchronous IO VFS the database
**   is also read or written from within another process, or via another
**   connection that does not use the asynchronous IO VFS within the same
**   process, the results are undefined (and may include crashes or database
**   corruption).
**
**   Alternatively, if this parameter is set to 1, then it is safe to access
**   the database from multiple connections within multiple processes using
**   either the asynchronous IO VFS or the parent VFS directly.
*/
int sqlite3async_control(int op, ...);

/*
** Values that can be used as the first argument to sqlite3async_control().
*/
#define SQLITEASYNC_HALT          1
#define SQLITEASYNC_GET_HALT      2
#define SQLITEASYNC_DELAY         3
#define SQLITEASYNC_GET_DELAY     4
#define SQLITEASYNC_LOCKFILES     5
#define SQLITEASYNC_GET_LOCKFILES 6

/*
** If the first argument to sqlite3async_control() is SQLITEASYNC_HALT,
** the second argument should be one of the following.
*/
#define SQLITEASYNC_HALT_NEVER 0       /* Never halt (default value) */
#define SQLITEASYNC_HALT_NOW   1       /* Halt as soon as possible */
#define SQLITEASYNC_HALT_IDLE  2       /* Halt when write-queue is empty */

#ifdef __cplusplus
}  /* End of the 'extern "C"' block */
#endif
#endif        /* ifndef __SQLITEASYNC_H_ */


1	zoff99	31
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
224