SQLITE3_GET_AUXDATA(3) | Library Functions Manual | SQLITE3_GET_AUXDATA(3) |
sqlite3_get_auxdata
,
sqlite3_set_auxdata
—
sqlite3_get_auxdata
(sqlite3_context*,
int N);
void
sqlite3_set_auxdata
(sqlite3_context*,
int N, void*,
void (*)(void*));
The sqlite3_get_auxdata(C,N) interface returns a pointer to the metadata associated by the sqlite3_set_auxdata(C,N,P,X) function with the Nth argument value to the application-defined function. N is zero for the left-most function argument. If there is no metadata associated with the function argument, the sqlite3_get_auxdata(C,N) interface returns a NULL pointer.
The sqlite3_set_auxdata(C,N,P,X) interface saves P as metadata for the N-th argument of the application-defined function. Subsequent calls to sqlite3_get_auxdata(C,N) return P from the most recent sqlite3_set_auxdata(C,N,P,X) call if the metadata is still valid or NULL if the metadata has been discarded. After each call to sqlite3_set_auxdata(C,N,P,X) where X is not NULL, SQLite will invoke the destructor function X with parameter P exactly once, when the metadata is discarded. SQLite is free to discard the metadata at any time, including:
Note the last bullet in particular. The destructor X in sqlite3_set_auxdata(C,N,P,X) might be called immediately, before the sqlite3_set_auxdata() interface even returns. Hence sqlite3_set_auxdata() should be called near the end of the function implementation and the function implementation should not make any use of P after sqlite3_set_auxdata() has been called.
In practice, metadata is preserved between function calls for function parameters that are compile-time constants, including literal values and parameters and expressions composed from the same.
The value of the N parameter to these interfaces should be non-negative. Future enhancements may make use of negative N values to define new kinds of function caching behavior.
These routines must be called from the same thread in which the SQL function is running.
December 19, 2018 | NetBSD 9.0 |