Interface design for a new sqlite3_trace_v2() method that supersedes

sqlite3_trace() and sqlite3_profile().

FossilOrigin-Name: 0c569f759f6c4701321d7fea5e7ccb371743bb6b

diff --git a/manifest b/manifest
index c9585f19cd260a69785ea8905d36545429d87a6b..91d158c9f495d3fb9dfe61712d2e39f34006e86f 100644 (file)
--- a/manifest
+++ b/manifest
@@ -1,5 +1,5 @@
-C Fix\sharmless\scompiler\swarnings\sin\sshell.c\sfor\sNetBSD.
-D 2016-07-13T13:05:13.449
+C Interface\sdesign\sfor\sa\snew\ssqlite3_trace_v2()\smethod\sthat\ssupersedes\nsqlite3_trace()\sand\ssqlite3_profile().
+D 2016-07-13T21:30:03.340
 F Makefile.in 6c20d44f72d4564f11652b26291a214c8367e5db
 F Makefile.linux-gcc 7bc79876b875010e8c8f9502eb935ca92aa3c434
 F Makefile.msc d66d0395c38571aab3804f8db0fa20707ae4609a
@@ -385,7 +385,7 @@ F src/resolve.c cca3aa77b95706df5d635a2141a4d1de60ae6598
 F src/rowset.c 7b7e7e479212e65b723bf40128c7b36dc5afdfac
 F src/select.c f3c6e9065fb34f6a23af27ec7f1f717ffbfc2ee4
 F src/shell.c a8a9e392a6a2777fabf5feb536931cb190f235e5
-F src/sqlite.h.in b9ba728c1083b7a8ab5f6a628b25cd2a00325fbf
+F src/sqlite.h.in 63774172623fe82336ad0757f373343a87bd0b36
 F src/sqlite3.rc 5121c9e10c3964d5755191c80dd1180c122fc3a8
 F src/sqlite3ext.h 2a170163d121095c6ab1ef05ed0413722f391d01
 F src/sqliteInt.h dcf43b8abc5605b70f54ba80f42b6ad054b8ba95
@@ -1505,7 +1505,10 @@ F vsixtest/vsixtest.tcl 6a9a6ab600c25a91a7acc6293828957a386a8a93
 F vsixtest/vsixtest.vcxproj.data 2ed517e100c66dc455b492e1a33350c1b20fbcdc
 F vsixtest/vsixtest.vcxproj.filters 37e51ffedcdb064aad6ff33b6148725226cd608e
 F vsixtest/vsixtest_TemporaryKey.pfx e5b1b036facdb453873e7084e1cae9102ccc67a0
-P 021d0fb8d85e44839d2b4fdb90b15f0e1f2442e6
-R f2c7097376b33c065f9732879605d098
+P 824b39e54fb9ba562be4d92cc9a54aee1cdf84cb
+R eb1a84643390ea5aba50eced8805fb76
+T *branch * sqlite3_trace_v2
+T *sym-sqlite3_trace_v2 *
+T -sym-trunk *
 U drh
-Z e160e6d632f23e86ebc551e9950cc211
+Z 6025cf3e994164a26dea4fb0e96d3f78

diff --git a/manifest.uuid b/manifest.uuid
index 6b7a74bfc9c2b34f825b3a62911b53da9c1f46d2..42e31abf534edf1793539d4c4349af330bdd9a7e 100644 (file)
--- a/manifest.uuid
+++ b/manifest.uuid
@@ -1 +1 @@
-824b39e54fb9ba562be4d92cc9a54aee1cdf84cb
\ No newline at end of file
+0c569f759f6c4701321d7fea5e7ccb371743bb6b
\ No newline at end of file

diff --git a/src/sqlite.h.in b/src/sqlite.h.in
index 12a07a9b4a65728cad16cc889ff48999aedfb8fc..a3b8f31f07fd162d4a98e04b4eb09f17d56c38cd 100644 (file)
--- a/src/sqlite.h.in
+++ b/src/sqlite.h.in
@@ -2755,6 +2755,9 @@ int sqlite3_set_authorizer(
 ** CAPI3REF: Tracing And Profiling Functions
 ** METHOD: sqlite3
 **
+** These routines are deprecated. Use the [sqlite3_trace_v2()] interface
+** instead of the routines described here.
+**
 ** These routines register callback functions that can be used for
 ** tracing and profiling the execution of SQL statements.
 **
@@ -2780,10 +2783,111 @@ int sqlite3_set_authorizer(
 ** sqlite3_profile() function is considered experimental and is
 ** subject to change in future versions of SQLite.
 */
-void *sqlite3_trace(sqlite3*, void(*xTrace)(void*,const char*), void*);
-SQLITE_EXPERIMENTAL void *sqlite3_profile(sqlite3*,
+SQLITE_DEPRECATED void *sqlite3_trace(sqlite3*,
+   void(*xTrace)(void*,const char*), void*);
+SQLITE_DEPRECATED void *sqlite3_profile(sqlite3*,
    void(*xProfile)(void*,const char*,sqlite3_uint64), void*);
 
+/*
+** CAPI3REF: SQL Trace Event Codes
+** KEYWORDS: SQLITE_TRACE
+**
+** These constants identify classes of events that can be monitored
+** using the [sqlite3_trace_v2()] tracing logic.  The third argument
+** to [sqlite3_trace_v2()] is an OR-ed combination of one or more of
+** the following constants.  The first argument to the trace callback
+** is one of the following constants.
+**
+** New tracing constants may be added in future releases.
+**
+** A trace callback has four arguments: xCallback(T,C,P,X).
+** The T argument is one of the integer type codes above.
+** The C argument is a copy of the context pointer passed in as the
+** fourth argument to [sqlite3_trace_v2()].
+** The P argument is a pointer whose meaning depends on T.
+** The X argument is an unsigned 64-bit integer whose meaning also
+** depends on T.
+**
+** <dl>
+** [[SQLITE_TRACE_SQL]] <dt>SQLITE_TRACE_SQL</dt>
+** <dd>An SQLITE_TRACE_SQL callback provides the same functionality
+** as the legacy [sqlite3_trace()] callback.
+** The P argument is a pointer to the constant UTF-8 string that is text
+** describing an SQL statement that is starting to run with all
+** [bound parameter] expanded.  The X argument is unused.  The size
+** of the expansion of [bound parameters] is limited by the
+** [SQLITE_TRACE_SIZE_LIMIT] compile-time option.
+**
+** [[SQLITE_TRACE_STMT]] <dt>SQLITE_TRACE_STMT</dt>
+** <dd>An SQLITE_TRACE_STMT callback is invoked on the same occasions
+** as SQLITE_TRACE_SQL.  The difference is that the P argument is a
+** pointer to the [prepared statement] rather than an SQL string.
+** The X argument is unused.
+**
+** [[SQLITE_TRACE_PROFILE]] <dt>SQLITE_TRACE_PROFILE</dt>
+** <dd>An SQLITE_TRACE_PROFILE callback provides approximately the same
+** information as is provided by the [sqlite3_profile()] callback.
+** The P argument is a pointer to the [prepared statement] and the
+** X argument is an estimate of the number of nanosecond for which
+** the prepared statement ran.  The SQLITE_TRACE_PROFILE callback is
+** invoked when the statement finishes.
+**
+** [[SQLITE_TRACE_ROW]] <dt>SQLITE_TRACE_ROW</dt>
+** <dd>An SQLITE_TRACE_ROW callback is invoked whenever a prepared
+** statement generates a single row of result.  
+** The P argument is a pointer to the [prepared statement] and the
+** X argument is unused.
+**
+** [[SQLITE_TRACE_CLOSE]] <dt>SQLITE_TRACE_CLOSE</dt>
+** <dd>An SQLITE_TRACE_CLOSE callback is invoked when a database
+** connection closes.
+** The P argument is a pointer to the [database connection] object
+** and the X argument is unused.
+** </dl>
+*/
+#define SQLITE_TRACE_SQL        0x0001
+#define SQLITE_TRACE_STMT       0x0002
+#define SQLITE_TRACE_PROFILE    0x0004
+#define SQLITE_TRACE_ROW        0x0008
+#define SQLITE_TRACE_CLOSE      0x0010
+
+/*
+** CAPI3REF: SQL Trace Hook
+** METHOD: sqlite3
+**
+** The sqlite3_trace_v2(D,X,M,P) interface registers a trace callback
+** function X against [database connection] D, using property mask M
+** and context pointer P.  If the X callback is
+** NULL or if the M mask is zero, then tracing is disabled.  The
+** M argument must be one or more of the [SQLITE_TRACE]
+** constants.
+**
+** Each call to either sqlite3_trace() or sqlite3_trace_v2() overrides 
+** (cancels) any prior calls to sqlite3_trace() or sqlite3_trace_v2().
+**
+** The X callback is invoked whenever any of the events identified by 
+** mask M occur.  The integer return value from the callback is currently
+** ignored, though this may change in future releases.  Callback
+** implementations should return zero to ensure future compatibility.
+**
+** A trace callback is invoked with four arguments: callback(T,C,P,X).
+** The T argument is one of the [SQLITE_TRACE]
+** constants to indicate why the callback was invoked.
+** The C argument is a copy of the context pointer.
+** The P and X arguments are a pointer and an unsigned 64-bit integer
+** whose meanings depend on T.
+**
+** The sqlite3_trace_v2() interface is intended to replace the legacy
+** interfaces [sqlite3_trace()] and [sqlite3_profile()], both of which
+** are deprecated.
+*/
+int sqlite3_trace_v2(
+  sqlite3*,
+  int(*xCallback)(unsigned,void*,void*,sqlite3_uint64),
+  unsigned uMask,
+  void *pCtx
+);
+
 /*
 ** CAPI3REF: Query Progress Callbacks
 ** METHOD: sqlite3