From: drh Date: Thu, 18 Jul 2013 18:45:53 +0000 (+0000) Subject: Improved documentation for sqlite3_set_auxdata(). X-Git-Tag: version-3.8.0~78 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=6b75329ae10cf01a0945c6f2296536ec57500bb8;p=thirdparty%2Fsqlite.git Improved documentation for sqlite3_set_auxdata(). Ticket [406d3b2ef91c]. FossilOrigin-Name: 62465ecba7431e1d71e17a61f1af7dc65fe4fe97 --- diff --git a/manifest b/manifest index e83f006318..a2f9baee61 100644 --- a/manifest +++ b/manifest @@ -1,5 +1,5 @@ -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 @@ -218,7 +218,7 @@ F src/resolve.c 89f9003e8316ee3a172795459efc2a0274e1d5a8 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 @@ -1103,7 +1103,7 @@ F tool/warnings-clang.sh f6aa929dc20ef1f856af04a730772f59283631d4 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 diff --git a/manifest.uuid b/manifest.uuid index 9c7179c3ce..c41b54ef2b 100644 --- a/manifest.uuid +++ b/manifest.uuid @@ -1 +1 @@ -153deac8faca3bcc95f6f37e500b659b39b3e872 \ No newline at end of file +62465ecba7431e1d71e17a61f1af7dc65fe4fe97 \ No newline at end of file diff --git a/src/sqlite.h.in b/src/sqlite.h.in index 8c600a1fa3..a87e8810f2 100644 --- a/src/sqlite.h.in +++ b/src/sqlite.h.in @@ -4176,46 +4176,45 @@ sqlite3 *sqlite3_context_db_handle(sqlite3_context*); /* ** 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 )^ -** -** 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: )^ +** +** 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