Функция вспомогательных данных

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 = 0 для крайнего левого аргумента функции. Если нет никаких вспомогательных данных, связанных с аргументом функции, sqlite3_get_auxdata(C,N) вернет NULL.

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(), когда ошибка распределения памяти происходит.

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

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

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

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

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