SQLite C 接口
互斥方法对象
typedef struct sqlite3_mutex_methods sqlite3_mutex_methods; struct sqlite3_mutex_methods { int (*xMutexInit)(void); int (*xMutexEnd)(void); sqlite3_mutex *(*xMutexAlloc)(int); void (*xMutexFree)(sqlite3_mutex *); void (*xMutexEnter)(sqlite3_mutex *); int (*xMutexTry)(sqlite3_mutex *); void (*xMutexLeave)(sqlite3_mutex *); int (*xMutexHeld)(sqlite3_mutex *); int (*xMutexNotheld)(sqlite3_mutex *); };
该结构的一个实例定义了用于分配和使用互斥量的低级例程。
通常,SQLite 提供的默认互斥锁实现就足够了,但是应用程序可以选择用自定义实现替换 SQLite 未提供合适实现的专用部署或系统。在这种情况下,应用程序创建并填充此结构的实例以传递给 sqlite3_config() 以及SQLITE_CONFIG_MUTEX选项。此外,在使用SQLITE_CONFIG_GETMUTEX选项查询系统当前互斥锁实现时,此结构的实例可用作输出变量。
此结构定义的 xMutexInit 方法作为系统初始化的一部分由 sqlite3_initialize() 函数调用。每次有效调用sqlite3_initialize()时,SQLite 只调用一次 xMutexInit 例程。
此结构定义的 xMutexEnd 方法作为系统关闭的一部分由 sqlite3_shutdown() 函数调用。此方法的实现预计会释放所有由互斥方法实现获得的未完成资源,尤其是那些由 xMutexInit 方法获得的资源。每次调用sqlite3_shutdown()时,xMutexEnd() 接口只被调用一次。
该结构定义的其余七个方法(xMutexAlloc、xMutexFree、xMutexEnter、xMutexTry、xMutexLeave、xMutexHeld和xMutexNotheld)实现了以下接口(分别):
- sqlite3_mutex_alloc()
- sqlite3_mutex_free()
- sqlite3_mutex_enter()
- sqlite3_mutex_try()
- sqlite3_mutex_leave()
- sqlite3_mutex_held()
- sqlite3_mutex_notheld()
唯一的区别是上面列举的公共 sqlite3_XXX 函数默默地忽略任何传递 NULL 指针而不是有效互斥句柄的调用。此结构定义的方法的实现不需要处理这种情况。传递一个 NULL 指针而不是一个有效的互斥句柄的结果是未定义的(即,如果它被传递一个 NULL 指针,则提供一个段错误的实现是可以接受的)。
xMutexInit() 方法必须是线程安全的。在同一个进程中多次调用 xMutexInit() 并且不干预对 xMutexEnd() 的调用一定是无害的。对 xMutexInit() 的第二次和后续调用必须是空操作。
xMutexInit() 不得使用 SQLite 内存分配(sqlite3_malloc() 及其关联)。同样,xMutexAlloc() 不得将 SQLite 内存分配用于静态互斥锁。但是 xMutexAlloc() 可以使用 SQLite 内存分配来实现快速或递归互斥锁。
SQLite 将在调用sqlite3_shutdown()时调用 xMutexEnd() 方法,但前提是先前对 xMutexInit 的调用返回了 SQLITE_OK。如果 xMutexInit 以任何方式失败,它应该在返回之前自行清理。