921 lines
49 KiB
HTML
921 lines
49 KiB
HTML
<!DOCTYPE html>
|
|
<html><head>
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
|
|
<link href="sqlite.css" rel="stylesheet">
|
|
<title>SQLite Changes From Version 3.4.2 To 3.5.0</title>
|
|
<!-- path= -->
|
|
</head>
|
|
<body>
|
|
<div class=nosearch>
|
|
<a href="index.html">
|
|
<img class="logo" src="images/sqlite370_banner.gif" alt="SQLite" border="0">
|
|
</a>
|
|
<div><!-- IE hack to prevent disappearing logo --></div>
|
|
<div class="tagline desktoponly">
|
|
Small. Fast. Reliable.<br>Choose any three.
|
|
</div>
|
|
<div class="menu mainmenu">
|
|
<ul>
|
|
<li><a href="index.html">Home</a>
|
|
<li class='mobileonly'><a href="javascript:void(0)" onclick='toggle_div("submenu")'>Menu</a>
|
|
<li class='wideonly'><a href='about.html'>About</a>
|
|
<li class='desktoponly'><a href="docs.html">Documentation</a>
|
|
<li class='desktoponly'><a href="download.html">Download</a>
|
|
<li class='wideonly'><a href='copyright.html'>License</a>
|
|
<li class='desktoponly'><a href="support.html">Support</a>
|
|
<li class='desktoponly'><a href="prosupport.html">Purchase</a>
|
|
<li class='search' id='search_menubutton'>
|
|
<a href="javascript:void(0)" onclick='toggle_search()'>Search</a>
|
|
</ul>
|
|
</div>
|
|
<div class="menu submenu" id="submenu">
|
|
<ul>
|
|
<li><a href='about.html'>About</a>
|
|
<li><a href='docs.html'>Documentation</a>
|
|
<li><a href='download.html'>Download</a>
|
|
<li><a href='support.html'>Support</a>
|
|
<li><a href='prosupport.html'>Purchase</a>
|
|
</ul>
|
|
</div>
|
|
<div class="searchmenu" id="searchmenu">
|
|
<form method="GET" action="search">
|
|
<select name="s" id="searchtype">
|
|
<option value="d">Search Documentation</option>
|
|
<option value="c">Search Changelog</option>
|
|
</select>
|
|
<input type="text" name="q" id="searchbox" value="">
|
|
<input type="submit" value="Go">
|
|
</form>
|
|
</div>
|
|
</div>
|
|
<script>
|
|
function toggle_div(nm) {
|
|
var w = document.getElementById(nm);
|
|
if( w.style.display=="block" ){
|
|
w.style.display = "none";
|
|
}else{
|
|
w.style.display = "block";
|
|
}
|
|
}
|
|
function toggle_search() {
|
|
var w = document.getElementById("searchmenu");
|
|
if( w.style.display=="block" ){
|
|
w.style.display = "none";
|
|
} else {
|
|
w.style.display = "block";
|
|
setTimeout(function(){
|
|
document.getElementById("searchbox").focus()
|
|
}, 30);
|
|
}
|
|
}
|
|
function div_off(nm){document.getElementById(nm).style.display="none";}
|
|
window.onbeforeunload = function(e){div_off("submenu");}
|
|
/* Disable the Search feature if we are not operating from CGI, since */
|
|
/* Search is accomplished using CGI and will not work without it. */
|
|
if( !location.origin || !location.origin.match || !location.origin.match(/http/) ){
|
|
document.getElementById("search_menubutton").style.display = "none";
|
|
}
|
|
/* Used by the Hide/Show button beside syntax diagrams, to toggle the */
|
|
function hideorshow(btn,obj){
|
|
var x = document.getElementById(obj);
|
|
var b = document.getElementById(btn);
|
|
if( x.style.display!='none' ){
|
|
x.style.display = 'none';
|
|
b.innerHTML='show';
|
|
}else{
|
|
x.style.display = '';
|
|
b.innerHTML='hide';
|
|
}
|
|
return false;
|
|
}
|
|
</script>
|
|
</div>
|
|
<?xml version="1.0" encoding="Windows-1252"?>
|
|
|
|
<h1> Moving From SQLite 3.4.2 to 3.5.0</h1><p>
|
|
SQLite version 3.5.0 (2007-09-04) introduces a new OS interface layer that
|
|
is incompatible with all prior versions of SQLite. In addition,
|
|
a few existing interfaces have been generalized to work across all
|
|
database connections within a process rather than just all
|
|
connections within a thread. The purpose of this article
|
|
is to describe the changes to 3.5.0 in detail so that users
|
|
of prior versions of SQLite can judge what, if any, effort will
|
|
be required to upgrade to newer versions.
|
|
</p>
|
|
<h2>1.0 Overview Of Changes</h2><p>
|
|
A quick enumeration of the changes in SQLite version 3.5.0
|
|
is provided here. Subsequent sections will describe these
|
|
changes in more detail.
|
|
</p>
|
|
<p>
|
|
<ol>
|
|
<li>The OS interface layer has been completely reworked:
|
|
<ol type="a">
|
|
<li>The undocumented <b>sqlite3_os_switch()</b> interface has
|
|
been removed.</li>
|
|
<li>The <b>SQLITE_ENABLE_REDEF_IO</b> compile-time flag no longer functions.
|
|
I/O procedures are now always redefinable.</li>
|
|
<li>Three new objects are defined for specifying I/O procedures:
|
|
<a href="c3ref/vfs.html">sqlite3_vfs</a>, <a href="c3ref/file.html">sqlite3_file</a>, and <a href="c3ref/io_methods.html">sqlite3_io_methods</a>.</li>
|
|
<li>Three new interfaces are used to create alternative OS interfaces:
|
|
<a href="c3ref/vfs_find.html">sqlite3_vfs_register()</a>, <a href="c3ref/vfs_find.html">sqlite3_vfs_unregister()</a>, and
|
|
<a href="c3ref/vfs_find.html">sqlite3_vfs_find()</a>.</li>
|
|
<li>A new interface has been added to provided additional control over
|
|
the creation of new database connections: <a href="c3ref/open.html">sqlite3_open_v2()</a>.
|
|
The legacy interfaces of <a href="c3ref/open.html">sqlite3_open()</a> and
|
|
<a href="c3ref/open.html">sqlite3_open16()</a> continue to be fully supported.</li>
|
|
</ol></li>
|
|
<li>The optional shared cache and memory management features that
|
|
were introduced in version 3.3.0 can now be used across multiple
|
|
threads within the same process. Formerly, these extensions only
|
|
applied to database connections operating within a single thread.
|
|
<ol type="a">
|
|
<li>The <a href="c3ref/enable_shared_cache.html">sqlite3_enable_shared_cache()</a> interface now applies to all
|
|
threads within a process, not to just the one thread in which it
|
|
was run.</li>
|
|
<li>The <a href="c3ref/soft_heap_limit.html">sqlite3_soft_heap_limit()</a> interface now applies to all threads
|
|
within a process, not to just the one thread in which it was run.</li>
|
|
<li>The <a href="c3ref/release_memory.html">sqlite3_release_memory()</a> interface will now attempt to reduce
|
|
the memory usages across all database connections in all threads, not
|
|
just connections in the thread where the interface is called.</li>
|
|
<li>The <a href="c3ref/aggregate_count.html">sqlite3_thread_cleanup()</a> interface has become a no-op.</li>
|
|
</ol></li>
|
|
<li>Restrictions on the use of the same database connection by multiple
|
|
threads have been dropped. It is now safe for
|
|
multiple threads to use the same database connection at the same
|
|
time.</li>
|
|
<li>There is now a compile-time option that allows an application to
|
|
define alternative malloc()/free() implementations without having
|
|
to modify any core SQLite code.</li>
|
|
<li>There is now a compile-time option that allows an application to
|
|
define alternative mutex implementations without having
|
|
to modify any core SQLite code.</li>
|
|
</ol>
|
|
</p>
|
|
<p>
|
|
Of these changes, only 1a and 2a through 2c are incompatibilities
|
|
in any formal sense.
|
|
But users who have previously made custom modifications to the
|
|
SQLite source (for example to add a custom OS layer for embedded
|
|
hardware) might find that these changes have a larger impact.
|
|
On the other hand, an important goal of these changes is to make
|
|
it much easier to customize SQLite for use on different operating
|
|
systems.
|
|
</p>
|
|
<h2>2.0 The OS Interface Layer</h2><p>
|
|
If your system defines a custom OS interface for SQLite or if you
|
|
were using the undocumented <b>sqlite3_os_switch()</b>
|
|
interface, then you will need to make modifications in order to
|
|
upgrade to SQLite version 3.5.0. This may seem painful at first
|
|
glance. But as you look more closely, you will probably discover
|
|
that your changes are made smaller and easier to understand and manage
|
|
by the new SQLite interface. It is likely that your changes will
|
|
now also work seamlessly with the SQLite amalgamation. You will
|
|
no longer need to make any changes to the code SQLite source code.
|
|
All of your changes can be effected by application code and you can
|
|
link against a standard, unmodified version of the SQLite amalgamation.
|
|
Furthermore, the OS interface layer, which was formerly undocumented,
|
|
is now an officially support interface for SQLite. So you have
|
|
some assurance that this will be a one-time change and that your
|
|
new backend will continue to work in future versions of SQLite.
|
|
</p>
|
|
<h3>2.1 The Virtual File System Object</h3><p>
|
|
The new OS interface for SQLite is built around an object named
|
|
<a href="c3ref/vfs.html">sqlite3_vfs</a>. The "vfs" stands for "Virtual File System".
|
|
The sqlite3_vfs object is basically a structure containing pointers
|
|
to functions that implement the primitive disk I/O operations that
|
|
SQLite needs to perform in order to read and write databases.
|
|
In this article, we will often refer to an sqlite3_vfs objects as a "VFS".
|
|
</p>
|
|
<p>
|
|
SQLite is able to use multiple VFSes at the same time. Each
|
|
individual database connection is associated with just one VFS.
|
|
But if you have multiple database connections, each connection
|
|
can be associated with a different VFS.
|
|
</p>
|
|
<p>
|
|
There is always a default VFS.
|
|
The legacy interfaces <a href="c3ref/open.html">sqlite3_open()</a> and <a href="c3ref/open.html">sqlite3_open16()</a> always
|
|
use the default VFS.
|
|
The new interface for creating database connections,
|
|
<a href="c3ref/open.html">sqlite3_open_v2()</a>, allows you to specify which VFS you want to
|
|
use by name.
|
|
</p>
|
|
<h4>2.1.1 Registering New VFS Objects</h4><p>
|
|
Standard builds of SQLite for Unix or Windows come with a single
|
|
VFS named "unix" or "win32", as appropriate. This one VFS is also
|
|
the default. So if you are using the legacy open functions, everything
|
|
will continue to operate as it has before. The change is that an application
|
|
now has the flexibility of adding new VFS modules to implement a
|
|
customized OS layer. The <a href="c3ref/vfs_find.html">sqlite3_vfs_register()</a> API can be used
|
|
to tell SQLite about one or more application-defined VFS modules:
|
|
</p>
|
|
<blockquote><pre>
|
|
int sqlite3_vfs_register(sqlite3_vfs*, int makeDflt);
|
|
</pre></blockquote><p>
|
|
Applications can call sqlite3_vfs_register() at any time, though of course
|
|
a VFS needs to be registered before it can be used. The first argument
|
|
is a pointer to a customized VFS object that the application has prepared.
|
|
The second argument is true to make the new VFS the default VFS so that
|
|
it will be used by the legacy <a href="c3ref/open.html">sqlite3_open()</a> and <a href="c3ref/open.html">sqlite3_open16()</a> APIs.
|
|
If the new VFS is not the default, then you will probably have to use
|
|
the new <a href="c3ref/open.html">sqlite3_open_v2()</a> API to use it. Note, however, that if
|
|
a new VFS is the only VFS known to SQLite (if SQLite was compiled without
|
|
its usual default VFS or if the precompiled default VFS was removed
|
|
using <a href="c3ref/vfs_find.html">sqlite3_vfs_unregister()</a>) then the new VFS automatically becomes the
|
|
default VFS regardless of the makeDflt argument to <a href="c3ref/vfs_find.html">sqlite3_vfs_register()</a>.
|
|
</p>
|
|
<p>
|
|
Standard builds include the default "unix" or "win32" VFSes.
|
|
But if you use the -DOS_OTHER=1 compile-time option, then SQLite is
|
|
built without a default VFS. In that case, the application must
|
|
register at least one VFS prior to calling <a href="c3ref/open.html">sqlite3_open()</a>.
|
|
This is the approach that embedded applications should use.
|
|
Rather than modifying the SQLite source to insert an alternative
|
|
OS layer as was done in prior releases of SQLite, instead compile
|
|
an unmodified SQLite source file (preferably the amalgamation)
|
|
with the -DOS_OTHER=1 option, then invoke <a href="c3ref/vfs_find.html">sqlite3_vfs_register()</a>
|
|
to define the interface to the underlying filesystem prior to
|
|
creating any database connections.
|
|
</p>
|
|
<h4>2.1.2 Additional Control Over VFS Objects</h4><p>
|
|
The <a href="c3ref/vfs_find.html">sqlite3_vfs_unregister()</a> API is used to remove an existing
|
|
VFS from the system.
|
|
</p>
|
|
<blockquote><pre>
|
|
int sqlite3_vfs_unregister(sqlite3_vfs*);
|
|
</pre></blockquote><p>
|
|
The <a href="c3ref/vfs_find.html">sqlite3_vfs_find()</a> API is used to locate a particular VFS
|
|
by name. Its prototype is as follows:
|
|
</p>
|
|
<blockquote><pre>
|
|
sqlite3_vfs *sqlite3_vfs_find(const char *zVfsName);
|
|
</pre></blockquote><p>
|
|
The argument is the symbolic name for the desired VFS. If the
|
|
argument is a NULL pointer, then the default VFS is returned.
|
|
The function returns a pointer to the <a href="c3ref/vfs.html">sqlite3_vfs</a> object that
|
|
implements the VFS. Or it returns a NULL pointer if no object
|
|
could be found that matched the search criteria.
|
|
</p>
|
|
<h4>2.1.3 Modifications Of Existing VFSes</h4><p>
|
|
Once a VFS has been registered, it should never be modified. If
|
|
a change in behavior is required, a new VFS should be registered.
|
|
The application could, perhaps, use <a href="c3ref/vfs_find.html">sqlite3_vfs_find()</a> to locate
|
|
the old VFS, make a copy of the old VFS into a new <a href="c3ref/vfs.html">sqlite3_vfs</a>
|
|
object, make the desired modifications to the new VFS, unregister
|
|
the old VFS, then register the new VFS in its place. Existing
|
|
database connections would continue to use the old VFS even after
|
|
it is unregistered, but new database connections would use the
|
|
new VFS.
|
|
</p>
|
|
<h4>2.1.4 The VFS Object</h4><p>
|
|
A VFS object is an instance of the following structure:
|
|
</p>
|
|
<blockquote><pre>
|
|
typedef struct sqlite3_vfs sqlite3_vfs;
|
|
struct sqlite3_vfs {
|
|
int iVersion; /* Structure version number */
|
|
int szOsFile; /* Size of subclassed sqlite3_file */
|
|
int mxPathname; /* Maximum file pathname length */
|
|
sqlite3_vfs *pNext; /* Next registered VFS */
|
|
const char *zName; /* Name of this virtual file system */
|
|
void *pAppData; /* Pointer to application-specific data */
|
|
int (*xOpen)(sqlite3_vfs*, const char *zName, sqlite3_file*,
|
|
int flags, int *pOutFlags);
|
|
int (*xDelete)(sqlite3_vfs*, const char *zName, int syncDir);
|
|
int (*xAccess)(sqlite3_vfs*, const char *zName, int flags);
|
|
int (*xGetTempName)(sqlite3_vfs*, char *zOut);
|
|
int (*xFullPathname)(sqlite3_vfs*, const char *zName, char *zOut);
|
|
void *(*xDlOpen)(sqlite3_vfs*, const char *zFilename);
|
|
void (*xDlError)(sqlite3_vfs*, int nByte, char *zErrMsg);
|
|
void *(*xDlSym)(sqlite3_vfs*,void*, const char *zSymbol);
|
|
void (*xDlClose)(sqlite3_vfs*, void*);
|
|
int (*xRandomness)(sqlite3_vfs*, int nByte, char *zOut);
|
|
int (*xSleep)(sqlite3_vfs*, int microseconds);
|
|
int (*xCurrentTime)(sqlite3_vfs*, double*);
|
|
/* New fields may be appended in figure versions. The iVersion
|
|
** value will increment whenever this happens. */
|
|
};
|
|
</pre></blockquote><p>
|
|
To create a new VFS, an application fills in an instance of this
|
|
structure with appropriate values and then calls <a href="c3ref/vfs_find.html">sqlite3_vfs_register()</a>.
|
|
</p>
|
|
<p>
|
|
The iVersion field of <a href="c3ref/vfs.html">sqlite3_vfs</a> should be 1 for SQLite version 3.5.0.
|
|
This number may increase in future versions of SQLite if we have to
|
|
modify the VFS object in some way. We hope that this never happens,
|
|
but the provision is made in case it does.
|
|
</p>
|
|
<p>
|
|
The szOsFile field is the size in bytes of the structure that defines
|
|
an open file: the <a href="c3ref/file.html">sqlite3_file</a> object. This object will be described
|
|
more fully below. The point here is that each VFS implementation can
|
|
define its own <a href="c3ref/file.html">sqlite3_file</a> object containing whatever information
|
|
the VFS implementation needs to store about an open file. SQLite needs
|
|
to know how big this object is, however, in order to preallocate enough
|
|
space to hold it.
|
|
</p>
|
|
<p>
|
|
The mxPathname field is the maximum length of a file pathname that
|
|
this VFS can use. SQLite sometimes has to preallocate buffers of
|
|
this size, so it should be as small as reasonably possible. Some
|
|
filesystems permit huge pathnames, but in practice pathnames rarely
|
|
extend beyond 100 bytes or so. You do not have to put the longest
|
|
pathname that the underlying filesystem can handle here. You only
|
|
have to put the longest pathname that you want SQLite to be able to
|
|
handle. A few hundred is a good value in most cases.
|
|
</p>
|
|
<p>
|
|
The pNext field is used internally by SQLite. Specifically, SQLite
|
|
uses this field to form a linked list of registered VFSes.
|
|
</p>
|
|
<p>
|
|
The zName field is the symbolic name of the VFS. This is the name
|
|
that the <a href="c3ref/vfs_find.html">sqlite3_vfs_find()</a> compares against when it is looking for
|
|
a VFS.
|
|
</p>
|
|
<p>
|
|
The pAppData pointer is unused by the SQLite core. The pointer is
|
|
available to store auxiliary information that a VFS information might
|
|
want to carry around.
|
|
</p>
|
|
<p>
|
|
The remaining fields of the <a href="c3ref/vfs.html">sqlite3_vfs</a> object all store pointers
|
|
to functions that implement primitive operations. We call these
|
|
"methods". The first method, xOpen, is used to open files on
|
|
the underlying storage media. The result is an <a href="c3ref/file.html">sqlite3_file</a>
|
|
object. There are additional methods, defined by the <a href="c3ref/file.html">sqlite3_file</a>
|
|
object itself that are used to read and write and close the file.
|
|
The additional methods are detailed below. The filename is in UTF-8.
|
|
SQLite will guarantee that the zFilename string passed to
|
|
xOpen() is a full pathname as generated by xFullPathname() and
|
|
that the string will be valid and unchanged until xClose() is
|
|
called. So the <a href="c3ref/file.html">sqlite3_file</a> can store a pointer to the
|
|
filename if it needs to remember the filename for some reason.
|
|
The flags argument to xOpen() is a copy of the flags argument
|
|
to sqlite3_open_v2(). If sqlite3_open() or sqlite3_open16()
|
|
is used, then flags is <a href="c3ref/c_open_autoproxy.html">SQLITE_OPEN_READWRITE</a> | <a href="c3ref/c_open_autoproxy.html">SQLITE_OPEN_CREATE</a>.
|
|
If xOpen() opens a file read-only then it sets *pOutFlags to
|
|
include <a href="c3ref/c_open_autoproxy.html">SQLITE_OPEN_READONLY</a>. Other bits in *pOutFlags may be
|
|
set.
|
|
SQLite will also add one of the following flags to the xOpen()
|
|
call, depending on the object being opened:
|
|
<ul>
|
|
<li> <a href="c3ref/c_open_autoproxy.html">SQLITE_OPEN_MAIN_DB</a>
|
|
<li> <a href="c3ref/c_open_autoproxy.html">SQLITE_OPEN_MAIN_JOURNAL</a>
|
|
<li> <a href="c3ref/c_open_autoproxy.html">SQLITE_OPEN_TEMP_DB</a>
|
|
<li> <a href="c3ref/c_open_autoproxy.html">SQLITE_OPEN_TEMP_JOURNAL</a>
|
|
<li> <a href="c3ref/c_open_autoproxy.html">SQLITE_OPEN_TRANSIENT_DB</a>
|
|
<li> <a href="c3ref/c_open_autoproxy.html">SQLITE_OPEN_SUBJOURNAL</a>
|
|
<li> <a href="c3ref/c_open_autoproxy.html">SQLITE_OPEN_SUPER_JOURNAL</a>
|
|
</ul>
|
|
The file I/O implementation can use the object type flags to
|
|
changes the way it deals with files. For example, an application
|
|
that does not care about crash recovery or rollback, might make
|
|
the open of a journal file a no-op. Writes to this journal are
|
|
also a no-op. Any attempt to read the journal returns <a href="rescode.html#ioerr">SQLITE_IOERR</a>.
|
|
Or the implementation might recognize the a database file will
|
|
be doing page-aligned sector reads and writes in a random order
|
|
and set up its I/O subsystem accordingly.
|
|
SQLite might also add one of the following flags to the xOpen
|
|
method:
|
|
<ul>
|
|
<li> <a href="c3ref/c_open_autoproxy.html">SQLITE_OPEN_DELETEONCLOSE</a>
|
|
<li> <a href="c3ref/c_open_autoproxy.html">SQLITE_OPEN_EXCLUSIVE</a>
|
|
</ul>
|
|
The <a href="c3ref/c_open_autoproxy.html">SQLITE_OPEN_DELETEONCLOSE</a> flag means the file should be
|
|
deleted when it is closed. This will always be set for TEMP
|
|
databases and journals and for subjournals. The
|
|
<a href="c3ref/c_open_autoproxy.html">SQLITE_OPEN_EXCLUSIVE</a> flag means the file should be opened
|
|
for exclusive access. This flag is set for all files except
|
|
for the main database file.
|
|
The <a href="c3ref/file.html">sqlite3_file</a> structure passed as the third argument to
|
|
xOpen is allocated by the caller. xOpen just fills it in. The
|
|
caller allocates a minimum of szOsFile bytes for the <a href="c3ref/file.html">sqlite3_file</a>
|
|
structure.
|
|
</p>
|
|
<p>
|
|
The differences between an <a href="c3ref/c_open_autoproxy.html">SQLITE_OPEN_TEMP_DB</a> database and an
|
|
<a href="c3ref/c_open_autoproxy.html">SQLITE_OPEN_TRANSIENT_DB</a> database is this: The <a href="c3ref/c_open_autoproxy.html">SQLITE_OPEN_TEMP_DB</a>
|
|
is used for explicitly declared and named TEMP tables (using the
|
|
CREATE TEMP TABLE syntax) or for named tables in a temporary database
|
|
that is created by opening a database with a filename that is an empty
|
|
string. An <a href="c3ref/c_open_autoproxy.html">SQLITE_OPEN_TRANSIENT_DB</a> holds a database table that
|
|
SQLite creates automatically in order to evaluate a subquery or
|
|
ORDER BY or GROUP BY clause. Both TEMP_DB and TRANSIENT_DB databases
|
|
are private and are deleted automatically. TEMP_DB databases last
|
|
for the duration of the database connection. TRANSIENT_DB databases
|
|
last only for the duration of a single SQL statement.
|
|
</p>
|
|
<p>
|
|
The xDelete method is used to delete a file. The name of the file is
|
|
given in the second parameter. The filename will be in UTF-8.
|
|
The VFS must convert the filename into whatever character representation
|
|
the underlying operating system expects. If the syncDir parameter is
|
|
true, then the xDelete method should not return until the change
|
|
to the directory contents for the directory containing the
|
|
deleted file have been synced to disk in order to ensure that the
|
|
file does not "reappear" if a power failure occurs soon after.
|
|
</p>
|
|
<p>
|
|
The xAccess method is used to check for access permissions on a file.
|
|
The filename will be UTF-8 encoded. The flags argument will be
|
|
<a href="c3ref/c_access_exists.html">SQLITE_ACCESS_EXISTS</a> to check for the existence of the file,
|
|
<a href="c3ref/c_access_exists.html">SQLITE_ACCESS_READWRITE</a> to check to see if the file is both readable
|
|
and writable, or <a href="c3ref/c_access_exists.html">SQLITE_ACCESS_READ</a> to check to see if the file is
|
|
at least readable. The "file" named by the second parameter might
|
|
be a directory or folder name.
|
|
</p>
|
|
<p>
|
|
The xGetTempName method computes the name of a temporary file that
|
|
SQLite can use. The name should be written into the buffer given
|
|
by the second parameter. SQLite will size that buffer to hold
|
|
at least mxPathname bytes. The generated filename should be in UTF-8.
|
|
To avoid security problems, the generated temporary filename should
|
|
contain enough randomness to prevent an attacker from guessing the
|
|
temporary filename in advance.
|
|
</p>
|
|
<p>
|
|
The xFullPathname method is used to convert a relative pathname
|
|
into a full pathname. The resulting full pathname is written into
|
|
the buffer provided by the third parameter. SQLite will size the
|
|
output buffer to at least mxPathname bytes. Both the input and
|
|
output names should be in UTF-8.
|
|
</p>
|
|
<p>
|
|
The xDlOpen, xDlError, xDlSym, and xDlClose methods are all used for
|
|
accessing shared libraries at run-time. These methods may be omitted
|
|
(and their pointers set to zero) if the library is compiled with
|
|
<a href="compile.html#omit_load_extension">SQLITE_OMIT_LOAD_EXTENSION</a> or if the <a href="c3ref/enable_load_extension.html">sqlite3_enable_load_extension()</a>
|
|
interface is never used to enable dynamic extension loading. The
|
|
xDlOpen method opens a shared library or DLL and returns a pointer to
|
|
a handle. NULL is returned if the open fails. If the open fails,
|
|
the xDlError method can be used to obtain a text error message.
|
|
The message is written into the zErrMsg buffer of the third parameter
|
|
which is at least nByte bytes in length. The xDlSym returns a pointer
|
|
to a symbol in the shared library. The name of the symbol is given
|
|
by the second parameter. UTF-8 encoding is assumed. If the symbol
|
|
is not found a NULL pointer is returned. The xDlClose routine closes
|
|
the shared library.
|
|
</p>
|
|
<p>
|
|
The xRandomness method is used exactly once to initialize the
|
|
pseudo-random number generator (PRNG) inside of SQLite. Only
|
|
the xRandomness method on the default VFS is used. The xRandomness
|
|
methods on other VFSes are never accessed by SQLite.
|
|
The xRandomness routine requests that nByte bytes of randomness
|
|
be written into zOut. The routine returns the actual number of
|
|
bytes of randomness obtained. The quality of the randomness so obtained
|
|
will determine the quality of the randomness generated by built-in
|
|
SQLite functions such as random() and randomblob(). SQLite also
|
|
uses its PRNG to generate temporary file names. On some platforms
|
|
(ex: Windows) SQLite assumes that temporary file names are unique
|
|
without actually testing for collisions, so it is important to have
|
|
good-quality randomness even if the random() and randomblob()
|
|
functions are never used.
|
|
</p>
|
|
<p>
|
|
The xSleep method is used to suspend the calling thread for at
|
|
least the number of microseconds given. This method is used to
|
|
implement the <a href="c3ref/sleep.html">sqlite3_sleep()</a> and <a href="c3ref/busy_timeout.html">sqlite3_busy_timeout()</a> APIs.
|
|
In the case of <a href="c3ref/sleep.html">sqlite3_sleep()</a> the xSleep method of the default
|
|
VFS is always used. If the underlying system does not have a
|
|
microsecond resolution sleep capability, then the sleep time should
|
|
be rounded up. xSleep returns this rounded-up value.
|
|
</p>
|
|
<p>
|
|
The xCurrentTime method finds the current time and date and writes
|
|
the result as a double-precision floating point value into pointer
|
|
provided by the second parameter. The time and date is in
|
|
coordinated universal time (UTC) and is a fractional Julian day number.
|
|
</p>
|
|
<h4>2.1.5 The Open File Object</h4><p>
|
|
The result of opening a file is an instance of an <a href="c3ref/file.html">sqlite3_file</a> object.
|
|
The <a href="c3ref/file.html">sqlite3_file</a> object is an abstract base class defined as follows:
|
|
</p>
|
|
<blockquote><pre>
|
|
typedef struct sqlite3_file sqlite3_file;
|
|
struct sqlite3_file {
|
|
const struct sqlite3_io_methods *pMethods;
|
|
};
|
|
</pre></blockquote><p>
|
|
Each VFS implementation will subclass the <a href="c3ref/file.html">sqlite3_file</a> by adding
|
|
additional fields at the end to hold whatever information the VFS
|
|
needs to know about an open file. It does not matter what information
|
|
is stored as long as the total size of the structure does not exceed
|
|
the szOsFile value recorded in the <a href="c3ref/vfs.html">sqlite3_vfs</a> object.
|
|
</p>
|
|
<p>
|
|
The <a href="c3ref/io_methods.html">sqlite3_io_methods</a> object is a structure that contains pointers
|
|
to methods for reading, writing, and otherwise dealing with files.
|
|
This object is defined as follows:
|
|
</p>
|
|
<blockquote><pre>
|
|
typedef struct sqlite3_io_methods sqlite3_io_methods;
|
|
struct sqlite3_io_methods {
|
|
int iVersion;
|
|
int (*xClose)(sqlite3_file*);
|
|
int (*xRead)(sqlite3_file*, void*, int iAmt, sqlite3_int64 iOfst);
|
|
int (*xWrite)(sqlite3_file*, const void*, int iAmt, sqlite3_int64 iOfst);
|
|
int (*xTruncate)(sqlite3_file*, sqlite3_int64 size);
|
|
int (*xSync)(sqlite3_file*, int flags);
|
|
int (*xFileSize)(sqlite3_file*, sqlite3_int64 *pSize);
|
|
int (*xLock)(sqlite3_file*, int);
|
|
int (*xUnlock)(sqlite3_file*, int);
|
|
int (*xCheckReservedLock)(sqlite3_file*);
|
|
int (*xFileControl)(sqlite3_file*, int op, void *pArg);
|
|
int (*xSectorSize)(sqlite3_file*);
|
|
int (*xDeviceCharacteristics)(sqlite3_file*);
|
|
/* Additional methods may be added in future releases */
|
|
};
|
|
</pre></blockquote><p>
|
|
The iVersion field of <a href="c3ref/io_methods.html">sqlite3_io_methods</a> is provided as insurance
|
|
against future enhancements. The iVersion value should always be
|
|
1 for SQLite version 3.5.
|
|
</p>
|
|
<p>
|
|
The xClose method closes the file. The space for the <a href="c3ref/file.html">sqlite3_file</a>
|
|
structure is deallocated by the caller. But if the <a href="c3ref/file.html">sqlite3_file</a>
|
|
contains pointers to other allocated memory or resources, those
|
|
allocations should be released by the xClose method.
|
|
</p>
|
|
<p>
|
|
The xRead method reads iAmt bytes from the file beginning at a byte
|
|
offset to iOfst. The data read is stored in the pointer of the
|
|
second parameter. xRead returns the <a href="rescode.html#ok">SQLITE_OK</a> on success,
|
|
<a href="rescode.html#ioerr_short_read">SQLITE_IOERR_SHORT_READ</a> if it was not able to read the full number
|
|
of bytes because it reached end-of-file, or <a href="rescode.html#ioerr_read">SQLITE_IOERR_READ</a> for
|
|
any other error.
|
|
</p>
|
|
<p>
|
|
The xWrite method writes iAmt bytes of data from the second parameter
|
|
into the file beginning at an offset of iOfst bytes. If the size of
|
|
the file is less than iOfst bytes prior to the write, then xWrite should
|
|
ensure that the file is extended with zeros up to iOfst bytes prior
|
|
to beginning its write. xWrite continues to extends the file as
|
|
necessary so that the size of the file is at least iAmt+iOfst bytes
|
|
at the conclusion of the xWrite call. The xWrite method returns
|
|
<a href="rescode.html#ok">SQLITE_OK</a> on success. If the write cannot complete because the
|
|
underlying storage medium is full, then <a href="rescode.html#full">SQLITE_FULL</a> is returned.
|
|
<a href="rescode.html#ioerr_write">SQLITE_IOERR_WRITE</a> should be returned for any other error.
|
|
</p>
|
|
<p>
|
|
The xTruncate method truncates a file to be nByte bytes in length.
|
|
If the file is already nByte bytes or less in length then this
|
|
method is a no-op. The xTruncate method returns <a href="rescode.html#ok">SQLITE_OK</a> on
|
|
success and <a href="rescode.html#ioerr_truncate">SQLITE_IOERR_TRUNCATE</a> if anything goes wrong.
|
|
</p>
|
|
<p>
|
|
The xSync method is used to force previously written data out of
|
|
operating system cache and into non-volatile memory. The second
|
|
parameter is usually <a href="c3ref/c_sync_dataonly.html">SQLITE_SYNC_NORMAL</a>. If the second parameter
|
|
is <a href="c3ref/c_sync_dataonly.html">SQLITE_SYNC_FULL</a> then the xSync method should make sure that
|
|
data has also been flushed through the disk controllers cache.
|
|
The <a href="c3ref/c_sync_dataonly.html">SQLITE_SYNC_FULL</a> parameter is the equivalent of the F_FULLSYNC
|
|
ioctl() on Mac OS X. The xSync method returns
|
|
<a href="rescode.html#ok">SQLITE_OK</a> on success and <a href="rescode.html#ioerr_fsync">SQLITE_IOERR_FSYNC</a> if anything goes wrong.
|
|
</p>
|
|
<p>
|
|
The xFileSize() method determines the current size of the file
|
|
in bytes and writes that value into *pSize. It returns <a href="rescode.html#ok">SQLITE_OK</a>
|
|
on success and <a href="rescode.html#ioerr_fstat">SQLITE_IOERR_FSTAT</a> if something goes wrong.
|
|
</p>
|
|
<p>
|
|
The xLock and xUnlock methods are used to set and clear file locks.
|
|
SQLite supports five levels of file locks, in order:
|
|
<ul>
|
|
<li> <a href="c3ref/c_lock_exclusive.html">SQLITE_LOCK_NONE</a>
|
|
<li> <a href="c3ref/c_lock_exclusive.html">SQLITE_LOCK_SHARED</a>
|
|
<li> <a href="c3ref/c_lock_exclusive.html">SQLITE_LOCK_RESERVED</a>
|
|
<li> <a href="c3ref/c_lock_exclusive.html">SQLITE_LOCK_PENDING</a>
|
|
<li> <a href="c3ref/c_lock_exclusive.html">SQLITE_LOCK_EXCLUSIVE</a>
|
|
</ul>
|
|
The underlying implementation can support some subset of these locking
|
|
levels as long as it meets the other requirements of this paragraph.
|
|
The locking level is specified as the second argument to both xLock
|
|
and xUnlock. The xLock method increases the locking level to the
|
|
specified locking level or higher. The xUnlock method decreases the
|
|
locking level to no lower than the level specified.
|
|
<a href="c3ref/c_lock_exclusive.html">SQLITE_LOCK_NONE</a> means that the file is unlocked. <a href="c3ref/c_lock_exclusive.html">SQLITE_LOCK_SHARED</a>
|
|
gives permission to read the file. Multiple database connections can
|
|
hold <a href="c3ref/c_lock_exclusive.html">SQLITE_LOCK_SHARED</a> at the same time.
|
|
<a href="c3ref/c_lock_exclusive.html">SQLITE_LOCK_RESERVED</a> is like <a href="c3ref/c_lock_exclusive.html">SQLITE_LOCK_SHARED</a> in that it is permission
|
|
to read the file. But only a single connection can hold a reserved lock
|
|
at any point in time. The <a href="c3ref/c_lock_exclusive.html">SQLITE_LOCK_PENDING</a> is also permission to
|
|
read the file. Other connections can continue to read the file as well,
|
|
but no other connection is allowed to escalate a lock from none to shared.
|
|
<a href="c3ref/c_lock_exclusive.html">SQLITE_LOCK_EXCLUSIVE</a> is permission to write on the file. Only a single
|
|
connection can hold an exclusive lock and no other connection can hold
|
|
any lock (other than "none") while one connection holds an exclusive
|
|
lock. The xLock returns <a href="rescode.html#ok">SQLITE_OK</a> on success, <a href="rescode.html#busy">SQLITE_BUSY</a> if it
|
|
is unable to obtain the lock, or <a href="rescode.html#ioerr_rdlock">SQLITE_IOERR_RDLOCK</a> if something else
|
|
goes wrong. The xUnlock method returns <a href="rescode.html#ok">SQLITE_OK</a> on success and
|
|
<a href="rescode.html#ioerr_unlock">SQLITE_IOERR_UNLOCK</a> for problems.
|
|
</p>
|
|
<p>
|
|
The xCheckReservedLock() method checks to see if another connection or
|
|
another process is currently holding a reserved, pending, or exclusive
|
|
lock on the file. It returns true or false.
|
|
</p>
|
|
<p>
|
|
The xFileControl() method is a generic interface that allows custom
|
|
VFS implementations to directly control an open file using the
|
|
(new and experimental)
|
|
<a href="c3ref/file_control.html">sqlite3_file_control()</a> interface. The second "op" argument
|
|
is an integer opcode. The third
|
|
argument is a generic pointer which is intended to be a pointer
|
|
to a structure that may contain arguments or space in which to
|
|
write return values. Potential uses for xFileControl() might be
|
|
functions to enable blocking locks with timeouts, to change the
|
|
locking strategy (for example to use dot-file locks), to inquire
|
|
about the status of a lock, or to break stale locks. The SQLite
|
|
core reserves opcodes less than 100 for its own use.
|
|
A <a href="c3ref/c_fcntl_begin_atomic_write.html#sqlitefcntllockstate">list of opcodes</a> less than 100 is available.
|
|
Applications that define a custom xFileControl method should use opcodes
|
|
greater than 100 to avoid conflicts.
|
|
</p>
|
|
<p>
|
|
The xSectorSize returns the "sector size" of the underlying
|
|
non-volatile media. A "sector" is defined as the smallest unit of
|
|
storage that can be written without disturbing adjacent storage.
|
|
On a disk drive the "sector size" has until recently been 512 bytes,
|
|
though there is a push to increase this value to 4KiB. SQLite needs
|
|
to know the sector size so that it can write a full sector at a
|
|
time, and thus avoid corrupting adjacent storage space if a power
|
|
loss occurs in the middle of a write.
|
|
</p>
|
|
<p>
|
|
The xDeviceCharacteristics method returns an integer bit vector that
|
|
defines any special properties that the underlying storage medium might
|
|
have that SQLite can use to increase performance. The allowed return
|
|
is the bit-wise OR of the following values:
|
|
<ul>
|
|
<li> <a href="c3ref/c_iocap_atomic.html">SQLITE_IOCAP_ATOMIC</a>
|
|
<li> <a href="c3ref/c_iocap_atomic.html">SQLITE_IOCAP_ATOMIC512</a>
|
|
<li> <a href="c3ref/c_iocap_atomic.html">SQLITE_IOCAP_ATOMIC1K</a>
|
|
<li> <a href="c3ref/c_iocap_atomic.html">SQLITE_IOCAP_ATOMIC2K</a>
|
|
<li> <a href="c3ref/c_iocap_atomic.html">SQLITE_IOCAP_ATOMIC4K</a>
|
|
<li> <a href="c3ref/c_iocap_atomic.html">SQLITE_IOCAP_ATOMIC8K</a>
|
|
<li> <a href="c3ref/c_iocap_atomic.html">SQLITE_IOCAP_ATOMIC16K</a>
|
|
<li> <a href="c3ref/c_iocap_atomic.html">SQLITE_IOCAP_ATOMIC32K</a>
|
|
<li> <a href="c3ref/c_iocap_atomic.html">SQLITE_IOCAP_ATOMIC64K</a>
|
|
<li> <a href="c3ref/c_iocap_atomic.html">SQLITE_IOCAP_SAFE_APPEND</a>
|
|
<li> <a href="c3ref/c_iocap_atomic.html">SQLITE_IOCAP_SEQUENTIAL</a>
|
|
</ul>
|
|
The <a href="c3ref/c_iocap_atomic.html">SQLITE_IOCAP_ATOMIC</a> bit means that all writes to this device are
|
|
atomic in the sense that either the entire write occurs or none of it
|
|
occurs. The other
|
|
<a href="c3ref/c_iocap_atomic.html">SQLITE_IOCAP_ATOMIC<i>nnn</i></a> values indicate that
|
|
writes of aligned blocks of the indicated size are atomic.
|
|
<a href="c3ref/c_iocap_atomic.html">SQLITE_IOCAP_SAFE_APPEND</a> means that when extending a file with new
|
|
data, the new data is written first and then the file size is updated.
|
|
So if a power failure occurs, there is no chance that the file might have
|
|
been extended with randomness. The <a href="c3ref/c_iocap_atomic.html">SQLITE_IOCAP_SEQUENTIAL</a> bit means
|
|
that all writes occur in the order that they are issued and are not
|
|
reordered by the underlying file system.
|
|
</p>
|
|
<h4>2.1.6 Checklist For Constructing A New VFS</h4><p>
|
|
The preceding paragraphs contain a lot of information.
|
|
To ease the task of constructing
|
|
a new VFS for SQLite we offer the following implementation checklist:
|
|
</p>
|
|
<p>
|
|
<ol>
|
|
<li> Define an appropriate subclass of the <a href="c3ref/file.html">sqlite3_file</a> object.
|
|
<li> Implement the methods required by the <a href="c3ref/io_methods.html">sqlite3_io_methods</a> object.
|
|
<li> Create a static and
|
|
constant <a href="c3ref/io_methods.html">sqlite3_io_methods</a> object containing pointers
|
|
to the methods from the previous step.
|
|
<li> Implement the xOpen method that opens a file and populates an
|
|
<a href="c3ref/file.html">sqlite3_file</a> object, including setting pMethods to
|
|
point to the <a href="c3ref/io_methods.html">sqlite3_io_methods</a> object from the previous step.
|
|
<li> Implement the other methods required by <a href="c3ref/vfs.html">sqlite3_vfs</a>.
|
|
<li> Define a static (but not constant) <a href="c3ref/vfs.html">sqlite3_vfs</a> structure that
|
|
contains pointers to the xOpen method and the other methods and
|
|
which contains the appropriate values for iVersion, szOsFile,
|
|
mxPathname, zName, and pAppData.
|
|
<li> Implement a procedure that calls <a href="c3ref/vfs_find.html">sqlite3_vfs_register()</a> and
|
|
passes it a pointer to the <a href="c3ref/vfs.html">sqlite3_vfs</a> structure from the previous
|
|
step. This procedure is probably the only exported symbol in the
|
|
source file that implements your VFS.
|
|
</ol>
|
|
</p>
|
|
<p>
|
|
Within your application, call the procedure implemented in the last
|
|
step above as part of your initialization process before any
|
|
database connections are opened.
|
|
</p>
|
|
<h2>3.0 The Memory Allocation Subsystem</h2><p>
|
|
Beginning with version 3.5, SQLite obtains all of the heap memory it
|
|
needs using the routines <a href="c3ref/free.html">sqlite3_malloc()</a>, <a href="c3ref/free.html">sqlite3_free()</a>, and
|
|
<a href="c3ref/free.html">sqlite3_realloc()</a>. These routines have existed in prior versions
|
|
of SQLite, but SQLite has previously bypassed these routines and used
|
|
its own memory allocator. This all changes in version 3.5.0.
|
|
</p>
|
|
<p>
|
|
The SQLite source tree actually contains multiple versions of the
|
|
memory allocator. The default high-speed version found in the
|
|
"mem1.c" source file is used for most builds. But if the SQLITE_MEMDEBUG
|
|
flag is enabled, a separate memory allocator the "mem2.c" source file
|
|
is used instead. The mem2.c allocator implements lots of hooks to
|
|
do error checking and to simulate memory allocation failures for testing
|
|
purposes. Both of these allocators use the malloc()/free() implementation
|
|
in the standard C library.
|
|
</p>
|
|
<p>
|
|
Applications are not required to use either of these standard memory
|
|
allocators. If SQLite is compiled with <a href="compile.html#omitfeatures">SQLITE_OMIT_MEMORY_ALLOCATION</a>
|
|
then no implementation for the <a href="c3ref/free.html">sqlite3_malloc()</a>, <a href="c3ref/free.html">sqlite3_realloc()</a>,
|
|
and <a href="c3ref/free.html">sqlite3_free()</a> functions is provided. Instead, the application
|
|
that links against SQLite must provide its own implementation of these
|
|
functions. The application provided memory allocator is not required
|
|
to use the malloc()/free() implementation in the standard C library.
|
|
An embedded application might provide an alternative memory allocator
|
|
that uses memory for a fixed memory pool set aside for the exclusive
|
|
use of SQLite, for example.
|
|
</p>
|
|
<p>
|
|
Applications that implement their own memory allocator must provide
|
|
implementation for the usual three allocation functions
|
|
<a href="c3ref/free.html">sqlite3_malloc()</a>, <a href="c3ref/free.html">sqlite3_realloc()</a>, and <a href="c3ref/free.html">sqlite3_free()</a>.
|
|
And they must also implement a fourth function:
|
|
</p>
|
|
<blockquote><pre>
|
|
int sqlite3_memory_alarm(
|
|
void(*xCallback)(void *pArg, sqlite3_int64 used, int N),
|
|
void *pArg,
|
|
sqlite3_int64 iThreshold
|
|
);
|
|
</pre></blockquote><p>
|
|
The <a href="c3ref/aggregate_count.html">sqlite3_memory_alarm</a> routine is used to register
|
|
a callback on memory allocation events.
|
|
This routine registers or clears a callback that fires when
|
|
the amount of memory allocated exceeds iThreshold. Only
|
|
a single callback can be registered at a time. Each call
|
|
to <a href="c3ref/aggregate_count.html">sqlite3_memory_alarm()</a> overwrites the previous callback.
|
|
The callback is disabled by setting xCallback to a NULL
|
|
pointer.
|
|
</p>
|
|
<p>
|
|
The parameters to the callback are the pArg value, the
|
|
amount of memory currently in use, and the size of the
|
|
allocation that provoked the callback. The callback will
|
|
presumably invoke <a href="c3ref/free.html">sqlite3_free()</a> to free up memory space.
|
|
The callback may invoke <a href="c3ref/free.html">sqlite3_malloc()</a> or <a href="c3ref/free.html">sqlite3_realloc()</a>
|
|
but if it does, no additional callbacks will be invoked by
|
|
the recursive calls.
|
|
</p>
|
|
<p>
|
|
The <a href="c3ref/soft_heap_limit.html">sqlite3_soft_heap_limit()</a> interface works by registering
|
|
a memory alarm at the soft heap limit and invoking
|
|
<a href="c3ref/release_memory.html">sqlite3_release_memory()</a> in the alarm callback. Application
|
|
programs should not attempt to use the <a href="c3ref/aggregate_count.html">sqlite3_memory_alarm()</a>
|
|
interface because doing so will interfere with the
|
|
<a href="c3ref/soft_heap_limit.html">sqlite3_soft_heap_limit()</a> module. This interface is exposed
|
|
only so that applications can provide their own
|
|
alternative implementation when the SQLite core is
|
|
compiled with <a href="compile.html#omitfeatures">SQLITE_OMIT_MEMORY_ALLOCATION</a>.
|
|
</p>
|
|
<p>
|
|
The built-in memory allocators in SQLite also provide the following
|
|
additional interfaces:
|
|
</p>
|
|
<blockquote><pre>
|
|
sqlite3_int64 sqlite3_memory_used(void);
|
|
sqlite3_int64 sqlite3_memory_highwater(int resetFlag);
|
|
</pre></blockquote><p>
|
|
These interfaces can be used by an application to monitor how
|
|
much memory SQLite is using. The <a href="c3ref/memory_highwater.html">sqlite3_memory_used()</a> routine
|
|
returns the number of bytes of memory currently in use and the
|
|
<a href="c3ref/memory_highwater.html">sqlite3_memory_highwater()</a> returns the maximum instantaneous
|
|
memory usage. Neither routine includes the overhead associated
|
|
with the memory allocator. These routines are provided for use
|
|
by the application. SQLite never invokes them itself. So if
|
|
the application is providing its own memory allocation subsystem,
|
|
it can omit these interfaces if desired.
|
|
</p>
|
|
<h2>4.0 The Mutex Subsystem</h2><p>
|
|
SQLite has always been threadsafe in the sense that it is safe to
|
|
use different SQLite database connections in different threads at the
|
|
same time. The constraint was that the same database connection
|
|
could not be used in two separate threads at once. SQLite version 3.5.0
|
|
relaxes this constraint.
|
|
</p>
|
|
<p>
|
|
In order to allow multiple threads to use the same database connection
|
|
at the same time, SQLite must make extensive use of mutexes. And for
|
|
this reason a new mutex subsystem as been added. The mutex subsystem
|
|
as the following interface:
|
|
</p>
|
|
<blockquote><pre>
|
|
sqlite3_mutex *sqlite3_mutex_alloc(int);
|
|
void sqlite3_mutex_free(sqlite3_mutex*);
|
|
void sqlite3_mutex_enter(sqlite3_mutex*);
|
|
int sqlite3_mutex_try(sqlite3_mutex*);
|
|
void sqlite3_mutex_leave(sqlite3_mutex*);
|
|
</pre></blockquote><p>
|
|
Though these routines exist for the use of the SQLite core,
|
|
application code is free to use these routines as well, if desired.
|
|
A mutex is an <a href="c3ref/mutex.html">sqlite3_mutex</a> object. The <a href="c3ref/mutex_alloc.html">sqlite3_mutex_alloc()</a>
|
|
routine allocates a new mutex object and returns a pointer to it.
|
|
The argument to <a href="c3ref/mutex_alloc.html">sqlite3_mutex_alloc()</a> should be
|
|
<a href="c3ref/c_mutex_fast.html">SQLITE_MUTEX_FAST</a> or <a href="c3ref/c_mutex_fast.html">SQLITE_MUTEX_RECURSIVE</a> for non-recursive
|
|
and recursive mutexes, respectively. If the underlying system does
|
|
not provide non-recursive mutexes, then a recursive mutex can be
|
|
substituted in that case. The argument to <a href="c3ref/mutex_alloc.html">sqlite3_mutex_alloc()</a>
|
|
can also be a constant designating one of several static mutexes:
|
|
<ul>
|
|
<li> <a href="c3ref/c_mutex_fast.html">SQLITE_MUTEX_STATIC_MAIN</a>
|
|
<li> <a href="c3ref/c_mutex_fast.html">SQLITE_MUTEX_STATIC_MEM</a>
|
|
<li> <a href="c3ref/c_mutex_fast.html">SQLITE_MUTEX_STATIC_MEM2</a>
|
|
<li> <a href="c3ref/c_mutex_fast.html">SQLITE_MUTEX_STATIC_PRNG</a>
|
|
<li> <a href="c3ref/c_mutex_fast.html">SQLITE_MUTEX_STATIC_LRU</a>
|
|
</ul>
|
|
These static mutexes are reserved for use internally by SQLite
|
|
and should not be used by the application. The static mutexes
|
|
are all non-recursive.
|
|
</p>
|
|
<p>
|
|
The <a href="c3ref/mutex_alloc.html">sqlite3_mutex_free()</a> routine should be used to deallocate
|
|
a non-static mutex. If a static mutex is passed to this routine
|
|
then the behavior is undefined.
|
|
</p>
|
|
<p>
|
|
The <a href="c3ref/mutex_alloc.html">sqlite3_mutex_enter()</a> attempts to enter the mutex and blocks
|
|
if another threads is already there. <a href="c3ref/mutex_alloc.html">sqlite3_mutex_try()</a> attempts
|
|
to enter and returns <a href="rescode.html#ok">SQLITE_OK</a> on success or <a href="rescode.html#busy">SQLITE_BUSY</a> if another
|
|
thread is already there. <a href="c3ref/mutex_alloc.html">sqlite3_mutex_leave()</a> exits a mutex.
|
|
The mutex is held until the number of exits matches the number of
|
|
entrances. If <a href="c3ref/mutex_alloc.html">sqlite3_mutex_leave()</a> is called on a mutex that
|
|
the thread is not currently holding, then the behavior is undefined.
|
|
If any routine is called for a deallocated mutex, then the behavior
|
|
is undefined.
|
|
</p>
|
|
<p>
|
|
The SQLite source code provides multiple implementations of these
|
|
APIs, suitable for varying environments. If SQLite is compiled with
|
|
the SQLITE_THREADSAFE=0 flag then a no-op mutex implementation that
|
|
is fast but does no real mutual exclusion is provided. That
|
|
implementation is suitable for use in single-threaded applications
|
|
or applications that only use SQLite in a single thread. Other
|
|
real mutex implementations are provided based on the underlying
|
|
operating system.
|
|
</p>
|
|
<p>
|
|
Embedded applications may wish to provide their own mutex implementation.
|
|
If SQLite is compiled with the -DSQLITE_MUTEX_APPDEF=1 compile-time flag
|
|
then the SQLite core provides no mutex subsystem and a mutex subsystem
|
|
that matches the interface described above must be provided by the
|
|
application that links against SQLite.
|
|
</p>
|
|
<h2>5.0 Other Interface Changes</h2><p>
|
|
Version 3.5.0 of SQLite changes the behavior of a few APIs in ways
|
|
that are technically incompatible. However, these APIs are seldom
|
|
used and even when they are used it is difficult to imagine a
|
|
scenario where the change might break something. The changes
|
|
actually makes these interface much more useful and powerful.
|
|
</p>
|
|
<p>
|
|
Prior to version 3.5.0, the <a href="c3ref/enable_shared_cache.html">sqlite3_enable_shared_cache()</a> API
|
|
would enable and disable the shared cache feature for all connections
|
|
within a single thread - the same thread from which the
|
|
sqlite3_enable_shared_cache() routine was called. Database connections
|
|
that used the shared cache were restricted to running in the same
|
|
thread in which they were opened. Beginning with version 3.5.0,
|
|
the sqlite3_enable_shared_cache() applies to all database connections
|
|
in all threads within the process. Now database connections running
|
|
in separate threads can share a cache. And database connections that
|
|
use shared cache can migrate from one thread to another.
|
|
</p>
|
|
<p>
|
|
Prior to version 3.5.0 the <a href="c3ref/soft_heap_limit.html">sqlite3_soft_heap_limit()</a> set an upper
|
|
bound on heap memory usage for all database connections within a
|
|
single thread. Each thread could have its own heap limit. Beginning
|
|
in version 3.5.0, there is a single heap limit for the entire process.
|
|
This seems more restrictive (one limit as opposed to many) but in
|
|
practice it is what most users want.
|
|
</p>
|
|
<p>
|
|
Prior to version 3.5.0 the <a href="c3ref/release_memory.html">sqlite3_release_memory()</a> function would
|
|
try to reclaim memory from all database connections in the same thread
|
|
as the sqlite3_release_memory() call. Beginning with version 3.5.0,
|
|
the sqlite3_release_memory() function will attempt to reclaim memory
|
|
from all database connections in all threads.
|
|
</p>
|
|
<h2>6.0 Summary</h2><p>
|
|
The transition from SQLite version 3.4.2 to 3.5.0 is a major change.
|
|
Every source code file in the SQLite core had to be modified, some
|
|
extensively. And the change introduced some minor incompatibilities
|
|
in the C interface. But we feel that the benefits of the transition
|
|
from 3.4.2 to 3.5.0 far outweigh the pain of porting. The new
|
|
VFS layer is now well-defined and stable and should simplify future
|
|
customizations. The VFS layer, and the separable memory allocator
|
|
and mutex subsystems allow a standard SQLite source code amalgamation
|
|
to be used in an embedded project without change, greatly simplifying
|
|
configuration management. And the resulting system is much more
|
|
tolerant of highly threaded designs.
|
|
</p>
|
|
|
|
|