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: |
0c569f759f6c4701321d7fea5e7ccb37 |
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
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 | ** 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. */ | > | | > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > | 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 |
︙ | ︙ |