Данные вспомогательных функций

void *sqlite3_get_auxdata(sqlite3_context*, int N);
void sqlite3_set_auxdata(sqlite3_context*, int N, void*, void (*)(void*));

Эти функции могут использоваться (не агрегированными) SQL-функциями для ассоциации вспомогательных данных со значениями аргументов. Если одно и то же значение аргумента передается в несколько вызовов одной и той же SQL-функции во время выполнения запроса, в некоторых случаях связанные вспомогательные данные могут сохраняться. Примером, где это может быть полезно, является функция сопоставления с использованием регулярных выражений. Скомпилированная версия регулярного выражения может храниться в качестве вспомогательных данных, связанных со строкой шаблона. Затем, пока строка шаблона остается неизменной, скомпилированное регулярное выражение может быть повторно использовано при многократных вызовах одной и той же функции.

Интерфейс sqlite3_get_auxdata(C,N) возвращает указатель на вспомогательные данные, связанные функцией sqlite3_set_auxdata(C,N,P,X) со значением N-го аргумента для функции, определенной приложением. N равно нулю для левого аргумента функции. Если вспомогательные данные, связанные с аргументом функции, отсутствуют, интерфейс sqlite3_get_auxdata(C,N) возвращает нулевой указатель.

Интерфейс sqlite3_set_auxdata(C,N,P,X) сохраняет P в качестве вспомогательных данных для N-го аргумента функции, определенной приложением. Последующие вызовы sqlite3_get_auxdata(C,N) возвращают P из последнего вызова sqlite3_set_auxdata(C,N,P,X), если вспомогательные данные все еще действительны, или NULL, если вспомогательные данные были удалены. После каждого вызова sqlite3_set_auxdata(C,N,P,X), где X не равен NULL, SQLite вызовет функцию-деструктор X с параметром P ровно один раз, когда вспомогательные данные будут удалены. SQLite может удалить вспомогательные данные в любое время, включая:

• при изменении соответствующего параметра функции, или
• при вызове sqlite3_reset() или sqlite3_finalize() для SQL-запроса, или
• при повторном вызове sqlite3_set_auxdata() для того же параметра, или
• во время первоначального вызова sqlite3_set_auxdata() при возникновении ошибки выделения памяти.
• во время первоначального вызова sqlite3_set_auxdata() если функция оценивается во время планирования запроса, а не во время выполнения запроса, как иногда происходит с SQLITE_ENABLE_STAT4.

Обратите особое внимание на последние два пункта. Деструктор X в sqlite3_set_auxdata(C,N,P,X) может быть вызван немедленно, до того, как интерфейс sqlite3_set_auxdata() даже вернёт результат. Следовательно, sqlite3_set_auxdata() следует вызывать в конце реализации функции, и реализация функции не должна использовать P после того, как был вызван sqlite3_set_auxdata(). Кроме того, вызов sqlite3_get_auxdata(), который происходит сразу после соответствующего вызова sqlite3_set_auxdata(), все еще может вернуть NULL, если во время вызова sqlite3_set_auxdata() произошла ошибка недостатка памяти или если функция оценивается во время планирования запроса, а не во время его выполнения.

На практике вспомогательные данные сохраняются между вызовами функции для параметров функции, которые являются константами времени компиляции, включая литеральные значения и параметры и выражения, составленные из тех же.

Значение параметра N для этих интерфейсов должно быть неотрицательным. Будущие улучшения могут использовать отрицательные значения N для определения новых типов поведения кеширования функций.

Эти процедуры должны вызываться из того же потока, в котором выполняется SQL-функция.

См. также: sqlite3_get_clientdata() и sqlite3_set_clientdata().

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