SQLite

Check-in [0c569f759f]
Login

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Interface design for a new sqlite3_trace_v2() method that supersedes sqlite3_trace() and sqlite3_profile().
Downloads: Tarball | ZIP archive
Timelines: family | ancestors | descendants | both | sqlite3_trace_v2
Files: files | file ages | folders
SHA1: 0c569f759f6c4701321d7fea5e7ccb371743bb6b
User & Date: drh 2016-07-13 21:30:03.340
Context
2016-07-13
22:55
First cut at implementing the new sqlite3_trace_v2() interface. (check-in: cb0062feb0 user: drh tags: sqlite3_trace_v2)
21:30
Interface design for a new sqlite3_trace_v2() method that supersedes sqlite3_trace() and sqlite3_profile(). (check-in: 0c569f759f user: drh tags: sqlite3_trace_v2)
13:05
Fix harmless compiler warnings in shell.c for NetBSD. (check-in: 824b39e54f user: drh tags: trunk)
Changes
Unified Diff Ignore Whitespace Patch
Changes to src/sqlite.h.in.
2750
2751
2752
2753
2754
2755
2756



2757
2758
2759
2760
2761
2762
2763
#define SQLITE_SAVEPOINT            32   /* Operation       Savepoint Name  */
#define SQLITE_COPY                  0   /* No longer used */
#define SQLITE_RECURSIVE            33   /* NULL            NULL            */

/*
** CAPI3REF: Tracing And Profiling Functions
** METHOD: sqlite3



**
** These routines register callback functions that can be used for
** tracing and profiling the execution of SQL statements.
**
** ^The callback function registered by sqlite3_trace() is invoked at
** various times when an SQL statement is being run by [sqlite3_step()].
** ^The sqlite3_trace() callback is invoked with a UTF-8 rendering of the







>
>
>







2750
2751
2752
2753
2754
2755
2756
2757
2758
2759
2760
2761
2762
2763
2764
2765
2766
#define SQLITE_SAVEPOINT            32   /* Operation       Savepoint Name  */
#define SQLITE_COPY                  0   /* No longer used */
#define SQLITE_RECURSIVE            33   /* NULL            NULL            */

/*
** 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.
**
** ^The callback function registered by sqlite3_trace() is invoked at
** various times when an SQL statement is being run by [sqlite3_step()].
** ^The sqlite3_trace() callback is invoked with a UTF-8 rendering of the
2776
2777
2778
2779
2780
2781
2782

2783
2784
2785




































































































2786
2787
2788
2789
2790
2791
2792
** time is in units of nanoseconds, however the current implementation
** is only capable of millisecond resolution so the six least significant
** digits in the time are meaningless.  Future versions of SQLite
** might provide greater resolution on the profiler callback.  The
** 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*,
   void(*xProfile)(void*,const char*,sqlite3_uint64), void*);





































































































/*
** CAPI3REF: Query Progress Callbacks
** METHOD: sqlite3
**
** ^The sqlite3_progress_handler(D,N,X,P) interface causes the callback
** function X to be invoked periodically during long running calls to







>
|
|

>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>







2779
2780
2781
2782
2783
2784
2785
2786
2787
2788
2789
2790
2791
2792
2793
2794
2795
2796
2797
2798
2799
2800
2801
2802
2803
2804
2805
2806
2807
2808
2809
2810
2811
2812
2813
2814
2815
2816
2817
2818
2819
2820
2821
2822
2823
2824
2825
2826
2827
2828
2829
2830
2831
2832
2833
2834
2835
2836
2837
2838
2839
2840
2841
2842
2843
2844
2845
2846
2847
2848
2849
2850
2851
2852
2853
2854
2855
2856
2857
2858
2859
2860
2861
2862
2863
2864
2865
2866
2867
2868
2869
2870
2871
2872
2873
2874
2875
2876
2877
2878
2879
2880
2881
2882
2883
2884
2885
2886
2887
2888
2889
2890
2891
2892
2893
2894
2895
2896
** time is in units of nanoseconds, however the current implementation
** is only capable of millisecond resolution so the six least significant
** digits in the time are meaningless.  Future versions of SQLite
** might provide greater resolution on the profiler callback.  The
** sqlite3_profile() function is considered experimental and is
** subject to change in future versions of SQLite.
*/
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
**
** ^The sqlite3_progress_handler(D,N,X,P) interface causes the callback
** function X to be invoked periodically during long running calls to