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

[Nick Coghlan]

https://github.com/python/cpython/commit/255f7a26da47ca6b7bd1d375b8a04920f68c119c
commit: 255f7a26da47ca6b7bd1d375b8a04920f68c119c
branch: master
author: Xiang Zhang <angwerzx at 126.com>
committer: Nick Coghlan <ncoghlan at gmail.com>
date: 2018-01-28T19:53:38+10:00
summary:

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

Updating the C API docs was missed when the per-opcode
tracing & profiling support was initially added.

files:
A Misc/NEWS.d/next/Documentation/2018-01-27-23-36-31.bpo-32649.o7qOjF.rst
M Doc/c-api/init.rst

diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst
index 9887d28b09d9..33cb02d8c9cc 100644
--- a/Doc/c-api/init.rst
+++ b/Doc/c-api/init.rst
@@ -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:
 
diff --git a/Misc/NEWS.d/next/Documentation/2018-01-27-23-36-31.bpo-32649.o7qOjF.rst b/Misc/NEWS.d/next/Documentation/2018-01-27-23-36-31.bpo-32649.o7qOjF.rst
new file mode 100644
index 000000000000..8e8045808fbd
--- /dev/null
+++ b/Misc/NEWS.d/next/Documentation/2018-01-27-23-36-31.bpo-32649.o7qOjF.rst
@@ -0,0 +1,2 @@
+Complete the C API documentation, profiling and tracing part with the newly
+added per-opcode events.