Debian Codegraph @

Doc/c-api/profiling.rst

raw
1 .. highlight:: c
2
3 .. _profiling:
4
5 Profiling and tracing
6 =====================
7
8 The Python interpreter provides some low-level support for attaching profiling
9 and execution tracing facilities. These are used for profiling, debugging, and
10 coverage analysis tools.
11
12 This C interface allows the profiling or tracing code to avoid the overhead of
13 calling through Python-level callable objects, making a direct C function call
14 instead. The essential attributes of the facility have not changed; the
15 interface allows trace functions to be installed per-thread, and the basic
16 events reported to the trace function are the same as had been reported to the
17 Python-level trace functions in previous versions.
18
19
20 .. c:type:: int (*Py_tracefunc)(PyObject *obj, PyFrameObject *frame, int what, PyObject *arg)
21
22 The type of the trace function registered using :c:func:`PyEval_SetProfile` and
23 :c:func:`PyEval_SetTrace`. The first parameter is the object passed to the
24 registration function as *obj*, *frame* is the frame object to which the event
25 pertains, *what* is one of the constants :c:data:`PyTrace_CALL`,
26 :c:data:`PyTrace_EXCEPTION`, :c:data:`PyTrace_LINE`, :c:data:`PyTrace_RETURN`,
27 :c:data:`PyTrace_C_CALL`, :c:data:`PyTrace_C_EXCEPTION`, :c:data:`PyTrace_C_RETURN`,
28 or :c:data:`PyTrace_OPCODE`, and *arg* depends on the value of *what*:
29
30 +-------------------------------+----------------------------------------+
31 | Value of *what* | Meaning of *arg* |
32 +===============================+========================================+
33 | :c:data:`PyTrace_CALL` | Always :c:data:`Py_None`. |
34 +-------------------------------+----------------------------------------+
35 | :c:data:`PyTrace_EXCEPTION` | Exception information as returned by |
36 | | :func:`sys.exc_info`. |
37 +-------------------------------+----------------------------------------+
38 | :c:data:`PyTrace_LINE` | Always :c:data:`Py_None`. |
39 +-------------------------------+----------------------------------------+
40 | :c:data:`PyTrace_RETURN` | Value being returned to the caller, |
41 | | or ``NULL`` if caused by an exception. |
42 +-------------------------------+----------------------------------------+
43 | :c:data:`PyTrace_C_CALL` | Function object being called. |
44 +-------------------------------+----------------------------------------+
45 | :c:data:`PyTrace_C_EXCEPTION` | Function object being called. |
46 +-------------------------------+----------------------------------------+
47 | :c:data:`PyTrace_C_RETURN` | Function object being called. |
48 +-------------------------------+----------------------------------------+
49 | :c:data:`PyTrace_OPCODE` | Always :c:data:`Py_None`. |
50 +-------------------------------+----------------------------------------+
51
52 .. c:var:: int PyTrace_CALL
53
54 The value of the *what* parameter to a :c:type:`Py_tracefunc` function when a new
55 call to a function or method is being reported, or a new entry into a generator.
56 Note that the creation of the iterator for a generator function is not reported
57 as there is no control transfer to the Python bytecode in the corresponding
58 frame.
59
60
61 .. c:var:: int PyTrace_EXCEPTION
62
63 The value of the *what* parameter to a :c:type:`Py_tracefunc` function when an
64 exception has been raised. The callback function is called with this value for
65 *what* when after any bytecode is processed after which the exception becomes
66 set within the frame being executed. The effect of this is that as exception
67 propagation causes the Python stack to unwind, the callback is called upon
68 return to each frame as the exception propagates. Only trace functions receive
69 these events; they are not needed by the profiler.
70
71
72 .. c:var:: int PyTrace_LINE
73
74 The value passed as the *what* parameter to a :c:type:`Py_tracefunc` function
75 (but not a profiling function) when a line-number event is being reported.
76 It may be disabled for a frame by setting :attr:`~frame.f_trace_lines` to
77 *0* on that frame.
78
79
80 .. c:var:: int PyTrace_RETURN
81
82 The value for the *what* parameter to :c:type:`Py_tracefunc` functions when a
83 call is about to return.
84
85
86 .. c:var:: int PyTrace_C_CALL
87
88 The value for the *what* parameter to :c:type:`Py_tracefunc` functions when a C
89 function is about to be called.
90
91
92 .. c:var:: int PyTrace_C_EXCEPTION
93
94 The value for the *what* parameter to :c:type:`Py_tracefunc` functions when a C
95 function has raised an exception.
96
97
98 .. c:var:: int PyTrace_C_RETURN
99
100 The value for the *what* parameter to :c:type:`Py_tracefunc` functions when a C
101 function has returned.
102
103
104 .. c:var:: int PyTrace_OPCODE
105
106 The value for the *what* parameter to :c:type:`Py_tracefunc` functions (but not
107 profiling functions) when a new opcode is about to be executed. This event is
108 not emitted by default: it must be explicitly requested by setting
109 :attr:`~frame.f_trace_opcodes` to *1* on the frame.
110
111
112 .. c:function:: void PyEval_SetProfile(Py_tracefunc func, PyObject *obj)
113
114 Set the profiler function to *func*. The *obj* parameter is passed to the
115 function as its first parameter, and may be any Python object, or ``NULL``. If
116 the profile function needs to maintain state, using a different value for *obj*
117 for each thread provides a convenient and thread-safe place to store it. The
118 profile function is called for all monitored events except :c:data:`PyTrace_LINE`
119 :c:data:`PyTrace_OPCODE` and :c:data:`PyTrace_EXCEPTION`.
120
121 See also the :func:`sys.setprofile` function.
122
123 The caller must have an :term:`attached thread state`.
124
125
126 .. c:function:: void PyEval_SetProfileAllThreads(Py_tracefunc func, PyObject *obj)
127
128 Like :c:func:`PyEval_SetProfile` but sets the profile function in all running threads
129 belonging to the current interpreter instead of the setting it only on the current thread.
130
131 The caller must have an :term:`attached thread state`.
132
133 As :c:func:`PyEval_SetProfile`, this function ignores any exceptions raised while
134 setting the profile functions in all threads.
135
136 .. versionadded:: 3.12
137
138
139 .. c:function:: void PyEval_SetTrace(Py_tracefunc func, PyObject *obj)
140
141 Set the tracing function to *func*. This is similar to
142 :c:func:`PyEval_SetProfile`, except the tracing function does receive line-number
143 events and per-opcode events, but does not receive any event related to C function
144 objects being called. Any trace function registered using :c:func:`PyEval_SetTrace`
145 will not receive :c:data:`PyTrace_C_CALL`, :c:data:`PyTrace_C_EXCEPTION` or
146 :c:data:`PyTrace_C_RETURN` as a value for the *what* parameter.
147
148 See also the :func:`sys.settrace` function.
149
150 The caller must have an :term:`attached thread state`.
151
152
153 .. c:function:: void PyEval_SetTraceAllThreads(Py_tracefunc func, PyObject *obj)
154
155 Like :c:func:`PyEval_SetTrace` but sets the tracing function in all running threads
156 belonging to the current interpreter instead of the setting it only on the current thread.
157
158 The caller must have an :term:`attached thread state`.
159
160 As :c:func:`PyEval_SetTrace`, this function ignores any exceptions raised while
161 setting the trace functions in all threads.
162
163 .. versionadded:: 3.12
164
165
166 Reference tracing
167 =================
168
169 .. versionadded:: 3.13
170
171
172 .. c:type:: int (*PyRefTracer)(PyObject *, int event, void* data)
173
174 The type of the trace function registered using :c:func:`PyRefTracer_SetTracer`.
175 The first parameter is a Python object that has been just created (when **event**
176 is set to :c:data:`PyRefTracer_CREATE`) or about to be destroyed (when **event**
177 is set to :c:data:`PyRefTracer_DESTROY`). The **data** argument is the opaque pointer
178 that was provided when :c:func:`PyRefTracer_SetTracer` was called.
179
180 If a new tracing function is registered replacing the current one, a call to the
181 trace function will be made with the object set to **NULL** and **event** set to
182 :c:data:`PyRefTracer_TRACKER_REMOVED`. This will happen just before the new
183 function is registered.
184
185 .. versionadded:: 3.13
186
187
188 .. c:var:: int PyRefTracer_CREATE
189
190 The value for the *event* parameter to :c:type:`PyRefTracer` functions when a Python
191 object has been created.
192
193
194 .. c:var:: int PyRefTracer_DESTROY
195
196 The value for the *event* parameter to :c:type:`PyRefTracer` functions when a Python
197 object has been destroyed.
198
199
200 .. c:var:: int PyRefTracer_TRACKER_REMOVED
201
202 The value for the *event* parameter to :c:type:`PyRefTracer` functions when the
203 current tracer is about to be replaced by a new one.
204
205 .. versionadded:: 3.14
206
207
208 .. c:function:: int PyRefTracer_SetTracer(PyRefTracer tracer, void *data)
209
210 Register a reference tracer function. The function will be called when a new
211 Python object has been created or when an object is going to be destroyed. If
212 **data** is provided it must be an opaque pointer that will be provided when
213 the tracer function is called. Return ``0`` on success. Set an exception and
214 return ``-1`` on error.
215
216 Note that tracer functions **must not** create Python objects inside or
217 otherwise the call will be re-entrant. The tracer also **must not** clear
218 any existing exception or set an exception. A :term:`thread state` will be active
219 every time the tracer function is called.
220
221 There must be an :term:`attached thread state` when calling this function.
222
223 If another tracer function was already registered, the old function will be
224 called with **event** set to :c:data:`PyRefTracer_TRACKER_REMOVED` just before
225 the new function is registered.
226
227 .. versionadded:: 3.13
228
229
230 .. c:function:: PyRefTracer PyRefTracer_GetTracer(void** data)
231
232 Get the registered reference tracer function and the value of the opaque data
233 pointer that was registered when :c:func:`PyRefTracer_SetTracer` was called.
234 If no tracer was registered this function will return NULL and will set the
235 **data** pointer to NULL.
236
237 There must be an :term:`attached thread state` when calling this function.
238
239 .. versionadded:: 3.13