Stowage/cpython
2
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-11-04 07:31:38 +00:00
Code Issues Projects Releases Packages Wiki Activity

bpo-32649: Add C API docs for per-opcode tracing & profiling (GH-5360)

Browse source 
Updating the C API docs was missed when the per-opcode
tracing & profiling support was initially added.
This commit is contained in:
Xiang Zhang 2018-01-28 17:53:38 +08:00 • committed by Nick Coghlan
parent 9ed0aee27c
commit 255f7a26da
2 changed files with 22 additions and 9 deletions
Download patch file Download diff file Expand all files Collapse all files

29
Doc/c-api/init.rst
View file

@ -1277,8 +1277,8 @@ Python-level trace functions in previous versions.
registration function as *obj*, *frame* is the frame object to which the event
pertains, *what* is one of the constants :const:`PyTrace_CALL`,
:const:`PyTrace_EXCEPTION`, :const:`PyTrace_LINE`, :const:`PyTrace_RETURN`,
:const:`PyTrace_C_CALL`, :const:`PyTrace_C_EXCEPTION`, or
:const:`PyTrace_C_RETURN`, and *arg* depends on the value of *what*:
:const:`PyTrace_C_CALL`, :const:`PyTrace_C_EXCEPTION`, :const:`PyTrace_C_RETURN`,
or :const:`PyTrace_OPCODE`, and *arg* depends on the value of *what*:
+------------------------------+--------------------------------------+
| Value of *what* | Meaning of *arg* |
@ -1299,6 +1299,8 @@ Python-level trace functions in previous versions.
+------------------------------+--------------------------------------+
| :const:`PyTrace_C_RETURN` | Function object being called. |
+------------------------------+--------------------------------------+
| :const:`PyTrace_OPCODE` | Always :c:data:`Py_None`. |
+------------------------------+--------------------------------------+
.. c:var:: int PyTrace_CALL
@ -1322,8 +1324,9 @@ Python-level trace functions in previous versions.
.. c:var:: int PyTrace_LINE
The value passed as the *what* parameter to a trace function (but not a
profiling function) when a line-number event is being reported.
The value passed as the *what* parameter to a :c:type:`Py_tracefunc` function
(but not a profiling function) when a line-number event is being reported.
It may be disabled for a frame by setting :attr:`f_trace_lines` to *0* on that frame.
.. c:var:: int PyTrace_RETURN
@ -1350,6 +1353,14 @@ Python-level trace functions in previous versions.
function has returned.
.. c:var:: int PyTrace_OPCODE
The value for the *what* parameter to :c:type:`Py_tracefunc` functions (but not
profiling functions) when a new opcode is about to be executed. This event is
not emitted by default: it must be explicitly requested by setting
:attr:`f_trace_opcodes` to *1* on the frame.
.. c:function:: void PyEval_SetProfile(Py_tracefunc func, PyObject *obj)
Set the profiler function to *func*. The *obj* parameter is passed to the
@ -1357,17 +1368,17 @@ Python-level trace functions in previous versions.
the profile function needs to maintain state, using a different value for *obj*
for each thread provides a convenient and thread-safe place to store it. The
profile function is called for all monitored events except :const:`PyTrace_LINE`
and :const:`PyTrace_EXCEPTION`.
:const:`PyTrace_OPCODE` and :const:`PyTrace_EXCEPTION`.
.. c:function:: void PyEval_SetTrace(Py_tracefunc func, PyObject *obj)
Set the tracing function to *func*. This is similar to
:c:func:`PyEval_SetProfile`, except the tracing function does receive line-number
events and does not receive any event related to C function objects being called. Any
trace function registered using :c:func:`PyEval_SetTrace` will not receive
:const:`PyTrace_C_CALL`, :const:`PyTrace_C_EXCEPTION` or :const:`PyTrace_C_RETURN`
as a value for the *what* parameter.
events and per-opcode events, but does not receive any event related to C function
objects being called. Any trace function registered using :c:func:`PyEval_SetTrace`
will not receive :const:`PyTrace_C_CALL`, :const:`PyTrace_C_EXCEPTION` or
:const:`PyTrace_C_RETURN` as a value for the *what* parameter.
.. _advanced-debugging:

2
Misc/NEWS.d/next/Documentation/2018-01-27-23-36-31.bpo-32649.o7qOjF.rst Normal file
View file

@ -0,0 +1,2 @@
Complete the C API documentation, profiling and tracing part with the newly
added per-opcode events.