/[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 - (hide annotations) (download)
Mon Feb 4 17:41:59 2013 UTC (7 years, 7 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 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    

   
Visit the ZANavi Wiki