Mutexes

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 содержит многократные внедрения этого mutex. Соответствующее внедрение отобрано автоматически во время компиляции. Следующие внедрения доступны в ядре 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"), то никакое mutex внедрение не включено в библиотеку. В этом случае приложение должно поставлять свой mutex, используя выбор SQLITE_CONFIG_MUTEX в функции sqlite3_config() перед вызовом sqlite3_initialize() или любой другой функции sqlite3_, вызывающей sqlite3_initialize().

sqlite3_mutex_alloc() ассигнует новый mutex и возвращает указатель на него. sqlite3_mutex_alloc() возвращает NULL, если это не может ассигновать требуемый mutex. Аргумент 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() создавать новый mutex. Новый mutex рекурсивный, когда SQLITE_MUTEX_RECURSIVE используется, но не обязательно поэтому, когда SQLITE_MUTEX_FAST используется. Внедрение mutex не должно делать различие между SQLITE_MUTEX_RECURSIVE и SQLITE_MUTEX_FAST, если это не хочет. SQLite будет просить рекурсивный mutex только в случаях, где он ему действительно нужен. Если более быстрое нерекурсивное внедрение mutex доступно на серверной платформе, подсистема mutex могла бы возвратить такой mutex в ответ на SQLITE_MUTEX_FAST.

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

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

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

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

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

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

Если аргумент sqlite3_mutex_enter(), sqlite3_mutex_try(), sqlite3_mutex_leave() или sqlite3_mutex_free() это NULL, то любая из этих функций не делает ничего.

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