Мьютексы

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 использует эти процедуры для синхронизации потоков. Хотя они предназначены для внутреннего использования SQLite, код, связанный со SQLite, может использовать любую из этих процедур.

Исходный код SQLite содержит несколько реализаций этих процедур мьютексов. Соответствующая реализация выбирается автоматически во время компиляции. Следующие реализации доступны в ядре SQLite:

• SQLITE_MUTEX_PTHREADS
• SQLITE_MUTEX_W32
• SQLITE_MUTEX_NOOP

Реализация SQLITE_MUTEX_NOOP представляет собой набор процедур, которые не выполняют реальной блокировки и подходят для использования в однопоточной программе. Реализации SQLITE_MUTEX_PTHREADS и SQLITE_MUTEX_W32 подходят для использования в Unix и Windows.

Если SQLite скомпилирован с определенным препроцессорным макросом SQLITE_MUTEX_APPDEF (с "-DSQLITE_MUTEX_APPDEF=1"), то никакая реализация мьютекса не включается в библиотеку. В этом случае приложение должно предоставить пользовательскую реализацию мьютекса, используя опцию SQLITE_CONFIG_MUTEX функции sqlite3_config() перед вызовом sqlite3_initialize() или любой другой публичной функции sqlite3_, которая вызывает sqlite3_initialize().

Процедура sqlite3_mutex_alloc() выделяет новый мьютекс и возвращает указатель на него. Процедура sqlite3_mutex_alloc() возвращает NULL, если она не может выделить запрашиваемый мьютекс. Аргумент для sqlite3_mutex_alloc() должен быть одним из этих целочисленных констант:

• SQLITE_MUTEX_FAST
• SQLITE_MUTEX_RECURSIVE
• SQLITE_MUTEX_STATIC_MAIN
• SQLITE_MUTEX_STATIC_MEM
• SQLITE_MUTEX_STATIC_OPEN
• SQLITE_MUTEX_STATIC_PRNG
• SQLITE_MUTEX_STATIC_LRU
• SQLITE_MUTEX_STATIC_PMEM
• SQLITE_MUTEX_STATIC_APP1
• SQLITE_MUTEX_STATIC_APP2
• SQLITE_MUTEX_STATIC_APP3
• SQLITE_MUTEX_STATIC_VFS1
• SQLITE_MUTEX_STATIC_VFS2
• SQLITE_MUTEX_STATIC_VFS3

Первые две константы (SQLITE_MUTEX_FAST и SQLITE_MUTEX_RECURSIVE) заставляют sqlite3_mutex_alloc() создать новый мьютекс. Новый мьютекс рекурсивный, когда используется SQLITE_MUTEX_RECURSIVE, но необязательно, когда используется SQLITE_MUTEX_FAST. Реализация мьютекса не должна различать SQLITE_MUTEX_RECURSIVE и SQLITE_MUTEX_FAST, если она этого не хочет. SQLite будет запрашивать рекурсивный мьютекс только в тех случаях, когда это действительно необходимо. Если на целевой платформе доступна более быстрая нерекурсивная реализация мьютекса, подсистема мьютексов может вернуть такой мьютекс в ответ на SQLITE_MUTEX_FAST.

Другие разрешенные параметры для sqlite3_mutex_alloc() (кроме SQLITE_MUTEX_FAST и SQLITE_MUTEX_RECURSIVE) каждый возвращают указатель на уже существующий статический мьютекс. Текущая версия SQLite использует девять статических мьютексов. Будущие версии SQLite могут добавить дополнительные статические мьютексы. Статические мьютексы предназначены только для внутреннего использования SQLite. Приложения, использующие мьютексы SQLite, должны использовать только динамические мьютексы, возвращаемые SQLITE_MUTEX_FAST или SQLITE_MUTEX_RECURSIVE.

Обратите внимание, что если используется один из динамических параметров мьютекса (SQLITE_MUTEX_FAST или SQLITE_MUTEX_RECURSIVE), то sqlite3_mutex_alloc() возвращает разные мьютексы при каждом вызове. Для статических типов мьютексов возвращается один и тот же мьютекс при каждом вызове с одинаковым номером типа.

Процедура sqlite3_mutex_free() освобождает ранее выделенный динамический мьютекс. Попытка освободить статический мьютекс приводит к неопределенному поведению.

Процедуры sqlite3_mutex_enter() и sqlite3_mutex_try() пытаются войти в мьютекс. Если другой поток уже находится внутри мьютекса, sqlite3_mutex_enter() заблокируется, а sqlite3_mutex_try() вернет SQLITE_BUSY. Интерфейс sqlite3_mutex_try() возвращает SQLITE_OK при успешном входе. Мьютексы, созданные с помощью SQLITE_MUTEX_RECURSIVE, могут быть введены несколько раз одним и тем же потоком. В таких случаях мьютекс должен быть выведен столько же раз, прежде чем другой поток сможет войти. Если один и тот же поток пытается войти в любой мьютекс, кроме SQLITE_MUTEX_RECURSIVE, более одного раза, поведение неопределенно.

Некоторые системы (например, Windows 95) не поддерживают операцию, реализованную sqlite3_mutex_try(). На этих системах sqlite3_mutex_try() всегда будет возвращать SQLITE_BUSY. В большинстве случаев ядро SQLite использует sqlite3_mutex_try() только в качестве оптимизации, поэтому такое поведение приемлемо. Исключением являются unix-сборки, которые устанавливают опцию сборки SQLITE_ENABLE_SETLK_TIMEOUT. В этом случае требуется работающая sqlite3_mutex_try().

Процедура sqlite3_mutex_leave() выходит из мьютекса, который ранее был введен тем же потоком. Поведение неопределено, если мьютекс не введен вызывающим потоком или не выделен.

Если аргумент для sqlite3_mutex_enter(), sqlite3_mutex_try(), sqlite3_mutex_leave() или sqlite3_mutex_free() является указателем NULL, то любая из четырех процедур ведет себя как no-op.

См. также: sqlite3_mutex_held() и sqlite3_mutex_notheld().

См. также списки Объектов, Констант и Функций.