Memory Allocation Routines

内存分配例程

typedef struct sqlite3_mem_methods sqlite3_mem_methods;
struct sqlite3_mem_methods {
  void *(*xMalloc)(int         /* Memory allocation function */
  void (*xFree)(void*          /* Free a prior allocation */
  void *(*xRealloc)(void*,int  /* Resize an allocation */
  int (*xSize)(void*           /* Return the size of an allocation */
  int (*xRoundup)(int          /* Round up request size to allocation size */
  int (*xInit)(void*           /* Initialize the memory allocator */
  void (*xShutdown)(void*      /* Deinitialize the memory allocator */
  void *pAppData;                /* Argument to xInit() and xShutdown() */
};

这个对象的一个实例定义了 SQLite 和低级内存分配例程之间的接口。

这个对象只在 SQLite 接口的一个地方使用。指向此对象实例的指针是当配置选项为 SQLITE_CONFIG_MALLOC 或 SQLITE_CONFIG_GETMALLOC 时 sqlite3_config（）的参数。通过创建此对象的实例并在配置期间将其传递给 sqlite3_config（SQLITE_CONFIG_MALLOC），应用程序可以指定一个备用内存分配子系统，以供 SQLite 用于其所有动态内存需求。

请注意，SQLite 附带了几个内置内存分配器，这些内存分配器对于绝大多数应用程序来说是完全足够的，并且此对象仅对少数具有专用内存分配要求的应用程序有用。在 SQLite 测试中也使用这个对象，以便指定一个替代内存分配器来模拟内存内存不足的情况，以便验证 SQLite 是否从这些条件中正常恢复。

xMalloc，xRealloc 和 xFree 方法必须像标准C库中的 malloc（），realloc（）和 free（）函数一样工作。SQLite 保证 xRealloc 的第二个参数总是先前调用 xRoundup 所返回的值。

xSize 应返回先前从 xMalloc 或 xRealloc 获得的内存分配的分配大小。分配的大小总是至少与请求的大小一样大，但可能更大。

xRoundup 方法返回给定特定请求大小的内存分配的分配大小。大多数内存分配器将内存分配至少集中到8的下一个倍数。一些分配器取整为更大的倍数或2的倍数。通过 sqlite3_malloc（）或 sqlite3_realloc（）首先调用的每个内存分配请求都会先调用 xRoundup。如果 xRoundup 返回0，则会导致相应的内存分配失败。

xInit 方法初始化内存分配器。例如，它可能会分配任何需要的互斥锁或初始化内部数据结构。xShutdown 方法由 sqlite3_shutdown（）调用（间接），并且应该释放由 xInit 获取的所有资源。pAppData 指针用作 xInit和xShutdown 的唯一参数。

SQLite 在调用 xInit 方法时保存 SQLITE_MUTEX_STATIC_MASTER 互斥量，所以 xInit 方法不需要是线程安全的。xShutdown 方法只能从 sqlite3_shutdown（）调用，所以它也不需要是线程安全的。对于其他所有方法，只要 SQLITE_CONFIG_MEMSTATUS 配置选项处于打开状态（默认情况下），SQLite 就会保留 SQLITE_MUTEX_STATIC_MEM 互斥体，因此方法会自动序列化。但是，如果禁用 SQLITE_CONFIG_MEMSTATUS，则其他方法必须是线程安全的，否则将自行安排序列化。

如果没有对 xShutdown（）的干预调用，SQLite 将永远不会调用 xInit（）。

另请参见对象，常量和函数的列表。