Мьютексы

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.

Процедура 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, соответствующая процедура ничего не делает.

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

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