从 SQLite 3.4.2 迁移到 3.5.0（二十）

返回：SQLite—系列文章目录

上一篇:SQLite---调试提示（十九）

SQLite 版本 3.5.0 （2007-09-04）引入了一个新的操作系统接口层，与所有先前版本的 SQLite 不兼容。另外一些现有的接口已被推广为适用于所有进程中的数据库连接，而不仅仅是所有进程中的数据库连接线程内的连接。本文的目的就是详细描述对 3.5.0 的改动，以便用户以前版本的SQLite可以判断什么（如果有的话）努力需要升级到较新版本。

1.0 变更概述

SQLite 版本 3.5.0 中更改的快速枚举在此处提供。后续章节将介绍这些内容更详细地更改。

操作系统接口层已完全返工：
1. 未记录的 sqlite3_os_switch（） 接口具有已被删除。
2. SQLITE_ENABLE_REDEF_IO编译时标志不再起作用。 I/O 过程现在始终是可重新定义的。
3. 定义了三个用于指定 I/O 过程的新对象：sqlite3_vfs、sqlite3_file 和 sqlite3_io_methods。
4. 三个新接口用于创建替代操作系统接口：sqlite3_vfs_register（）、sqlite3_vfs_unregister（）和 sqlite3_vfs_find（）。
5. 添加了一个新界面，以提供对创建新的数据库连接：sqlite3_open_v2（）。 sqlite3_open（）和 sqlite3_open16（）的旧接口继续得到完全支持。
可选的共享缓存和内存管理功能在 3.3.0 版中引入，现在可以跨多个同一进程中的线程。以前，这些扩展仅应用于在单个线程中运行的数据库连接。
1. sqlite3_enable_shared_cache（）接口现在适用于所有进程中的线程，而不仅仅是进程中的一个线程运行了。
2. sqlite3_soft_heap_limit（）接口现在适用于所有线程在一个进程中，而不仅仅是运行它的一个线程。
3. sqlite3_release_memory（）接口现在将尝试减少所有线程中所有数据库连接的内存使用情况，而不是只是调用接口的线程中的连接。
4. sqlite3_thread_cleanup（）接口已成为无操作接口。
对多个数据库连接使用同一数据库的限制线程已被删除。现在它是安全的多个线程同时使用相同的数据库连接时间。
现在有一个编译时选项，允许应用程序定义替代 malloc（）/free（）实现，而无需修改任何核心 SQLite 代码。
现在有一个编译时选项，允许应用程序定义替代互斥锁实现，而无需修改任何核心 SQLite 代码。

在这些更改中，只有 1a 和 2a 到 2c 是不兼容的在任何正式意义上。但是之前对 SQLite 源（例如，为嵌入式添加自定义操作系统层 hardware）可能会发现这些更改具有更大的影响。另一方面，这些变化的一个重要目标是使自定义 SQLite 以用于不同的操作要容易得多系统。

2.0 操作系统接口层

如果您的系统为 SQLite 定义了自定义操作系统接口，或者如果您使用未记录的 sqlite3_os_switch（） 接口，则需要进行修改才能升级到 SQLite 版本 3.5.0。乍一看，这似乎很痛苦一目了然。但当你更仔细地观察时，你可能会发现使更改更小，更易于理解和管理通过新的SQLite接口。您的更改很可能会现在还可以与SQLite合并无缝协作。你会不再需要对代码SQLite源代码进行任何更改。您的所有更改都可以通过应用程序代码进行，您可以链接到标准的、未经修改的 SQLite 合并版本。此外，以前未记录的操作系统接口层，现在是SQLite的官方支持接口。所以你有一些保证这将是一次性的更改，并且您的新的后端将继续在SQLite的未来版本中工作。

2.1 虚拟文件系统对象

SQLite 的新操作系统接口是围绕一个名为 sqlite3_vfs 的对象构建的。“vfs”代表“虚拟文件系统”。 sqlite3_vfs对象基本上是一个包含指针的结构到实现原始磁盘 I/O 操作的函数 SQLite需要执行才能读取和写入数据库。在本文中，我们经常将sqlite3_vfs对象称为“VFS”。

SQLite能够同时使用多个VFS。每单个数据库连接仅与一个 VFS 关联。但是，如果有多个数据库连接，则每个连接可以与不同的 VFS 相关联。

始终有一个默认的 VFS。旧接口始终 sqlite3_open（）和 sqlite3_open16（）使用默认 VFS。用于创建数据库连接的新接口 sqlite3_open_v2（）允许您指定要使用的 VFS 按名称使用。

2.1.1 注册新的 VFS 对象

适用于 Unix 或 Windows 的 SQLite 标准版本带有一个 VFS 根据需要命名为“unix”或“win32”。这个VFS也是默认值。因此，如果您使用的是传统的开放函数，那么一切都会如此将继续像以前一样运作。更改是应用程序现在可以灵活地添加新的 VFS 模块来实现自定义操作系统层。可以使用 sqlite3_vfs_register（） API 要告诉 SQLite 一个或多个应用程序定义的 VFS 模块：

int sqlite3_vfs_register(sqlite3_vfs*, int makeDflt);

当然，应用程序可以随时调用 sqlite3_vfs_register（） VFS 需要先注册，然后才能使用。第一个参数是指向应用程序已准备的自定义 VFS 对象的指针。第二个参数为 true，使新 VFS 成为默认 VFS，以便它将由旧版 sqlite3_open（）和 sqlite3_open16（） API 使用。如果新的 VFS 不是默认值，那么您可能必须使用新的 sqlite3_open_v2（） API 来使用它。但是请注意，如果新的 VFS 是 SQLite 唯一已知的 VFS（如果 SQLite 是在没有其通常的默认 VFS 或是否删除了预编译的默认 VFS 使用 sqlite3_vfs_unregister（））则新的 VFS 自动变为默认 VFS，无论 makeDflt 参数为 sqlite3_vfs_register（）。

标准版本包括默认的“unix”或“win32”VFS。但是，如果您使用 -DOS_OTHER=1 编译时选项，那么 SQLite 是在没有默认 VFS 的情况下构建。在这种情况下，应用程序必须在调用 sqlite3_open（）之前至少注册一个 VFS。这是嵌入式应用程序应使用的方法。而不是修改 SQLite 源以插入替代方案操作系统层，就像在以前的SQLite版本中所做的那样，而是编译未修改的 SQLite 源文件（最好是合并）使用 -DOS_OTHER=1 选项，然后调用 sqlite3_vfs_register（）来定义底层文件系统的接口，然后再创建任何数据库连接。

2.1.2 对 VFS 对象的附加控制

sqlite3_vfs_unregister（） API 用于删除现有的来自系统的 VFS。

int sqlite3_vfs_unregister(sqlite3_vfs*);

sqlite3_vfs_find（） API 用于定位特定的 VFS 按名称。其原型如下：

sqlite3_vfs *sqlite3_vfs_find(const char *zVfsName);

该参数是所需 VFS 的符号名称。如果参数为 NULL 指针，则返回默认 VFS。该函数返回指向 sqlite3_vfs 对象的指针，该对象实现 VFS。或者，如果没有对象，则返回 NULL 指针可以找到符合搜索条件的。

2.1.3 现有 VFS 的修改

一旦注册了 VFS，就不应对其进行修改。如果需要更改行为，应注册新的 VFS。应用程序也许可以使用 sqlite3_vfs_find（）来定位旧的 VFS，将旧的 VFS 复制到新的 sqlite3_vfs 对象中，对新的 VFS 进行所需的修改，取消注册旧的 VFS，然后在其位置注册新的 VFS。现存即使在之后，数据库连接仍将继续使用旧的 VFS 它未注册，但新的数据库连接将使用新的 VFS。

2.1.4 VFS 对象

VFS 对象是以下结构的实例：

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. */
};

要创建新的 VFS，应用程序会填写此实例结构，然后调用 sqlite3_vfs_register（）。

对于 SQLite 版本 3.5.0，sqlite3_vfs 的 iVersion 字段应为 1。如果有必要，这个数字可能会在 SQLite 的未来版本中增加以某种方式修改 VFS 对象。我们希望这永远不会发生，但该规定是在万一的情况下做出的。

szOsFile 字段是定义打开的文件：sqlite3_file对象。将描述此对象更全面地见下文。这里的重点是，每个 VFS 实现都可以定义自己的 sqlite3_file 对象，其中包含任何信息 VFS 实现需要存储一个打开的文件。SQLite需求但是，要知道这个对象有多大，以便预先分配足够的空间来容纳它。

mxPathname 字段是文件路径名的最大长度，它此 VFS 可以使用。SQLite 有时必须预先分配这个尺寸，所以它应该尽可能小。一些文件系统允许巨大的路径名，但实际上路径名很少扩展超过 100 个字节左右。你不必把最长的底层文件系统可以在此处处理的路径名。只有你必须放置您希望SQLite能够的最长路径名处理。在大多数情况下，几百个是物有所值的。

pNext 字段由 SQLite 在内部使用。具体来说，SQLite 使用此字段形成已注册 VFS 的链表。

zName 字段是 VFS 的符号名称。这是名字 sqlite3_vfs_find（）与查找时进行比较 a VFS。

SQLite 核心未使用 pAppData 指针。指针是可用于存储 VFS 信息可能提供的辅助信息想随身携带。

sqlite3_vfs对象的其余字段都存储指针到实现基元操作的函数。我们称这些 “方法”。第一种方法 xOpen 用于打开文件底层存储介质。结果是一个sqlite3_file对象。还有其他方法，由 sqlite3_file 对象本身定义，用于读取、写入和关闭文件。下面详细介绍了其他方法。文件名为 UTF-8。 SQLite 将保证传递给 zFilename 字符串 xOpen（）是由 xFullPathname（）和字符串将有效且不变，直到 xClose（）为叫。因此，sqlite3_file可以存储指向 filename，如果它出于某种原因需要记住文件名。 xOpen（）的 flags 参数是 flags 参数的副本 sqlite3_open_v2（）。如果 sqlite3_open（）或 sqlite3_open16（）则 flags SQLITE_OPEN_READWRITE |SQLITE_OPEN_CREATE。如果 xOpen（）以只读方式打开文件，则它将 *pOutFlags 设置为包括SQLITE_OPEN_READONLY。*pOutFlags 中的其他位可能是设置。 SQLite 还会向 xOpen（）添加以下标志之一调用，具体取决于要打开的对象：

SQLITE_OPEN_MAIN_DB
SQLITE_OPEN_MAIN_JOURNAL
SQLITE_OPEN_TEMP_DB
SQLITE_OPEN_TEMP_JOURNAL
SQLITE_OPEN_TRANSIENT_DB
SQLITE_OPEN_SUBJOURNAL
SQLITE_OPEN_SUPER_JOURNAL

文件 I/O 实现可以使用对象类型标志来执行以下操作更改了处理文件的方式。例如，应用程序不关心崩溃恢复或回滚，可能会使打开日志文件 a no-op。对本期刊的写入是也是一个不操作。任何读取日志的尝试都会返回SQLITE_IOERR。或者，实现可能会识别数据库文件将以随机顺序进行页面对齐的扇区读取和写入并相应地设置其 I/O 子系统。 SQLite 还可以向 xOpen 添加以下标志之一方法：

SQLITE_OPEN_DELETEONCLOSE
SQLITE_OPEN_EXCLUSIVE

SQLITE_OPEN_DELETEONCLOSE 标志表示文件应为关闭时删除。这将始终设置为 TEMP 数据库和期刊以及子期刊。SQLITE_OPEN_EXCLUSIVE 标志表示应打开文件用于独家访问。此标志针对除用于主数据库文件。作为第三个参数传递的sqlite3_file结构 xOpen 由调用方分配。xOpen 只是填写它。这调用方为 sqlite3_file 结构分配最少的 szOsFile 字节。

SQLITE_OPEN_TEMP_DB 数据库和 SQLITE_OPEN_TRANSIENT_DB 数据库之间的区别在于：SQLITE_OPEN_TEMP_DB用于显式声明和命名的 TEMP 表（使用 CREATE TEMP TABLE 语法）或临时数据库中的命名表这是通过打开文件名为空的数据库创建的字符串。SQLITE_OPEN_TRANSIENT_DB保存一个数据库表，该表 SQLite 自动创建以评估子查询或 ORDER BY 或 GROUP BY 子句。TEMP_DB数据库和TRANSIENT_DB数据库是私有的，并会自动删除。TEMP_DB数据库最后在数据库连接的持续时间内。TRANSIENT_DB数据库 last 仅在单个 SQL 语句的持续时间内。

xDelete 方法用于删除文件。文件的名称是在第二个参数中给出。文件名将为 UTF-8。 VFS 必须将文件名转换为任何字符表示形式底层操作系统期望。如果 syncDir 参数为 true，则 xDelete 方法在更改之前不应返回添加到包含已删除的文件已同步到磁盘，以确保如果不久后发生电源故障，文件不会“重新出现”。

xAccess 方法用于检查文件的访问权限。文件名将采用 UTF-8 编码。将SQLITE_ACCESS_EXISTS flags 参数来检查文件是否存在，SQLITE_ACCESS_READWRITE检查文件是否可读和可写的，或者SQLITE_ACCESS_READ检查文件是否至少可读。由第二个参数命名的“文件”可能是目录或文件夹名称。

xGetTempName 方法计算临时文件的名称，该文件 SQLite可以使用。名称应写入给定的缓冲区通过第二个参数。SQLite 会调整该缓冲区的大小以保存至少 mxPathname 字节。生成的文件名应为 UTF-8。为避免安全问题，生成的临时文件名应包含足够的随机性，以防止攻击者猜测临时文件名。

xFullPathname 方法用于转换相对路径名转换为完整路径名。生成的完整路径名将写入第三个参数提供的缓冲区。SQLite 将调整输出缓冲区至少为 mxPathname 字节。输入和输出名称应为 UTF-8。

xDlOpen、xDlError、xDlSym 和 xDlClose 方法都用于在运行时访问共享库。这些方法可以省略（并且它们的指针设置为零）如果库是使用 SQLITE_OMIT_LOAD_EXTENSION 编译的，或者如果 sqlite3_enable_load_extension（）接口从未用于启用动态扩展加载。这 xDlOpen 方法打开共享库或 DLL，并返回指向一个句柄。如果打开失败，则返回 NULL。如果打开失败， xDlError 方法可用于获取文本错误消息。该消息将写入第三个参数的 zErrMsg 缓冲区长度至少为 nByte 字节。xDlSym 返回指针更改为共享库中的符号。给出符号的名称通过第二个参数。假定使用 UTF-8 编码。如果符号未找到 NULL 指针。xDlClose 例程关闭共享库。

xRandomness 方法只使用一次来初始化 SQLite内部的伪随机数生成器（PRNG）。只使用默认 VFS 上的 xRandomness 方法。xRandomness SQLite 永远不会访问其他 VFS 上的方法。 xRandomness 例程请求 nByte 字节的随机性写入 zOut。例程返回获得的随机字节数。这样获得的随机性的质量将决定内置生成的随机性的质量 SQLite 函数，例如 random（）和 randomblob（）。SQLite 也使用其 PRNG 生成临时文件名。在某些平台上（例如：Windows）SQLite 假定临时文件名是唯一的没有实际测试碰撞，所以有即使 random（）和 randomblob（）从不使用函数。

xSleep 方法用于挂起 at 的调用线程至少给定的微秒数。此方法用于实现 sqlite3_sleep（）和 sqlite3_busy_timeout（） API。在 sqlite3_sleep（）的情况下，默认的 xSleep 方法始终使用 VFS。如果底层系统没有微秒分辨率的睡眠能力，那么睡眠时间应该被围捕。xSleep 返回此舍入值。

xCurrentTime 方法查找当前时间和日期并写入结果作为双精度浮点值输入指针由第二个参数提供。时间和日期在协调世界时（UTC），是一个儒略日小数。

2.1.5 Open File 对象

打开文件的结果是 sqlite3_file 对象的实例。 sqlite3_file对象是一个抽象基类，定义如下：

typedef struct sqlite3_file sqlite3_file;
struct sqlite3_file {
  const struct sqlite3_io_methods *pMethods;
};

每个 VFS 实现sqlite3_file都将通过添加末尾的附加字段，用于保存 VFS 的任何信息需要了解打开的文件。什么信息并不重要只要结构的总大小不超过 sqlite3_vfs 对象中记录的 szOsFile 值。

sqlite3_io_methods对象是包含指针的结构用于读取、写入和以其他方式处理文件的方法。此对象定义如下：

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 */
};

sqlite3_io_methods 的 iVersion 字段作为保险提供针对未来的增强功能。iVersion 值应始终为 1 表示 SQLite 版本 3.5。

xClose 方法关闭文件。sqlite3_file结构的空间由调用方解除分配。但是，如果sqlite3_file包含指向其他分配的内存或资源的指针，则这些分配应通过 xClose 方法释放。

xRead 方法从以字节开头的文件中读取 iAmt 字节偏移到 iOfst。读取的数据存储在第二个参数。xRead 在成功时返回SQLITE_OK，SQLITE_IOERR_SHORT_READ如果它无法读取完整数字的字节数，因为它到达了文件末尾，或者SQLITE_IOERR_READ 任何其他错误。

xWrite 方法从第二个参数写入 iAmt 字节的数据到以 iOfst 字节偏移量开始的文件。如果大小在写入之前，文件小于 iOfst 字节，则 xWrite 应该确保文件在 iOfst 字节之前以零扩展开始写入。xWrite 继续将文件扩展为必需的，以便文件的大小至少为 iAmt+iOfst 字节在 xWrite 调用结束时。xWrite 方法在成功时返回SQLITE_OK。如果写入无法完成，因为底层存储介质已满，然后返回SQLITE_FULL。对于任何其他错误，应返回SQLITE_IOERR_WRITE。

xTruncate 方法将文件截断为长度为 nByte 字节。如果文件的长度已经是 nByte 字节或更少，那么这个方法是无操作的。xTruncate 方法返回 SQLITE_OK on 成功，如果出现任何问题，SQLITE_IOERR_TRUNCATE。

xSync 方法用于强制将以前写入的数据从操作系统缓存并进入非易失性存储器。第二个参数通常为 SQLITE_SYNC_NORMAL。如果第二个参数 SQLITE_SYNC_FULL则 xSync 方法应确保数据也已通过磁盘控制器缓存刷新。 SQLITE_SYNC_FULL 参数等效于 F_FULLSYNC ioctl（）在 Mac OS X 上。xSync 方法返回成功SQLITE_OK，并在出现任何问题时SQLITE_IOERR_FSYNC。

xFileSize（）方法确定文件的当前大小以字节为单位，并将该值写入 *pSize。它返回成功SQLITE_OK，并在出现问题时SQLITE_IOERR_FSTAT。

xLock 和 xUnlock 方法用于设置和清除文件锁。 SQLite支持五个级别的文件锁，顺序是：

SQLITE_LOCK_NONE
SQLITE_LOCK_SHARED
SQLITE_LOCK_RESERVED
SQLITE_LOCK_PENDING
SQLITE_LOCK_EXCLUSIVE

底层实现可以支持这些锁定的某些子集只要符合本款的其他要求即可。锁定级别被指定为两个 xLock 的第二个参数和 xUnlock。xLock 方法将锁定级别提高到指定的锁定级别或更高。xUnlock 方法可降低锁定级别不低于指定的级别。SQLITE_LOCK_NONE表示文件已解锁。SQLITE_LOCK_SHARED授予读取文件的权限。多个数据库连接可以同时握住SQLITE_LOCK_SHARED。SQLITE_LOCK_RESERVED就像SQLITE_LOCK_SHARED一样，因为它是许可读取文件。但只有一个连接可以保留保留锁在任何时间点。SQLITE_LOCK_PENDING也是允许读取文件。其他连接也可以继续读取文件，但不允许其他连接将锁从无升级为共享。SQLITE_LOCK_EXCLUSIVE是在文件上写入的权限。只有一个连接可以保持独占锁，其他任何连接都无法保持任何锁（“无”除外），而一个连接具有独占性锁。xLock 在成功时返回SQLITE_OK，SQLITE_BUSY如果它无法获得锁，或者SQLITE_IOERR_RDLOCK其他情况出错。xUnlock 方法返回成功SQLITE_OK和问题SQLITE_IOERR_UNLOCK。

xCheckReservedLock（）方法检查另一个连接或另一个进程当前持有保留、待处理或独占锁定文件。它返回 true 或 false。

xFileControl（）方法是一个通用接口，允许自定义 VFS 实现，使用（新的和实验性的）sqlite3_file_control（）接口。第二个“op”参数是整数操作码。第三个 argument 是一个泛型指针，旨在成为指针到可能包含参数或空间的结构，其中写入返回值。xFileControl（）的潜在用途可能是函数以启用超时阻塞锁，以更改锁定策略（例如使用点文件锁），查询关于锁的状态，或打破陈旧的锁。SQLite的 Core 保留的操作码少于 100 个供自己使用。小于 100 的操作码列表可用。定义自定义 xFileControl 方法的应用程序应使用操作码大于 100 以避免冲突。

xSectorSize 返回基础的“扇区大小” 非易失性介质。“扇区”被定义为可以在不干扰相邻存储的情况下写入的存储。在磁盘驱动器上，“扇区大小”直到最近才为 512 字节，尽管有人推动将该值增加到 4KiB。SQLite需求知道扇区大小，以便它可以在时间，从而避免损坏相邻的存储空间，如果电源丢失发生在写入过程中。

xDeviceCharacteristics 方法返回一个整数位向量，定义底层存储介质可能具有的任何特殊属性 SQLite可以使用它来提高性能。允许的退货是以下值的按位 OR：

SQLITE_IOCAP_ATOMIC
SQLITE_IOCAP_ATOMIC512
SQLITE_IOCAP_ATOMIC1K
SQLITE_IOCAP_ATOMIC2K
SQLITE_IOCAP_ATOMIC4K
SQLITE_IOCAP_ATOMIC8K
SQLITE_IOCAP_ATOMIC16K
SQLITE_IOCAP_ATOMIC32K
SQLITE_IOCAP_ATOMIC64K
SQLITE_IOCAP_SAFE_APPEND
SQLITE_IOCAP_SEQUENTIAL

SQLITE_IOCAP_ATOMIC 位表示对此设备的所有写入都是原子，从某种意义上说，要么整个写入发生，要么不发生发生。其他 SQLITE_IOCAP_ATOMICnnn 值表示对指定大小的对齐块的写入是原子的。SQLITE_IOCAP_SAFE_APPEND 意味着在使用 new 扩展文件时 data，则先写入新数据，然后更新文件大小。因此，如果发生电源故障，则文件不可能有以随机性扩展。SQLITE_IOCAP_SEQUENTIAL位表示所有写入都按照发出的顺序发生，而不是发出的顺序由底层文件系统重新排序。

2.1.6 构建新 VFS 的清单

前面的段落包含了很多信息。简化构建任务一个新的 VFS for SQLite 我们提供以下实现清单：

定义 sqlite3_file 对象的相应子类。
实现 sqlite3_io_methods 对象所需的方法。
创建一个静态和包含指针的常量sqlite3_io_methods对象到上一步中的方法。
实现打开文件并填充 sqlite3_file 对象的 xOpen 方法，包括将 pMethods 设置为指向上一步中的sqlite3_io_methods对象。
实现sqlite3_vfs所需的其他方法。
定义一个静态（但不是常量）sqlite3_vfs结构包含指向 xOpen 方法和其他方法的指针，以及其中包含 iVersion、szOsFile、 mxPathname、zName 和 pAppData。
实现调用 sqlite3_vfs_register（）和将指向上一个 sqlite3_vfs 结构的指针传递给它步。此过程可能是实现 VFS 的源文件。

在应用程序中，调用上次实现的过程在初始化过程之前，先执行上述步骤数据库连接将打开。

3.0 内存分配子系统

从版本 3.5 开始，SQLite 获取所有堆内存需要使用例程 sqlite3_malloc（）、sqlite3_free（）和 sqlite3_realloc（）。这些例程在以前的版本中已存在的 SQLite，但 SQLite 之前已经绕过了这些例程并使用它自己的内存分配器。这一切都在版本 3.5.0 中更改。

SQLite 源代码树实际上包含多个版本的内存分配器。在 “mem1.c”源文件用于大多数构建。但如果SQLITE_MEMDEBUG 标志被启用，一个单独的内存分配器“mem2.c”源文件改用。mem2.c 分配器实现了许多钩子执行错误检查并模拟内存分配失败以进行测试目的。这两个分配器都使用 malloc（）/free（）实现在标准 C 库中。

应用程序不需要使用这些标准内存中的任何一个分配器。如果 SQLite 是用 SQLITE_OMIT_MEMORY_ALLOCATION 编译的，那么 sqlite3_malloc（）、sqlite3_realloc（）没有实现，并提供 sqlite3_free（）函数。相反，应用程序针对 SQLite 的链接必须提供自己的实现功能。不需要应用程序提供的内存分配器在标准 C 库中使用 malloc（）/free（）实现。嵌入式应用程序可能会提供备用内存分配器将内存用于为独占预留的固定内存池例如，使用 SQLite。

实现自己的内存分配器的应用程序必须提供通常的三个分配函数sqlite3_malloc（）、sqlite3_realloc（）和 sqlite3_free（）的实现。他们还必须实现第四个功能：

int sqlite3_memory_alarm(
  void(*xCallback)(void *pArg, sqlite3_int64 used, int N),
  void *pArg,
  sqlite3_int64 iThreshold
);

sqlite3_memory_alarm例程用于注册内存分配事件的回调。此例程注册或清除在以下情况下触发的回调分配的内存量超过 iThreshold。只一次可以注册一个回调。每次通话 to sqlite3_memory_alarm（）覆盖之前的回调。通过将 xCallback 设置为 NULL 来禁用回调指针。

回调的参数是 pArg 值、当前正在使用的内存量，以及引发回调的分配。回调将大概调用 sqlite3_free（）来释放内存空间。回调可能会调用 sqlite3_malloc（）或 sqlite3_realloc（），但如果调用，则不会调用其他回调递归调用。

sqlite3_soft_heap_limit（）接口通过注册来工作处于软堆限制的内存警报，并在警报回调中调用 sqlite3_release_memory（）。应用程序不应尝试使用 sqlite3_memory_alarm（）接口，因为这样做会干扰 sqlite3_soft_heap_limit（）模块。此接口已公开只有这样应用程序才能提供自己的当 SQLite 核心是用SQLITE_OMIT_MEMORY_ALLOCATION编译。

SQLite中的内置内存分配器还提供以下功能其他接口：

sqlite3_int64 sqlite3_memory_used(void);
sqlite3_int64 sqlite3_memory_highwater(int resetFlag);

应用程序可以使用这些接口来监视如何 SQLite正在使用大量内存。sqlite3_memory_used（）例程返回当前正在使用的内存字节数，sqlite3_memory_highwater（）返回最大瞬时值内存使用情况。这两个例程都不包括相关的开销使用内存分配器。提供这些例程以供使用通过应用程序。SQLite从不调用它们本身。所以如果应用程序提供自己的内存分配子系统，如果需要，它可以省略这些接口。

4.0 互斥子系统

从某种意义上说，SQLite一直是线程安全的，因为它是安全的在不同的线程中使用不同的 SQLite 数据库连接同时。限制是相同的数据库连接不能同时在两个单独的线程中使用。SQLite 版本 3.5.0 放宽此约束。

为了允许多个线程使用相同的数据库连接同时，SQLite必须广泛使用互斥锁。和因此，添加了一个新的互斥子系统。互斥子系统作为以下接口：

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*);

尽管这些例程是为SQLite核心的使用而存在的，如果需要，应用程序代码也可以自由使用这些例程。互斥锁是一个sqlite3_mutex对象。sqlite3_mutex_alloc（）例程分配一个新的互斥对象并返回指向该对象的指针。对于非递归，sqlite3_mutex_alloc（）的参数应该是 SQLITE_MUTEX_FAST 或 SQLITE_MUTEX_RECURSIVE 和递归互斥锁。如果底层系统这样做不提供非递归互斥锁，则递归互斥锁可以在这种情况下被替换。sqlite3_mutex_alloc（）的参数也可以是一个常量，指定几个静态互斥锁之一：

SQLITE_MUTEX_STATIC_MAIN
SQLITE_MUTEX_STATIC_MEM
SQLITE_MUTEX_STATIC_MEM2
SQLITE_MUTEX_STATIC_PRNG
SQLITE_MUTEX_STATIC_LRU

这些静态互斥锁保留供 SQLite 内部使用并且不应由应用程序使用。静态互斥锁都是非递归的。

应使用 sqlite3_mutex_free（）例程进行解除分配非静态互斥锁。如果将静态互斥锁传递到此例程则行为未定义。

sqlite3_mutex_enter（）尝试输入互斥锁和块如果另一个线程已经存在。sqlite3_mutex_try（）次尝试输入并返回SQLITE_OK成功或SQLITE_BUSY如果另一个线程已经存在。sqlite3_mutex_leave（）退出互斥锁。互斥锁一直保持，直到出口数量与出口数量匹配入口。如果在互斥锁上调用 sqlite3_mutex_leave（），则线程当前未持有，则行为未定义。如果为解除分配的互斥锁调用任何例程，则行为未定义。

SQLite源代码提供了这些的多种实现 API，适用于不同的环境。如果 SQLite 编译为 SQLITE_THREADSAFE=0 标志，然后是一个无操作互斥锁实现速度很快，但没有提供真正的相互排斥。那实现适用于单线程应用程序或仅在单个线程中使用 SQLite 的应用程序。其他真正的互斥锁实现是基于底层提供的操作系统。

嵌入式应用程序可能希望提供自己的互斥锁实现。如果使用 -DSQLITE_MUTEX_APPDEF=1 编译时标志编译 SQLite 则 SQLite 核心不提供互斥子系统和互斥子系统与上述接口匹配的接口必须由链接到 SQLite 的应用程序。

5.0 其他界面更改

SQLite 的 3.5.0 版以某种方式更改了一些 API 的行为在技术上不兼容。但是，这些 API 很少使用过，即使使用它们，也很难想象更改可能会破坏某些内容的场景。变化实际上使这些界面更加有用和强大。

在版本 3.5.0 之前，sqlite3_enable_shared_cache（） API 将启用和禁用所有连接的共享缓存功能在单个线程中 - 从中调用了 sqlite3_enable_shared_cache（）例程。数据库连接使用共享缓存的缓存仅限于在相同的缓存中运行打开它们的线程。从版本 3.5.0 开始， sqlite3_enable_shared_cache（）适用于所有数据库连接在进程内的所有线程中。现在数据库连接正在运行在单独的线程中可以共享缓存。和数据库连接使用共享缓存可以从一个线程迁移到另一个线程。

在版本 3.5.0 之前，sqlite3_soft_heap_limit（）设置了上限限制单线程。每个线程都可以有自己的堆限制。开始在版本 3.5.0 中，整个过程有一个堆限制。这似乎更具限制性（一个限制而不是许多限制），但在练习它是大多数用户想要的。

在版本 3.5.0 之前，sqlite3_release_memory（）函数将尝试从同一线程中的所有数据库连接中回收内存作为 sqlite3_release_memory（）调用。从版本 3.5.0 开始， sqlite3_release_memory（）函数将尝试回收内存来自所有线程中的所有数据库连接。

6.0 总结

从 SQLite 版本 3.4.2 到 3.5.0 的过渡是一个重大变化。 SQLite核心中的每个源代码文件都必须修改，一些广阔地。这种变化引入了一些小的不兼容性在 C 接口中。但我们觉得过渡的好处从 3.4.2 到 3.5.0 远远超过移植的痛苦。新的 VFS 层现在定义明确且稳定，应该会简化未来的定制。VFS 层和可分离内存分配器互斥子系统允许标准SQLite源代码合并无需更改即可在嵌入式项目中使用，大大简化配置管理。由此产生的系统要多得多耐受高螺纹设计。