1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
|
.Dd January 24, 2024
.Dt SQLITE3_GET_AUXDATA 3
.Os
.Sh NAME
.Nm sqlite3_get_auxdata ,
.Nm sqlite3_set_auxdata
.Nd function auxiliary data
.Sh SYNOPSIS
.In sqlite3.h
.Ft void *
.Fo sqlite3_get_auxdata
.Fa "sqlite3_context*"
.Fa "int N"
.Fc
.Ft void
.Fo sqlite3_set_auxdata
.Fa "sqlite3_context*"
.Fa "int N"
.Fa "void*"
.Fa "void (*)(void*)"
.Fc
.Sh DESCRIPTION
These functions may be used by (non-aggregate) SQL functions to associate
auxiliary data with argument values.
If the same argument value is passed to multiple invocations of the
same SQL function during query execution, under some circumstances
the associated auxiliary data might be preserved.
An example of where this might be useful is in a regular-expression
matching function.
The compiled version of the regular expression can be stored as auxiliary
data associated with the pattern string.
Then as long as the pattern string remains the same, the compiled regular
expression can be reused on multiple invocations of the same function.
.Pp
The sqlite3_get_auxdata(C,N) interface returns a pointer to the auxiliary
data 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 auxiliary data associated with the function argument,
the sqlite3_get_auxdata(C,N) interface returns a NULL pointer.
.Pp
The sqlite3_set_auxdata(C,N,P,X) interface saves P as auxiliary data
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 auxiliary data is still
valid or NULL if the auxiliary data 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 auxiliary data is discarded.
SQLite is free to discard the auxiliary data at any time, including:
.Bl -bullet
.It
when the corresponding function parameter changes, or
.It
when
.Fn sqlite3_reset
or
.Fn sqlite3_finalize
is called for the SQL statement, or
.It
when sqlite3_set_auxdata() is invoked again on the same parameter,
or
.It
during the original sqlite3_set_auxdata() call when a memory allocation
error occurs.
.It
during the original sqlite3_set_auxdata() call if the function is evaluated
during query planning instead of during query execution, as sometimes
happens with SQLITE_ENABLE_STAT4.
.El
.Pp
Note the last two bullets 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.
Furthermore, a call to sqlite3_get_auxdata() that occurs immediately
after a corresponding call to sqlite3_set_auxdata() might still return
NULL if an out-of-memory condition occurred during the sqlite3_set_auxdata()
call or if the function is being evaluated during query planning rather
than during query execution.
.Pp
In practice, auxiliary data is preserved between function calls for
function parameters that are compile-time constants, including literal
values and parameters and expressions composed from the same.
.Pp
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.
.Pp
These routines must be called from the same thread in which the SQL
function is running.
.Pp
.Sh IMPLEMENTATION NOTES
These declarations were extracted from the
interface documentation at line 5903.
.Bd -literal
SQLITE_API void *sqlite3_get_auxdata(sqlite3_context*, int N);
SQLITE_API void sqlite3_set_auxdata(sqlite3_context*, int N, void*, void (*)(void*));
.Ed
.Sh SEE ALSO
.Xr sqlite3_finalize 3 ,
.Xr sqlite3_get_clientdata 3 ,
.Xr sqlite3_reset 3
|
