/[zanavi_public1]/navit/navit/maptool/sqlite3async.h
ZANavi

Contents of /navit/navit/maptool/sqlite3async.h

Parent Directory Parent Directory | Revision Log Revision Log


Revision 31 - (show annotations) (download)
Mon Feb 4 17:41:59 2013 UTC (7 years, 8 months ago) by zoff99
File MIME type: text/plain
File size: 9437 byte(s)
new map version, lots of fixes and experimental new features
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
224

   
Visit the ZANavi Wiki