-C Ensure\sthat\sall\sauxiliary\sdata\sregistered\sby\scalls\sto\ssqlite3_set_auxdata()\sis\sdestroyed\swhen\sthe\sVM\sis\shalted.
-D 2013-07-18T18:29:24.793
+C Improved\sdocumentation\sfor\ssqlite3_set_auxdata().\nTicket\s[406d3b2ef91c].
+D 2013-07-18T18:45:53.278
F Makefile.arm-wince-mingw32ce-gcc d6df77f1f48d690bd73162294bbba7f59507c72f
F Makefile.in 5e41da95d92656a5004b03d3576e8b226858a28e
F Makefile.linux-gcc 91d710bdc4998cb015f39edf3cb314ec4f4d7e23
F src/rowset.c 64655f1a627c9c212d9ab497899e7424a34222e0
F src/select.c 91b62654caf8dfe292fb8882715e575d34ad3874
F src/shell.c 4c02ec99e42aeb624bb221b253273da6c910b814
-F src/sqlite.h.in ab59321198fe4e002890c8154642338e7da75e82
+F src/sqlite.h.in ba19609c0dab076a169b0cd2e7d4a479c5b3f664
F src/sqlite3.rc fea433eb0a59f4c9393c8e6d76a6e2596b1fe0c0
F src/sqlite3ext.h 886f5a34de171002ad46fae8c36a7d8051c190fc
F src/sqliteInt.h 6d3115f774aa3e87737f9447c9c0cea992c5bdbf
F tool/warnings.sh fbc018d67fd7395f440c28f33ef0f94420226381
F tool/wherecosttest.c f407dc4c79786982a475261866a161cd007947ae
F tool/win/sqlite.vsix 97894c2790eda7b5bce3cc79cb2a8ec2fde9b3ac
-P 5dcffa671f592ae9355628afa439ae9a2d26f0cd cd9096e64b86c8d45f6744e6eb6ced2aa1a18279
-R 4421f283285a2b7794dd87eb2ccfa514
-U dan
-Z 29564540b2246ca0de6b786ea5d703ab
+P 153deac8faca3bcc95f6f37e500b659b39b3e872
+R ec74b1ee673935f130bb86648a1098ae
+U drh
+Z 00f72fcc18f51e2cc40bcf22d8fab123
/*
** CAPI3REF: Function Auxiliary Data
**
-** The following two functions may be used by scalar SQL functions to
+** These functions may be used by (non-aggregate) SQL functions to
** associate metadata with argument values. If the same value is passed to
** multiple invocations of the same SQL function during query execution, under
-** some circumstances the associated metadata may be preserved. This might
-** be used, for example, in a regular-expression matching
-** function. The compiled version of the regular expression is stored as
-** metadata associated with the SQL value passed as the regular expression
-** pattern. The compiled regular expression can be reused on multiple
-** invocations of the same function so that the original pattern string
-** does not need to be recompiled on each invocation.
+** some circumstances the associated metadata may 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
+** metadata 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.
**
** ^The sqlite3_get_auxdata() interface returns a pointer to the metadata
** associated by the sqlite3_set_auxdata() function with the Nth argument
-** value to the application-defined function. ^If no metadata has been ever
-** been set for the Nth argument of the function, or if the corresponding
-** function parameter has changed since the meta-data was set,
-** then sqlite3_get_auxdata() returns a NULL pointer.
+** value to the application-defined function. ^If there is no metadata
+** associated with the function argument, this sqlite3_get_auxdata() 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 data has not been dropped, or
-** NULL if the data has been dropped.
-** ^(If it is not NULL, SQLite will invoke the destructor
-** function X passed to sqlite3_set_auxdata(C,N,P,X) when <ul>
-** <li> the corresponding function parameter changes,
-** <li> [sqlite3_reset()] or [sqlite3_finalize()] is called for the
-** SQL statement,
-** <li> sqlite3_set_auxdata() is invoked again on the same parameter, or
-** <li> a memory allocation error occurs. </ul>)^
-**
-** SQLite is free to call the destructor and drop metadata on any
-** parameter of any function at any time. ^The only guarantee is that
-** the destructor will be called when the [prepared statement] is destroyed.
-** Note in particular that the destructor X in the call to
-** sqlite3_set_auxdata(C,N,P,X) might be called immediately, before
-** the sqlite3_set_auxdata() call even returns. Hence sqlite3_set_auxdata()
+** 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: <ul>
+** <li> when the corresponding function parameter changes, or
+** <li> when [sqlite3_reset()] or [sqlite3_finalize()] is called for the
+** SQL statement, or
+** <li> when sqlite3_set_auxdata() is invoked again on the same parameter, or
+** <li> during the original sqlite3_set_auxdata() call when a memory
+** allocation error occurs. </ul>)^
+**
+** 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
-** implementation should not make any use of P after sqlite3_set_auxdata()
-** has been called.
+** 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
projects / thirdparty / sqlite.git / commitdiff
